docs: ai 协作文档体系重构与多 ai 仲裁结果落地
1.AI 协作文档体系重构(objections/worklines/contracts+matrix.md) 2.coord 仲裁文档(final-decisions/cross-review/final-rulings/orchestration) 3.各服务 01/02 文档补全 4.共享包初始化(shared-ts/shared-go/hooks/ui-components/ui-tokens) 5.Proto 契约补全 6.004 架构影响地图更新 7.端口分配表 8.设计规格文档
This commit is contained in:
SpecialX
@@ -0,0 +1,147 @@
|
||||
# AI 协作文档体系重构设计
|
||||
|
||||
> 日期：2026-07-09
|
||||
> 状态：已批准，已实现
|
||||
> 关联：[president-final-rulings.md](../../architecture/president-final-rulings.md)、[ai-work-orchestration.md](../../architecture/ai-work-orchestration.md)
|
||||
|
||||
---
|
||||
|
||||
## 1. 背景与问题
|
||||
|
||||
### 1.1 原始问题
|
||||
|
||||
Edu 项目有 16 个 AI 协作开发微服务架构。此前的协作文档存在两个核心问题：
|
||||
|
||||
1. **issues.md 单文件多 AI 写入冲突**：70+ 问题由多个 AI 追加到同一文件，导致编号严重冲突（ISSUE-024/025/028~~031/032~~036/044~048 多处重复），文件结构混乱（3 个 `## 2.` 标题，章节标题与 issue 标题合并）。
|
||||
|
||||
2. **coord 集中规划批次不符合全并行需求**：原模式按 6 批次串行推进（批次 0→1→2→...→5），各 AI 等待批次信号才能开始。用户决定改为**全并行模式**：各 AI 一口气完成自己模块从 P2 到 P6 的所有代码，开发期间用 mock，最后统一集成测试。
|
||||
|
||||
### 1.2 用户需求
|
||||
|
||||
- 模块问题和模块 workline 分子文件夹存放
|
||||
- coord 的 coord.md 和 workline.md 位置不变（留根目录）
|
||||
- workline 由各模块 AI 自己详细规划（不是 coord 规划）
|
||||
- 需要一份上下游对接契约文档，支持全并行开发期间用 mock
|
||||
|
||||
---
|
||||
|
||||
## 2. 设计方案
|
||||
|
||||
### 2.1 目录结构
|
||||
|
||||
```
|
||||
docs/architecture/issues/
|
||||
├── coord.md # coord 仲裁汇总（不变）
|
||||
├── workline.md # coord 总工作安排（不变）
|
||||
├── matrix.md # 新增：上下游对接总矩阵
|
||||
├── objections/ # 各模块问题/异议（AI 提请，coord 仲裁）
|
||||
│ ├── [模块名]_issue.md # 15 个模块各一个
|
||||
│ └── cross_issue.md # 跨模块问题
|
||||
├── worklines/ # 各模块工作排期（AI 自己写，覆盖 P2-P6 全阶段）
|
||||
│ └── [模块名]_workline.md # 15 个模块各一个
|
||||
└── contracts/ # 各模块对接契约（我提供什么 + 我消费什么 + mock 策略）
|
||||
└── [模块名]_contract.md # 15 个模块各一个
|
||||
```
|
||||
|
||||
**命名冲突解决**：外层文件夹保持 `issues/`（coord.md/workline.md 位置不变），内层"模块问题"子文件夹改名为 `objections/`（语义更准确：AI 提请的异议），避免 `issues/issues/` 路径。
|
||||
|
||||
### 2.2 三类文档职责
|
||||
|
||||
| 文档类型 | 子文件夹 | 维护方 | 内容 |
|
||||
| ---------------- | ------------- | ---------------------- | ---------------------------------------------- |
|
||||
| issue（异议） | `objections/` | 各 AI 提请，coord 仲裁 | 遇到问题时追加条目，coord 仲裁后更新状态 |
|
||||
| workline（排期） | `worklines/` | 各 AI 自己写 | 全阶段甘特图 + 详细任务 + 依赖与就绪信号 |
|
||||
| contract（契约） | `contracts/` | 各 AI 维护，coord 汇总 | 我提供什么 + 我消费什么 + mock 策略 + 就绪信号 |
|
||||
|
||||
**coord 根目录文件**：
|
||||
|
||||
- `coord.md`：coord 仲裁结果汇总（各 AI 提请异议后，coord 在此写入仲裁结论）
|
||||
- `workline.md`：coord 总工作安排（16 AI 甘特图 + 批次概览 + 各 AI 工作清单链接）
|
||||
- `matrix.md`：coord 汇总的上下游对接总矩阵（服务依赖图 + gRPC/GraphQL/Kafka/HTTP 矩阵 + mock 策略 + 就绪信号跟踪）
|
||||
|
||||
### 2.3 全并行开发模式
|
||||
|
||||
**核心原则**：各 AI 一口气完成自己模块从 P2 到 P6 的所有代码，开发期间用 mock，最后统一集成测试。
|
||||
|
||||
**工作流**：
|
||||
|
||||
1. 各 AI 读取自己的 `contract.md` 了解上下游接口
|
||||
2. 各 AI 在 `workline.md` 详细规划全阶段任务
|
||||
3. 开发期间消费上游的 mock（见 contract.md §4 mock 策略）
|
||||
4. 上游就绪后在 `matrix.md` §8 更新就绪信号
|
||||
5. 所有模块就绪后统一集成测试（见 matrix.md §9 检查清单）
|
||||
|
||||
**Mock 策略**（见 matrix.md §7）：
|
||||
|
||||
- gRPC 调用：grpc-mock 拦截 + 固定 JSON
|
||||
- GraphQL 调用：MSW 拦截 + 固定 response
|
||||
- Kafka 事件：本地 Kafka mock producer
|
||||
- HTTP 调用：MSW / fetch mock
|
||||
|
||||
### 2.4 contract.md 模板结构
|
||||
|
||||
```markdown
|
||||
# [模块名] 对接契约
|
||||
|
||||
## §1 我提供什么（对外接口）
|
||||
|
||||
- 1.1 gRPC 接口（如有）
|
||||
- 1.2 HTTP 端点（如有）
|
||||
- 1.3 GraphQL schema（如 BFF）
|
||||
- 1.4 Kafka 事件发布（如有）
|
||||
- 1.5 错误码前缀
|
||||
|
||||
## §2 我消费什么（依赖上游）
|
||||
|
||||
- 2.1 gRPC 调用（同步）+ mock 策略
|
||||
- 2.2 Kafka 事件订阅（异步）+ mock 策略
|
||||
- 2.3 HTTP 调用（如有）+ mock 策略
|
||||
|
||||
## §3 就绪信号
|
||||
|
||||
- 3.1 我依赖的上游就绪标志
|
||||
- 3.2 我的就绪标志（供下游消费）
|
||||
|
||||
## §4 Mock 策略
|
||||
|
||||
- 4.1 我提供的 mock
|
||||
- 4.2 我消费的 mock
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 实现清单
|
||||
|
||||
### 3.1 文件创建（共 48 个文件）
|
||||
|
||||
| 类型 | 数量 | 位置 |
|
||||
| ----------- | -------------------------- | ----------- |
|
||||
| contract.md | 15 | contracts/ |
|
||||
| workline.md | 15（4 个已有 + 11 个新建） | worklines/ |
|
||||
| issue.md | 16（15 模块 + 1 跨模块） | objections/ |
|
||||
| matrix.md | 1 | 根目录 |
|
||||
| **合计** | 47 + matrix.md = 48 | |
|
||||
|
||||
### 3.2 文件迁移
|
||||
|
||||
- 旧 `issues/[模块名]_workline.md`（4 个）→ 迁移到 `worklines/` 子文件夹，更新路径引用
|
||||
- 旧文件删除
|
||||
|
||||
### 3.3 文档更新
|
||||
|
||||
- `coord.md` §3：更新仲裁流程指向 `objections/` 子文件夹
|
||||
- `workline.md`：更新维护规则指向 `worklines/` 子文件夹 + 全并行模式说明
|
||||
- `issues.md`（旧）：添加迁移说明指向新流程
|
||||
- `ai-work-orchestration.md` §9.2：指向新流程
|
||||
|
||||
---
|
||||
|
||||
## 4. 验收标准
|
||||
|
||||
- [ ] `docs/architecture/issues/` 下有 3 个子文件夹（objections/ worklines/ contracts/）
|
||||
- [ ] 每个子文件夹有 15-16 个 `.md` 文件
|
||||
- [ ] `coord.md` 和 `workline.md` 在根目录
|
||||
- [ ] `matrix.md` 在根目录
|
||||
- [ ] 所有路径引用正确（`../coord.md` 而非 `./coord.md`）
|
||||
- [ ] 旧 `issues/[模块名]_workline.md` 文件已删除
|
||||
- [ ] `issues.md` 顶部有迁移说明
|
||||
Reference in New Issue
Block a user