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

docs: ai 协作文档体系重构与多 ai 仲裁结果落地

Browse Source 
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
2026-07-10 12:58:22 +08:00
parent 2a2a56f541
commit faaaf29f67
120 changed files with 23201 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

268
docs/architecture/issues/workline.md Normal file
View File

@@ -0,0 +1,268 @@
# 总工作安排（coord 汇总）
> 维护者：coord（协调 AI）
> 维护规则：各 AI 在 `worklines/[模块名]_workline.md` 写入甘特图工作排期 → coord 汇总到本文件
> 模式：**全并行**（各 AI 一口气完成 P2-P6 全部代码，开发期间用 mock，最后统一集成测试）
> 关联文档：[ai-work-orchestration.md](../ai-work-orchestration.md)、[coord.md](./coord.md)、[matrix.md](./matrix.md)、[president-final-rulings.md](../president-final-rulings.md)
---
## §1 16 AI 总时间线（甘特图）
```mermaid
gantt
title Edu 项目 16 AI 功能时间线（总裁裁决 §6.1 最终版）
dateFormat YYYY-MM-DD
axisFormat %m-%d
section 批次0 coord前置 3-5天
coord 0.1-0.14 proto+工具包 :crit, b0, 2026-07-09, 4d
ai13 0.15 packages骨架 :b0a, 2026-07-09, 3d
section 批次1 P2 7-10天
ai01 Gateway路由+shared-go :b1a, after b0, 8d
ai06 iam P2.1 gRPC+8RPC :crit, b1b, after b0, 8d
ai03 teacher-bff GraphQL Must :b1c, after b0, 8d
ai13 teacher-portal P2 MF Shell :b1d, after b0, 8d
section 批次2 P3 7-10天
ai07 classes代码交接 :b2a, after b1b, 2d
ai08 core-edu gRPC 50053 :crit, b2b, after b1b, 8d
ai04 student-bff GraphQL :b2c, after b1c, 8d
ai14 student-portal P3 :b2d, after b1d, 8d
ai03 teacher-bff P3扩展 :b2e, after b1c, 5d
section 批次3 P4 10-12天
ai09 content gRPC 50054+Question :crit, b3a, after b2b, 11d
ai11 data-ana gRPC 50055 :b3b, after b2b, 11d
ai05 parent-bff GraphQL :b3c, after b2c, 11d
ai15 parent-portal P4 :b3d, after b2d, 11d
section 批次4 P5 12-15天
ai10 msg gRPC 50056 :crit, b4a, after b3a, 13d
ai02 push-gateway HTTP :b4b, after b3a, 13d
ai12 ai服务 gRPC 50058 :b4c, after b3a, 13d
ai03 teacher-bff P5扩展 :b4d, after b3a, 8d
section 批次5 P6 10-12天
ai16 admin-portal MVP :crit, b5a, after b4a, 11d
iam P2.2补全 :b5b, after b4a, 11d
持续优化 /readyz硬化 :b5c, after b4a, 11d
```
**关键路径**（红色 crit）：批次0 → iam P2.1 → core-edu → content → msg → admin-portal
**总时间线**：49-64 天（约 10-13 周）
---
## §2 批次概览
| 批次 | 阶段 | 时间 | 参与AI | 完成信号 |
| ---- | ---------- | -------- | ------------------------------------ | ------------------ |
| 0 | coord 前置 | 3-5 天 | coord + ai13 | ✅ 2026-07-09 完成 |
| 1 | P2 | 7-10 天 | ai01 + ai06 + ai03 ⟷ ai13 | ⏳ 进行中 |
| 2 | P3 | 7-10 天 | ai07 + ai08 + ai04 ⟷ ai14 + ai03扩展 | ⏳ |
| 3 | P4 | 10-12 天 | ai09 + ai11 + ai05 ⟷ ai15 | ⏳ |
| 4 | P5 | 12-15 天 | ai10 ⟷ ai02 + ai12 + ai03扩展 | ⏳ |
| 5 | P6 | 10-12 天 | ai16 + 持续优化 | ⏳ |
---
## §3 批次 1（P2）详细排期
### 3.1 总甘特图
```mermaid
gantt
title 批次 1（P2）详细排期
dateFormat YYYY-MM-DD
axisFormat %m-%d
section ai01 api-gateway
1.1 路由表+双入口+shared-go接入 :a1a, 2026-07-10, 3d
1.2 JWT校验+JWKS fetcher :a1b, after a1a, 3d
1.3 限流+熔断+CORS :a1c, after a1b, 2d
section ai06 iam P2.1
6.1 gRPC server 50052启用 :crit, a6a, 2026-07-10, 2d
6.2 8 RPC实现(Register-GetChildrenByParent) :crit, a6b, after a6a, 4d
6.3 /readyz深度(5依赖检查) :a6c, after a6b, 1d
6.4 iam_student_guardians表+DataScope :a6d, after a6b, 1d
section ai03 teacher-bff
3.1 GraphQL schema第一版(ARB-001) :crit, a3a, 2026-07-10, 2d
3.2 Yoga endpoint+5 Query Resolver :crit, a3b, after a3a, 3d
3.3 DataLoader+N+1防御 :a3c, after a3b, 1d
3.4 ActionState信封+降级模式B :a3d, after a3b, 1d
3.5 /readyz探针列表 :a3e, after a3d, 1d
section ai13 teacher-portal
13.1 MF Shell配置(exposes+shared) :crit, a13a, 2026-07-10, 2d
13.2 GraphQLProvider+urql client单例 :crit, a13b, after a13a, 2d
13.3 AppShell改造(REST→GraphQL) :a13c, after a13b, 2d
13.4 登录页+Dashboard页+班级列表页 :a13d, after a13c, 2d
```
### 3.2 依赖关系
```
ai06.6.1 gRPC 启用 ──┬──> ai03.3.2 GraphQL Resolver（调用 iam gRPC）
└──> ai01.1.2 JWT 校验（调用 iam GetPublicKey）
ai03.3.1 schema 第一版 ──> ai13.13.2 GraphQLProvider（消费 schema）
ai03.3.2 Resolver ────────> ai13.13.3 AppShell 改造（viewports query）
ai01.1.1 路由表 ──> ai03.3.2 endpoint 对外可访问
└──> ai13.13.4 页面可访问
```
### 3.3 完成信号
批次 1 完成的 5 个标志：
1. ai06：iam gRPC 50052 启用 + 12 RPC 全部实现 + /readyz 返回 5 项依赖状态
2. ai01：api-gateway 路由 `/api/v1/teacher/*` → teacher-bff:3003 + JWKS 验签 + 限流
3. ai03：teacher-bff `POST /graphql` 可用 + 5 Query Resolver + DataLoader + ActionState
4. ai13：teacher-portal MF Shell 配置就绪 + 登录/Dashboard/班级列表页可用
5. 端到端：教师登录 → 看到 Dashboard（含班级列表 + 视口导航）
---
## §4 各 AI 工作清单（汇总）
> 详细排期见各模块 `_workline.md` 文件
### 4.1 ai01（api-gateway）
- P2：路由表 + JWT RS256 验签（JWKS） + 限流 + 熔断 + CORS + shared-go 接入
- 详见：[api-gateway_workline.md](./api-gateway_workline.md)
### 4.2 ai02（push-gateway）
- P5：HTTP /internal/* + Kafka 双通道 + 多设备会话隔离 + 审计表
- 详见：[push-gateway_workline.md](./push-gateway_workline.md)
### 4.3 ai03（teacher-bff）
- P2：GraphQL schema 第一版 + 5 Query Resolver + DataLoader + ActionState
- P3 扩展：exams/homework/grades Query + Mutation
- P5 扩展：notifications Query + SSE
- 详见：[teacher-bff_workline.md](./teacher-bff_workline.md)
### 4.4 ai04（student-bff）
- P3：GraphQL schema + Dashboard + 考试作答 + 作业提交
- 详见：[student-bff_workline.md](./student-bff_workline.md)
### 4.5 ai05（parent-bff）
- P4：GraphQL schema + Dashboard + 多子女切换 + 成绩趋势
- 详见：[parent-bff_workline.md](./parent-bff_workline.md)
### 4.6 ai06（iam）
- P2.1：gRPC 50052 + 12 RPC + /readyz 深度 + iam_student_guardians + DataScope
- P2.2：P3-P6 期间持续补充
- 详见：[iam_workline.md](./iam_workline.md)
### 4.7 ai07（classes → core-edu 交接）
- P3：classes 代码交接 + core-edu 服务骨架
- 详见：[core-edu_workline.md](./core-edu_workline.md)
### 4.8 ai08（core-edu）
- P3：gRPC 50053 + exams/homework/grades/attendance/class 全部 RPC + Outbox
- 详见：[core-edu_workline.md](./core-edu_workline.md)
### 4.9 ai09（content）
- P4：gRPC 50054 + textbook/chapter/knowledge-graph/question 4 service + Neo4j + ES
- 详见：[content_workline.md](./content_workline.md)
### 4.10 ai10（msg）
- P5：gRPC 50056 + notification/preference/template 3 service + Outbox
- 详见：[msg_workline.md](./msg_workline.md)
### 4.11 ai11（data-ana）
- P4：gRPC 50055 + 4 Dashboard + Warning + Mastery + ClickHouse + CDC 消费
- 详见：[data-ana_workline.md](./data-ana_workline.md)
### 4.12 ai12（ai 服务）
- P5：gRPC 50058 + Chat/GenerateQuestion/OptimizeExpression/LessonPlan + ES 检索
- 详见：[ai_workline.md](./ai_workline.md)
### 4.13 ai13（teacher-portal）
- P2：MF Shell + AppShell + GraphQL client + 登录/Dashboard/班级列表
- P3：考试/作业/成绩页面 + MF Remote 就绪
- 详见：[teacher-portal_workline.md](./teacher-portal_workline.md)
### 4.14 ai14（student-portal）
- P3：MF Remote + 考试作答 + 作业提交
- 详见：[student-portal_workline.md](./student-portal_workline.md)
### 4.15 ai15（parent-portal）
- P4：MF Remote + Dashboard + 多子女切换
- 详见：[parent-portal_workline.md](./parent-portal_workline.md)
### 4.16 ai16（admin-portal）
- P6：MVP + 用户管理 + 角色权限 + 审计日志
- 详见：[admin-portal_workline.md](./admin-portal_workline.md)
---
## §5 工作流说明
### 5.1 各 AI 写入 `_workline.md`
各 AI 在自己模块的 `[模块名]_workline.md` 中写入甘特图排期，格式：
````markdown
# [模块名] 工作排期
## §1 总览
[模块职责简述]
## §2 甘特图
```mermaid
gantt
title [模块名] 工作排期
dateFormat YYYY-MM-DD
...
```
````
## §3 详细任务
### [阶段] [任务编号]：[任务名]
- 负责人：aiXX
- 依赖：[前置任务]
- 交付物：[具体文件/功能]
- 验收标准：[验收点]
```
### 5.2 coord 汇总
coord 审阅各 `_workline.md` 后，在本文件（workline.md）汇总：
- §1 总时间线（16 AI 甘特图）
- §2 批次概览
- §3 当前批次详细排期
- §4 各 AI 工作清单（链接到各 `_workline.md`）
### 5.3 更新时机
- 批次启动前：coord 写入 §3 当前批次详细排期
- 批次进行中：各 AI 更新自己的 `_workline.md`（标记完成进度）
- 批次完成后：coord 更新 §2 完成信号 + §1 总进度
```