概述
系列定位：在项目中要搭建出完整的Harness Engineering四层文档体系，基本分为6步，接下来我会通过本系列共 6 篇文章，指导从零搭建 Harness Engineering 四层文档体系，最终实现从 BRD/PRD 到代码交付的一站式 AI 开发与自检闭环。
本篇定位：第 1 步------在编写任何业务代码之前，建立项目入口文件和架构基线文档，为后续所有文档和 AI Agent 行为提供锚点。
1. 为什么第一步是"项目入口 + 架构基线"
1.1 核心问题
当你用 IDEA 新建一个 Java 项目时，面对的是空工程。此时 AI Agent 对你的项目一无所知：
- 项目用什么技术栈？版本是什么？
- 模块怎么划分？依赖方向是什么？
- 数据怎么流转？有哪些核心流程？
- 代码资产有哪些基类和接口可以复用？
如果这些信息不存在，后续的 Rules 层（硬性约束）无从写起------因为你无法约束一个尚未定义的架构。
1.2 本步要解决的三件事
| 问题 | 解决方式 | 产出文件 |
|---|---|---|
| AI Agent 不知道项目"是什么" | 编写项目入口文件 | AGENTS.md、README.md |
| AI Agent 不知道"怎么分层" | 编写架构知识文档 | docs/architecture/overview.md、boundaries.md、data-flow.md、code-assets.md |
| 所有 .md 文件缺乏统一的元信息规范 | 建立文档元信息 front matter 规范 | 每个文件的 YAML 头 |
2. 需要创建的文件清单
项目根/
├── AGENTS.md # AI Agent 项目入口
├── README.md # 项目整体说明
└── docs/
└── architecture/
├── overview.md # 系统架构概览
├── boundaries.md # 模块边界与依赖约束
├── data-flow.md # 数据流转路径
└── code-assets.md # 代码资产清单共 6 个文件，全部是 Markdown 文档，不涉及任何代码。
3. 逐个文件编写指南
3.1 AGENTS.md--- AI Agent 的"第一印象"
定位
AGENTS.md 是 AI Agent 进入项目后读取的第一个文件，类似于人类新员工的"入职手册"，AGENTS.md是写地图，不是写百科全书。它必须在一屏内传达：项目是做什么的、技术栈是什么、去哪里找更多信息。
关键设计原则
- AGENTS.md 控制在 50-100 行。超过就说明你在写百科全书了
- "你想做什么 → 去哪里看" 比 "这是什么"更有效------面向任务而非面向知识
- 硬性规则单独列出，这些是 CI 会强制验证的，不是 "建议"。
必须包含的章节
markdown
# AGENTS.md
## 项目简介
{一段话描述项目做什么、解决什么问题、核心技术选型}
## 技术栈基线（不允许擅自升级）
- JDK: {版本}
- Spring Boot: {版本}
- {其他关键依赖及版本}
{每个版本后标注"不可升级"的约束}
## 快速导航
| 你想做什么 | 去哪里看 |
|-----------|---------|
| 查看 Rules 层规则 | .qoder/rules/*.md |
| 查看 Skills 层技能 | .qoder/skills/*.md |
| 了解系统架构 | docs/architecture/*.md |
{...}
## 硬性规范（CI 强制验证，违反即拒绝合并）
| 规则 | 禁止 | 验证方式 |
|------|------|---------|
| 模块依赖只能向上：common→dal→business→ext→app→runner | 反向依赖/跨层引用 | ArchUnit |
| JSON 统一用 FastJSON 1.2.83 | Jackson / Gson | PMD |
| HTTP 统一用 OkHttp3 + HttpClientFactory | RestTemplate / Apache HttpClient | PMD |
## 提交规范
- feat: 新功能
- fix: 修复 Bug
- refactor: 重构
- docs: 文档变更
- test: 测试
- chore: 构建/配置编写要点
- 技术栈基线必须精确到版本号 ：AI Agent 会严格遵循这些版本约束。如果写
JDK 1.8，AI 就不会用var、record等 Java 9+ 语法。当技术栈多时可以单独放入一个文档 - 快速导航表是文档索引的入口：后续 5 步创建的所有文档都要在此表中注册
- 保持精简：控制在 50~100 行以内，AI Agent 每次任务都会加载此文件
实际示例
markdown
---
last_updated: 2026-06-26
status: active # active | deprecated | draft
owner: @zhangsan
---
# AGENTS.md
## 项目简介
第三方数据交换平台，对接XXX/XXX/XXX等供应商，完成数据采集、加工、分片批量编排与结果持久化。
## 技术栈基线（不允许擅自升级）
技术栈基线详见 `.qoder/rules/always-on.md` 第 1 节（JDK 1.8 / Spring Boot 2.3 / MyBatis-Plus 3.4 / FastJSON 唯一 / OkHttp3 统一）。
## 快速导航（你想做什么 → 去哪里看）
| 你想做什么 | 去哪里看 |
|-----------|---------|
| **--- Rules 层（始终生效，CI 强制验证）** | |
| 写代码前确认技术红线 | .qoder/rules/always-on.md |
| 确认开发流程顺序/门禁 | .qoder/rules/agent-workflow.md |
| 不确定类/方法怎么命名 | .qoder/rules/java-code-style.md |
| 写测试时不确定框架/Mock 策略 | .qoder/rules/java-testing.md |
| **--- Skills 层（按场景触发）** | |
| 收到 PRD 要开发 | .qoder/skills/prd-to-code.md |
| 全流程编排/断点恢复 | .qoder/skills/flow-orchestration.md |
| 设计文档写好了要评审 | .qoder/skills/design-review.md |
| 新增供应商对接 | .qoder/skills/add-vendor-adapter.md |
| 新增数据库表 | .qoder/skills/add-entity-mapper.md |
| 新增对外 API 接口 | .qoder/skills/add-api-endpoint.md |
| 提交前检查文档健康度 | .qoder/skills/doc-gardening.md |
| 交付前自动治理巡检 | .qoder/skills/auto-governance.md |
| **--- Wiki 层（按需查阅）** | |
| 设计新功能前查有哪些基类可复用 | docs/architecture/code-assets.md |
| 确认模块归属和依赖方向 | docs/architecture/boundaries.md |
| 设计功能时参考数据怎么流转 | docs/architecture/data-flow.md |
| 不确定异常怎么抛/错误码怎么定 | docs/conventions/error-handling.md |
| 不确定日志格式/traceId 怎么传 | docs/conventions/logging.md |
| Linter 报错后查规则详情和修复指引 | docs/conventions/linter-rules.md |
| 写 PRD 时参照模板 | docs/reference/prd-template.md |
| 业务方提需求时参照 BRD→PRD 指南 | docs/reference/brd-to-prd-guide.md |
| 查/新增错误码 | docs/reference/error-codes.md |
| 查/新增 API 定义 | docs/reference/api.spec.yaml |
| 写设计文档时用模板 | docs/design/_template.md |
| PR 提交前逐项自检 | docs/changes/pr-checklist.md |
| 变更前做影响分析 | docs/changes/impact-analysis.md |
| 了解整体 AI Coding 开发流程 | docs/ai-coding-guide.md |
| **--- 自动化层脚本** | |
| 环境前置检查 | build/automation/scripts/pre-check.ps1 |
| Git Worktree 自动化管理 | build/automation/scripts/worktree-manager.ps1 |
| 采集构建/测试/Linter 客观数据 | build/automation/scripts/collect-sidecar.ps1 |
| 自动衰减检测 | build/automation/scripts/decay-detector.ps1 |
| 生成治理报告 | build/automation/scripts/governance-report.ps1 |
| 文档全景索引一致性检测 | build/automation/scripts/index-sync-check.ps1 |
| **--- 代码定位** | |
| 找启动入口 | exchange-runner/.../WebApplication.java |
| 找 HTTP 控制器 | exchange-runner/.../controller/ |
| 找 SOA 同步单笔服务 | exchange-soa-service/.../SyncSingleService.java |
| 批量调度入口（XXL-JOB） | exchange-runner/.../ShardingScheduler.java |
| 找供应商适配器 | exchange-ext/exchange-ext-{tianchuang,youmeng,baihang}/ |
| Maven 环境与 Nacos 配置 | pom.xml (profiles 章节) |
## 硬性规则（CI 强制验证，违反即拒绝合并）
| 规则 | 禁止 | 验证方式 |
|------|------|---------|
| 模块依赖只能向上：common→dal→business→ext→app→runner | 反向依赖/跨层引用 | ArchUnit |
| JSON 统一用 FastJSON 1.2.83 | Jackson / Gson | PMD |
| HTTP 统一用 OkHttp3 + HttpClientFactory | RestTemplate / Apache HttpClient | PMD |
| 数据库用 DalManager.of(beanName) | 直接注入 Mapper | PMD |
| 事务用 TransactionTemplate 编程式 | @Transactional 注解 | PMD |
| 日志用 @Slf4j + 占位符 | LoggerFactory / System.out | Checkstyle |
| 注入用 @Resource / 构造器 | 字段级 @Autowired | Checkstyle |
| 线程池用 BatchExecutorTemplate / Builder | 裸 new ThreadPoolExecutor | PMD |
| 限流用 Resilience4j + RateLimitFactory | 自行实现限流 | PMD |
| traceId 用 @MDC + ContextHolder | 线程切换丢失 traceId | PMD |
| 配置用 Nacos | 硬编码环境地址/密钥 | Checkstyle |
| commit 前缀：feat/fix/refactor/docs/test/chore | 无前缀或不规范 | Git Hook |
| 交付前必须通过自动治理巡检 | 跳过巡检直接交付 | agent-workflow.md §8 |
| 完整规则 → `.qoder/rules/` 全部 4 个文件 | | |关键提醒：此文件会在后续步骤中持续更新------每新增一个 Rules、Skills 或 Wiki 文件，都要在"快速导航"表中注册对应条目。
3.2 README.md --- 面向人类的入口
定位
README.md 面向人类开发者（非 AI），提供项目概览、模块拓扑、启动方式和环境准备。与 AGENTS.md 互补：AGENTS.md 偏"约束"，README.md 偏"说明"。
建议包含的章节
- 项目简介（1~2 段话）
- 模块拓扑图（ASCII 或 Mermaid）
- 技术栈表（与 AGENTS.md 一致，但可更详细）
- 环境准备（JDK、Maven、MySQL、Redis 版本要求）
- 启动方式（本地开发、测试、生产）
- 模块说明链接（指向各模块的 readme.md）
实际示例
markdown
---
last_updated: 2026-06-26
status: active
owner: @zhangsan
---
# app-exchange-port
第三方系统数据交换平台，对接天创/友盟/百行等外部供应商，完成数据采集、加密转换、分片批量编排与结果持久化。
## 技术栈
| 层面 | 选型 |
|------|------|
| JDK | 1.8 |
| 框架 | Spring Boot 2.3.12 + Spring Cloud Hoxton.SR12 + Alibaba Cloud 2021.1 |
| 持久化 | MyBatis-Plus 3.4.3 + MySQL 8.0.28 + Dynamic Datasource |
| 缓存 | Redis + Caffeine |
| 调度 | XXL-JOB 2.2.0 |
| HTTP | OkHttp3 3.14.9（统一客户端） |
| JSON | FastJSON 1.2.83（唯一序列化库） |
| 限流 | Resilience4j |
| 配置中心 | Nacos |
| 测试 | JUnit 5.6.3 + Mockito 3.12.4 |
> 完整技术约束见 `.qoder/rules/always-on.md`
## 模块结构
依赖只能向上流动，严禁反向依赖或跨层引用：
common → dal → business → ext → app → runner （Web 部署链路）
common → dal → business → ext → soa-service → app-soa → deploy-set （SOA 部署链路）
| 模块 | 职责 |
|------|------|
| exchange-common | 通用基础设施：trace / juc / cache / scheduler / http / sentinel / event |
| exchange-dal | 仓储层：entity / mapper / manager / datasource |
| exchange-business | 核心业务层：core(async/sync/lifecycle) / base / ext / infra |
| exchange-ext | 供应商适配层：tianchuang（天创）/ youmeng（友盟）/ baihang（百行） |
| exchange-app | 应用编排层：config / trigger / admin / facade |
| exchange-runner | Web 部署包：WebApplication + controllers |
| exchange-api | SOA 接口契约（独立发布，仅依赖 Lombok） |
| exchange-soa-service | SOA 服务实现：SyncSingleService + RateLimitDelegate |
| exchange-app-soa | SOA 应用配置 |
| exchange-deploy-set | 部署集合（pom 聚合）→ exchange-soa-runner |
| exchange-test | 集成测试集 |
## 快速开始
### 环境要求
- JDK 1.8
- Maven 3.6+
- MySQL 8.0
- Redis
- Nacos（⚠️ exchange-test 模块下的 `app-exchange-port.yml` 需与 Nacos 上 `namespace=dev1` 保持一致）
### 构建
```bash
mvn clean package -DskipTests
### 启动
项目有两个部署入口：
| 部署形态 | 启动类 | 模块 | 用途 |
|---------|--------|------|------|
| Web 应用 | `com.jzsk.exchange.WebApplication` | exchange-runner | 批量调度、手动触发、管理运维、监控 |
| SOA 服务 | `com.jzsk.exchange.SoaRunner` | exchange-deploy-set/exchange-soa-runner | 同步单笔请求（Dubbo/HTTP） |
## 运维接口
| 接口 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 批量执行 | GET | `/schedule/triggerBatch/{YYYY-MM-DD~HH}/{planId}/{sourceIds}` | 手动触发批量数据交换。时间到小时，如 `2024-12-23~09` |
| 数据分片 | GET | `/schedule/trigger/{clusterSize}/{clusterIndex}` | 指定集群规模和机器索引执行分片 |
| 监控面板 | GET | `/monitor` | 查看线程池（阻塞任务数/线程参数）、全局配置、业务配置 |
| ⚠️ 重置数据 | GET | `/schedule/reset/{YYYY-MM-DD~HH}/{tb_name}` | 清理目标表数据，**仅限测试环境**。时间作为验证密码，`{tb_name}` 为目标表名 |
> **日志排查**：基于 traceId 查找上下文，主/子线程 traceId 可关联查询，搜索关键词 `start,parentTraceId=` 或 `start,preTraceId=`
## 重要配置
| 配置项 | 说明 | 备注 |
|--------|------|------|
| `exchange.biz.global` | 全局业务配置 | --- |
| `exchange.biz.global.close` | 全局开关 | 关闭后阻塞下一批扫描 |
| `exchange.biz.global.executors` | 线程池配置 | ⚠️ 阻塞队列数不可修改 |
| `spring.redis` | Redis 客户端配置 | ⚠️ 目前不可动态修改 |
| `spring.redis.pool` | Redis 连接池 | --- |
| `xxl.job` | XXL-JOB 分布式调度配置 | --- |
## 开发指南
| 你想做什么 | 去哪里看 |
|-----------|---------|
| 了解 AI Coding 规范化开发流程 | [docs/ai-coding-guide.md](docs/ai-coding-guide.md) |
| AI Agent 项目入口（导航地图） | [AGENTS.md](AGENTS.md) |
| 查看技术红线和 CI 验证规则 | `.qoder/rules/always-on.md` |
| 了解系统架构和数据流转 | [docs/architecture/overview.md](docs/architecture/overview.md) |
| 确认模块边界和依赖方向 | [docs/architecture/boundaries.md](docs/architecture/boundaries.md) |
| 查看可复用的基类/接口清单 | [docs/architecture/code-assets.md](docs/architecture/code-assets.md) |
## 文档目录
docs/
├── architecture/ 架构知识（overview / boundaries / code-assets / data-flow）
├── conventions/ 编码规范（naming / error-handling / testing / logging / linter-rules）
├── design/ 功能设计文档（_template + feature-*.md）
├── reference/ 参考资料（prd-template / api.spec.yaml / error-codes）
├── changes/ 变更管理（pr-checklist / impact-analysis）
└── plans/ 迭代计划（current-sprint / backlog）
## 变更记录
见 [CHANGELOG.md](CHANGELOG.md)3.3 docs/architecture/overview.md --- 架构概览
定位
这是 Wiki 层的第一个文档，为 AI Agent 提供系统全局视角。AI Agent 在 PRD 解析阶段会加载此文件理解项目全貌。
必须包含的章节
| 章节 | 内容 | 为什么 AI 需要知道 |
|---|---|---|
| 定位 | 项目解决什么问题 | 帮助 AI 理解业务上下文 |
| 技术栈明细 | 全部技术选型及版本 | 决定 AI 能使用哪些技术 |
| 模块全景 | 所有 Maven 模块及其职责 | AI 需要知道代码放在哪个模块 |
| 部署入口 | 启动类和部署形态 | AI 需要知道在哪里暴露接口 |
| 核心流程 | 一句话概括主要业务流程 | AI 需要理解数据流转方向 |
编写模板
markdown
---
last_updated: 2026-06-29
status: active
owner: @zhangsan
---
# 系统架构概览
## 定位
{一段话：项目解决什么问题，核心能力是什么}
## 技术栈
| 层面 | 技术选型 |
|------|---------|
| JDK | 1.8 |
| 框架 | Spring Boot 2.3.12 + Spring Cloud |
| 持久化 | MyBatis-Plus + MySQL |
| 缓存 | Redis + Caffeine |
| HTTP | OkHttp3 + HttpClientFactory |
| JSON | FastJSON |
| 配置中心 | Nacos |
| 测试 | JUnit 5 + Mockito |
## 模块全景
{ASCII 图或 Mermaid，展示所有 Maven 模块及其层次关系}
## 部署入口
| 部署形态 | 入口类 | 模块 | 职责 |
|---------|--------|------|------|
| Web 应用 | WebApplication | {module} | {职责} |
| SOA 服务 | {Runner} | {module} | {职责} |
## 核心流程
{用编号列表概括 1~3 个核心业务流程，详见 data-flow.md}实际示例
markdown
---
last_updated: 2026-03-28
status: active # active | deprecated | draft
owner: @zhangsan
---
# 系统架构概览
## 定位
app-exchange-port 是一个第三方系统数据交换平台，负责对接天创（Tianchuang）、友盟（Youmeng）、百行（Baihang）等外部供应商，完成数据采集、加密转换、分片批量编排、结果持久化与文件处理。
## 技术栈
| 层面 | 技术选型 |
|------|---------|
| JDK | 1.8 |
| 框架 | Spring Boot 2.3.12 + Spring Cloud Hoxton.SR12 + Alibaba Cloud 2021.1 |
| 持久化 | MyBatis-Plus 3.4.3 + MySQL 8.0.28 + Dynamic Datasource 3.5.0 + HikariCP 3.4.5 |
| 缓存 | Redis (Lettuce / Jedis 3.3.0) + Caffeine 2.8.8 |
| 调度 | XXL-JOB 2.2.0 + 自研 @Trigger/@Job 调度框架 |
| HTTP | OkHttp3 3.14.9 + HttpClientFactory |
| 限流 | Resilience4j-ratelimiter + RateLimitFactory |
| 监控 | CAT + 自研 HttpMonitorInterceptor |
| JSON | FastJSON 1.2.83 |
| 对象映射 | MapStruct 1.5.2 + Lombok 1.18.12 |
| 配置中心 | Nacos（namespace: dev1 / test1 / pre / prod） |
| 消息 | RocketMQ (ons-client 1.8.8) |
| 测试 | JUnit 5.6.3 + Mockito 3.12.4 |
## 模块全景
\```
app-exchange-port (root pom)
├── exchange-common 通用基础设施：trace / juc / cache / scheduler / http / sentinel / event
├── exchange-dal 仓储层：entity / mapper / manager / datasource
├── exchange-business 核心业务层：core(async/sync/lifecycle) / base / ext / infra
├── exchange-ext 供应商适配层（pom 聚合）
│ ├── exchange-ext-tianchuang 天创适配器
│ ├── exchange-ext-youmeng 友盟适配器（文件批处理）
│ └── exchange-ext-baihang 百行适配器
├── exchange-app 应用编排层：config / trigger / admin / facade
├── exchange-runner Web 部署包：WebApplication + controllers
├── exchange-api SOA 接口契约（独立发布，仅依赖 Lombok）
├── exchange-soa-service SOA 服务实现：SyncSingleService + RateLimitDelegate
├── exchange-app-soa SOA 应用配置
├── exchange-deploy-set 部署集合（pom 聚合）
│ └── exchange-soa-runner SOA 部署包
└── exchange-test 集成测试集
\```
## 双部署入口
| 部署形态 | 入口类 | 模块 | 职责 |
|---------|--------|------|------|
| Web 应用 | `WebApplication` | exchange-runner | 批量调度、手动触发、管理运维、监控 |
| SOA 服务 | SOA Runner | exchange-deploy-set/exchange-soa-runner | 同步单笔请求（Dubbo/HTTP） |
## 核心流程
1. **同步单笔**：外部系统 → SOA 接口 → `SyncSingleService.request()` → 限流 → 构造上下文 → HTTP 调用供应商 → 结果解析 → 返回
2. **异步批量**：XXL-JOB 触发 → `PlanLifecycleTrigger.trigInit()` → 数据分片 → 分区任务执行（同步/异步） → 结果持久化 → 文件处理（友盟）
详细流程见 [data-flow.md](data-flow.md)。3.4 docs/architecture/boundaries.md --- 模块边界与依赖约束
定位
这是整个 Harness 体系最关键的架构文档之一。 AI Agent 在每次影响分析（PRD-to-Code Step 2）时都会加载此文件，判断代码应该放在哪个模块、依赖是否合规。
必须包含的内容
- 依赖方向图（ASCII 图，清晰展示谁依赖谁）
- 铁律声明（依赖只能向上流动，禁止反向/跨层）
- 各模块职责（每个模块的"做什么"和"不做什么"）
- 跨模块约束（如数据库访问方式、配置注册方式、扩展点规则）
编写模板
markdown
---
last_updated: 2026-06-29
status: active
owner: @zhangsan
---
# 模块边界与依赖约束
## 依赖方向图
{ASCII 图：从底层到高层展示模块依赖关系}
**铁律：依赖只能向上流动，禁止反向依赖或跨层引用。**
## 各模块职责
### {module-common}
- **职责**：通用基础设施，业务无关
- **内容**：{列出此模块包含的核心功能}
- **禁止**：{明确列出不能做的事}
### {module-dal}
- **职责**：仓储层，操作数据库
- **内容**：Entity / Mapper / Manager / 数据源配置
- **禁止**：包含业务逻辑
{...其他模块}
## 跨模块约束
| 约束 | 说明 |
|------|------|
| 数据库访问方式 | {如通过 DalManager.of()} |
| 配置注册方式 | {如在何处注册} |
| 扩展点规则 | {如新增供应商必须新建子模块} |编写要点
- 每个模块的"禁止"项与 Rules 层的硬性约束一一对应
- 依赖方向图必须使用 ASCII 或 Mermaid，确保 AI Agent 能解析
- 模块职责描述要精确到"子目录"级别
实际示例
markdown
---
last_updated: 2026-03-28
status: active # active | deprecated | draft
owner: @zhangsan
---
# 模块边界与依赖约束
## 依赖方向图
\```
exchange-common ← 最底层，无项目内依赖
↑
exchange-dal ← 依赖 common
↑
exchange-business ← 依赖 dal + common
↑
exchange-ext (聚合) ← 依赖 business
├── ext-tianchuang
├── ext-youmeng
└── ext-baihang
↑
exchange-app ← 依赖全部 ext 子模块
↑
exchange-runner ← 依赖 app（Web 部署包）
exchange-api ← 独立模块，仅依赖 Lombok，独立发布 0.0.1.RELEASE
↑
exchange-soa-service ← 依赖 api + ext-tianchuang + ext-baihang
↑
exchange-app-soa ← 依赖 soa-service
↑
exchange-deploy-set / exchange-soa-runner ← 依赖 app-soa（SOA 部署包）
\```
**铁律：依赖只能向上流动，禁止反向依赖或跨层引用。**
## 各模块职责
### exchange-common
- **职责**：通用基础设施，业务无关
- **内容**：trace（traceId 传播）、juc（线程池/闭锁）、cache（Redis 锁/布隆过滤器）、scheduler（@Trigger/@Job 调度框架）、http（HttpClientFactory/监控拦截器）、sentinel（限流/CAT 监控）、event（EventBus）、shutdown（优雅停机）
- **禁止**：引入任何业务模块依赖
### exchange-dal
- **职责**：仓储层，操作数据库
- **内容**：entity（DO 模型）、mapper（MyBatis-Plus Mapper）、manager（Manager 模板方法封装）、datasource（数据源配置）
- **禁止**：包含业务逻辑；直接被 ext/runner 引用
### exchange-business
- **职责**：核心业务逻辑
- **内容**：
- `core/` --- 接口规范与核心编排（async 异步流程、sync 同步流程、lifecycle 生命周期）
- `base/` --- 对 core 接口的通用基础实现（HttpJsonPostRequestProcessor、HttpResultParserStrategy）
- `ext/` --- 增强功能（通知等）
- `infra/` --- 基础设施（InfraExecutorFactory）
- `exception/` --- 业务异常定义
- **禁止**：直接依赖具体供应商 SDK
### exchange-ext（及子模块）
- **职责**：按供应商接口规范定制适配器
- **模式**：每个子模块继承 business 中的抽象基类（InputConvertor、HttpResultParser、PortResultConvertor、PlanPartitionTaskProcessor 等）
- **ext-tianchuang**：天创 AES 加密 + MD5 签名 + 同步请求
- **ext-youmeng**：友盟文件批处理（CSV 读取、OSS 上传、批量计算、超时判定、布隆过滤）
- **ext-baihang**：百行征信数据对接
- **禁止**：被其他 ext 子模块互相引用
### exchange-app
- **职责**：全流程编排与全局配置
- **内容**：config（BizConfiguration/RedisConfiguration/AppConfig）、trigger（PlanLifecycleTrigger/AsyncTrigger/AsyncCompleteTrigger）、admin（管理操作）、facade（查询门面）
- **禁止**：直接操作 HTTP 客户端或数据库 Mapper
### exchange-runner
- **职责**：Web 部署入口
- **内容**：WebApplication 启动类、controllers（Schedule/Admin/Monitor/JobInfo/JobLifeCycle/TargetData）、ShardingScheduler（XXL-JOB 分片调度）
- **禁止**：包含核心业务逻辑，仅做请求转发与触发
### exchange-api
- **职责**：SOA 接口契约定义
- **内容**：SyncSingleRequestProvider 接口、RequestDTO/ResponseDTO、CodeEnum
- **特点**：独立版本号 0.0.1.RELEASE，独立发布到 Nexus，仅依赖 Lombok
### exchange-soa-service
- **职责**：SOA 接口实现
- **内容**：SyncSingleService（同步单笔）、HttpJsonPostRateLimitDelegate（限流委托）
## 跨模块约束
| 约束 | 说明 |
|------|------|
| Manager 模式 | 数据库操作必须通过 `DalManager.of(beanName)` 获取 Manager 实例，禁止直接注入 Mapper |
| 配置注册 | 供应商配置类需在 `BizConfiguration.preInitAppConfig()` 中注册到 PortConfigFactory / PlanConfigFactory |
| 扩展点 | 新增供应商必须新建 ext 子模块，禁止在 business 中硬编码供应商逻辑 |3.5 docs/architecture/data-flow.md --- 数据流转
定位
描述系统中数据如何在模块间流转。AI Agent 在设计文档生成阶段（Step 3）会参考此文件，确保新功能的数据流转路径与现有架构一致。
必须包含的内容
- 每种核心流程的调用链路图（从入口到出口的完整路径）
- 关键数据结构说明（DTO、Context、Config 等）
- 数据库表流转（数据从哪个表流到哪个表）
- 跨线程的上下文传播（如 traceId 传播机制）
编写要点
- 使用 ASCII 流程图，每个节点标注所属模块和类名
- 关键数据结构用表格列出，标明所属模块
- 一个流程一个章节，不要混在一起
实际示例
markdown
---
last_updated: 2026-03-28
status: active # active | deprecated | draft
owner: @zhangsan
---
# 数据流转
## 流程一：同步单笔请求（SOA）
\```
外部调用方
│
▼
SyncSingleRequestProvider.request(RequestDTO) ← exchange-api 接口契约
│
▼
SyncSingleService.request() ← exchange-soa-service
│
├─ 1. 参数校验（macro.portId / macro.appId / body.reqId / body.userId / body.phoneMd5）
├─ 2. 通过 PortConfigFactory.getPortConfig(portId) 获取供应商端口配置
├─ 3. 通过 PlanContextFactory.initContext(appId, portId) 构造计划上下文
├─ 4. 构造 PortRequestContext（含 SourceData、PortRequest、PortTraceInfo）
│
▼
HttpJsonPostRateLimitDelegate.execute(context) ← 限流委托
│
├─ Resilience4j RateLimiter 获取许可
│
▼
HttpJsonPostRequestProcessor ← exchange-business/base
│
├─ InputConvertor.buildInput() ← ext 模块（如 TCInputConvertor）
│ └─ 供应商特定的加密/签名逻辑（AES / MD5）
├─ HttpClientFactory 获取 OkHttp 客户端
├─ 发起 HTTP POST 请求
│
▼
HttpResultParserStrategy ← exchange-business/base
│
├─ HttpResultParser.parse() ← ext 模块（如 TCHttpResultParser3605）
│ └─ 解析供应商返回的加密响应体
├─ PortResultConvertor.convert() ← ext 模块（如 TCPortResultConvertor）
│ └─ 转换为统一 ResponseBodyDTO
│
▼
ResponseDTO.successInstance(body) ← 返回调用方
\```
### 关键数据结构
| 结构 | 模块 | 说明 |
|------|------|------|
| `RequestDTO` | exchange-api | macro(portId, appId) + body(reqId, userId, phoneMd5, ext) |
| `ResponseDTO` | exchange-api | macro(success, code, message) + body(reqId, content) |
| `PortRequestContext` | exchange-business | 封装端口请求上下文（ExchangePortRefWrap + PortRequest + PortTraceInfo） |
| `SyncPortConfig` | exchange-business | 供应商端口配置（url, tokenId, 限流参数等） |
---
## 流程二：异步批量分片执行（XXL-JOB）
\```
XXL-JOB 调度中心
│
▼
ShardingScheduler / ScheduleController ← exchange-runner
│
├─ ShardingUtil.getShardingVo() 获取分片参数（shardIndex / clusterSize）
├─ 构造 SchedulerScope + PlanSchedulerContext
│
▼
PlanLifecycleTrigger.trigInit() ← exchange-app
│
▼
PlanTaskInitializer ← exchange-business/core/lifecycle
│
├─ 1. 按 planId 查询 SourceData 未处理数据量
├─ 2. 按 clusterSize / shardIndex 计算分片 Segment（startId ~ endId）
├─ 3. 创建 PlanExecRecord（计划执行记录）
├─ 4. 创建 PlanDetailExecRecord（明细执行记录）
├─ 5. 创建 PlanPartitionTask / PlanDetailPartitionTask（分区任务）
│
▼
PlanPartitionTaskDriver ← exchange-business/core/lifecycle
│
├─ 遍历分区任务
├─ PlanPartitionTaskProcessor.process() ← 同步: SyncPlanPartitionTaskProcessor / 异步: 自定义
│ │
│ ├─ 按 cursor 游标分批拉取 SourceData
│ ├─ PortRequestProcessor / BatchPortRequestProcessor
│ │ └─ 调用供应商接口（复用同步单笔的 HTTP 通道）
│ ├─ PortResultConvertor 转换结果
│ ├─ ResultBatchSaveProcessor 批量写入 TargetData
│ └─ 更新游标 cursor / 分区状态
│
▼
PlanSegmentPersistence ← 持久化分段结果
│
▼
PartitionsAggregation ← 分区聚合
│
├─ 全部分区完成后
├─ 更新 PlanExecRecord / PlanDetailExecRecord 状态为 SUBMIT
│
▼
AsyncProcessor.afterProcess() ← 后续处理
│
├─ 友盟：AsyncFileProcessor（文件上传 OSS、CSV 读取、批量计算）
├─ 更新执行记录状态
└─ 事务保证（TransactionTemplate 编程式事务）
\```
### 数据库表流转
\```
tb_source_data ──分片──▶ tb_plan_exec_record ──▶ tb_plan_detail_exec_record
│ │
▼ ▼
tb_plan_partition_task ◀──▶ tb_plan_detail_partition_task
│
▼
tb_target_data（结果表）
│
tb_plan_file_record（文件记录，友盟异步）
tb_non_exist_data（不存在数据，布隆过滤）
tb_retry_data（重试数据）
\```
---
## 流程三：友盟文件批处理（异步增强）
\```
友盟供应商回调
│
▼
AsyncTaskBatchFetchProcessor.process() ← exchange-ext-youmeng
│
├─ 获取文件信息与解压密码
├─ 落库 PlanFileRecord
│
▼
AsyncReadTrigger.planFileExecute() ← CSV 读取触发
│
├─ CSVStreamReader 读取文件行
├─ YmLineDataProcessor 逐行处理
├─ 布隆过滤不存在数据（RedisBloomFilter）
├─ 批量写入 TargetData
│
▼
YmAsyncFileProcessor ← 文件后处理
│
├─ BatchComputeHelper 批量计算
├─ OSS 文件上传
├─ TimeoutJudeEventHandler 超时判定
└─ deleteFileSafely 清理本地文件
\```
---
## traceId 跨线程传播
\```
主线程
│ @MDC(types={TIMER, LOG}) → MDCAspect 注入 traceId
│
▼
ContextHolder / MDCTemplate
│ 捕获当前 traceId 上下文
│
▼
子线程（BatchExecutorTemplate / InfraExecutorFactory）
│ ContextHolder.runWithContext() 恢复 traceId
│
▼
日志关联查询：",start,parentTraceId=" 或 ",start,preTraceId="
\```3.6 docs/architecture/code-assets.md --- 代码资产清单
定位
记录项目中所有可复用的基类、接口和工厂。AI Agent 在设计文档生成阶段（Step 3）会查询此文件，决定新增类应该继承哪个基类。
必须包含的内容
| 资产类型 | 记录内容 |
|---|---|
| 基类/抽象类 | 类名、所属模块、职责、关键方法、子类列表 |
| 接口 | 接口名、所属模块、方法签名、实现类列表 |
| 工厂 | 工厂名、产出物、注册方式 |
| Manager 模式 | 模式 A / 模式 B 的选择决策树 |
编写要点
- 新建项目时此文件可能只有少量条目（甚至为空框架），随着代码积累逐步完善
- 使用表格格式，便于 AI Agent 结构化解析
- 每个 Manager 模式要给出选择依据（什么情况用模式 A，什么情况用模式 B）
实际示例
markdown
---
last_updated: 2026-06-24
status: active
owner: @zhangsan
---
# 代码资产清单
> **定位**：本文档列出项目中所有可复用的基类、接口、工厂和工具类，供 AI Agent 在技术设计阶段（prd-to-code Step 3）快速选择正确的继承/实现目标，避免临时探索代码。
> **维护规则**：新增基类/接口/工厂时必须同步更新本清单。
---
## 1. business/core --- 核心接口与抽象类
### 1.1 供应商适配器基类
| 类型 | 名称 | 路径 | 用途 | 选择条件 |
|------|------|------|------|---------|
| 接口 | `HttpResultParser` | exchange-business/base/ | HTTP 响应解析 | 新增供应商需要解析 HTTP 响应时实现 |
| 接口 | `PortResultConvertor` | exchange-business/core/sync/ | 端口结果转换 | 新增供应商需要转换结果数据时实现 |
| 接口 | `SupplierConvertor` | exchange-business/core/sync/ | 供应商转换器 | 需要统一供应商转换逻辑时实现 |
| 接口 | `PortRequestProcessor` | exchange-business/core/sync/ | 端口请求处理器 | 需要自定义请求发送逻辑时实现 |
| 抽象类 | `InputConvertor` | exchange-business/ext/ | 请求参数转换 | 新增供应商需要构造请求参数时继承 |
### 1.2 同步流程组件
| 类型 | 名称 | 路径 | 用途 |
|------|------|------|------|
| 类 | `HttpHandler` | core/sync/ | HTTP 调用处理器（封装 OkHttp3 调用） |
| 类 | `BatchPortRequestProcessor` | core/sync/ | 批量端口请求处理器 |
| 类 | `SyncPlanSegmentProcessor` | core/sync/ | 同步计划分段处理器 |
| 类 | `SyncPlanSegmentPersistence` | core/sync/ | 同步计划分段持久化 |
| 类 | `SyncPlanPartitionTaskProcessor` | core/sync/ | 同步计划分区任务处理器 |
| 类 | `ResultBatchSaveProcessor` | core/sync/ | 结果批量保存处理器 |
| 类 | `DefaultPlanDetailInitProcessor` | core/sync/ | 默认计划详情初始化处理器 |
### 1.3 策略类
| 类型 | 名称 | 路径 | 用途 |
|------|------|------|------|
| 类 | `HttpResultParserStrategy` | base/ | HTTP 结果解析策略（按 beanName 查找实现） |
| 类 | `PortResultConvertStrategy` | core/sync/ | 端口结果转换策略（按 beanName 查找实现） |
### 1.4 工厂类
| 类型 | 名称 | 路径 | 用途 |
|------|------|------|------|
| 类 | `PortConfigFactory` | core/model/config/factory/ | 端口配置工厂（按 portId 获取 PortConfig） |
| 类 | `PlanConfigFactory` | core/model/config/factory/ | 计划配置工厂（按 planId 获取 PlanConfig） |
| 类 | `AppConfigFactory` | core/model/config/factory/ | 应用配置工厂 |
| 类 | `PortRequestFactory` | core/model/factory/ | 端口请求工厂 |
| 类 | `PlanContextFactory` | core/model/factory/ | 计划上下文工厂 |
| 类 | `ScanContextFactory` | core/model/factory/ | 扫描上下文工厂 |
---
## 2. business/base --- 通用基础实现
| 类型 | 名称 | 路径 | 用途 |
|------|------|------|------|
| 类 | `HttpJsonPostRequestProcessor` | base/ | HTTP JSON POST 请求处理器（默认实现 PortRequestProcessor） |
| 类 | `HttpJsonPostReqConfig` | base/ | HTTP POST 请求配置 |
| 类 | `BeanUtils` | base/ | Bean 工具类（ApplicationContextAware） |
| 类 | `PhoneMd5Appender` | base/ | 手机号 MD5 追加器（实现 PlanRequestAppender） |
---
## 3. common/scheduler --- 调度框架基类
| 类型 | 名称 | 路径 | 用途 | 选择条件 |
|------|------|------|------|---------|
| 抽象类 | `BaseSchedulerCxtFactory<E,T>` | common/scheduler/ | 调度上下文工厂基类 | 新增调度任务时继承，实现 construct() 和 parser() |
| 抽象类 | `BaseScheduleContext<T>` | common/scheduler/model/ | 调度上下文基类 | 新增调度上下文时继承 |
| 类 | `BaseSchedulerConfig` | common/scheduler/model/ | 调度配置基类 | 新增调度配置时继承 |
| 接口 | `Trigger` | common/scheduler/ | 触发器接口 | 新增触发器时实现 |
| 类 | `SchedulerFactory` | common/scheduler/ | 调度工厂（XXL-JOB 集成） | 自动注册，无需继承 |
---
## 4. common/trace --- 链路追踪组件
| 类型 | 名称 | 路径 | 用途 |
|------|------|------|------|
| 类 | `MDCTemplate` | common/trace/ | MDC 操作模板（traceId 设置/清除/获取） |
| 类 | `ContextHolder` | common/trace/ | 线程上下文持有器（跨线程传递 traceId） |
| 类 | `ContextTaskDecorator` | common/trace/juc/ | 线程池任务装饰器（自动传递 traceId） |
| 类 | `DecoratorThreadPoolExecutor` | common/trace/juc/ | 装饰线程池（自动传递 traceId） |
| 类 | `MDCAspect` | common/trace/aspect/ | MDC 切面（@MDC 注解处理） |
| 类 | `TraceContextWrap` | common/trace/ | 追踪上下文包装器 |
---
## 5. common/juc --- 线程池组件
| 类型 | 名称 | 路径 | 用途 |
|------|------|------|------|
| 类 | `BatchExecutorTemplate` | common/juc/ | 批量执行模板 |
| 类 | `ThreadPoolExecutorBuilder` | common/juc/ | 线程池构建器 |
---
## 6. dal --- 数据访问层基类
### 6.1 Manager 接口
| 名称 | 用途 | 选择条件 |
|------|------|---------|
| `DalManager<T>` | 基础 Manager 接口（extends IService + BeanNameAware） | 所有 Manager 的根接口 |
| `TargetDataManager<T>` | 目标数据 Manager | 新增供应商目标数据表时实现 |
| `DefaultTargetDataManager` | 默认目标数据 Manager（TargetData 表） | 操作通用 tb_target_data 表时使用 |
| `SourceDataManager` | 源数据 Manager | 操作 tb_source_data 表时使用 |
| `PlanExecRecordManager` | 计划执行记录 Manager | 操作 tb_plan_exec_record 表时使用 |
| `PlanDetailExecRecordManager<T>` | 计划详情执行记录 Manager | 操作 tb_plan_detail_exec_record 表时使用 |
| `PlanPartitionTaskManager` | 计划分区任务 Manager | 操作 tb_plan_partition_task 表时使用 |
| `PlanDetailPartitionTaskManager` | 计划详情分区任务 Manager | 操作 tb_plan_detail_partition_task 表时使用 |
| `PlanFileRecordManager` | 计划文件记录 Manager | 操作 tb_plan_file_record 表时使用 |
| `NonExistDataManager` | 不存在数据 Manager | 操作 tb_non_exist_data 表时使用 |
| `RetryDataManager` | 重试数据 Manager | 操作 tb_retry_data 表时使用 |
### 6.2 Manager 实现模式
项目中存在两种 Manager 模式，根据是否需要 `DalManager.of(beanName)` 动态获取来选择：
#### 模式 A：DalManager（需动态获取时使用）
适用场景：计划执行、分区任务、目标数据等需要在 business 层通过 beanName 动态获取的 Manager。
\```
接口层: XxxManager extends DalManager<XxxEntity>
实现层: XxxManagerImpl extends BaseManager<XxxMapper, XxxEntity> implements XxxManager
获取方式: DalManager.of("xxxManagerImpl") 获取 Bean 实例
\```
实际使用：`PlanDetailPartitionTaskManager`、`PlanPartitionTaskManager`、`PlanDetailExecRecordManager`、`TargetDataManager`/`DefaultTargetDataManager`
#### 模式 B：IService（直接注入时使用）
适用场景：源数据、重试数据、文件记录等只需在固定代码中通过 @Resource 注入的简单 Manager。
\```
接口层: XxxManager extends IService<XxxEntity>
实现层: XxxManagerImpl extends ServiceImpl<XxxMapper, XxxEntity> implements XxxManager
获取方式: @Resource 注入
\```
实际使用：`SourceDataManager`、`RetryDataManager`、`PlanFileRecordManager`、`PlanExecRecordManager`、`NonExistDataManager`
#### 选择规则
| 条件 | 选择 |
|------|------|
| business 层需要通过 `DalManager.of("beanName")` 动态获取 | 模式 A（DalManager + BaseManager） |
| 仅需在固定代码中通过 `@Resource` 注入 | 模式 B（IService + ServiceImpl） |
| 不确定时默认 | 模式 B（更简单，后续如需动态获取再重构为模式 A） |
---
## 7. soa-service --- SOA 服务基类
| 类型 | 名称 | 路径 | 用途 | 选择条件 |
|------|------|------|------|---------|
| 类 | `SyncSingleService` | soa-service/ | 同步单笔服务（实现 SyncSingleRequestProvider） | 新增同步单笔查询接口时参考 |
| 类 | `SyncSingleQueryService` | soa-service/ | 同步查询服务（实现 SyncSingleRequestYmProvider） | 新增高并发查询接口时参考 |
| 类 | `QueryRateLimitDelegate` | soa-service/ | 查询限流委托（extends BaseRateLimitTemplate） | 新增限流查询时继承 |
| 类 | `HttpJsonPostRateLimitDelegate` | soa-service/ | HTTP POST 限流委托（extends BaseRateLimitTemplate） | 新增限流 HTTP 调用时继承 |
### SOA Service 实现模式
\```
1. exchange-api 定义 Provider 接口 + RequestDTO/ResponseDTO
2. exchange-soa-service 创建 Service 类 implements Provider 接口
3. @Slf4j + @Component + @MDC 注解
4. 参数校验 → 上下文构造 → 限流委托 → HTTP 调用 → 结果封装
5. exchange-deploy-set 修改 spring/spring-dubbo-provider.xml 注册 Dubbo 服务
\```
---
## 8. ext --- 供应商适配器参考实现
| 供应商 | 模块 | 关键类 | 参考场景 |
|--------|------|--------|---------|
| 天创 | exchange-ext-tianchuang | TCInputConvertor, TCHttpResultParser3605/3606, TCPortResultConvertor | 同步请求 + AES 加密 + MD5 签名 |
| 百行 | exchange-ext-baihang | BhInputConvertor, BhHttpResultParser, BhPortResultConvertor, BhTargetData | 征信数据 + 自有 Entity |
| 友盟 | exchange-ext-youmeng | YmContextRegister, YmPlanDetailInitProcessor, YmTaskFetchProcessor, YmAsyncFileProcessor | 异步文件批处理 + CSV + OSS |
### 新增供应商适配器选择条件
\```
PRD 要求同步请求 + 加密签名 → 参考 ext-tianchuang 模式
PRD 要求异步文件批处理 → 参考 ext-youmeng 模式
PRD 要求征信数据对接 → 参考 ext-baihang 模式
PRD 要求高并发实时查询 → 参考 SyncSingleQueryService + QueryRateLimitDelegate 模式
\```
---
## 9. 基类选择决策树
\```
PRD 需要新增什么？
│
├─ 新增数据库表/字段
│ └─ Entity extends BaseTargetData (或新建 Entity implements Serializable)
│ Mapper extends BaseMapper
│ Manager 接口:
│ ├─ 需 DalManager.of() 动态获取 → extends DalManager → Impl extends BaseManager (模式 A)
│ └─ 仅 @Resource 注入 → extends IService → Impl extends ServiceImpl (模式 B)
│ Mapper XML (如有自定义 SQL)
│
├─ 新增供应商适配器
│ ├─ 需要构造请求参数 → 继承 InputConvertor
│ ├─ 需要解析 HTTP 响应 → 实现 HttpResultParser
│ ├─ 需要转换结果数据 → 实现 PortResultConvertor
│ └─ 需要处理分区任务 → 实现 PlanPartitionTaskProcessor
│
├─ 新增 SOA 服务接口
│ ├─ 需要限流 → 继承 BaseRateLimitTemplate
│ ├─ 需要限流 + HTTP 调用 → 参考 HttpJsonPostRateLimitDelegate
│ └─ 需要限流 + 查询 → 参考 QueryRateLimitDelegate
│
├─ 新增调度任务
│ ├─ 上下文工厂 → 继承 BaseSchedulerCxtFactory
│ ├─ 调度上下文 → 继承 BaseScheduleContext
│ ├─ 调度配置 → 继承 BaseSchedulerConfig
│ └─ 触发器 → 实现 Trigger
│
├─ 新增 REST Controller
│ └─ 参考 add-api-endpoint.md 场景一
│
└─ 新增事件处理
└─ 实现 EventHandler<C, E>
\```4. 文档元信息规范
所有 .md 文件头部必须包含 YAML front matter：
yaml
---
last_updated: 2026-06-29
status: active # active | deprecated | draft
owner: @zhangsan
---| 字段 | 说明 | 为什么需要 |
|---|---|---|
last_updated |
最后更新日期，格式 YYYY-MM-DD | 文档健康度扫描时检测过期（>90天标记 stale） |
status |
active / draft / deprecated |
区分生效中、草稿、已废弃的文档 |
owner |
文档负责人 | 发现问题时知道找谁 |
过期检测规则（后续自动化层会用到）：
last_updated距今 > 90 天 → 标记为 stalelast_updated距今 > 180 天 → 标记为 criticalstatus: draft→ 标记为待发布owner缺失 → 标记为 orphan（无主文档）
5. 完成验证清单
完成本步后，逐项检查：
-
AGENTS.md存在，包含项目简介、技术栈基线（精确到版本号）、快速导航表、提交规范 -
README.md存在，包含模块拓扑图和环境准备说明 -
docs/architecture/overview.md存在，包含技术栈明细、模块全景、部署入口、核心流程 -
docs/architecture/boundaries.md存在，包含依赖方向图、各模块职责（含禁止项）、跨模块约束 -
docs/architecture/data-flow.md存在，包含每种核心流程的调用链路图 -
docs/architecture/code-assets.md存在（可为框架结构，随代码积累完善） - 所有
.md文件头部包含 YAML front matter（last_updated / status / owner） -
AGENTS.md的快速导航表中已注册本步创建的所有文档路径
6. 与下一步的衔接
本步建立了架构基线，定义了"模块怎么分层"和"依赖方向是什么"。下一步需要在此基础上编写 Rules 层（硬性约束）------将架构边界转化为 AI Agent 必须遵守的规则。
Step 1（本步） Step 2（下一步）
┌─────────────────┐ ┌─────────────────┐
│ AGENTS.md │ 定义约束 │ always-on.md │ ← 技术栈锁定
│ overview.md │ ──────────▶ │ agent-workflow │ ← 流程约束
│ boundaries.md │ 依赖方向 │ java-code-style │ ← 代码风格
│ data-flow.md │ 转化为规则 │ java-testing │ ← 测试规则
└─────────────────┘ └─────────────────┘衔接关系：
boundaries.md中的依赖方向图 →always-on.md第 2 节"模块依赖方向"overview.md中的技术栈 →always-on.md第 1 节"技术栈锁定"- 各模块的"禁止"项 →
always-on.md中对应的硬性约束 - 核心流程 →
agent-workflow.md中的强制流程顺序
说明
- 实际示例的格式是markdown格式，在示例中出现\符号是因为格式采用markdown编辑的，若不转译就会直接markdown格式断裂。使用时将\去掉即可