# AI 协作文档使用指南

> 本文档是 15 AI + coord 使用 `issues/` 目录体系的唯一指南。
> 关联：[ai-allocation.md](../ai-allocation.md)、[matrix.md](./matrix.md)、[coord.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 追加格式

```markdown
### 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](./contracts/api-gateway_contract.md)       | [api-gateway](./worklines/api-gateway_workline.md)       | [api-gateway](./objections/api-gateway_issue.md)       |
| ai02 | [push-gateway](./contracts/push-gateway_contract.md)     | [push-gateway](./worklines/push-gateway_workline.md)     | [push-gateway](./objections/push-gateway_issue.md)     |
| ai03 | [teacher-bff](./contracts/teacher-bff_contract.md)       | [teacher-bff](./worklines/teacher-bff_workline.md)       | [teacher-bff](./objections/teacher-bff_issue.md)       |
| ai04 | [student-bff](./contracts/student-bff_contract.md)       | [student-bff](./worklines/student-bff_workline.md)       | [student-bff](./objections/student-bff_issue.md)       |
| ai05 | [parent-bff](./contracts/parent-bff_contract.md)         | [parent-bff](./worklines/parent-bff_workline.md)         | [parent-bff](./objections/parent-bff_issue.md)         |
| ai06 | [iam](./contracts/iam_contract.md)                       | [iam](./worklines/iam_workline.md)                       | [iam](./objections/iam_issue.md)                       |
| ai08 | [core-edu](./contracts/core-edu_contract.md)             | [core-edu](./worklines/core-edu_workline.md)             | [core-edu](./objections/core-edu_issue.md)             |
| ai09 | [content](./contracts/content_contract.md)               | [content](./worklines/content_workline.md)               | [content](./objections/content_issue.md)               |
| ai10 | [msg](./contracts/msg_contract.md)                       | [msg](./worklines/msg_workline.md)                       | [msg](./objections/msg_issue.md)                       |
| ai11 | [data-ana](./contracts/data-ana_contract.md)             | [data-ana](./worklines/data-ana_workline.md)             | [data-ana](./objections/data-ana_issue.md)             |
| ai12 | [ai](./contracts/ai_contract.md)                         | [ai](./worklines/ai_workline.md)                         | [ai](./objections/ai_issue.md)                         |
| ai13 | [teacher-portal](./contracts/teacher-portal_contract.md) | [teacher-portal](./worklines/teacher-portal_workline.md) | [teacher-portal](./objections/teacher-portal_issue.md) |
| ai14 | [student-portal](./contracts/student-portal_contract.md) | [student-portal](./worklines/student-portal_workline.md) | [student-portal](./objections/student-portal_issue.md) |
| ai15 | [parent-portal](./contracts/parent-portal_contract.md)   | [parent-portal](./worklines/parent-portal_workline.md)   | [parent-portal](./objections/parent-portal_issue.md)   |
| ai16 | [admin-portal](./contracts/admin-portal_contract.md)     | [admin-portal](./worklines/admin-portal_workline.md)     | [admin-portal](./objections/admin-portal_issue.md)     |

**跨模块问题**：[cross_issue.md](./objections/cross_issue.md)

---

## 8. 快速开始（每个 AI 的第一步）

```bash
# 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
```