# 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` 顶部有迁移说明