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

docs: 文档体系修正 - 模块边界强化与按需阅读架构

Browse Source
This commit is contained in:
SpecialX
2026-07-10 13:33:31 +08:00
parent faaaf29f67
commit f15912c7ee
5 changed files with 594 additions and 918 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
docs/architecture/ai-allocation.md
View File

@@ -10,10 +10,10 @@
## 1. 外包总流程：三阶段
```
阶段 1：全局理解 阶段 2：模块架构设计 阶段 3：按图实施
阶段 1：模块理解 阶段 2：模块架构设计 阶段 3：按图实施
(每个 AI 独立) (每个 AI 独立) (并行开发)
│ │ │
阅读全局架构文档 产出模块内部架构图 按自己画的图写代码
按需阅读模块架构文档 产出模块内部架构图 按自己画的图写代码
理解边界与契约 定义内部模块/数据流 coord 定期巡检一致性
理解与其他模块的接口 标注与其他模块的交互点 遇到偏差更新架构图
│ │ │
@@ -21,8 +21,8 @@
交付：理解确认书 交付：模块架构设计文档 交付：代码 + 更新图
```
**阶段 1 目标**：每个 AI 读懂自己负责的模块在全局架构中的位置、边界、契约。
**阶段 2 目标**：每个 AI 产出自己模块的内部架构设计，经过 coord 交叉审查后放行。
**阶段 1 目标**：每个 AI 读懂自己负责的模块在架构中的位置、边界、契约（按需阅读，见 §4）。
**阶段 2 目标**：每个 AI 产出自己模块的内部架构设计，经过 coord 交叉审查后放行。
**阶段 3 目标**：按设计文档写代码，coord 定期巡检一致性。
---
@@ -92,30 +92,61 @@
---
## 4. 各 AI 阶段 1 必读文档清单
## 4. 各 AI 阶段 1 文档阅读清单（按需阅读）
以下为每个 AI 在阶段 1 必须按顺序阅读的文档（标注 ★ 为强制必读）：
> **架构文档按需阅读原则**（见 [project_rules §10](../../.trae/rules/project_rules.md) 与 [multi-ai-collaboration §2.2](../standards/multi-ai-collaboration.md)）：
>
> - **模块开发**：只读自己模块的架构与服务 README，不读其他模块内部实现
> - **全局工作**（coord、跨模块契约、基础设施、文档体系）：读全局架构文档
> - **功能开发/文档书写等强依赖场景**：必须读对应架构
> - **严格模块边界**：AI 只读自己负责模块的文档与源码，仅在确认跨模块契约时才读对方的对外接口（proto/API/事件），不读对方内部实现
| 顺序 | 文档 | ai01 | ai02 | ai03 | ai04 | ai05 | ai06 | ai07 | coord |
| ---- | ------------------------------------------------------------------- | :--: | :--: | :--: | :--: | :--: | :--: | :--: | :---: |
| 1 | [README.md](../../README.md) | ★ | ★ | ★ | ★ | ★ | ★ | ★ | ★ |
| 2 | [MIGRATION_GUIDE.md](../../MIGRATION_GUIDE.md) | ★ | ★ | ★ | ★ | ★ | ★ | ★ | ★ |
| 3 | [004 架构影响地图](./004_architecture_impact_map.md) | ★ | ★ | ★ | ★ | ★ | ★ | ★ | ★ |
| 4 | [pending-features.md](./roadmap/pending-features.md) | ★ | ★ | ★ | ★ | ★ | ★ | ★ | ★ |
| 5 | [project_rules.md](../../.trae/rules/project_rules.md) | ★ | ★ | ★ | ★ | ★ | ★ | ★ | ★ |
| 6 | [coding-standards.md](../standards/coding-standards.md) | ★ | ★ | ★ | ★ | ★ | ★ | ★ | ★ |
| 7 | [multi-ai-collaboration.md](../standards/multi-ai-collaboration.md) | ★ | ★ | ★ | ★ | ★ | ★ | ★ | ★ |
| 8 | 黄金模板 `services/classes/src/` 全部源码 | ★ | ★ | ★ | ★ | — | — | — | ★ |
| 9 | `packages/shared-proto/proto/` 全部 .proto | ★ | ★ | ★ | ★ | ★ | ★ | — | ★ |
### 4.1 全员必读（所有 AI，无论模块开发还是全局工作）
**语言特定补充阅读**：
| 顺序 | 文档 | 说明 |
| ---- | ------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| 1 | [project_rules.md](../../.trae/rules/project_rules.md) | 项目强制约束（架构规则、编码规范、提交规范、多 AI 协作、直接 push main） |
| 2 | [coding-standards.md](../standards/coding-standards.md) | 多语言编码标准 |
| 3 | [multi-ai-collaboration.md](../standards/multi-ai-collaboration.md) | 多 AI 协作指南（§2.1 严格模块边界、§2.2 按需阅读、§3 直接 push main） |
| AI | 语言 | 补充文档 |
| ------- | -------- | --------------------------------------------------------------- |
| ai01 | Go | `services/api-gateway/` 全部源码 |
| ai02-05 | TS | `services/iam/`、`services/teacher-bff/` 源码（参考已实现模板） |
| ai06 | Python | `services/data-ana/`、`services/ai/` 骨架源码 |
| ai07 | TS/React | `apps/teacher-portal/` 全部源码、Module Federation 配置 |
### 4.2 模块开发按需阅读（只读自己模块，禁止读其他模块内部实现）
| AI | 必读文档 | 说明 |
| ---- | ------------------------------------------------------------------------------------ | ------------------- |
| ai01 | `services/api-gateway/README.md`、`services/push-gateway/README.md`、004 §网关层章节 | Go 网关层架构 |
| ai02 | `services/iam/README.md`、004 §iam 章节 | 身份认证架构 |
| ai03 | `services/teacher-bff/README.md`、`services/core-edu/README.md`、004 §教学场景域章节 | 教学场景域架构 |
| ai04 | 004 §student-bff / parent-bff 章节（待建立服务，无 README） | 学习+家长场景域 BFF |
| ai05 | 004 §content / msg 章节（待建立服务，无 README） | 内容+通知架构 |
| ai06 | `services/data-ana/README.md`、`services/ai/README.md`、004 §数据分析/AI 章节 | Python 数据+AI 架构 |
| ai07 | `apps/teacher-portal/README.md`、004 §前端章节 | 前端 4 端架构 |
> **禁止越界阅读**：上表只列自己模块。如需确认与某模块的契约，走 §4.4 跨模块契约阅读，不读对方内部源码与 README。
### 4.3 全局工作必读（仅 coord，以及 AI 执行跨模块/全局任务时）
| 顺序 | 文档 | 说明 |
| ---- | --------------------------------------------------------- | ---------------------------------------------------- |
| 1 | [README.md](../../README.md) | 项目总览 |
| 2 | [MIGRATION_GUIDE.md](../../MIGRATION_GUIDE.md) | 迁移指南 |
| 3 | [004 架构影响地图](./004_architecture_impact_map.md) 全文 | 全局架构与依赖（coord 必读；模块开发只读 §4.2 章节） |
| 4 | [pending-features.md](./roadmap/pending-features.md) | 六阶段路线图 |
> 模块开发 AI **不需要**通读上述全局文档，仅在任务涉及跨模块协调、基础设施变更、文档体系维护时按需阅读。
### 4.4 跨模块契约按需阅读（仅涉及 proto 变更或确认接口时）
| 场景 | 必读文档 |
| ----------------------- | ----------------------------------------------------------------------------------------------------- |
| 修改/新增 proto message | `packages/shared-proto/proto/` 中**相关** .proto 文件（不读全部，只读变更涉及的文件） |
| 确认与其他模块的接口 | 004 §跨模块交互章节 + 对方服务的**对外接口**（proto / API 端点 / Kafka 事件名），**不读对方内部实现** |
### 4.5 黄金模板参考（仅 TS 服务首次实现新服务时）
| AI | 参考文档 |
| ------------------ | ---------------------------------------------------------------------------------- |
| ai02-05（TS 服务） | `services/classes/src/` 黄金模板源码（首次实现新服务时参考横切关注点，不强制全读） |
| ai01 / ai06 / ai07 | 按需参考 classes 的横切关注点实现模式（错误处理/可观测/健康检查等），不强制读源码 |
---
@@ -185,7 +216,7 @@
## 6. 阶段 1 交付物模板
每个 AI 阅读完 §4 的文档清单后，必须产出以下确认书：
每个 AI 按需阅读完 §4 对应文档后，必须产出以下确认书：
```markdown
## 模块理解确认书 — [模块名]