docs(docs): 新增 AI 协作文档使用指南

docs/architecture/issues/README.md

@@ -0,0 +1,211 @@
+# 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
+```