docs(docs): coord 完成 15 模块 issue 仲裁与基础设施同步

coord.md 新增 ARB-019/020/021 三章仲裁章节,修正 ARB-001。

- coord.md: 新增 ARB-019/020/021(student/parent/admin-portal 24 项)
- coord.md: 修正 ARB-001(admin P2 预留/schema 文件名/classes 数据源)
- 004 §4: 依赖图加 PBFF→DataAna+Msg
- 004 §7.2: push-gateway→Redis 软失败标注
- 004 §11.4: 错误码前缀矩阵(11 服务+i18n key)
- 004 §11.5: ActionState 信封规范(降级模式方案 B)
- matrix §1: 依赖矩阵加 PBFF 边
- matrix §2: 移除 api-gateway 为 iam gRPC 消费方
- matrix §4: admin-portal→teacher-bff
- matrix §5: 移除 /sse+鉴权头统一
- matrix §6: 错误码表补 i18n key 列
- 15 个 issue.md: 仲裁结论回写
- push-gateway_contract: 移除 /sse+鉴权头改 X-Internal-Token
- packages/contracts: 新建包 ADMIN_* 权限点常量

AI: coord
This commit is contained in:
SpecialX
2026-07-10 16:30:51 +08:00
parent df62ffc176
commit c179af64a6
22 changed files with 2320 additions and 382 deletions

View File

