AI 协作文档使用指南
本文档是 15 AI + coord 使用
issues/目录体系的唯一指南。 关联：ai-allocation.md、matrix.md、coord.md
1. 目录结构
docs/architecture/issues/
├── README.md # 本文件（使用指南）
├── coord.md # coord 仲裁汇总
├── workline.md # 总工作安排（15 AI 甘特图）
├── matrix.md # 上下游对接总矩阵
├── objections/ # 各模块问题/异议（AI 提请，coord 仲裁）
│ ├── [模块名]_issue.md # 15 个模块各一个
│ └── cross_issue.md # 跨模块问题
├── worklines/ # 各模块工作排期（AI 自己写）
│ └── [模块名]_workline.md # 15 个模块各一个
└── contracts/ # 各模块对接契约（我提供什么 + 我消费什么）
└── [模块名]_contract.md # 15 个模块各一个
2. 三类文档职责
| 文档 | 位置 | 维护方 | 何时读 | 何时写 |
|---|---|---|---|---|
| contract.md | contracts/ |
各 AI 维护 | 开发前（了解上下游接口）+ 集成时（确认就绪信号） | 开发前（定义接口）+ 接口变更时 |
| workline.md | worklines/ |
各 AI 自己写 | 开发前（规划）+ coord 汇总时 | 开发前（规划全阶段）+ 进度更新时 |
| issue.md | objections/ |
各 AI 提请，coord 仲裁 | 遇到问题时 | 遇到问题追加条目 |
| coord.md | 根目录 | coord | 查仲裁结论 | coord 仲裁后写入 |
| matrix.md | 根目录 | coord | 查全局依赖 + 就绪信号 | coord 汇总 |
| workline.md | 根目录 | coord | 查总排期 | coord 汇总 |
3. 各 AI 必做清单（按顺序）
3.1 开发前（必做）
-
读自己的 contract.md：
contracts/[你的模块名]_contract.md- §1 我提供什么：明确自己要实现的接口
- §2 我消费什么：明确依赖哪些上游 + mock 策略
- §3 就绪信号：明确自己的就绪标志
-
读 matrix.md：了解全局依赖关系
- §1 服务依赖图：你在哪条链路上
- §7 Mock 策略汇总：你消费的上游用什么 mock
-
写自己的 workline.md：
worklines/[你的模块名]_workline.md- §2 全阶段甘特图：覆盖 P2-P6 所有任务
- §3 详细任务：每个阶段的交付物/依赖/验收标准
- §4 依赖与就绪信号
-
读 coord.md：查看是否有影响你的仲裁结论（ARB-XXX）
3.2 开发中
- 用 mock 开发：按 contract.md §4 的 mock 策略，消费上游 mock
- 遇到问题时：在
objections/[你的模块名]_issue.md追加条目 - 接口变更时：更新自己的
contracts/[你的模块名]_contract.md
3.3 开发完成后（必做）
- 更新 matrix.md §8 就绪信号跟踪表：将自己的状态从 ⏳ 改为 ✅
- 更新自己的 workline.md：标记任务完成
- 通知 coord：模块就绪，可合并到
release/integration集成
4. 全并行开发模式
核心原则：各 AI 一口气完成自己模块从 P2 到 P6 的所有代码，开发期间用 mock，最后统一集成测试。
各 AI 独立开发（全并行） coord 协调
│ │
读 contract.md 维护 proto 契约
写 workline.md 仲裁异议（objections/）
用 mock 开发 汇总就绪信号（matrix.md §8）
│ │
▼ ▼
交付：完整代码 + 就绪信号 交付：契约 + 仲裁 + 总矩阵
│ │
└────────► 统一集成测试 ◄──────┘
(release/integration)
4.1 Mock 策略（见 matrix.md §7）
| 消费方类型 | Mock 方式 | 切换真实时机 |
|---|---|---|
| gRPC 调用 | grpc-mock 拦截 + 固定 JSON | 上游就绪信号 ✅ |
| GraphQL 调用 | MSW 拦截 + 固定 response | BFF GraphQL 就绪 ✅ |
| Kafka 事件 | 本地 Kafka mock producer | 发布方就绪信号 ✅ |
| HTTP 调用 | MSW / fetch mock | 上游就绪 ✅ |
4.2 就绪信号（见 matrix.md §8）
每个 AI 完成后，在 matrix.md §8 将自己的状态改为 ✅：
| 模块 | 就绪信号 | 状态 |
|---|---|---|
| iam | gRPC 50052 + 12 RPC + HealthService SERVING | ⏳ → ✅ |
| api-gateway | :8080 可访问 + JWT 验签 | ⏳ → ✅ |
| ...（15 个模块） | ... | ⏳ → ✅ |
4.3 统一集成测试（见 matrix.md §9）
所有模块就绪后，按 matrix.md §9 检查清单进行集成测试：
- 认证链路（前端 → gateway → iam → JWT）
- GraphQL 链路（前端 → BFF → 业务服务 gRPC）
- 事件链路（业务服务 → Kafka → msg → push-gateway）
- MF 链路（Shell + Remote 加载）
- 推送链路（msg → push-gateway → WebSocket）
5. 遇到问题怎么办
5.1 问题类型与处理
| 问题类型 | 处理方式 |
|---|---|
| 上下游接口不明确 | 读对方 contract.md → 仍有疑问在 objections/cross_issue.md 追加 |
| 工作量过大 | 在 objections/[你的模块]_issue.md 追加，请求 coord 重新评估 |
| 前置依赖缺失 | 在 objections/[你的模块]_issue.md 追加，标注阻塞 |
| 编号冲突 | 在 objections/[你的模块]_issue.md 追加，标注冲突项 |
| 跨模块问题 | 在 objections/cross_issue.md 追加 |
5.2 issue 追加格式
### ISSUE-[编号]-[AI标识]：[标题]
- **提请方**：aiXX
- **日期**：YYYY-MM-DD
- **类型**：契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他
- **描述**：[详细描述问题]
- **建议方案**：[AI 的建议]
- **状态**：待 coord 仲裁
5.3 coord 仲裁流程
- 各 AI 在
objections/追加条目 - coord 审阅后，在
coord.md写入仲裁结论（ARB-XXX） - coord 在对应
objections/[模块名]_issue.md更新状态为"已裁决（见 coord.md §N）" - 相关 AI 按仲裁结论执行
6. 分支配合
| 分支 | 用途 |
|---|---|
feat/<module>-aiXX |
你的开发分支，所有提交在此 |
feat/coord-coord |
coord 维护契约/文档/共享包 |
release/integration |
集成测试，coord 合并各模块 |
规则：
- 你只能在
feat/<module>-aiXX分支上git add+git commit - 禁止
git checkout -b/git switch/git branch/git merge/git push origin main - 模块就绪后通知 coord，由 coord 合并到
release/integration
7. 各 AI 文件清单
| AI | contract.md | workline.md | issue.md |
|---|---|---|---|
| ai01 | api-gateway | api-gateway | api-gateway |
| ai02 | push-gateway | push-gateway | push-gateway |
| ai03 | teacher-bff | teacher-bff | teacher-bff |
| ai04 | student-bff | student-bff | student-bff |
| ai05 | parent-bff | parent-bff | parent-bff |
| ai06 | iam | iam | iam |
| ai08 | core-edu | core-edu | core-edu |
| ai09 | content | content | content |
| ai10 | msg | msg | msg |
| ai11 | data-ana | data-ana | data-ana |
| ai12 | ai | ai | ai |
| ai13 | teacher-portal | teacher-portal | teacher-portal |
| ai14 | student-portal | student-portal | student-portal |
| ai15 | parent-portal | parent-portal | parent-portal |
| ai16 | admin-portal | admin-portal | admin-portal |
跨模块问题：cross_issue.md
8. 快速开始（每个 AI 的第一步）
# 1. 切换到你的分支（由人类决策者创建，AI 只切换）
git checkout feat/<你的模块名>-aiXX
# 2. 读你的 contract.md（了解接口）
# 3. 读 matrix.md（了解全局依赖）
# 4. 读 coord.md（了解仲裁结论）
# 5. 写你的 workline.md（规划全阶段任务）
# 6. 开始用 mock 开发
# 7. 遇到问题在 objections/ 追加
# 8. 完成后在 matrix.md §8 更新就绪信号
# 9. 通知 coord 合并到 release/integration