Edu/docs/architecture/issues

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 开发前（必做）

1. 读自己的 contract.md：contracts/[你的模块名]_contract.md

   • §1 我提供什么：明确自己要实现的接口
   • §2 我消费什么：明确依赖哪些上游 + mock 策略
   • §3 就绪信号：明确自己的就绪标志

2. 读 matrix.md：了解全局依赖关系

   • §1 服务依赖图：你在哪条链路上
   • §7 Mock 策略汇总：你消费的上游用什么 mock

3. 写自己的 workline.md：worklines/[你的模块名]_workline.md

   • §2 全阶段甘特图：覆盖 P2-P6 所有任务
   • §3 详细任务：每个阶段的交付物/依赖/验收标准
   • §4 依赖与就绪信号

4. 读 coord.md：查看是否有影响你的仲裁结论（ARB-XXX）

3.2 开发中

1. 用 mock 开发：按 contract.md §4 的 mock 策略，消费上游 mock
2. 遇到问题时：在 objections/[你的模块名]_issue.md 追加条目
3. 接口变更时：更新自己的 contracts/[你的模块名]_contract.md

3.3 开发完成后（必做）

1. 更新 matrix.md §8 就绪信号跟踪表：将自己的状态从 ⏳ 改为 ✅
2. 更新自己的 workline.md：标记任务完成
3. 通知 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 仲裁流程

1. 各 AI 在 objections/ 追加条目
2. coord 审阅后，在 coord.md 写入仲裁结论（ARB-XXX）
3. coord 在对应 objections/[模块名]_issue.md 更新状态为"已裁决（见 coord.md §N）"
4. 相关 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