xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
dc0a6feec4389aee0316234224796b5840bb228e
Edu/docs/architecture/issues/README.md
SpecialX 3852873964 docs(docs): 新增 AI 协作文档使用指南
2026-07-10 14:09:27 +08:00

212 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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
```
Reference in New Issue View Git Blame Copy Permalink