@@ -12,12 +12,12 @@
### 0.1 核查通过项(已正确执行)
| 仲裁 | 主题 | 核查结论 |
| --- | --- | --- |
| U2 | push-gateway 豁免 gRPCHTTP /internal/push | ✅ 02 §5.3/§7.1 已执行 HTTP 调用 push-gateway |
| C2 | 端口 3010不暴露 gRPC | ✅ 02 §7.2 + matrix.md §3 已执行 |
| C3 | core-edu 错误码 CORE_EDU_* | ✅ 02 §6.2 已执行 |
| C5 | Kafka topic edu.notification.sent/read/recalled/failed | ✅ 02 §5.2 已执行004 §7.2 同步属 coord 待办 #7,不阻塞 parent-bff |
| 仲裁 | 主题 | 核查结论 |
| ---- | ------------------------------------------------------ | --------------------------------------------------------------------- |
| U2 | push-gateway 豁免 gRPCHTTP /internal/push | ✅ 02 §5.3/§7.1 已执行 HTTP 调用 push-gateway |
| C2 | 端口 3010不暴露 gRPC | ✅ 02 §7.2 + matrix.md §3 已执行 |
| C3 | core-edu 错误码 CORE_EDU_* | ✅ 02 §6.2 已执行 |
| C5 | Kafka topic edu.notification.sent/read/recalled/failed | ✅ 02 §5.2 已执行004 §7.2 同步属 coord 待办 #7,不阻塞 parent-bff |
### 0.2 核查发现的问题(仲裁已裁决但文档未同步/执行有偏差)
@@ -48,7 +48,7 @@
- §3.1.1 Redis 缓存 Schema 表:写 "60s"coord 推断原值)
- §9 #2 ai05 review 结论:调整为 "30s + 主动失效"
- §13 #7 黄金模板对齐表:写 "30s"
§3.1.1 表格未同步 §9 的调整,导致同一文档内 60s 与 30s 并存。
§3.1.1 表格未同步 §9 的调整,导致同一文档内 60s 与 30s 并存。
- **建议方案**§3.1.1 表格 ChildGuard 行 TTL 改为 "30s",与 §9 #2 + §13 #7 一致
- **状态**:待 coord 仲裁ai05 建议直接修正,属于文档勘误)
@@ -73,7 +73,7 @@
- 004_architecture_impact_map.md §4 服务依赖图line 376-377仍只画 `PBFF --> IAM` + `PBFF --> CoreEdu`,未加 DataAna + Msg
- matrix.md §1 服务依赖矩阵line 64-65同样只画 `PBFF --> IAM` + `PBFF --> CORE`
- 02 §0.1 C6 行已标注 "004 §4 待 coord 同步更新",但至今未同步
此差异导致新接手的 AI 看 004/matrix 会误以为 parent-bff 不依赖 data-ana/msg与 02 设计冲突。
此差异导致新接手的 AI 看 004/matrix 会误以为 parent-bff 不依赖 data-ana/msg与 02 设计冲突。
- **建议方案**coord 在 004 §4 服务依赖图补 `PBFF --> DataAna` + `PBFF --> Msg`matrix.md §1 同步;更新 004 时按 project_rules §1 "改码必同步图" 执行
- **状态**:待 coord 仲裁
@@ -87,7 +87,7 @@
- parent-bff 02 §4.1 明确 "不实现 REST 业务端点(仅保留 /healthz /readyz /metrics"
- parent-portal §3.1 还引用 `GET /iam/effective-permissions`C4 仲裁已改为 `/iam/permissions/effective`
- parent-portal §3.1 标 "BFF 对接parent-bffai04 设计)"ai04 已过时(现 ai05
此冲突若不解决parent-portalai15会按 REST 实现 frontend client与 parent-bff GraphQL 端点不兼容。
此冲突若不解决parent-portalai15会按 REST 实现 frontend client与 parent-bff GraphQL 端点不兼容。
- **建议方案**coord 协调 ai15 将 parent-portal 01/02 文档的 parent-bff 消费契约从 REST 改为 GraphQL`POST /api/v1/parent/graphql`),同步 C4 iam 路径仲裁;此属跨模块契约,按 project_rules §14.4 跨模块变更顺序处理
- **状态**:待 coord 仲裁
@@ -101,7 +101,7 @@
- core_edu.proto: `package next_edu_cloud.core_edu.v1;`
- analytics.proto: `package next_edu_cloud.analytics.v1;`
- msg.proto: `package next_edu_cloud.msg.v1;`
引用不一致会导致 gRPC client 代码生成时 package 路径错误。
引用不一致会导致 gRPC client 代码生成时 package 路径错误。
- **建议方案**02 §3.3 DTO 映射表 proto message 列全部补 `next_edu_cloud.` 前缀;或确认是否统一去掉前缀(需 buf.yaml 配置一致)
- **状态**:待 coord 仲裁
@@ -165,6 +165,25 @@
---
## §3 仲裁结论coord2026-07-10
> 详见 [coord.md](../coord.md) §20 ARB-018
| ISSUE | 仲裁结论 | 状态 |
| ------------------------------------ | -------------------------------------------------------------------------------------------------- | --------------------- |
| 00101 文档未同步) | ✅ 01 作为阶段 1 历史快照保留原样,以 02 为准02 已执行 U3/U4/C1 | 已裁决§20 ARB-018 |
| 002ChildGuard TTL 不一致) | ✅ 统一为 30s§3.1.1 表格改为 30s对齐 §9 #2 + §13 #7 | 已裁决§20 ARB-018 |
| 003引用 I3 → I6 错误) | ✅ 修正为 I6 裁决coord-final-decisions §1 I6家长-学生关联) | 已裁决§20 ARB-018 |
| 004004 §4 依赖图未同步 C6 | ✅ coord 补全 004 §4 服务依赖图 + matrix.md §1 依赖矩阵(加 PBFF → DataAna + PBFF → Msg | 已裁决§20 ARB-018 |
| 005parent-portal REST vs GraphQL | ✅ coord 协调 ai15 将 parent-portal 01/02 改为 GraphQL 消费POST /api/v1/parent/v1/graphql | 已裁决§20 ARB-018 |
| 006proto 包名缺前缀) | ✅ 统一补 next_edu_cloud. 前缀ARB-011 已裁决) | 已裁决§20 ARB-018 |
| 007Notification.childId 缺失) | ✅ coord 协调 ai10 在 msg.proto Notification 补 child_id = 9 字段(可选) | 已裁决§20 ARB-018 |
| 008ClassService 缺失) | ✅ coord 已在 ARB-007 补全 ClassService 4 RPC02 §7.1 状态改 ✅ 已有Grade.score 转换规则补 §3.3 | 已裁决§20 ARB-018 |
| 009ai02→ai06 责任方过时) | ✅ 修正为 ai06iam 现归属 ai06ai-allocation §3.2 确认) | 已裁决§20 ARB-018 |
| 01002 缺 ADR/NFR | ✅ P6 硬化阶段补全(当前不阻塞 P4 实施) | 已裁决§20 ARB-018 |
---
<!--
追加条目格式: