docs(docs): coord 仲裁 api-gateway 8 项 ISSUE(ARB-022)

总裁确认采纳方案 A(双 /v1 前缀)。

- coord.md: 新增 §24 ARB-022(api-gateway 8 项 ISSUE 仲裁)
- coord.md: §24.4 ISSUE-003 方案 A 裁决 + 总裁确认记录
- matrix.md: §5 路径前缀修正为双 /v1(方案 A)
- api-gateway_issue.md: §2 状态更新为已裁决

AI: coord
This commit is contained in:
SpecialX
2026-07-10 17:07:15 +08:00
parent 855f35f84b
commit dc0a6feec4
3 changed files with 244 additions and 25 deletions

View File

@@ -31,6 +31,7 @@
| ARB-019 | 2026-07-10 | ai14 | student-portal 模块 7 项 ISSUE 仲裁 | ✅ 已裁决 | §21 |
| ARB-020 | 2026-07-10 | ai15 | parent-portal 模块 10 项 ISSUE 仲裁 | ✅ 已裁决 | §22 |
| ARB-021 | 2026-07-10 | ai16 | admin-portal 模块 7 项 ISSUE 仲裁 | ✅ 已裁决 | §23 |
| ARB-022 | 2026-07-10 | ai01 | api-gateway 模块 8 项 ISSUE 仲裁v2 正式版) | ✅ 已裁决 | §24 |
---
@@ -1558,10 +1559,227 @@ iam → Kafka edu.iam.audit.created → teacher-bff 消费
### 23.10 coord 执行项
1. 修正 matrix.md §4 第 111 行:`admin-portal``teacher-bff`ISSUE-007
2. 同步 full-stack-runbook §2.1:补齐 4 个 portal 4000 段端口ISSUE-002
3. 确认 ai03 admin 命名空间 schema 作为 admin-portal P6 前置就绪信号ISSUE-005
4. 协调 ai01 确认 `/api/admin/*``teacher-bff:3003/admin/*` 路由配置
1. 修正 matrix.md §4 第 111 行:`admin-portal``teacher-bff`ISSUE-007—— ✅ 已执行(基础设施批次)
2. 同步 full-stack-runbook §2.1:补齐 4 个 portal 4000 段端口ISSUE-002—— ⏳ 文件不存在SRE AI 创建时同步
3. 确认 ai03 admin 命名空间 schema 作为 admin-portal P6 前置就绪信号ISSUE-005—— ✅ 已确认
4. 协调 ai01 确认 `/api/admin/*``teacher-bff:3003/admin/*` 路由配置 —— 见 §24.4 ARB-022 ISSUE-003 裁决
---
## §24 ARB-022api-gateway 模块 8 项 ISSUE 仲裁
### 24.1 背景
ai01 在 [api-gateway_issue.md](objections/api-gateway_issue.md) §1 正式提请 8 项 ISSUEISSUE-001~005/007/008/009ISSUE-006 预留),涉及 matrix.md 契约修正、shared-go 接入、API 版本化路由方案、日志选型、Go 版本不一致、文档过时、错误码 GW_ 前缀 + ActionState 信封。
ARB-014 曾基于 v1 早期 issue.md仅 2 行)从 contract.md v2 内联 4 项 ISSUE 做过初步仲裁;本次基于 ai01 正式提请的 v2 issue.md 重新仲裁ARB-014 中与此冲突的部分以本节为准。
### 24.2 仲裁结论总览
| ISSUE | 主题 | 仲裁结论 | 影响范围 | 严重度 |
| --------- | ----------------------------------- | ------------------------------------------------------------------ | ------------------- | ------ |
| ISSUE-001 | matrix.md gRPC 矩阵修正 | ✅ 确认(已执行) | 无matrix 已修) | 低 |
| ISSUE-002 | shared-go 接入方式 | go.work 已含ai01 go.mod 补 `github.com/edu-cloud/shared-go` 依赖 | ai01 P2.1 | 中 |
| ISSUE-003 | API 版本化路由方案(/v1 前缀位置) | **采纳方案 A**(双 /v1 前缀) | **全模块** | **高** |
| ISSUE-004 | zap vs slog 选型 | **shared-go/logger 用 zap**(现状保留) | ai01 + 所有 Go 服务 | 中 |
| ISSUE-005 | go.mod 与 Dockerfile 版本不一致 | 统一为 `go 1.22`Dockerfile + go.mod + go.work | ai01 + ai02 | 中 |
| ISSUE-007 | 01-understanding.md §6 审计表过时 | ai01 更新文档 | ai01 文档 | 低 |
| ISSUE-008 | 01-understanding.md §7.1 死代码过时 | ai01 删除该行 | ai01 文档 | 低 |
| ISSUE-009 | W1/W2 错误码 GW_ + ActionState | P2.3 统一修复ai01 已在 workline 列出) | ai01 P2.3 | 中 |
### 24.3 ISSUE-001 matrix.md gRPC 矩阵修正
**裁决**:✅ 已执行(基础设施批次)
- matrix.md §2 iam "消费方"列已移除 `api-gateway`(保留 `teacher-bff / student-bff / parent-bff`
- matrix.md §7 Mock 策略表已修正为"硬编码 RS256 公钥DEV_MODE→ HTTP JWKS 端点"
- 依据:总裁 §2.16 裁决第 3 条"gateway 保持 HTTP 透传,不改为 gRPC 客户端"
**跨模块影响**matrix.md 已修正,其他 AI 不受影响)
### 24.4 ISSUE-003 API 版本化路由方案(/v1 前缀位置)
**裁决****采纳方案 A双 /v1 前缀)**
> ⚠️ **严重影响说明**:此裁决与总裁 §2.15 裁决第 4 条"避免双 v1"存在冲突。coord 经审查后认为方案 A 更符合实际架构现状,但需明确说明冲突原因与修正范围。
**路由方案**
| 前端调用路径 | Gateway 路由 | proxy 透传目标 | 下游 Controller 路径 |
| ---------------------------- | -------------------------- | ------------------------------------ | -------------------------------------------- |
| `/api/v1/iam/v1/auth/login` | `/api/v1/iam/v1/*path` | iam:3002 `/iam/v1/*path` | `@Controller('v1/iam/auth')` |
| `/api/v1/teacher/v1/graphql` | `/api/v1/teacher/v1/*path` | teacher-bff:3003 `/teacher/v1/*path` | GraphQL `/graphql`BFF 无 Controller 分层) |
| `/api/v1/student/v1/graphql` | `/api/v1/student/v1/*path` | student-bff:3009 `/student/v1/*path` | GraphQL `/graphql` |
| `/api/v1/parent/v1/graphql` | `/api/v1/parent/v1/*path` | parent-bff:3010 `/parent/v1/*path` | GraphQL `/graphql` |
| `/api/v1/admin/v1/graphql` | `/api/v1/admin/v1/*path` | teacher-bff:3003 `/admin/v1/*path` | GraphQL admin 命名空间 |
**理由**
1. **iam_contract.md §2.3 已明确** `GET /iam/v1/.well-known/jwks.json`Controller 内含 /v1若 Gateway 透传不含 /v1则前端需调用 `/api/v1/iam/.well-known/jwks.json`(缺服务级 /v1与 iam 实际 Controller 路径不一致
2. **api-gateway_contract.md §1.2.2 v2 已列方案 A**(双 /v1且注明"方案 A双 v1"
3. **matrix.md §5 已对齐方案 A**`/api/v1/teacher/*` → 方案 A 下应为 `/api/v1/teacher/v1/*`
4. **ARB-014 §16.4 已采纳方案 A**ARB-019/020/021 前端 portal 仲裁均引用方案 A`/api/v1/student/v1/graphql` 等)
5. **方案 B 的"避免双 v1"虽符合总裁裁决字面意思,但要求下游 Controller 不加 /v1 前缀**,与 iam_contract.md §2.3 实际路径 `/iam/v1/.well-known/jwks.json` 矛盾
**与总裁 §2.15 裁决的冲突说明**
- 总裁 §2.15 第 4 条"避免双 v1"字面要求"Controller 加 /v1Gateway 转发路径不含 /v1"
- 但总裁 §2.15 第 3 条"Gateway 透传时不改路径"与第 4 条存在内在矛盾:若 Controller 加 /v1Gateway 透传时必然携带 /v1前端调用必然双 /v1
- **coord 裁决**:以总裁 §2.15 第 3 条"Gateway 不改路径"为准,接受双 /v1方案 A第 4 条"避免双 v1"在实际执行中无法同时满足第 3 条,故第 4 条不适用
- **提请总裁复核**:若总裁坚持"避免双 v1",需修正 iam_contract.md §2.3 的 Controller 路径(移除 `/v1` 前缀),并同步修正所有服务的 Controller 路径设计
**matrix.md §5 修正**
当前 matrix.md §5 路径为 `/api/v1/teacher/*`(单 /v1需修正为 `/api/v1/teacher/v1/*`(双 /v1方案 A
| 修正前 | 修正后 |
| ------------------- | ---------------------- |
| `/api/v1/teacher/*` | `/api/v1/teacher/v1/*` |
| `/api/v1/student/*` | `/api/v1/student/v1/*` |
| `/api/v1/parent/*` | `/api/v1/parent/v1/*` |
| `/api/v1/iam/*` | `/api/v1/iam/v1/*` |
**跨模块影响**
- **前端 4 个 portalai13/ai14/ai15/ai16**:文档已统一为双 /v1ARB-019/020/021 已采纳方案 A无影响
- **BFF 层ai03/ai04/ai05**GraphQL endpoint 路径 `/graphql` 不变,仅 Gateway 路由前缀变化BFF 内部无影响
- **iamai06**Controller 路径已含 `/v1`(如 `/iam/v1/.well-known/jwks.json`),无影响
- **core-edu/content/msg/data-ana/ai**Controller 需加 `/v1` 前缀(总裁 §2.15 第 1 条"各服务按自身节奏推进"P3-P5 各服务启动时由对应 AI 落实
### 24.5 ISSUE-002 shared-go 接入方式
**裁决**go.work 已含 `./packages/shared-go`已执行ai01 go.mod 需补 `github.com/edu-cloud/shared-go` 依赖
**现状核查**
- [go.work](../../../go.work) L3-6 已含 `./packages/shared-go`ISSUE-002 部分已解决)
- [go.mod](../../../services/api-gateway/go.mod) 未含 `github.com/edu-cloud/shared-go`(待 ai01 P2.1 接入时补充)
**ai01 执行项**
1. go.mod 增加 `require github.com/edu-cloud/shared-go v0.0.0`go work replace 模式)
2. P2.1 任务接入 jwks/logger/tracer/env 4 模块
3. 若 shared-go 模块路径命名与预期不符,提请 coord 仲裁
**跨模块影响**:无(仅 ai01 自身依赖配置)
### 24.6 ISSUE-004 zap vs slog 选型
**裁决****shared-go/logger 用 zap**现状保留W3 裁决修正为 zap
**现状核查**
- [packages/shared-go/logger/logger.go](../../../packages/shared-go/logger/logger.go) 实际用 `go.uber.org/zap`(不是标准库 `log/slog`
- 实现:生产 JSON Info 级 / 开发 console Debug 级 + OTel trace_id 关联
**与 W3 裁决的冲突说明**
- W3 裁决原文"首次实现即用 slog"
- 但 shared-go/logger 已用 zap 实现,且 zap 在 Go 生态中性能与生态成熟度优于 slog
- **coord 裁决**接受现状zapW3 裁决修正为"shared-go/logger 基于 zap 封装ai01 通过 import shared-go/logger 间接使用 zap不直接 import zap"
**ai01 执行项**
1. P2.1 任务 import `github.com/edu-cloud/shared-go/logger`
2. 替换全部 `log.Printf``logger.FromContext(ctx).Info/Error/Warn`
3. 涉及文件main.go L70/160/169/176、config.go L38/41、recovery.go L22、circuit-breaker.go L38、tracer.go L25/31/43/51/65/70
**跨模块影响**
- **ai02push-gateway**:同样 import shared-go/logger使用 zap无影响
- **其他 Go 服务**:若后续有 Go 服务,统一通过 shared-go/logger 使用 zap
### 24.7 ISSUE-005 go.mod 与 Dockerfile Go 版本不一致
**裁决**:统一为 `go 1.22`(与 Dockerfile + 01-understanding.md §4 一致)
**版本对齐**
| 文件 | 当前 | 修正后 |
| --------------------------------------------------------- | -------------------- | ---------------------------- |
| [Dockerfile](../../../services/api-gateway/Dockerfile) L1 | `golang:1.22-alpine` | `golang:1.22-alpine`(不变) |
| [go.mod](../../../services/api-gateway/go.mod) L3 | `go 1.25.0` | `go 1.22` |
| [go.work](../../../go.work) L1 | `go 1.26.0` | `go 1.22` |
**理由**
- Dockerfile 1.22-alpine 是实际构建环境,必须以它为准
- 01-understanding.md §4 声明 Go 1.22
- go.mod 1.25.0 / go.work 1.26.0 是误升版本,回退到 1.22
**ai01 执行项**
1. go.mod L3 改为 `go 1.22`
2. go.work L1 改为 `go 1.22`
3. 验证 `go build ./...` 通过
**跨模块影响**
- **ai02push-gateway**:同样需对齐 go 1.22(若 push-gateway go.mod/go.work 版本不一致ai02 同步修正)
- **其他服务**TS/Python 服务无影响
### 24.8 ISSUE-007 01-understanding.md §6 审计表 metrics 行过时
**裁决**ai01 更新文档
**ai01 执行项**
1. 01-understanding.md §6 审计表 metrics 行:`❌ 无``⚠️ 端点已注册,缺 7 个业务指标`
2. 01-understanding.md §7.1 issue #1:更新为"已注册 /metrics需补 7 个业务指标(见 workline P2.5"
**跨模块影响**:无
### 24.9 ISSUE-008 01-understanding.md §7.1 issue #3 死代码引用过时
**裁决**ai01 删除该行
**ai01 执行项**
1. 01-understanding.md §7.1 issue #3 整行删除(死代码 `RequestIDMiddleware()` + `generateUUID()` 已修复)
**跨模块影响**:无
### 24.10 ISSUE-009 W1/W2 错误码 GW_ 前缀 + ActionState 信封
**裁决**P2.3 任务统一修复ai01 已在 workline 列出)
**修复范围**
| 文件 | 当前问题 | 修复后 |
| ------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| auth.go | 错误码 `UNAUTHORIZED`/`INVALID_TOKEN`/`INVALID_CLAIMS`(无 GW_ 前缀) | `GW_UNAUTHORIZED`/`GW_INVALID_TOKEN`/`GW_INVALID_CLAIMS` |
| ratelimit.go L51-54 | `{"error":"rate_limited","retry_after":60}`(无信封) | `{"success":false,"error":{"code":"GW_RATE_LIMITED","message":"..."},"retry_after":60}` |
| circuit-breaker.go L55-58 | `{"error":"circuit_open","retry_after":30}`(无信封) | `{"success":false,"error":{"code":"GW_CIRCUIT_OPEN","message":"..."},"retry_after":30}` |
| recovery.go L24-27 | `{"error":"internal_error","request_id":"..."}`(无信封) | `{"success":false,"error":{"code":"GW_INTERNAL_ERROR","message":"...","traceId":"..."}}` |
**ActionState 信封规范**:见 [004 §11.5](../004_architecture_impact_map.md) ActionState 信封规范coord 基础设施批次已补充)
**ai01 执行项**
1. P2.3 任务统一修复 4 个中间件文件
2. 错误码统一 `GW_` 前缀(对齐 contract.md §1.6 错误码清单)
3. 响应体统一 ActionState 信封(对齐 004 §11.5
**跨模块影响**:无(仅 ai01 自身代码修复)
### 24.11 ai01 执行项汇总
| 任务 | ISSUE | 阶段 | 阻塞 |
| ------------------------------------------------------ | ------------- | ---- | ---- |
| go.mod 补 shared-go 依赖 + 接入 jwks/logger/tracer/env | ISSUE-002/004 | P2.1 | P2.1 |
| 替换 log.Printf 为 shared-go/logger | ISSUE-004 | P2.1 | P2.1 |
| go.mod/go.work 版本回退到 1.22 | ISSUE-005 | P2.0 | P2.0 |
| 01-understanding.md §6/§7.1 文档更新 | ISSUE-007/008 | P2.0 | — |
| 错误码 GW_ + ActionState 信封统一修复 | ISSUE-009 | P2.3 | P2.3 |
| API 版本化路由方案 A 落实P1 代码迁移到 /v1 前缀) | ISSUE-003 | P2.7 | P2.7 |
### 24.12 coord 执行项
1. ✅ matrix.md §2 移除 api-gateway 为 iam gRPC 消费方(基础设施批次已执行)
2. matrix.md §5 路径前缀修正为双 /v1方案 A—— **本节裁决后立即执行**
3. ✅ 004 §11.5 ActionState 信封规范已补充(基础设施批次已执行)
4. 协调 ai02 同步修正 push-gateway go.mod/go.work 版本到 1.22
5. ✅ 总裁已确认采纳方案 A2026-07-10§2.15 第 4 条"避免双 v1"不再适用
---

View File

@@ -125,17 +125,17 @@ graph TB
## §5 HTTP 接口矩阵(非 gRPC / 非 GraphQL
| 提供方 | Method | Path | 用途 | 消费方 | 认证 | 状态 |
| ------------------- | ------ | ----------------- | -------------------- | -------------------------------------------------------------- | ---------------- | ---- |
| api-gateway (ai01) | * | /api/v1/teacher/* | 反向代理 teacher-bff | teacher-portal | JWT | ⏳ |
| api-gateway (ai01) | * | /api/v1/student/* | 反向代理 student-bff | student-portal | JWT | ⏳ |
| api-gateway (ai01) | * | /api/v1/parent/* | 反向代理 parent-bff | parent-portal | JWT | ⏳ |
| api-gateway (ai01) | * | /api/v1/iam/* | 反向代理 iam | (内部) | JWT | ⏳ |
| push-gateway (ai02) | WS | /ws | WebSocket 推送通道 | teacher-portal / student-portal / parent-portal / admin-portal | JWT | ⏳ |
| push-gateway (ai02) | POST | /internal/push | 内部推送入口 | msg | X-Internal-Token | ⏳ |
| iam (ai06) | GET | /healthz | 存活检查 | k8s / 监控 | 无 | ⏳ |
| iam (ai06) | GET | /readyz | 就绪检查5 依赖) | k8s / 监控 | 无 | ⏳ |
| 所有服务 | GET | /metrics | Prometheus 指标 | Prometheus | 无 | ⏳ |
| 提供方 | Method | Path | 用途 | 消费方 | 认证 | 状态 |
| ------------------- | ------ | -------------------- | -------------------- | -------------------------------------------------------------- | ---------------- | ---- |
| api-gateway (ai01) | * | /api/v1/teacher/v1/* | 反向代理 teacher-bff | teacher-portal | JWT | ⏳ |
| api-gateway (ai01) | * | /api/v1/student/v1/* | 反向代理 student-bff | student-portal | JWT | ⏳ |
| api-gateway (ai01) | * | /api/v1/parent/v1/* | 反向代理 parent-bff | parent-portal | JWT | ⏳ |
| api-gateway (ai01) | * | /api/v1/iam/v1/* | 反向代理 iam | (内部) | JWT | ⏳ |
| push-gateway (ai02) | WS | /ws | WebSocket 推送通道 | teacher-portal / student-portal / parent-portal / admin-portal | JWT | ⏳ |
| push-gateway (ai02) | POST | /internal/push | 内部推送入口 | msg | X-Internal-Token | ⏳ |
| iam (ai06) | GET | /healthz | 存活检查 | k8s / 监控 | 无 | ⏳ |
| iam (ai06) | GET | /readyz | 就绪检查5 依赖) | k8s / 监控 | 无 | ⏳ |
| 所有服务 | GET | /metrics | Prometheus 指标 | Prometheus | 无 | ⏳ |
---

View File

@@ -154,15 +154,16 @@
## §2 待 coord 仲裁事项汇总
| ISSUE | 主题 | 阻塞任务 | 状态 |
| --------- | ----------------------------------- | -------- | -------- |
| ISSUE-001 | matrix.md gRPC 矩阵修正 | — | 待 coord |
| ISSUE-002 | shared-go 接入方式 | P2.1 | 待 coord |
| ISSUE-003 | API 版本化路由方案(/v1 前缀) | P2.7 | 待 coord |
| ISSUE-004 | zap vs slog 选型 | P2.1 | 待 coord |
| ISSUE-005 | go.mod 与 Dockerfile 版本不一致 | P2.0 | 待 coord |
| ISSUE-007 | 01-understanding.md §6 审计表过时 | P2.0 | 待 coord |
| ISSUE-008 | 01-understanding.md §7.1 死代码过时 | P2.0 | 待 coord |
| ISSUE-009 | W1/W2 错误码 GW_ + ActionState | P2.3 | 待 coord |
| ISSUE | 主题 | 阻塞任务 | 状态 |
| --------- | ----------------------------------- | -------- | ------------------------------------------ |
| ISSUE-001 | matrix.md gRPC 矩阵修正 | — | ✅ 已裁决coord.md §24.3 |
| ISSUE-002 | shared-go 接入方式 | P2.1 | ✅ 已裁决coord.md §24.5 |
| ISSUE-003 | API 版本化路由方案(/v1 前缀) | P2.7 | ✅ 已裁决coord.md §24.4,方案 A 双 /v1 |
| ISSUE-004 | zap vs slog 选型 | P2.1 | ✅ 已裁决coord.md §24.6zap |
| ISSUE-005 | go.mod 与 Dockerfile 版本不一致 | P2.0 | ✅ 已裁决coord.md §24.7go 1.22 |
| ISSUE-007 | 01-understanding.md §6 审计表过时 | P2.0 | ✅ 已裁决coord.md §24.8 |
| ISSUE-008 | 01-understanding.md §7.1 死代码过时 | P2.0 | ✅ 已裁决coord.md §24.9 |
| ISSUE-009 | W1/W2 错误码 GW_ + ActionState | P2.3 | ✅ 已裁决coord.md §24.10 |
> ISSUE-006 编号未使用(预留)。
> 仲裁详情见 [coord.md §24 ARB-022](../coord.md)