xiner/Edu

Files

SpecialX faaaf29f67 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.设计规格文档

2026-07-10 12:58:22 +08:00

6.0 KiB

Raw Permalink Blame History

AI 协作文档体系重构设计

日期：2026-07-09 状态：已批准，已实现关联：president-final-rulings.md、ai-work-orchestration.md

1. 背景与问题

1.1 原始问题

Edu 项目有 16 个 AI 协作开发微服务架构。此前的协作文档存在两个核心问题：

issues.md 单文件多 AI 写入冲突：70+ 问题由多个 AI 追加到同一文件，导致编号严重冲突（ISSUE-024/025/028~~031/032~~036/044~048 多处重复），文件结构混乱（3 个 ## 2. 标题，章节标题与 issue 标题合并）。
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，最后统一集成测试。

工作流：

各 AI 读取自己的 contract.md 了解上下游接口
各 AI 在 workline.md 详细规划全阶段任务
开发期间消费上游的 mock（见 contract.md §4 mock 策略）
上游就绪后在 matrix.md §8 更新就绪信号
所有模块就绪后统一集成测试（见 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 模板结构

# [模块名] 对接契约

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

6.0 KiB Raw Permalink Blame History Unescape Escape