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
@@ -15,13 +15,13 @@
|
||||
|
||||
### 核查矩阵
|
||||
|
||||
| 裁决编号 | 主题 | 裁决要求（摘要） | 02 文档现状 | 核查结论 | 状态 |
|
||||
| -------- | ---- | ---------------- | ----------- | -------- | ---- |
|
||||
| ISSUE-053 | Kafka topic 命名 | 02 §5.1 topic 改为 `edu.notification.requested`，禁止抽象名 `edu.*.events` | §5.1 仍写 `edu.notification.events` / `NotificationRequested` | ❌ 未回写 | 待 ai02 修复 |
|
||||
| ISSUE-055 | /readyz 软失败 | push-gateway /readyz 对 Kafka 软失败（失败仅告警 + `degraded: true` + 返 200，不返 503） | §6.7 仅 Redis PING 硬失败返 503，无 Kafka 软失败逻辑 | ❌ 未回写 | 待 ai02 修复 |
|
||||
| ISSUE-056 | 设计决策记录章节 | 02 §5.4 改名为"设计决策记录：gRPC vs HTTP 协议选型（coord 已采纳 P1）"，正文标注"coord 已采纳" | 02 无"设计决策记录"章节 | ❌ 未回写 | 待 ai02 修复 |
|
||||
| ISSUE-058 | Redis SET 启动重建 | 02 §3.1 补充"Hub 启动时遍历内存连接 SADD + EXPIRE 60s + 清空旧 instanceID 成员"；/readyz Redis 失败仅告警不阻塞；metrics 暴露 `push_gateway_redis_set_rebuild_total`；文档化 60s 不一致窗口 | §3.1/§8.4 仅描述运行期 SADD/SREM，无启动重建；§6.7 Redis 硬失败返 503（与"仅告警不阻塞"冲突）；无重建指标；无 60s 窗口说明 | ❌ 未回写 | 待 ai02 修复 |
|
||||
| ARB /internal/push 契约（§4.2） | 第一版 /internal/push 契约 | coord "as-is" 采纳 ai02 02 §4.2 作为第一版契约，仅在 ai10 异议时调整 | 02 §4.2 已定义 `{user_id, event, data, ttl?}` → `{success, delivered, online}` | ✅ 已落地 | 无需动作 |
|
||||
| 裁决编号 | 主题 | 裁决要求（摘要） | 02 文档现状 | 核查结论 | 状态 |
|
||||
| ------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | --------- | ------------ |
|
||||
| ISSUE-053 | Kafka topic 命名 | 02 §5.1 topic 改为 `edu.notification.requested`，禁止抽象名 `edu.*.events` | §5.1 仍写 `edu.notification.events` / `NotificationRequested` | ❌ 未回写 | 待 ai02 修复 |
|
||||
| ISSUE-055 | /readyz 软失败 | push-gateway /readyz 对 Kafka 软失败（失败仅告警 + `degraded: true` + 返 200，不返 503） | §6.7 仅 Redis PING 硬失败返 503，无 Kafka 软失败逻辑 | ❌ 未回写 | 待 ai02 修复 |
|
||||
| ISSUE-056 | 设计决策记录章节 | 02 §5.4 改名为"设计决策记录：gRPC vs HTTP 协议选型（coord 已采纳 P1）"，正文标注"coord 已采纳" | 02 无"设计决策记录"章节 | ❌ 未回写 | 待 ai02 修复 |
|
||||
| ISSUE-058 | Redis SET 启动重建 | 02 §3.1 补充"Hub 启动时遍历内存连接 SADD + EXPIRE 60s + 清空旧 instanceID 成员"；/readyz Redis 失败仅告警不阻塞；metrics 暴露 `push_gateway_redis_set_rebuild_total`；文档化 60s 不一致窗口 | §3.1/§8.4 仅描述运行期 SADD/SREM，无启动重建；§6.7 Redis 硬失败返 503（与"仅告警不阻塞"冲突）；无重建指标；无 60s 窗口说明 | ❌ 未回写 | 待 ai02 修复 |
|
||||
| ARB /internal/push 契约（§4.2） | 第一版 /internal/push 契约 | coord "as-is" 采纳 ai02 02 §4.2 作为第一版契约，仅在 ai10 异议时调整 | 02 §4.2 已定义 `{user_id, event, data, ttl?}` → `{success, delivered, online}` | ✅ 已落地 | 无需动作 |
|
||||
|
||||
### 核查结论
|
||||
|
||||
@@ -150,18 +150,34 @@
|
||||
|
||||
> 以下为 01-understanding.md 与现码不符的偏差，ai02 在批次 0 自主修复
|
||||
|
||||
| # | 位置 | 偏差 | 修复方向 |
|
||||
| - | ---- | ---- | -------- |
|
||||
| 1 | 01 §3.2 | `/readyz` 标"无（待实现）"，实际已实现（仅未检查 Redis） | 改为"已实现，仅返连接数，待补 Redis PING" |
|
||||
| 2 | 01 §3.2 | `/metrics` 标"无（待实现）"，实际已挂载 promhttp | 改为"已实现，待补自定义指标" |
|
||||
| 3 | 01 §3.2 | `/internal/push` `/internal/broadcast` 标"待补鉴权"，实际已实现 X-Internal-Key | 改为"已实现 X-Internal-Key 校验（DevMode 跳过）" |
|
||||
| 4 | 01 §6 + §7 | Dockerfile 标"❌ 单阶段"，实际为多阶段（缺非 root/healthcheck/ldflags） | 改为"⚠️ 多阶段但缺非 root + healthcheck + ldflags" |
|
||||
| 5 | 01 §7.1 #6 | 引用 `main.go L44-46` 行号过期，鉴权状态错误 | 更新行号并改为"已实现" |
|
||||
| 6 | 01 全文 | 未提及 SSE 端点（contract.md/matrix.md 列出但 02 建议不支持） | 待 ISSUE-001 仲裁后补充结论 |
|
||||
| 7 | 01 全文 | 未提及审计表（ai-allocation §5 设计重点） | 待 ISSUE-005 仲裁后补充 |
|
||||
| # | 位置 | 偏差 | 修复方向 |
|
||||
| --- | ---------- | ------------------------------------------------------------------------------ | -------------------------------------------------- |
|
||||
| 1 | 01 §3.2 | `/readyz` 标"无（待实现）"，实际已实现（仅未检查 Redis） | 改为"已实现，仅返连接数，待补 Redis PING" |
|
||||
| 2 | 01 §3.2 | `/metrics` 标"无（待实现）"，实际已挂载 promhttp | 改为"已实现，待补自定义指标" |
|
||||
| 3 | 01 §3.2 | `/internal/push` `/internal/broadcast` 标"待补鉴权"，实际已实现 X-Internal-Key | 改为"已实现 X-Internal-Key 校验（DevMode 跳过）" |
|
||||
| 4 | 01 §6 + §7 | Dockerfile 标"❌ 单阶段"，实际为多阶段（缺非 root/healthcheck/ldflags） | 改为"⚠️ 多阶段但缺非 root + healthcheck + ldflags" |
|
||||
| 5 | 01 §7.1 #6 | 引用 `main.go L44-46` 行号过期，鉴权状态错误 | 更新行号并改为"已实现" |
|
||||
| 6 | 01 全文 | 未提及 SSE 端点（contract.md/matrix.md 列出但 02 建议不支持） | 待 ISSUE-001 仲裁后补充结论 |
|
||||
| 7 | 01 全文 | 未提及审计表（ai-allocation §5 设计重点） | 待 ISSUE-005 仲裁后补充 |
|
||||
|
||||
---
|
||||
|
||||
## §3 历史问题
|
||||
|
||||
（暂无）
|
||||
|
||||
---
|
||||
|
||||
## §4 仲裁结论（coord，2026-07-10）
|
||||
|
||||
> 详见 [coord.md](../coord.md) §17 ARB-015
|
||||
|
||||
| ISSUE | 仲裁结论 | 状态 |
|
||||
| -------------------- | --------------------------------------------------------------- | --------------------- |
|
||||
| 001（SSE 端点） | ✅ 不支持 SSE，仅 WebSocket；coord 移除 contract/matrix 的 /sse | 已裁决（§17 ARB-015） |
|
||||
| 002（鉴权命名） | ✅ 统一 `X-Internal-Token` + `INTERNAL_API_TOKEN`（总裁 §7.2） | 已裁决（§17 ARB-015） |
|
||||
| 003（容量目标） | ✅ 统一 10w+（对齐 02 文档 + pending-features） | 已裁决（§17 ARB-015） |
|
||||
| 004（端点路径） | ✅ 统一 /internal/push（ai02 已自行修复） | 已裁决（§17 ARB-015） |
|
||||
| 005（审计表） | ✅ 方案 2：审计由 msg 维护，push-gateway 无 DB | 已裁决（§17 ARB-015） |
|
||||
| 006（Redis /readyz） | ✅ Redis 软失败（仅告警不阻塞，ISSUE-058 覆盖 ISSUE-055） | 已裁决（§17 ARB-015） |
|
||||
| 007（02 缺 ADR/NFR） | ✅ P5 批次 4 补全 02 §14-§17 四章节 | 已裁决（§17 ARB-015） |
|
||||
|
||||
Reference in New Issue
Block a user