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
@@ -10,15 +10,15 @@
|
||||
|
||||
> 任务要求：对已有的仲裁进行核查。coord.md 当前仅含 ARB-001 / ARB-002；另在 [port-allocation.md](../../../../infra/port-allocation.md) §7、coord-final-decisions.md、president-final-rulings.md 中存在涉及 ai 的历史仲裁。逐项核查如下。
|
||||
|
||||
| 仲裁编号 / 来源 | 主题 | 涉及 ai？ | 核查结论 | 状态 |
|
||||
| -------------------------- | ----------------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
|
||||
| ARB-001（coord.md §1） | teacher-bff GraphQL schema 第一版 | ❌ 否 | 与 ai 无关，不适用。 | — |
|
||||
| ARB-002（coord.md §2） | MF Shell 暴露清单 | ❌ 否 | 与 ai 无关，不适用。 | — |
|
||||
| port-allocation.md §7 | 50058 让给 ai（push-gateway 豁免 gRPC） | ✅ 是 | **仲裁有效**：port-allocation.md §3/§5 已登记 ai = HTTP 3008 / gRPC 50058。ai 的 01/02 文档已按 50058 设计，一致。**但 [matrix.md](../matrix.md) §2 gRPC 接口提供方矩阵、§8 就绪信号跟踪表仍写 50057，未同步** → 提请 coord 同步（见 ISSUE-01） | ⚠️ 仲裁有效但未同步 |
|
||||
| coord-final-decisions §1-§4 | iam P2 契约 / BFF 设计 / Gateway / content | ❌ 否 | 历史仲裁，与 ai 无直接约束。ai 仅消费 content/data-ana gRPC，需待其就绪。 | — |
|
||||
| president-final-rulings §2.3 | Temporal 用于 AI 编排 | ✅ 是 | **部分仲裁**：004 §2.3 列出 Temporal。ai12 已在 02-architecture-design.md §8.3 建议简单 4 步工作流用 BackgroundTasks + Redis，长运行评估 Temporal。需 coord 在 P6 决策点确认（见 ISSUE-06）。 | ⚠️ 部分仲裁 |
|
||||
| 01/02 文档引用"004 §7.2 已确认 topic edu.insight.ai.usage" | ai 用量事件 topic | ✅ 是 | **核查不通过**：grep 004 全文未发现 `ai.usage` / `insight.ai` / `AIUsage` 任何字样，004 §7.2 并未确认 ai 的 topic。该引用无法证实，topic 命名实际处于三义未决状态（见 ISSUE-02）。 | ❌ 引用失实 |
|
||||
| 01/02 文档引用"004 §1.2 端口矩阵 HTTP+10050 规则" | ai gRPC 端口推导规则 | ✅ 是 | **核查不通过**：004 全文无端口矩阵；`HTTP+10050` 公式不成立（3008+10050=13058≠50058）。端口唯一源是 port-allocation.md（顺序分配），ai=50058。ai 文档应改引 port-allocation.md。 | ❌ 引用失实 |
|
||||
| 仲裁编号 / 来源 | 主题 | 涉及 ai？ | 核查结论 | 状态 |
|
||||
| ---------------------------------------------------------- | ------------------------------------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
|
||||
| ARB-001（coord.md §1） | teacher-bff GraphQL schema 第一版 | ❌ 否 | 与 ai 无关，不适用。 | — |
|
||||
| ARB-002（coord.md §2） | MF Shell 暴露清单 | ❌ 否 | 与 ai 无关，不适用。 | — |
|
||||
| port-allocation.md §7 | 50058 让给 ai（push-gateway 豁免 gRPC） | ✅ 是 | **仲裁有效**：port-allocation.md §3/§5 已登记 ai = HTTP 3008 / gRPC 50058。ai 的 01/02 文档已按 50058 设计，一致。**但 [matrix.md](../matrix.md) §2 gRPC 接口提供方矩阵、§8 就绪信号跟踪表仍写 50057，未同步** → 提请 coord 同步（见 ISSUE-01） | ⚠️ 仲裁有效但未同步 |
|
||||
| coord-final-decisions §1-§4 | iam P2 契约 / BFF 设计 / Gateway / content | ❌ 否 | 历史仲裁，与 ai 无直接约束。ai 仅消费 content/data-ana gRPC，需待其就绪。 | — |
|
||||
| president-final-rulings §2.3 | Temporal 用于 AI 编排 | ✅ 是 | **部分仲裁**：004 §2.3 列出 Temporal。ai12 已在 02-architecture-design.md §8.3 建议简单 4 步工作流用 BackgroundTasks + Redis，长运行评估 Temporal。需 coord 在 P6 决策点确认（见 ISSUE-06）。 | ⚠️ 部分仲裁 |
|
||||
| 01/02 文档引用"004 §7.2 已确认 topic edu.insight.ai.usage" | ai 用量事件 topic | ✅ 是 | **核查不通过**：grep 004 全文未发现 `ai.usage` / `insight.ai` / `AIUsage` 任何字样，004 §7.2 并未确认 ai 的 topic。该引用无法证实，topic 命名实际处于三义未决状态（见 ISSUE-02）。 | ❌ 引用失实 |
|
||||
| 01/02 文档引用"004 §1.2 端口矩阵 HTTP+10050 规则" | ai gRPC 端口推导规则 | ✅ 是 | **核查不通过**：004 全文无端口矩阵；`HTTP+10050` 公式不成立（3008+10050=13058≠50058）。端口唯一源是 port-allocation.md（顺序分配），ai=50058。ai 文档应改引 port-allocation.md。 | ❌ 引用失实 |
|
||||
|
||||
**核查总结**：coord.md 现有 2 项仲裁（ARB-001/002）均与 ai 无关；涉及 ai 的真实仲裁在 port-allocation.md（50058 已定）与 004 §2.3（Temporal 部分仲裁）。ai 文档对"004 §7.2/§1.2"的两处引用失实，需修正引用源。
|
||||
|
||||
@@ -44,8 +44,9 @@
|
||||
- 01-understanding.md §3.2 / 02-architecture-design.md §5.2：`edu.insight.ai.usage`（自称"004 §7.2 已确认"，但 004 中不存在）
|
||||
- matrix.md §4 Kafka 事件发布方矩阵：`edu.ai.usage`，事件 `AIUsageEvent`
|
||||
- contracts/ai_contract.md §1.4：`edu.ai.usage.events`
|
||||
|
||||
|
||||
events.proto 现状无 `AIUsageEvent` message，004 无 topic 记录。三义导致 data-ana 消费方无法对齐。
|
||||
|
||||
- **建议方案**：ai12 建议采用 `edu.ai.usage`（与 matrix.md 一致，最简短，符合 `edu.<domain>.<action>` 简洁约定）。请 coord 裁定并在 004 §7.2 补登 + events.proto 补 `AIUsageEvent` message（schema 见 02-architecture-design.md §3.3）。ai12 据裁决同步 01/02 文档与 contract。
|
||||
- **状态**：待 coord 仲裁
|
||||
|
||||
@@ -58,8 +59,9 @@
|
||||
- 新增 RPC：`GenerateLessonPlan`、`StreamGenerateQuestion`（ai-allocation §5 "题目逐字生成"）
|
||||
- `GenerateQuestionRequest` 扩展字段：grade / knowledge_point_ids / question_type / count
|
||||
- `ChatRequest` 扩展可选字段：user_id / session_id / data_scope
|
||||
|
||||
|
||||
关于 RPC 总数存在分歧：matrix.md §2 与 contract 写 6 RPC；02-architecture-design.md §4.2 单方面扩到 8 RPC（追加 GetLessonPlanStatus / ConfirmLessonPlan）。需 coord 裁定 P5 目标 RPC 清单。
|
||||
|
||||
- **建议方案**：ai12 建议 P5 目标 6 RPC（Chat / StreamChat / GenerateQuestion / StreamGenerateQuestion / OptimizeExpression / GenerateLessonPlan）。备课工作流的"查询状态/确认入库"用 HTTP 端点（`GET /ai/v1/lesson/preparation/{id}` + `POST .../confirm`）实现，避免 RPC 膨胀；如 coord 认为查询/确认也需 gRPC，则定为 8 RPC。请 coord 在 P5 启动前升级 ai.proto 到 v1 完整版。
|
||||
- **状态**：待 coord 仲裁
|
||||
|
||||
@@ -83,7 +85,7 @@
|
||||
3. §1.4 topic `edu.ai.usage.events`（三义，见 ISSUE-02）
|
||||
4. §1.5 错误码示例 `AI_PROVIDER_UNAVAILABLE` / `AI_TOKEN_LIMIT_EXCEEDED` / `AI_CONTENT_FILTERED` 与 02-architecture-design.md §6.2 清单（`AI_LLM_UNAVAILABLE` / `AI_QUOTA_EXCEEDED` / `AI_CONTENT_MODERATION_REJECTED`）命名不一致
|
||||
5. §2.2 列出 ai 消费 2 个 content Kafka 事件，与 01/02 §5.1 "ai 不消费任何事件（无状态）"矛盾
|
||||
|
||||
|
||||
- **建议方案**：ai12 在本次工作中直接重写 contracts/ai_contract.md 对齐设计文档（端口 50058 / 补 HTTP 端点 / topic 待 ISSUE-02 裁决后填 / 错误码对齐 02 §6.2 / 删除消费事件或标注 P6+ 评估）。仅 RPC 数与 topic 命名待 coord 裁决后最终定稿。
|
||||
- **状态**：ai12 自纠中（依赖 ISSUE-01/02/03 裁决的字段待补）
|
||||
|
||||
@@ -121,7 +123,25 @@
|
||||
- **类型**：架构约束
|
||||
- **描述**：004 §11.5 强制响应信封为 ActionState（`{success, data, error:{code,message,details,traceId}}`）。ai 当前 main.py 违反：返回 `{success:true, data:..., degraded:false}` 顶层 degraded 字段（见 main.py:89/201-210/233-244）。01/02 文档已提请（A5），contracts 未记录。P5 实施必须整改。
|
||||
- **建议方案**：P5 实施时所有 HTTP 端点 + gRPC RPC 返回值改为 ActionState；degraded 作为 `error.details.degraded` 子字段。请 coord 在 known-issues §2.9 ai 分区记录此约束（01 文档已提请，需 coord 落地 known-issues）。
|
||||
- **状态**：待 coord 在 known-issues 记录约束（整改由 ai12 P5 执行）
|
||||
- **状态**：已裁决（见 [coord.md §12 ARB-010](../coord.md#12-arb-010ai-模块-9-项-issue-仲裁)）
|
||||
|
||||
---
|
||||
|
||||
## §1 仲裁结论（2026-07-10 coord）
|
||||
|
||||
> 详见 [coord.md §12 ARB-010](../coord.md#12-arb-010ai-模块-9-项-issue-仲裁)
|
||||
|
||||
| ISSUE | 仲裁结论 | 执行方 |
|
||||
| ----- | ---------------------------------------------------------------------- | ------------ |
|
||||
| 01 | ✅ 统一端口 50058；coord 修 matrix.md | coord |
|
||||
| 02 | ✅ 统一 `edu.ai.usage`（ARB-013） | coord |
|
||||
| 03 | ✅ P5 目标 6 RPC；备课状态查询/确认用 HTTP（ARB-012） | coord |
|
||||
| 04 | ✅ coord 补全 events.proto AIUsageEvent（ARB-011） | coord |
|
||||
| 05 | ✅ ai12 自纠重写 contract（端口 50058 / 补 HTTP / topic / 错误码对齐） | ai12 |
|
||||
| 06 | ✅ P5 用 BackgroundTasks + Redis；P6 评估 Temporal | ai12 + coord |
|
||||
| 07 | ✅ coord 批次 0 补全 iam.proto 12 RPC（ARB-007） | coord |
|
||||
| 08 | ✅ 统一 `next_edu_cloud.<domain>.v1`（ARB-011） | coord |
|
||||
| 09 | ✅ P5 强制整改 ActionState（degraded 移至 error.details） | ai12 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user