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

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

Browse Source 
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
Download Patch File Download Diff File Expand all files Collapse all files

69
docs/architecture/issues/objections/data-ana_issue.md
View File

@@ -12,37 +12,37 @@
### 0.1 coord.md 仲裁核查
| 编号 | 主题 | 涉及 data-ana | 核查结论 |
| ------- | ---------------------------- | ------------- | ------------------------------ |
| ARB-001 | teacher-bff GraphQL schema | ❌ 否 | 不涉及，无需 action |
| ARB-002 | MF Shell 暴露清单 | ❌ 否 | 不涉及，无需 action |
| 编号 | 主题 | 涉及 data-ana | 核查结论 |
| ------- | -------------------------- | ------------- | ------------------- |
| ARB-001 | teacher-bff GraphQL schema | ❌ 否 | 不涉及，无需 action |
| ARB-002 | MF Shell 暴露清单 | ❌ 否 | 不涉及，无需 action |
**结论**：coord.md 无 data-ana 直接仲裁。
### 0.2 coord-cross-review.md 仲裁核查（8 项涉及 data-ana）
| # | 审查章节 | 裁决内容 | 责任方 | 核查结论 |
| -- | ---------------- | ------------------------------------------------------------------ | ------ | ---------------------------------------------------------------------------------------------------- |
| 1 | §2.2 #3 | iam 新增 `GetEffectiveDataScope` RPC，P4 补全，data-ana gRPC 调用 | iam | ⚠️ **未落实**：iam.proto 当前仅 4 RPC（Register/Login/RefreshToken/GetUserInfo），无 GetEffectiveDataScope |
| 2 | §2.3 P4 行 | content + data-ana P4 启用 gRPC server | ai11 | ⏳ 未到 P4 阶段，待执行 |
| 3 | §3.2 | 补登 `edu.insight.ai.usage` topic + events.proto 补 AIUsageEvent | coord | ⚠️ **未落实**：events.proto 当前仅 4 message（Class/Exam/Homework/GradeEvent），缺 AIUsageEvent |
| 4 | §3.3 | Python 服务 Outbox 豁免（MasteryUpdated / WarningTriggered） | coord | ✅ **已对齐**：01/02 文档已声明豁免，引用 coord-cross-review.md §3.3 |
| 5 | §4.3 | data-ana HTTP=3006 / gRPC=50055 | coord | ✅ **已对齐**：01/02 文档端口声明一致 |
| 6 | §5.3 | Python 服务信封改为 ActionState（degraded 放 details 子字段） | ai11 | ✅ **已对齐**：02 §4.3 ActionState 实现已修正，degraded 移至顶层 details |
| 7 | §6 #4 | 同 #6，ai06 修正 data-ana/ai 02 文档 + 代码 | ai11 | ✅ **已对齐（文档）**：02 已修正；代码待 P4 实现阶段重构 |
| 8 | §6 #7/#8/#9/#10 | coord 在 004 §7.2 补登 topic + §1.2 端口列 + §4.1 gRPC 矩阵 + §12.2 豁免 | coord | ⚠️ **未落实**：004 正文无 §4.2/§7.2 补登段/§11.4/§11.5，01/02 引用断裂已临时改为引 coord-cross-review.md |
| # | 审查章节 | 裁决内容 | 责任方 | 核查结论 |
| --- | --------------- | ------------------------------------------------------------------------ | ------ | ---------------------------------------------------------------------------------------------------------- |
| 1 | §2.2 #3 | iam 新增 `GetEffectiveDataScope` RPC，P4 补全，data-ana gRPC 调用 | iam | ⚠️ **未落实**：iam.proto 当前仅 4 RPC（Register/Login/RefreshToken/GetUserInfo），无 GetEffectiveDataScope |
| 2 | §2.3 P4 行 | content + data-ana P4 启用 gRPC server | ai11 | ⏳ 未到 P4 阶段，待执行 |
| 3 | §3.2 | 补登 `edu.insight.ai.usage` topic + events.proto 补 AIUsageEvent | coord | ⚠️ **未落实**：events.proto 当前仅 4 message（Class/Exam/Homework/GradeEvent），缺 AIUsageEvent |
| 4 | §3.3 | Python 服务 Outbox 豁免（MasteryUpdated / WarningTriggered） | coord | ✅ **已对齐**：01/02 文档已声明豁免，引用 coord-cross-review.md §3.3 |
| 5 | §4.3 | data-ana HTTP=3006 / gRPC=50055 | coord | ✅ **已对齐**：01/02 文档端口声明一致 |
| 6 | §5.3 | Python 服务信封改为 ActionState（degraded 放 details 子字段） | ai11 | ✅ **已对齐**：02 §4.3 ActionState 实现已修正，degraded 移至顶层 details |
| 7 | §6 #4 | 同 #6，ai06 修正 data-ana/ai 02 文档 + 代码 | ai11 | ✅ **已对齐（文档）**：02 已修正；代码待 P4 实现阶段重构 |
| 8 | §6 #7/#8/#9/#10 | coord 在 004 §7.2 补登 topic + §1.2 端口列 + §4.1 gRPC 矩阵 + §12.2 豁免 | coord | ⚠️ **未落实**：004 正文无 §4.2/§7.2 补登段/§11.4/§11.5，01/02 引用断裂已临时改为引 coord-cross-review.md |
### 0.3 coord-cross-review §8.2 批次 0 产出声明核查
coord-cross-review.md §8.2 声称批次 0 已完成 proto 补全，ai11 逐文件核查实际状态：
| 声明产出项 | 声明状态 | 实际文件状态（ai11 核查） | 核查结论 |
| -------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------- | ------------ |
| iam.proto 12 RPC | ✅ 12 RPC | **4 RPC**（Register/Login/RefreshToken/GetUserInfo） | ⚠️ 严重不符 |
| analytics.proto 扩展 | ✅ 12 RPC（含 Stream） | **3 RPC**（GetClassPerformance/GetStudentWeakness/GetLearningTrend） | ⚠️ 严重不符 |
| events.proto 补全 | ✅ 9 message（+AuditEvent） | **4 message**（ClassEvent/ExamEvent/HomeworkEvent/GradeEvent） | ⚠️ 严重不符 |
| core_edu.proto 补全 | ✅ 5 service | 未由 ai11 核查（非本模块边界） | — |
| buf.gen.yaml 插件 | ✅ go + python | 未由 ai11 核查（coord 维护） | — |
| 声明产出项 | 声明状态 | 实际文件状态（ai11 核查） | 核查结论 |
| -------------------- | --------------------------- | -------------------------------------------------------------------- | ----------- |
| iam.proto 12 RPC | ✅ 12 RPC | **4 RPC**（Register/Login/RefreshToken/GetUserInfo） | ⚠️ 严重不符 |
| analytics.proto 扩展 | ✅ 12 RPC（含 Stream） | **3 RPC**（GetClassPerformance/GetStudentWeakness/GetLearningTrend） | ⚠️ 严重不符 |
| events.proto 补全 | ✅ 9 message（+AuditEvent） | **4 message**（ClassEvent/ExamEvent/HomeworkEvent/GradeEvent） | ⚠️ 严重不符 |
| core_edu.proto 补全 | ✅ 5 service | 未由 ai11 核查（非本模块边界） | — |
| buf.gen.yaml 插件 | ✅ go + python | 未由 ai11 核查（coord 维护） | — |
> **核查说明**：ai11 仅核查与 data-ana 直接相关的 proto（iam/analytics/events）。§8.2 声明与实际文件严重不符，可能原因：(a) 声明为计划态但未执行；(b) 执行后未提交到本 worktree 分支；(c) 在其他分支已执行但未合并。无论哪种原因，data-ana 的 P4 实现依赖这些 proto 补全，当前实际状态构成 P4 阻塞。
@@ -95,6 +95,7 @@ coord-cross-review.md §8.2 声称批次 0 已完成 proto 补全，ai11 逐文
- #10：004 §12.2 补充派生数据事件 Outbox 豁免条款 → 004 §12.2 未补充
这导致 01-understanding.md 和 02-architecture-design.md 中引用 004 §4.2/§11.4/§11.5/§15.3 等章节均断裂（004 正文仅到 §14，§15 在 004-p6-addendum.md 但内容不同）。ai11 已在 v2.1 修订中临时改为引用 coord-cross-review.md 对应裁决章节，但这是过渡方案。
- **建议方案**：coord 按整改清单 #7/#8/#9/#10 补全 004 对应章节，使 004 成为可信的架构设计意图唯一源。各 AI 文档随后将引用从 coord-cross-review.md 回切到 004 对应章节。
- **状态**：待 coord 仲裁
@@ -107,13 +108,14 @@ coord-cross-review.md §8.2 声称批次 0 已完成 proto 补全，ai11 逐文
- **类型**：契约不明确
- **描述**：data-ana 发布的掌握度/预警事件 topic 命名在三个文档中不一致：
| 文档 | topic 命名 |
| -------------------------------------- | ------------------------------------- |
| 文档 | topic 命名 |
| ----------------------------------------------- | --------------------------------------------------------------- |
| 01-understanding.md / 02-architecture-design.md | `edu.insight.mastery.updated` + `edu.insight.warning.triggered` |
| matrix.md §4 | `edu.analytics.mastery` |
| contracts/data-ana_contract.md（修正前） | `edu.data_ana.mastery.events` |
| matrix.md §4 | `edu.analytics.mastery` |
| contracts/data-ana_contract.md（修正前） | `edu.data_ana.mastery.events` |
按 004 §7.2 命名规范 `edu.<domain>.<aggregate>.<action>`，data-ana 属于 D6 智能洞察领域（domain=insight），故 `edu.insight.mastery.updated` 符合规范。matrix.md 的 `edu.analytics.mastery` 不符合命名规范（缺 action 层级，且 domain 用了服务名而非领域名）。
- **建议方案**：coord 裁决统一为 `edu.insight.mastery.updated` + `edu.insight.warning.triggered`，coord 修正 matrix.md §4。ai11 已在 contract.md 中采用此命名。
- **状态**：待 coord 仲裁
@@ -126,4 +128,19 @@ coord-cross-review.md §8.2 声称批次 0 已完成 proto 补全，ai11 逐文
- **类型**：其他（声明与实际不符）
- **描述**：coord-cross-review.md §8.2 声称批次 0 已完成 iam.proto（12 RPC）/ analytics.proto（12 RPC）/ events.proto（9 message）补全，但 ai11 逐文件核查发现实际均未补全（详见 §0.3 核查表）。这影响所有依赖这些 proto 的下游 AI 的排期评估——若 AI 信任 §8.2 声明，会在排期中忽略 proto 补全的等待时间，导致排期失真。
- **建议方案**：coord 核实 §8.2 声明真实性。若实际已补全但未合并到各 worktree 分支，请协调合并；若实际未补全，请更新 §8.2 状态为"计划中"或"待执行"，并明确补全时间点，以便下游 AI 据此排期。
- **状态**：待 coord 仲裁
- **状态**：已裁决（见 [coord.md §11 ARB-009](../coord.md#11-arb-009data-ana-模块-6-项-issue-仲裁)）
---
## §2 仲裁结论（2026-07-10 coord）
> 详见 [coord.md §11 ARB-009](../coord.md#11-arb-009data-ana-模块-6-项-issue-仲裁)
| ISSUE | 仲裁结论 | 执行方 |
| ----- | ---------------------------------------------------------------------------------- | ------ |
| 001 | ✅ coord 批次 0 补全 iam.proto 12 RPC（ARB-007，含 GetEffectiveDataScope） | coord |
| 002 | ✅ coord 补全 events.proto AIUsageEvent（ARB-011） | coord |
| 003 | ✅ coord 批次 0 补全 analytics.proto 至 12 RPC（ARB-012） | coord |
| 004 | ✅ coord 补全 004 §7.2/§1.2/§4.1/§12.2 对应章节 | coord |
| 005 | ✅ 统一 `edu.insight.mastery.updated` + `edu.insight.warning.triggered`（ARB-013） | coord |
| 006 | ✅ coord 更正 coord-cross-review.md §8.2 状态为"待执行" | coord |