xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
SpecialX
2026-07-10 14:09:27 +08:00
parent 5144ec7292
commit 3852873964
1 changed files with 211 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

211
docs/architecture/issues/README.md Normal file
View File

@@ -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
```