diff --git a/docs/architecture/issues/objections/admin-portal_issue.md b/docs/architecture/issues/objections/admin-portal_issue.md index 36d5ad8..2227ceb 100644 --- a/docs/architecture/issues/objections/admin-portal_issue.md +++ b/docs/architecture/issues/objections/admin-portal_issue.md @@ -16,7 +16,7 @@ - **核查结论**:裁决方向正确(admin-portal 复用 teacher-bff + admin schema 命名空间,与 ai-allocation §5 ai16 设计重点一致)。 - **发现的缺口**:teacher-bff 当前 [02-architecture-design.md](../../../services/teacher-bff/docs/02-architecture-design.md) **未定义 admin 命名空间的 GraphQL schema**(全文仅 1 处 audit 提及,无 adminUsers/adminRoles/auditLogs/adminDashboard 等 Query)。admin-portal P6 的全部业务查询依赖该 schema,属前置依赖缺失。 - **建议**:请 coord 仲裁 admin 命名空间 schema 的归属与时间点——是否由 ai03(teacher-bff)在 P6 启动前补齐 `packages/shared-ts/contracts/graphql/teacher-bff.graphql` 的 admin 命名空间部分(参照本模块 [contract §2.4](../contracts/admin-portal_contract.md) 的 Query 清单)。 -- **状态**:待 coord 仲裁(见新异议 ISSUE-005) +- **状态**:已裁决(见 coord.md §23) ### 0.2 ARB-002(MF Shell 暴露清单)— 核查结论:✅ 通过,但 01/02 文档未跟进 @@ -46,7 +46,7 @@ ARB-001/ARB-002 均未明确仲裁以下三项,而它们直接影响 admin-por - **类型**:编号冲突 / 文档归属 - **描述**:[01-understanding.md](../../../apps/admin-portal/docs/01-understanding.md) 与 [02-architecture-design.md](../../../apps/admin-portal/docs/02-architecture-design.md) 头部均标注"AI:ai07(TS/React · 管理场景域前端 remote)",分支名 `docs/admin-portal-stage1-stage2-design-ai07`。但 [ai-allocation.md §5](../../ai-allocation.md) 第 54/97/118/159/278 行明确 admin-portal 归属 **ai16**,ai07 实际负责 classes → core-edu 交接(见 [workline.md §4.7](../workline.md))。 - **建议方案**:将 01/02 文档头部 AI 标识与分支命名更正为 ai16;ai07 在 admin-portal 的产出视为历史草稿,由 ai16 接管修订。 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §23) ### ISSUE-002-ai16:01/02 文档端口错误(3003 → 4003),且 3003 与 teacher-bff 冲突 @@ -55,7 +55,7 @@ ARB-001/ARB-002 均未明确仲裁以下三项,而它们直接影响 admin-por - **类型**:契约不明确 / 编号冲突 - **描述**:01 §1 与 02 §12.1 声明 admin-portal 端口 3003,并称"与 [full-stack-runbook](../../../docs/standards/full-stack-runbook.md) 端口矩阵对齐"。但 full-stack-runbook §2.1 中 **3003 = teacher-bff**,admin-portal 未列入该 runbook。coord 维护的 [matrix.md §1](../matrix.md) 与 ai-allocation.md 统一采用 4000 段:teacher-portal :4000 / student-portal :4001 / parent-portal :4002 / admin-portal :4003。 - **建议方案**:确认 admin-portal 端口为 **4003**;同步更新 full-stack-runbook §2.1 补齐 4 个 portal 的 4000 段端口(消除 runbook 与 matrix.md 的端口双轨制)。 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §23) ### ISSUE-003-ai16:01/02 文档通信协议与 ARB-001/ARB-002 不一致(REST → GraphQL) @@ -64,7 +64,7 @@ ARB-001/ARB-002 均未明确仲裁以下三项,而它们直接影响 admin-por - **类型**:契约不明确 / 前置依赖缺失 - **描述**:01 §3.1 / 02 §1、§4 全文基于 REST(`/api/v1/iam/*` + `/api/v1/admin/*` + `useApi()` + `ApiClient`)。但 ARB-001 已裁决 admin-portal 复用 teacher-bff GraphQL **admin 命名空间**,ARB-002 已裁决 Shell 暴露 `GraphQLProvider` + `useGraphQLClient`(不含 `useApi`)。02 §11.3 仍将"GraphQL vs REST"列为未决,与仲裁结论冲突。根因:01/02 文档参照的 teacher-portal 02 文档(同样基于 REST、将 GraphQL 列为未决)早于 ARB-001/002(2026-07-09),未跟进仲裁。 - **建议方案**:admin-portal 通信协议统一为 GraphQL(`POST /api/admin/graphql` → teacher-bff admin 命名空间);删除 `useApi`/`ApiClient` 依赖,改用 `useGraphQLClient()`;02 §11.3 移除已裁决项。本模块 [contract.md](../contracts/admin-portal_contract.md) 已按 GraphQL 编写,作为修订基准。 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §23) ### ISSUE-004-ai16:01/02 文档遗漏审计日志与学校设置(ai-allocation §5 明确职责) @@ -73,7 +73,7 @@ ARB-001/ARB-002 均未明确仲裁以下三项,而它们直接影响 admin-por - **类型**:工作量超批 / 契约不明确 - **描述**:[ai-allocation.md §5 ai16](../../ai-allocation.md) 第 282 行明确 admin-portal 设计重点含"用户管理 + 角色权限管理 + 学校设置 + 组织管理 + **审计日志消费**"。但 01 §2.1/§L1 导航/§L2 路由表均**无审计日志、无学校设置**(仅有 dashboard/users/roles/permissions/viewports/organization/monitoring 7 个视口)。本模块 [contract.md §1.2/§2.4](../contracts/admin-portal_contract.md) 已含 audit-logs / system 路由与 auditLogs Query,与 01/02 不一致。 - **建议方案**:admin-portal 视口补齐为 9 个:dashboard / users / roles / permissions / viewports / organization / classes / teachers / students / audit-logs / system(按 ai-allocation §5 + contract §1.2 对齐);审计日志经 teacher-bff GraphQL `auditLogs` Query 消费(聚合 iam `AuditEvent`)。 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §23) ### ISSUE-005-ai16:teacher-bff 缺 admin 命名空间 GraphQL schema(前置依赖缺失) @@ -82,7 +82,7 @@ ARB-001/ARB-002 均未明确仲裁以下三项,而它们直接影响 admin-por - **类型**:前置依赖缺失 - **描述**:ARB-001 裁决 P6 新增 admin 命名空间,但 teacher-bff [02-architecture-design.md](../../../services/teacher-bff/docs/02-architecture-design.md) 未定义该 schema(无 adminUsers / adminRoles / adminClasses / adminTeachers / adminStudents / auditLogs / adminDashboard 等 Query/Mutation)。admin-portal P6 全部业务查询依赖此 schema,且需 SDL-first 存放于 `packages/shared-ts/contracts/graphql/teacher-bff.graphql`(ARB-001 §1.3)。 - **建议方案**:请 coord 仲裁——由 ai03 在 P6 启动前补齐 teacher-bff admin 命名空间 schema(参照本模块 contract §2.4 Query 清单),作为 admin-portal P6 的前置就绪信号;并更新 [matrix.md §3](../matrix.md) teacher-bff 行的 schema 文件状态。 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §23) ### ISSUE-006-ai16:01/02 文档推送策略与同类 portal 契约不一致(轮询 → WebSocket) @@ -91,7 +91,7 @@ ARB-001/ARB-002 均未明确仲裁以下三项,而它们直接影响 admin-por - **类型**:契约不明确 - **描述**:01 §3.3 / 02 §5 声明 admin-portal"不消费 WebSocket/SSE,采用轮询"。但同类 portal 契约([parent-portal_contract.md §2.3](./parent-portal_contract.md))消费 push-gateway `GET /ws`,本模块 [contract.md §2.3](../contracts/admin-portal_contract.md) 亦声明消费 WebSocket 实时通知。matrix.md §5 列 push-gateway WS 消费方含全部 portal。管理端审计告警/异常登录等场景对实时性有合理需求。 - **建议方案**:admin-portal 接入 push-gateway WebSocket(与同类 portal 一致),用于审计告警、异常登录、系统异常等实时通知;保留轮询仅用于监控指标(60s)与统计(5min)这类天然适合轮询的低频数据。 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §23) ### ISSUE-007-ai16:matrix.md §4 将 admin-portal 列为 Kafka 直消费方,与前端层级矛盾 @@ -100,7 +100,7 @@ ARB-001/ARB-002 均未明确仲裁以下三项,而它们直接影响 admin-por - **类型**:契约不明确 - **描述**:[matrix.md §4](../matrix.md) 第 111 行将 admin-portal 列为 `edu.iam.audit.created` 的消费方。但前端不直连 Kafka([contract.md §2.2](../contracts/admin-portal_contract.md) 已明确审计日志经 GraphQL 查询)。实际链路应为:iam → Kafka → **teacher-bff** 消费 → GraphQL `auditLogs` Query → admin-portal。 - **建议方案**:matrix.md §4 该行消费方更正为 **teacher-bff**(admin-portal 经 teacher-bff 间接消费),避免误导架构分层。 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §23) --- diff --git a/docs/architecture/issues/objections/ai_issue.md b/docs/architecture/issues/objections/ai_issue.md index df43b11..9a54c8b 100644 --- a/docs/architecture/issues/objections/ai_issue.md +++ b/docs/architecture/issues/objections/ai_issue.md @@ -33,7 +33,7 @@ - **类型**:编号冲突 / 文档不同步 - **描述**:[matrix.md](../matrix.md) §2 gRPC 接口提供方矩阵写 "ai (ai12) | 50057",§8 就绪信号跟踪表写 "ai gRPC 50057"。但 [port-allocation.md](../../../../infra/port-allocation.md) §3/§5/§7 明确 ai = HTTP 3008 / gRPC 50058(2026-07-09 coord 仲裁"push-gateway 豁免 gRPC,释放 50057;50058 让给 ai")。两份 coord 文件矛盾,matrix.md 过时。ai 01/02 文档与 workline.md §1/§4.12 已正确采用 50058。 - **建议方案**:coord 将 matrix.md §2 ai 行 gRPC 端口 50057 → 50058,§8 就绪信号"ai gRPC 50057"→ 50058。ai12 同步将 contracts/ai_contract.md 全部 50057 改 50058。 -- **状态**:待 coord 仲裁(实为同步操作,仲裁已存在于 port-allocation.md §7) +- **状态**:已裁决(见 coord.md §12) ### ISSUE-02-ai12:ai 用量事件 Kafka topic 命名三义未决 @@ -48,7 +48,7 @@ events.proto 现状无 `AIUsageEvent` message,004 无 topic 记录。三义导致 data-ana 消费方无法对齐。 - **建议方案**:ai12 建议采用 `edu.ai.usage`(与 matrix.md 一致,最简短,符合 `edu..` 简洁约定)。请 coord 裁定并在 004 §7.2 补登 + events.proto 补 `AIUsageEvent` message(schema 见 02-architecture-design.md §3.3)。ai12 据裁决同步 01/02 文档与 contract。 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §12) ### ISSUE-03-ai12:ai.proto 待补全(备课工作流 RPC + 字段扩展) @@ -63,7 +63,7 @@ 关于 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 仲裁 +- **状态**:已裁决(见 coord.md §12) ### ISSUE-04-ai12:events.proto 缺 AIUsageEvent message @@ -72,7 +72,7 @@ - **类型**:契约不明确 / 前置依赖缺失 - **描述**:004 §12.2 + §15.3 #6 仲裁 ai 用量事件豁免 Outbox(派生数据),但 events.proto 现状仅有 ClassEvent / ExamEvent / HomeworkEvent / GradeEvent,**无 AIUsageEvent**。data-ana 消费方无 schema 可循。01/02 文档已提请(A3),matrix.md §4 已列事件名,但 proto 未落地。 - **建议方案**:coord 在 events.proto 新增 `AIUsageEvent` message,建议 schema 见 02-architecture-design.md §3.3(含 event_id / user_id / school_id / provider / model / operation / prompt_tokens / completion_tokens / total_tokens / latency_ms / success / degraded / metadata)。与 ISSUE-02 一并裁决。 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §12) ### ISSUE-05-ai12:contracts/ai_contract.md 与设计文档多处矛盾(ai12 自查自纠清单) @@ -96,7 +96,7 @@ - **类型**:工作量超批 / 前置依赖缺失 - **描述**:004 §2.3 列出 Temporal 用于"AI 编排",属部分仲裁。ai12 在 02-architecture-design.md §8.3 建议:P5 用 FastAPI BackgroundTasks + Redis(24h TTL)实现 4 步备课工作流;P6 评估迁移 Temporal(支持长运行跨天审核 + 复杂状态机)。需 coord 在 P6 决策点确认是否引入,避免 P5 实现被推翻重做。 - **建议方案**:P5 采用 BackgroundTasks + Redis(02-architecture-design.md §2.4 状态机已设计);P6 由 coord 评估 Temporal 引入时机。请 coord 在 roadmap 标注 P6 决策点。 -- **状态**:待 coord 仲裁(P6 决策点) +- **状态**:已裁决(见 coord.md §12) ### ISSUE-07-ai12:iam GetEffectiveDataScope gRPC RPC 待 P4 补全 @@ -114,7 +114,7 @@ - **类型**:契约不明确 / 架构约束 - **描述**:project_rules §5 规定 proto 包名规范 `edu..v1`(如 `edu.iam.v1`、`edu.core_edu.v1`)。但 ai.proto 现状 package 为 `next_edu_cloud.ai.v1`,events.proto 为 `next_edu_cloud.events.v1`,均不符合规范。01/02 文档未指出此偏离。此为全局 proto 命名问题(涉及全部 proto 文件),非 ai 独有,但 ai12 在审查中发现需提请。 - **建议方案**:请 coord 裁定是否统一迁移 proto package 至 `edu..v1`(全局变更,需 buf breaking 评估);或保留现状作为历史包袱。ai12 在 ai.proto 补全 RPC 时遵循最终裁定。 -- **状态**:待 coord 仲裁(全局 proto 命名) +- **状态**:已裁决(见 coord.md §12) ### ISSUE-09-ai12:响应信封偏离 ActionState 强制整改(P0) @@ -137,5 +137,5 @@ - **类型**:契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他 - **描述**:[详细描述问题] - **建议方案**:[AI 的建议] -- **状态**:待 coord 仲裁 / 已裁决(见 coord.md §X) +- **状态**:已裁决(见 coord.md §X) --> diff --git a/docs/architecture/issues/objections/api-gateway_issue.md b/docs/architecture/issues/objections/api-gateway_issue.md index 2d1eeb5..65d52a1 100644 --- a/docs/architecture/issues/objections/api-gateway_issue.md +++ b/docs/architecture/issues/objections/api-gateway_issue.md @@ -62,7 +62,7 @@ - **类型**:契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他 - **描述**:[详细描述问题] - **建议方案**:[AI 的建议] -- **状态**:待 coord 仲裁 / 已裁决(见 coord.md §X) +- **状态**:已裁决(见 coord.md §X) --> ### ISSUE-001-ai01:matrix.md gRPC 矩阵错误声明 api-gateway 消费 iam gRPC @@ -74,7 +74,7 @@ - **建议方案**: 1. matrix.md §2 iam 行"消费方"列移除 `api-gateway` 2. matrix.md §7 Mock 策略表中 api-gateway 行改为"硬编码 RS256 公钥(DEV_MODE)→ HTTP JWKS 端点" -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §24.3) ### ISSUE-002-ai01:shared-go 接入方式与时机 @@ -87,7 +87,7 @@ 2. go.work 增加 `./packages/shared-go` 3. ai01 go.mod 增加 `github.com/edu-cloud/shared-go` 依赖 4. P2.1 任务接入 jwks/logger/tracer/env -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §24.5) ### ISSUE-003-ai01:API 版本化路由方案(/v1 前缀位置) @@ -99,7 +99,7 @@ - 方案 B:Gateway 路由 `/api/v1/iam/*path`,proxy 透传 `/iam/*path`,下游 Controller 内加 `/v1`(前端调用 `/api/v1/iam/v1/auth/login`,Gateway 不含 `/v1`) - 方案 C:其他 - **建议方案**:采纳方案 B(Gateway 路由不含服务级 `/v1`,由下游 Controller 添加),符合裁决第 4 条"避免双 v1"和第 3 条"Gateway 不改路径直接透传" -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §24.4) ### ISSUE-004-ai01:zap vs slog 选型 @@ -108,7 +108,7 @@ - **类型**:契约不明确 - **描述**:W3 裁决"首次实现即用 slog",但 [shared-go/logger](../../../packages/shared-go/logger/logger.go) 的实现选型(zap 还是 slog)影响 ai01 接入方式。若 shared-go 用 zap,ai01 需通过 shared-go/logger 间接使用 zap;若 shared-go 用 slog,ai01 可直接用标准库 `log/slog` 或 shared-go 封装。需 coord 仲裁 shared-go/logger 最终选型。 - **建议方案**:shared-go/logger 基于 `log/slog` 封装(标准库零依赖,W3 裁决原文即 slog),ai01 直接 import shared-go/logger -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §24.6) ### ISSUE-005-ai01:go.mod 与 Dockerfile Go 版本不一致 @@ -117,7 +117,7 @@ - **类型**:其他 - **描述**:[go.mod](../../../services/api-gateway/go.mod) L3 声明 `go 1.25.0`,[go.work](../../../go.work) L1 声明 `go 1.26.0`,但 [Dockerfile](../../../services/api-gateway/Dockerfile) L1 用 `golang:1.22-alpine`。三者不一致,可能导致构建环境与本地开发环境行为差异。 - **建议方案**:统一为 `go 1.22`(与 Dockerfile 一致,与 [01-understanding.md](../../../services/api-gateway/docs/01-understanding.md) §4 声明一致),或升级 Dockerfile 到 `golang:1.25-alpine` 并同步 go.mod/go.work -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §24.7) ### ISSUE-007-ai01:01-understanding.md §6 审计表 metrics 行过时 @@ -126,7 +126,7 @@ - **类型**:其他 - **描述**:[01-understanding.md](../../../services/api-gateway/docs/01-understanding.md) §6 审计表 metrics 行标注 `❌ 无`,§7.1 issue #1 也说"无 `/metrics` 端点,Prometheus 404"。但实际 [main.go](../../../services/api-gateway/main.go) L56 已注册 `r.GET("/metrics", gin.WrapH(promhttp.Handler()))`,`/metrics` 端点已存在。文档过时,需更新为"⚠️ 端点已注册,但缺 7 个业务指标"。 - **建议方案**:更新 01-understanding.md §6 审计表 metrics 行为 `⚠️ 端点已注册,缺业务指标`;§7.1 issue #1 更新为"已注册 /metrics,需补 7 个业务指标" -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §24.8) ### ISSUE-008-ai01:01-understanding.md §7.1 issue #3 死代码引用过时 @@ -135,7 +135,7 @@ - **类型**:其他 - **描述**:[01-understanding.md](../../../services/api-gateway/docs/01-understanding.md) §7.1 issue #3 引用"auth.go L124-139 死代码 `RequestIDMiddleware()` + `generateUUID()`",但实际 [auth.go](../../../services/api-gateway/internal/middleware/auth.go) 当前仅 121 行,L124-139 不存在,死代码已删除。文档引用过时。 - **建议方案**:删除 01-understanding.md §7.1 issue #3 整行(死代码已修复) -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §24.9) ### ISSUE-009-ai01:W1/W2 错误码 GW_ 前缀 + ActionState 信封未遵循 @@ -148,7 +148,7 @@ - [circuit-breaker.go](../../../services/api-gateway/internal/middleware/circuit-breaker.go) L55-58 响应 `{"error":"circuit_open","retry_after":30}`(无 GW_ 前缀,无信封) - [recovery.go](../../../services/api-gateway/internal/middleware/recovery.go) L24-27 响应 `{"error":"internal_error","request_id":"..."}`(无 GW_ 前缀,无信封) - **建议方案**:P2.3 任务统一修复(见 [workline.md](../worklines/api-gateway_workline.md) P2.3),所有错误码改为 `GW_*`,所有响应体改为 `{success:false,error:{code:"GW_*",message:"..."},...}` -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §24.10) --- diff --git a/docs/architecture/issues/objections/content_issue.md b/docs/architecture/issues/objections/content_issue.md index e9fd1c9..d963462 100644 --- a/docs/architecture/issues/objections/content_issue.md +++ b/docs/architecture/issues/objections/content_issue.md @@ -46,7 +46,7 @@ N1-N5 与 C2/C4/C10 共 8 项已有仲裁**全部在 02-architecture-design.md 2. **knowledge-points 删除前置**:设计文档列 `DELETE /knowledge-points/:id/prerequisites/:prereqId`,源码未实现该端点 3. **chapters 列表**:设计文档为 `GET /chapters?textbookId=`,源码实现为 `GET /chapters/textbook/:textbookId` - **建议方案**:以设计文档为目标态(query 参数 + 补 DELETE prerequisite 端点),在 P4 重构时统一对齐。但需 coord 确认是否允许 API 路径变更(影响 teacher-bff 消费方)。 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §5) ### ISSUE-002-ai09:content 发布事件 topic 命名策略与契约文档不一致 @@ -62,7 +62,7 @@ N1-N5 与 C2/C4/C10 共 8 项已有仲裁**全部在 02-architecture-design.md 2. 减少 topic 数量(12 → 4),降低 Kafka 集群元数据压力 3. 消费方按 action 字段过滤,订阅灵活性更高 4. 需补 `KnowledgePointEvent` / `QuestionEvent` / `TextbookEvent` / `ChapterEvent` proto message -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §5) ### ISSUE-003-ai09:Textbook/Chapter 事件在契约文档遗漏 @@ -71,7 +71,7 @@ N1-N5 与 C2/C4/C10 共 8 项已有仲裁**全部在 02-architecture-design.md - **类型**:契约不明确 - **描述**:02-architecture-design.md §5.1 列出 4 类 textbook 事件 + 1 类 chapter 事件,但 contracts/content_contract.md §1.4 仅列出 knowledge_point 与 question 两类事件,Textbook/Chapter 事件未登记。matrix.md §4 也仅列 kp + question。导致下游(data-ana)无法感知教材/章节变更。 - **建议方案**:在 contract.md 与 matrix.md 补登记 `edu.content.textbook.events`(action: created/updated/published/archived)与 `edu.content.chapter.events`(action: created/updated/deleted)。若 coord 认为教材/章节无需对外发事件,则在 design doc §5.1 删除相关事件。 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §5) ### ISSUE-004-ai09:gRPC RPC 数量三方文档不一致 @@ -96,7 +96,7 @@ N1-N5 与 C2/C4/C10 共 8 项已有仲裁**全部在 02-architecture-design.md 2. ChapterService 补 Update + Delete(design doc + contract 都缺 Delete,需补) 3. QuestionService 补 PublishQuestion + SearchQuestions(与 contract 对齐) 4. 最终 RPC 总数:TextbookService 5 + ChapterService 5 + KnowledgeGraphService 4 + QuestionService 7 = **21 RPC**(需同步更新 matrix.md §2 的 18 → 21) -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §5) ### ISSUE-005-ai09:core-edu → content 失效事件 topic 无定义 @@ -109,7 +109,7 @@ N1-N5 与 C2/C4/C10 共 8 项已有仲裁**全部在 02-architecture-design.md 3. core-edu 设计文档(ai08)未明确发布该事件 4. 01-understanding.md §5 也标注"具体 topic 待 core-edu ai03 设计确认"——此处 ai03 疑为笔误,core-edu 实际由 ai08 负责 - **建议方案**:content 不主动消费 core-edu 失效事件(content 是上游内容提供方,core-edu 是消费方),删除 §5.2 中该条目;若确有联动需求,由 core-edu 主动调用 content gRPC UpdateQuestion 状态变更,而非事件驱动。 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §5) ### ISSUE-006-ai09:文档结尾"直接 push main"与项目规则冲突 @@ -121,7 +121,7 @@ N1-N5 与 C2/C4/C10 共 8 项已有仲裁**全部在 02-architecture-design.md - §14.3:AI 禁止 `git merge`、`git push origin main` - 当前 worktree 分支为 `feat-review-content-module-docs-WAIyMA` - **建议方案**:删除两份文档末尾"单仓库并行模式(直接 push main)"字样,改为 `Branch: feat-review-content-module-docs-WAIyMA(分支开发,提交后通知人类合并)`。 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §5) ### ISSUE-007-ai09:questions 表 created_by 字段迁移风险 @@ -130,7 +130,7 @@ N1-N5 与 C2/C4/C10 共 8 项已有仲裁**全部在 02-architecture-design.md - **类型**:其他 - **描述**:02-architecture-design.md §3.1.4 questions 表新增 `created_by varchar(32) NOT NULL`,但现有 [questions.schema.ts](../../../services/content/src/questions/questions.schema.ts) 无该字段,且现有数据无 created_by 值。schema 迁移时 NOT NULL 约束会导致历史数据迁移失败。 - **建议方案**:迁移期间先用 `created_by varchar(32) NULL`,数据回填后再加 NOT NULL 约束;或为新数据强制要求 created_by(应用层校验),历史数据用 `'system'` 默认值回填。 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §5) ### ISSUE-008-ai09:设计文档缺缓存策略与 API 版本化策略 @@ -143,7 +143,7 @@ N1-N5 与 C2/C4/C10 共 8 项已有仲裁**全部在 02-architecture-design.md - **建议方案**: 1. P4 在 design doc §6 补"缓存策略"小节:教材树/章节树 Redis 缓存 + 失效策略(Outbox 事件触发缓存失效) 2. P4 在 design doc §4 补"API 版本化"说明:REST 端点统一加 `/v1/` 前缀(gRPC 用 proto package version) -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §5) ### ISSUE-009-ai09:knowledge-points schema 实际缺 difficulty/metadata 字段 @@ -152,7 +152,7 @@ N1-N5 与 C2/C4/C10 共 8 项已有仲裁**全部在 02-architecture-design.md - **类型**:其他 - **描述**:02-architecture-design.md §3.1.3 knowledge_points 表列出 `difficulty tinyint NOT NULL DEFAULT 3` 与 `metadata json NULL`,但实际 [textbooks.schema.ts](../../../services/content/src/textbooks/textbooks.schema.ts) 中 `knowledgePoints` 表仅含 id/chapterId/title/description 四个字段,无 difficulty 与 metadata。01-understanding.md C7 提到"时间戳缺失"但未提到 difficulty/metadata 缺失。 - **建议方案**:P4 schema 迁移时一并补齐 difficulty + metadata + created_at + updated_at(与 design doc §3.1.3 对齐)。 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §5) ### ISSUE-010-ai09:Neo4j Sync Worker 与 ES Sync Worker 在 P4 阶段不必要 @@ -167,21 +167,21 @@ N1-N5 与 C2/C4/C10 共 8 项已有仲裁**全部在 02-architecture-design.md 1. §1.1 图中明确标注 ES Sync Worker 为 P5 组件(虚线或灰显) 2. §1.1 图中 Neo4j Sync Worker 的输入仅来自 content 自身 Outbox 事件(不消费 core-edu 事件) 3. P4 任务 T6 明确"重构 knowledge-points.service.ts:移除 safeCreateNode 同步写,改为发 Outbox 事件" -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §5) --- ## §2 待 coord 仲裁项汇总 -| # | 标题 | 阻塞性 | 状态 | -| --- | ---------------------------------------- | ------------------- | ------------- | -| 001 | REST 端点设计与实现不一致 | 🟡 P4 重构时对齐 | 待 coord 仲裁 | -| 002 | 事件 topic 命名策略冲突(独立 vs 聚合) | 🔴 阻塞 Outbox 实现 | 待 coord 仲裁 | -| 003 | Textbook/Chapter 事件在契约文档遗漏 | 🟡 契约完整性 | 待 coord 仲裁 | -| 004 | gRPC RPC 数量三方文档不一致 | 🔴 阻塞 proto 修改 | 待 coord 仲裁 | -| 005 | core-edu → content 失效事件 topic 无定义 | 🟢 建议删除 | 待 coord 仲裁 | -| 006 | "直接 push main"与项目规则冲突 | 🟡 文档修正 | 待 coord 仲裁 | -| 007 | questions.created_by 迁移风险 | 🟡 schema 迁移 | 待 coord 仲裁 | -| 008 | 缓存策略与 API 版本化策略缺失 | 🟢 长远架构 | 待 coord 仲裁 | -| 009 | knowledge-points schema 实际缺字段 | 🟡 P4 schema 迁移 | 待 coord 仲裁 | -| 010 | Sync Worker 链路与 P4 阶段不必要 | 🟡 设计澄清 | 待 coord 仲裁 | +| # | 标题 | 阻塞性 | 状态 | +| --- | ---------------------------------------- | ------------------- | ------ | +| 001 | REST 端点设计与实现不一致 | 🟡 P4 重构时对齐 | 已裁决 | +| 002 | 事件 topic 命名策略冲突(独立 vs 聚合) | 🔴 阻塞 Outbox 实现 | 已裁决 | +| 003 | Textbook/Chapter 事件在契约文档遗漏 | 🟡 契约完整性 | 已裁决 | +| 004 | gRPC RPC 数量三方文档不一致 | 🔴 阻塞 proto 修改 | 已裁决 | +| 005 | core-edu → content 失效事件 topic 无定义 | 🟢 建议删除 | 已裁决 | +| 006 | "直接 push main"与项目规则冲突 | 🟡 文档修正 | 已裁决 | +| 007 | questions.created_by 迁移风险 | 🟡 schema 迁移 | 已裁决 | +| 008 | 缓存策略与 API 版本化策略缺失 | 🟢 长远架构 | 已裁决 | +| 009 | knowledge-points schema 实际缺字段 | 🟡 P4 schema 迁移 | 已裁决 | +| 010 | Sync Worker 链路与 P4 阶段不必要 | 🟡 设计澄清 | 已裁决 | diff --git a/docs/architecture/issues/objections/core-edu_issue.md b/docs/architecture/issues/objections/core-edu_issue.md index dc42c0d..9d6cc69 100644 --- a/docs/architecture/issues/objections/core-edu_issue.md +++ b/docs/architecture/issues/objections/core-edu_issue.md @@ -41,7 +41,7 @@ - **类型**:契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他 - **描述**:[详细描述问题] - **建议方案**:[AI 的建议] -- **状态**:待 coord 仲裁 / 已裁决(见 coord.md §X) +- **状态**:已裁决(见 coord.md §X) --> ### ISSUE-001-ai08:core_edu.proto 实际状态与 coord 仲裁声称不一致(P0) @@ -82,7 +82,7 @@ coord 确认 `core_edu.proto` 补全工作的实际负责人(coord 自行补全,还是交由 ai08 在 P3 补全)。 - 若 coord 已补全但未提交:请 coord 提交最新 proto - 若待 ai08 P3 补全:coord-cross-review.md L312 的 "✅ 已补全" 状态需更正为 "⏳ 待 ai08 P3 补全",01-understanding.md L48 需补"ClassService 也缺失" -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §4) --- @@ -122,7 +122,7 @@ - 所有 Event message 新增 `string schema_version = N;` 字段 2. coord 同步更新 matrix.md §4 为 `edu.teaching.*` 命名 3. ai08 在 core-edu `outbox.publisher.ts` TOPIC_MAP 按 `edu.teaching.*` 命名实现 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §4) --- @@ -151,7 +151,7 @@ - **方案 A(推荐)**:core-edu DB status 统一为小写动词形式 `draft / published / in_progress / grading / graded / archived / cancelled`,GraphQL 枚举映射为大写 `DRAFT / PUBLISHED / IN_PROGRESS / GRADING / GRADED / ARCHIVED / CANCELLED`(去掉 `SCORED`,统一用 `GRADED`)。SubmissionStatus 统一为 `NOT_SUBMITTED / SUBMITTED / GRADED`,core-edu exam/homework submissions 初始状态统一为 `not_submitted`(不再用 `in_progress` 或 `draft`)。 - **方案 B**:保留 coord GraphQL 现状(`SCORED`),core-edu 改 `graded` 为 `scored`。 ai08 倾向方案 A(`graded` 是教育领域通用术语,`scored` 歧义大)。 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §4) --- @@ -179,7 +179,7 @@ - 若 classes 合并到 core-edu 后仍归"教学组织域",则 topic 应为 `edu.teaching.class.transferred`(遵循 §3.1 仲裁的 `edu.teaching..` 风格) - 若归"组织域",则为 `edu.org.class.transferred`(注意 action 应为 `transferred` 而非 `created`) ai08 倾向 `edu.teaching.class.transferred`(与 §3.1 仲裁风格一致,classes 合并到 core-edu 后属教学域)。 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §4) --- @@ -207,7 +207,7 @@ - matrix.md §2 改为 "27 RPC(P3 全量:ClassService 4 + ExamService 8 + HomeworkService 5 + GradeService 6 + AttendanceService 4)" - 就绪信号改为 "core-edu gRPC 50053 + 27 RPC + HealthService SERVING" - core-edu_contract.md §1.1 补全 P3 新增 RPC -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §4) --- @@ -236,7 +236,7 @@ - 决策 #4 schema 默认值与倾向不一致,仲裁前可能实现错 - **建议方案**: coord 逐项仲裁,ai08 按倾向方案实现。决策 #4 若采 (b) 300 秒,02 文档 §3.1.2 schema 默认值改为 `.default(300)`。 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §4) --- @@ -255,4 +255,4 @@ - **建议方案**: coord 确认上述 3 项是否纳入 P3 验收标准;若纳入,ai08 在 P3 实施时补齐。 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §4) diff --git a/docs/architecture/issues/objections/data-ana_issue.md b/docs/architecture/issues/objections/data-ana_issue.md index 6452887..916d476 100644 --- a/docs/architecture/issues/objections/data-ana_issue.md +++ b/docs/architecture/issues/objections/data-ana_issue.md @@ -57,7 +57,7 @@ coord-cross-review.md §8.2 声称批次 0 已完成 proto 补全,ai11 逐文 - **类型**:前置依赖缺失 - **描述**:coord-cross-review.md §2.2 #3 已仲裁"iam P4 补全 `GetEffectiveDataScope` RPC,data-ana gRPC 调用",但 iam.proto 当前仅 4 RPC,无此 RPC。data-ana 的 DataScope 6 级过滤(SELF/CLASS/GRADE/SCHOOL/DISTRICT/ALL)依赖此 RPC 解析用户可见数据范围,是 P4 实现的硬阻塞项。 - **建议方案**:coord 确认 iam.proto 补全进度。若 iam 侧尚未实现,data-ana P4 阶段将使用硬编码 DataScope 降级(按 role 映射默认 scope),并标注 `details.degraded: true`,待 iam 就绪后切换。 -- **状态**:待 coord 仲裁(核查已有仲裁 §0.2 #1 未落实) +- **状态**:已裁决(见 coord.md §11) --- @@ -68,7 +68,7 @@ coord-cross-review.md §8.2 声称批次 0 已完成 proto 补全,ai11 逐文 - **类型**:前置依赖缺失 - **描述**:coord-cross-review.md §3.2 已仲裁"补登 `edu.insight.ai.usage` topic + events.proto 补 `AIUsageEvent` message",但 events.proto 当前仅 4 message(ClassEvent/ExamEvent/HomeworkEvent/GradeEvent),缺 AIUsageEvent。data-ana 需消费此事件落 `ai_usage_log` 宽表,供管理员仪表盘展示 AI 用量统计。 - **建议方案**:coord 在 events.proto 补 `AIUsageEvent` message,字段建议:`{event_id, request_id, user_id, provider, model, prompt_tokens, completion_tokens, total_tokens, latency_ms, success, cost_cents, occurred_at}`。P5 前补全即可,P4 仪表盘 AI 用量区块显示"暂无数据"。 -- **状态**:待 coord 仲裁(核查已有仲裁 §0.2 #3 未落实) +- **状态**:已裁决(见 coord.md §11) --- @@ -79,7 +79,7 @@ coord-cross-review.md §8.2 声称批次 0 已完成 proto 补全,ai11 逐文 - **类型**:前置依赖缺失 + 声明与实际不符 - **描述**:coord-cross-review.md §8.2 声称"analytics.proto 扩展 ✅ 12 RPC(含 Stream)",但实际文件仅 3 RPC(GetClassPerformance/GetStudentWeakness/GetLearningTrend)。ai-allocation.md §5 与 matrix.md §2 均要求 data-ana 提供 12 RPC,02-architecture-design.md §4.2 已设计完整 12 RPC 清单(含 4 端 Dashboard + Warning + Mastery + Server Streaming),但 proto 未补全导致无法生成 stub。 - **建议方案**:coord 确认 analytics.proto 扩展进度。ai11 可提供 12 RPC 的完整 message 定义提案(见 [02-architecture-design.md §4.2](../../../services/data-ana/docs/02-architecture-design.md)),coord 审议后合并到 analytics.proto。若 coord 未补全,ai11 在 P4 阶段自行补全 proto(本分支内),提请 coord 合并。 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §11) --- @@ -97,7 +97,7 @@ coord-cross-review.md §8.2 声称批次 0 已完成 proto 补全,ai11 逐文 这导致 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 仲裁 +- **状态**:已裁决(见 coord.md §11) --- @@ -117,7 +117,7 @@ coord-cross-review.md §8.2 声称批次 0 已完成 proto 补全,ai11 逐文 按 004 §7.2 命名规范 `edu...`,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 仲裁 +- **状态**:已裁决(见 coord.md §11) --- @@ -128,4 +128,4 @@ 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) diff --git a/docs/architecture/issues/objections/iam_issue.md b/docs/architecture/issues/objections/iam_issue.md index b77208e..fae087c 100644 --- a/docs/architecture/issues/objections/iam_issue.md +++ b/docs/architecture/issues/objections/iam_issue.md @@ -58,7 +58,7 @@ - 02 §4.1:API 路径无 /v1 前缀(违反 I7) - 01 §1:teacher-bff HTTP 调用 iam(违反 B2,应 gRPC) - **建议方案**:ai06 立即回写 01/02 文档,删除全部中间过渡方案描述,对齐 I1-I8 + §2.15/§2.16/§5.5 最终方案。 -- **状态**:待 coord 仲裁(确认回写范围与验收标准) +- **状态**:已裁决(见 coord.md §3) ### ISSUE-002-ai06:events.proto 缺少 UserEvent/RoleEvent/AuditEvent message @@ -67,7 +67,7 @@ - **类型**:前置依赖缺失 - **描述**:coord-final-decisions §5.1 标注"events.proto ✅ 已补全(UserEvent/RoleEvent/NotificationEvent/MasteryEvent/AIUsageEvent/KnowledgePointEvent/QuestionEvent)",president §5.5 也要求"events.proto 补 AuditEvent 在批次 0.10 完成"。但实际 [events.proto](../../../packages/shared-proto/proto/events.proto) 仅定义 ClassEvent/ExamEvent/HomeworkEvent/GradeEvent 4 个 message,**完全缺少** UserEvent/RoleEvent/AuditEvent 等 iam 依赖的事件契约。这直接阻塞 iam Outbox 事件发布(iam 无法写入未定义 schema 的事件)。 - **建议方案**:coord 立即补全 events.proto,至少新增 UserEvent、RoleEvent、AuditEvent 三个 message(按 02 文档 §5.2 和 president §5.5 的字段定义)。 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §3) ### ISSUE-003-ai06:Topic 命名三方不一致(edu.identity.* vs edu.iam.*) @@ -80,7 +80,7 @@ - president §5.5:`edu.iam.audit.created`(用 `iam` 域名) - coord-final-decisions G16 规则:`edu...` - **建议方案**:统一用 `edu.iam.*`(服务名为 iam,非 identity),coord 同步修正 004 §7.2 的 `edu.identity.*` → `edu.iam.*`。同时明确 Topic 粒度:matrix.md 用聚合 topic(`edu.iam.user.events` 含多 action),004 §7.2 用具体动作 topic(`edu.iam.user.created`),需统一为一种风格。 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §3) ### ISSUE-004-ai06:DataScope 枚举三方不一致 @@ -93,7 +93,7 @@ - president §3.2 P2.2:ALL/SCHOOL/GRADE/CLASS/SUBJECT/SELF(**SUBJECT 替代 DISTRICT**) - 源码 [iam.schema.ts](../../../services/iam/src/iam/iam.schema.ts) 第 16-25 行:self/class/grade/school/district/all(与 004 表一致,与 president 不一致) - **建议方案**:coord 统一裁定最终枚举值。若采用 president 的 SUBJECT(学科级数据范围,K12 场景更实用),需同步修改源码 schema + 004 §5.3 表 + 02 文档;若保留 DISTRICT,需修正 president §3.2。同时修正 004 行 505 的语义命名使其与枚举表一致。 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §3) ### ISSUE-005-ai06:iam.proto 仅 4 RPC,未补全至 12 RPC @@ -102,7 +102,7 @@ - **类型**:前置依赖缺失 - **描述**:coord-final-decisions §5.1 要求 iam.proto 在"P2 启动前"补全 8 个新 RPC(GetViewports / GetEffectivePermissions / GetEffectiveAccess / Logout / GetPublicKey / BatchGetUsers / GetEffectiveDataScope / GetChildrenByParent),president §6 批次 0 任务 0.3 也明确"coord 补全 iam.proto 8 RPC"。但实际 [iam.proto](../../../packages/shared-proto/proto/iam.proto) 仍仅 4 RPC(Register/Login/RefreshToken/GetUserInfo),未补全。这阻塞 iam P2.1 的 8 RPC 实现(proto 是契约先行前提)。 - **建议方案**:coord 立即补全 iam.proto 至 12 RPC(含对应 message 定义),对齐 [iam_contract.md §1.1](../contracts/iam_contract.md) 的 12 RPC 清单。 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §3) ### ISSUE-006-ai06:01/02 文档 AI 身份署名错误 @@ -111,7 +111,7 @@ - **类型**:其他 - **描述**:[01-understanding.md](../../../services/iam/docs/01-understanding.md) 和 [02-architecture-design.md](../../../services/iam/docs/02-architecture-design.md) 署名"AI:ai02(TS / 身份认证)"、"AI Agent: ai02 (iam-module)"。但 coord-final-decisions §3.1、president §3.2、[matrix.md](../matrix.md)、[workline.md](../workline.md)、[iam_workline.md](../worklines/iam_workline.md)、[iam_contract.md](../contracts/iam_contract.md) 全部指明 iam 由 **ai06** 负责。ai02 实际负责 push-gateway(coord-final-decisions §3.7)。文档署名错误会导致多 AI 协作时身份混淆。 - **建议方案**:回写时将 01/02 文档署名从 ai02 改为 ai06。 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §3) ### ISSUE-007-ai06:contract.md §1.2 与双入口策略冲突 @@ -120,7 +120,7 @@ - **类型**:契约不明确 - **描述**:[iam_contract.md §1.2](../contracts/iam_contract.md) 写"无对外 HTTP 端点,仅 gRPC"。但 president §2.16 裁决双入口策略:REST 供 gateway 透传 + gRPC 供 BFF 聚合调用,"gateway 保持 HTTP 透传"。若 iam 不暴露 HTTP 端点,gateway 无法透传(gateway 不改为 gRPC 客户端)。 - **建议方案**:修正 contract.md §1.2,补充 REST 端点清单(/iam/v1/* 系列),标明"REST 供 gateway 透传 + admin-portal 直连,gRPC 供 BFF 聚合调用"。 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §3) --- @@ -136,7 +136,7 @@ - **类型**:契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他 - **描述**:[详细描述问题] - **建议方案**:[AI 的建议] -- **状态**:待 coord 仲裁 / 已裁决(见 coord.md §X) +- **状态**:已裁决(见 coord.md §X) --> 见上方 §2 新提请异议(ISSUE-001 ~ ISSUE-007)。 diff --git a/docs/architecture/issues/objections/msg_issue.md b/docs/architecture/issues/objections/msg_issue.md index 9aaaeb6..c687e70 100644 --- a/docs/architecture/issues/objections/msg_issue.md +++ b/docs/architecture/issues/objections/msg_issue.md @@ -73,7 +73,7 @@ - `GradeEvent` L50-59 **无** `class_id`(仅有 `student_id`)❌ - 三者均**无** `student_ids[]`(复数,用于 fan-out 广播)❌ - **建议方案**:修正 P9 表述为"`GradeEvent` 需补 `class_id`;全部事件需补 `student_ids[]` 字段(msg fan-out 广播通知需要)" -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §10) ### ISSUE-007-ai10:proto 包名规则冲突(project_rules vs 实际) @@ -84,7 +84,7 @@ - **建议方案**:coord 统一裁决,二选一: - 方案 A:更新 project_rules §5 为 `next_edu_cloud..v1`(与实际 proto 一致) - 方案 B:重命名所有 proto package 为 `edu..v1`(与规则一致,但改动大) -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §10) ### ISSUE-008-ai10:Kafka topic 命名三套约定并存 @@ -100,7 +100,7 @@ - 004 §7.2 已采用,是架构设计意图唯一源 - per-event topic 便于消费者按需订阅,避免反序列化无关事件 - 与 NotificationSent / NotificationRead 等事件命名(PascalCase)对齐 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §10) ### ISSUE-009-ai10:RPC 数量超预算(17 vs 13) @@ -115,7 +115,7 @@ - **建议方案**:coord 裁决 RPC 范围,二选一: - 方案 A:维持 13 RPC 预算,02-architecture-design.md 裁剪至 13(移除 BatchSendNotification / GetUnreadCount / BatchMarkAsRead / MarkAllAsRead / UpdateTemplate / DeleteTemplate,降级为 REST only 或合并) - 方案 B:放宽至 17 RPC,同步更新 ai-allocation.md + matrix.md + msg_contract.md -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §10) ### ISSUE-010-ai10:markAsRead 权限点与设计不一致 @@ -140,7 +140,7 @@ - ES 故障 → DB LIKE 查询(设计文档已覆盖) - DB 故障 → ES 只读模式(ai-allocation 要求,设计文档需补充) - 但 DB 故障时写操作无法降级(必须等 DB 恢复),仅读操作可走 ES -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §10) ### ISSUE-012-ai10:设计文档缺 DLQ 与三层幂等防线 @@ -167,7 +167,7 @@ - `MasteryEvent`(data-ana 发布 mastery.updated)— 阻塞学情预警通知 - `NotificationEvent`(msg 发布 notification.sent/read/recalled/failed)— 阻塞 push-gateway 消费 msg 事件 - **建议方案**:coord 维护 shared-proto,在 P5 启动前补齐这 4 个 message。msg 在 proto 补齐前用通用 JSON payload 解析(A6 假设) -- **状态**:待 coord 仲裁(🔴 阻塞 P5 消费链路) +- **状态**:已裁决(见 coord.md §10) ### ISSUE-014-ai10:msg_contract.md 与 02-architecture-design.md RPC 清单不一致 @@ -179,7 +179,7 @@ - 02-architecture-design.md 独有(contract 缺):BatchSendNotification、GetUnreadCount、BatchMarkAsRead、MarkAllAsRead、UpdateTemplate、DeleteTemplate - 即使忽略 ISSUE-009 的数量问题,两文档的 RPC 组合也不同 - **建议方案**:待 ISSUE-009 仲裁后,统一两文档 RPC 清单 -- **状态**:待 coord 仲裁(依赖 ISSUE-009) +- **状态**:已裁决(见 coord.md §10) ### ISSUE-015-ai10:msg_contract.md Kafka 发布事件与设计文档不一致 @@ -191,4 +191,4 @@ - 02-architecture-design.md §5.2:4 个 per-event topic(`edu.notification.sent` / `edu.notification.read` / `edu.notification.recalled` / `edu.notification.failed`) - matrix.md §4 L118:`edu.notification.requested`(第三种命名) - **建议方案**:待 ISSUE-008 仲裁 topic 命名约定后统一 -- **状态**:待 coord 仲裁(依赖 ISSUE-008) +- **状态**:已裁决(见 coord.md §10) diff --git a/docs/architecture/issues/objections/parent-bff_issue.md b/docs/architecture/issues/objections/parent-bff_issue.md index bc1cc33..c012efb 100644 --- a/docs/architecture/issues/objections/parent-bff_issue.md +++ b/docs/architecture/issues/objections/parent-bff_issue.md @@ -37,7 +37,7 @@ - U4(BFF 豁免 @RequirePermission):01 §6 表格"权限装饰器"行标"⚠️ 不对齐",未引用 U4 仲裁 - C1(错误码前缀 BFF_PARENT_):01 §3.3 仍用 `PARENT_BFF_` 旧前缀 - **建议方案**:01-understanding.md 头部更新为 ai05 复审版,同步 U3/U4/C1 仲裁结论;或由 coord 确认 01 作为"阶段 1 历史快照"保留原样,以 02 为准 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §20) ### ISSUE-002-ai05:02 文档内部 ChildGuard 缓存 TTL 不一致 @@ -50,7 +50,7 @@ - §13 #7 黄金模板对齐表:写 "30s" §3.1.1 表格未同步 §9 的调整,导致同一文档内 60s 与 30s 并存。 - **建议方案**:§3.1.1 表格 ChildGuard 行 TTL 改为 "30s",与 §9 #2 + §13 #7 一致 -- **状态**:待 coord 仲裁(ai05 建议直接修正,属于文档勘误) +- **状态**:已裁决(见 coord.md §20) ### ISSUE-003-ai05:contract.md 仲裁引用编号错误(I3 → I6) @@ -62,7 +62,7 @@ - I6 才是 "家长-学生关联:P2 即补全 iam_student_guardians 表 + GetChildrenByParent RPC" 裁决 - 全仓库未检索到 "ISSUE-047" 编号(grep 无结果),疑为虚构编号 - **建议方案**:contract.md 将 "I3/ISSUE-047 裁决" 修正为 "I6 裁决(coord-final-decisions.md §1)" -- **状态**:待 coord 仲裁(ai05 建议直接修正,属于引用勘误) +- **状态**:已裁决(见 coord.md §20) ### ISSUE-004-ai05:004 §4 服务依赖图与 matrix.md §1 未同步 C6 仲裁 @@ -75,7 +75,7 @@ - 02 §0.1 C6 行已标注 "004 §4 待 coord 同步更新",但至今未同步 此差异导致新接手的 AI 看 004/matrix 会误以为 parent-bff 不依赖 data-ana/msg,与 02 设计冲突。 - **建议方案**:coord 在 004 §4 服务依赖图补 `PBFF --> DataAna` + `PBFF --> Msg`,matrix.md §1 同步;更新 004 时按 project_rules §1 "改码必同步图" 执行 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §20) ### ISSUE-005-ai05:parent-portal 01 文档与 parent-bff GraphQL 决策跨模块冲突 @@ -89,7 +89,7 @@ - parent-portal §3.1 标 "BFF 对接:parent-bff(ai04 设计)",ai04 已过时(现 ai05) 此冲突若不解决,parent-portal(ai15)会按 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 仲裁 +- **状态**:已裁决(见 coord.md §20) ### ISSUE-006-ai05:proto 包名引用不一致(缺失 next_edu_cloud 前缀) @@ -103,7 +103,7 @@ - msg.proto: `package next_edu_cloud.msg.v1;` 引用不一致会导致 gRPC client 代码生成时 package 路径错误。 - **建议方案**:02 §3.3 DTO 映射表 proto message 列全部补 `next_edu_cloud.` 前缀;或确认是否统一去掉前缀(需 buf.yaml 配置一致) -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §20) ### ISSUE-007-ai05:GraphQL Notification.childId 字段在 msg.proto 缺失 @@ -125,7 +125,7 @@ ``` parent-bff 无法从 msg 服务获取通知关联的孩子 ID,影响"按孩子过滤通知"场景。 - **建议方案**:coord 协调 ai10 在 msg.proto Notification message 补 `string child_id = 9;` 字段(可选,非家长通知为空);或 parent-bff 从 notification.content 解析(脆弱,不推荐) -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §20) ### ISSUE-008-ai05:core_edu.proto 缺 ClassService,02 §7.1 列为已有 @@ -138,7 +138,7 @@ 1. coord 确认 ClassService 归属(core-edu 还是 classes 服务),补 proto 2. 02 §7.1 ClassService.GetClass 状态从 "✅ 已有" 改为 "❌ 待补" 3. 02 §3.3 补 Grade.score string→Float 转换规则说明 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §20) ### ISSUE-009-ai05:ai-allocation iam 责任方与 01/02 文档不一致 @@ -147,7 +147,7 @@ - **类型**:责任方引用过时 - **描述**:01-understanding.md §7.1/§7.3 多处提"推动 ai02 在 iam 补接口",02 §8.1 P0 阻塞项 + §14.1 P0-1 也标 iam 责任方为 "ai06(iam 现归属)" 但 §7.3 #1 仍标 ai02。实际 ai-allocation.md §3.2 确认 iam 归属 ai06。01 文档未同步。 - **建议方案**:01 §7.1/§7.3 将 "ai02" 改为 "ai06";02 §7.3 #1 同步 -- **状态**:待 coord 仲裁(ai05 建议直接修正,属于引用勘误) +- **状态**:已裁决(见 coord.md §20) ### ISSUE-010-ai05:02 缺少 ADR / NFR / 容量规划 / 威胁建模(业界规范差距) @@ -161,7 +161,7 @@ 4. **安全威胁建模缺失**:§6.2 列错误码但未做威胁建模(STRIDE)。家长场景涉及未成年人数据(COPPA/FERPA/PIPL),应补威胁模型。 5. **数据流图(DFD)缺失**:§1.2 只有 Dashboard 时序图,缺少 DFD 展示数据跨信任边界流动。 - **建议方案**:coord 确认是否在 02 补全上述章节,或作为 P6 硬化阶段补全;当前不阻塞 P4 实施 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §20) --- @@ -175,5 +175,5 @@ - **类型**:契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他 - **描述**:[详细描述问题] - **建议方案**:[AI 的建议] -- **状态**:待 coord 仲裁 / 已裁决(见 coord.md §X) +- **状态**:已裁决(见 coord.md §X) --> diff --git a/docs/architecture/issues/objections/parent-portal_issue.md b/docs/architecture/issues/objections/parent-portal_issue.md index 33f777b..4364e0d 100644 --- a/docs/architecture/issues/objections/parent-portal_issue.md +++ b/docs/architecture/issues/objections/parent-portal_issue.md @@ -45,7 +45,7 @@ - **类型**:契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他 - **描述**:[详细描述问题] - **建议方案**:[AI 的建议] -- **状态**:待 coord 仲裁 / 已裁决(见 coord.md §X) +- **状态**:已裁决(见 coord.md §X) --> ### ISSUE-001-ai15:01/02 文档 REST 消费 parent-bff 与 ARB-001 GraphQL 裁决冲突 @@ -63,7 +63,7 @@ 1. coord 确认 parent-portal 消费 parent-bff **统一用 GraphQL**(与 ARB-001、parent-bff contract、matrix.md 一致) 2. ai15 据此修订 01 §3.1(改为 GraphQL Query/Mutation 域)、§3.1.1(X-Fields 字段裁剪改为 GraphQL query 字段选择)、02 §4.1(`useParentApi` 改为 GraphQL hooks)、§4.2(TanStack Query 约定配合 GraphQL operations)、§11.3 未决设计决策 #2(移除,已裁决) 3. 若 coord 另有裁决(如 parent-portal 特殊走 REST),以 coord 裁决为准 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §22) ### ISSUE-002-ai15:MF shared 配置缺 urql/graphql/@edu/* 与 ARB-002 冲突 @@ -80,7 +80,7 @@ 1. coord 确认 parent-portal MF `shared` 必须包含 ARB-002 全部 7 项(react/react-dom/urql/graphql/@edu/ui-tokens/@edu/ui-components/@edu/hooks) 2. ai15 修订 02 §1.2 `shared` 配置 + 01 §4 技术栈表(新增 urql + GraphQL client 行) 3. 02 §4.1 `useParentApi` 改为从 Shell 暴露的 `useGraphQLClient()` 获取 urql client,不再用 REST ApiClient -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §22) ### ISSUE-003-ai15:switch-child 端点在 01/02 文档间不一致 @@ -96,7 +96,7 @@ 1. 若走 GraphQL(依 ISSUE-001 裁决):switch-child 应为 `mutation switchChild(childId: ID!): SwitchChildPayload!`,不存在 REST 路径 2. 若走 REST:统一为 `POST /api/v1/parent/switch-child`(body 携带 childId,与 02 一致),修订 01 §3.1 3. 请 coord 一并明确 parent-bff GraphQL schema 是否包含 `switchChild` Mutation(当前 parent-bff contract.md 未列) -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §22) ### ISSUE-004-ai15:登录端点在 01 / contract.md / matrix.md 间三方不一致 @@ -112,7 +112,7 @@ 1. 统一为 `POST /api/v1/iam/login`(与 matrix.md §5 + 01 §3.1 的 `/api/v1/iam/*` 前缀一致) 2. ai15 修订 contract.md §2.3 路径 3. 注意:登录是 parent-portal 唯一可能走 REST(非 GraphQL)的端点,因登录前无 JWT,GraphQL endpoint 需鉴权。请 coord 确认登录是否走 REST `/api/v1/iam/login`,其余走 GraphQL -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §22) ### ISSUE-005-ai15:02 §11.3 未决设计决策 #2 "GraphQL vs REST" 已由 ARB-001 裁决,应移除 @@ -126,7 +126,7 @@ - **建议方案**: 1. coord 确认 ARB-001 适用于 parent-portal(即 parent-portal P4 起必须用 GraphQL 消费 parent-bff) 2. ai15 移除 02 §11.3 第 2 项,改为 "已裁决:见 ARB-001,parent-portal 用 GraphQL 消费 parent-bff" -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §22) ### ISSUE-006-ai15:contract.md §1.2 将前端页面路由误标为 HTTP 端点 @@ -142,7 +142,7 @@ 1. coord 确认 parent-portal 作为前端 Remote,不对外提供 HTTP API 端点(§1.2 应为"无") 2. ai15 将 contract.md §1.2 改为 "无(parent-portal 是前端 Remote,不对外提供 HTTP API)",页面路由信息保留在 01 §8 L2 路由表中,不进 contract.md 3. 若需保留 MF 暴露信息,归入 §1.6 微前端架构(已有) -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §22) ### ISSUE-007-ai15:contract.md §1.6 module-federation.config.ts 与 02 next.config.js 不一致 @@ -156,7 +156,7 @@ - **建议方案**: 1. 统一为 `apps/parent-portal/next.config.js`(与 02 + teacher-portal Shell 一致,Next.js 项目 MF 配置应在 next.config.js) 2. ai15 修订 contract.md §1.6 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §22) ### ISSUE-008-ai15:contract.md §2.3 GraphQL 路径前缀与 matrix.md 不一致 @@ -170,7 +170,7 @@ - **建议方案**: 1. 统一为 `POST /api/v1/parent/graphql`(与 matrix.md §5 一致) 2. ai15 修订 contract.md §2.3 + §2.4 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §22) ### ISSUE-009-ai15:parent-bff GraphQL schema 是否包含 switchChild Mutation 未明确 @@ -186,7 +186,7 @@ 1. 请 coord 协调 ai05(parent-bff)确认:switchChild 是 GraphQL Mutation 还是纯前端状态(localStorage + Zustand) 2. 若纯前端:01/02 移除 `POST /parent/switch-child` 调用,改为 `useChildSwitcher` 直接写 Zustand + localStorage 3. 若需后端记录:请 ai05 在 parent-bff contract.md §1.3 补充 `switchChild` Mutation -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §22) ### ISSUE-010-ai15:iam GetChildrenByParent 接口缺失(P0 阻塞,跨模块) @@ -202,7 +202,7 @@ - **建议方案**: 1. coord 确认 ai06 补全 `GetChildrenByParent` 的时间点(应在 P4 启动前) 2. 在补全前,parent-portal 用 mock(固定 2 个子女)开发,mock 数据与 parent-bff mock 一致(student-001 + student-002) -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §22) --- diff --git a/docs/architecture/issues/objections/push-gateway_issue.md b/docs/architecture/issues/objections/push-gateway_issue.md index b4d83ef..099ff9b 100644 --- a/docs/architecture/issues/objections/push-gateway_issue.md +++ b/docs/architecture/issues/objections/push-gateway_issue.md @@ -49,7 +49,7 @@ 2. SSE 单向下行 + 文本协议,不适合未来 reconnect/ack 双向协议 3. 各 portal 已规划 WebSocket 接入([coord-cross-review.md](../../coord-cross-review.md)) - **影响方**:ai13/ai14/ai15(前端需统一走 WebSocket,移除 SSE 兜底)、ai10(msg 不需调 /sse)、coord(更新 matrix.md §5 与 contract.md) -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §17) ### ISSUE-002-ai02:内部 API 鉴权命名三方不一致 @@ -67,7 +67,7 @@ 2. "Token"语义比"Key"更准确(共享密钥而非公私钥对) 3. mTLS 在 P5 阶段引入成本过高,且 K8s 内网已有 NetworkPolicy 隔离,共享密钥足够 - **影响方**:ai10(msg 调用方需用相同头名)、coord(更新 contract.md 与 matrix.md §5 移除 mTLS) -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §17) ### ISSUE-003-ai02:单节点容量目标 50k vs 10w+ 冲突 @@ -83,7 +83,7 @@ 2. Go goroutine-per-connection + 64KB send chan 单连接约 20-30KB,10w 连接约 2-3GB,单节点可承载 3. 50k 目标过于保守,与横向扩展方案不匹配 - **影响方**:coord(更新 modules/README.md §7)、ai02(02 §11 已正确) -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §17) ### ISSUE-004-ai02:contract.md 内部端点路径 /internal/send vs /internal/push 冲突 @@ -112,7 +112,7 @@ 3. ai-allocation 表述过度,审计需求由 msg 满足 - **建议方案**:方案 2(审计由 msg 维护,push-gateway 仅同步返结果)。理由:保持 push-gateway 无 DB 定位,避免引入持久化层增加运维复杂度。 - **影响方**:ai10(msg 需确认审计字段是否覆盖 push-gateway 推送结果)、coord(澄清 ai-allocation §5 表述) -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §17) ### ISSUE-006-ai02:ISSUE-058 与 ISSUE-055 对 Redis /readyz 失败策略耦合冲突 @@ -128,7 +128,7 @@ 2. Redis 故障时单实例仍能服务本地连接(仅跨实例广播失效) 3. 雪崩风险高于短暂不一致 - **影响方**:coord(澄清两裁决优先级) -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §17) ### ISSUE-007-ai02:02 文档缺 ADR / 非功能性需求 / 失败模式章节(不符业界架构文档规范) diff --git a/docs/architecture/issues/objections/student-bff_issue.md b/docs/architecture/issues/objections/student-bff_issue.md index b8639e5..36acc59 100644 --- a/docs/architecture/issues/objections/student-bff_issue.md +++ b/docs/architecture/issues/objections/student-bff_issue.md @@ -56,7 +56,7 @@ - **不存在 §11.4 和 §11.5** - **影响**:错误码前缀 BFF_STUDENT_ 的权威来源应改为 [coord-final-decisions.md](../../coord-final-decisions.md) G14 + B5;ActionState 信封规范应改为 [coord-final-decisions.md](../../coord-final-decisions.md) G8 + F9 - **建议方案**:02 文档回写时修正引用源;coord 确认是否需要在 004 补充 §11.4/§11.5 章节,或统一指向 coord-final-decisions -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §19) ### ISSUE-STU-003-ai04:02 文档 §8.3 列 12 项未决决策,其中 8 项已裁决 diff --git a/docs/architecture/issues/objections/student-portal_issue.md b/docs/architecture/issues/objections/student-portal_issue.md index 7169f64..52cf10b 100644 --- a/docs/architecture/issues/objections/student-portal_issue.md +++ b/docs/architecture/issues/objections/student-portal_issue.md @@ -70,7 +70,7 @@ - 统一为 `POST /api/v1/student/graphql` - 由 ai01(api-gateway)确认路由:`/api/v1/student/*` → `student-bff:3009/*`(即 `/api/v1/student/graphql` → `student-bff:3009/graphql`) - 由 ai04(student-bff)确认 GraphQL endpoint 路径为 `POST /graphql`(与 teacher-bff 一致) -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §21) --- @@ -88,7 +88,7 @@ - 统一为 `packages/shared-ts/contracts/graphql/student-bff.graphql`(与 ARB-001 原则对齐,集中管理便于前端 codegen) - ai14 在 student-portal 端使用 `graphql-codegen` 从该 schema 生成 TypeScript 类型 - 由 ai04(student-bff)创建该 schema 文件并维护 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §21) --- @@ -109,7 +109,7 @@ - **离开页面策略**:visibilitychange hidden 触发时仅记录(不自动提交),累计 3 次警告后教师端可见 - **多标签检测**:警告 + 记录,不阻止作答(避免误伤合法场景如查词典) - **防作弊事件上报**:走 student-bff GraphQL mutation `recordExamViolation(examId, type, payload)`,由 ai04 在 P3 提供 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §21) --- @@ -127,7 +127,7 @@ - **主观题(简答/论述)**:允许粘贴,但记录粘贴事件 + 粘贴内容长度,教师端批改时可见 - **作文题**:允许粘贴(学生体验优先),不记录 - 由 ai04(student-bff)在 P3 提供 `recordPasteEvent` mutation(或复用 ISSUE-014-03 的 `recordExamViolation`,type=`PASTE`) -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §21) --- @@ -147,7 +147,7 @@ - **推荐 A**:走 api-gateway REST `POST /api/v1/student/upload` → 对象存储(MinIO/OSS),返回 signed URL,再走 GraphQL `submitHomework(attachmentUrls: [String!])` mutation 提交 - 理由:GraphQL 不适合大文件传输;REST + 对象存储是业界通用方案;api-gateway 已有 JWT 鉴权 - 由 ai01(api-gateway)确认是否提供 `/api/v1/student/upload` 路由,由 ai04(student-bff)确认 `submitHomework` mutation 是否接受 `attachmentUrls` 字段 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §21) --- @@ -167,7 +167,7 @@ - **题目重排**:P3 不实现(题目顺序固定),P4 评估是否需要实时重排 - **考试强制提交**:ai08 发布 `ExamForceSubmitted` 事件,student-portal 收到后立即触发提交流程 - 由 ai08(core-edu)确认事件命名,由 ai10(msg)确认推送路径 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §21) --- @@ -186,21 +186,21 @@ - **统一为方案 A**:student-bff 在 Resolver 层从 JWT `x-user-id` 提取 studentId,强制过滤,前端 query 不传 `studentId` 参数 - ai14 修改 02-architecture-design.md §4.2 的 GraphQL query 定义,移除 `studentId` 参数(如 `myClasses` 改为无参 query) - 由 ai04(student-bff)确认所有学生端 Query 均从 JWT 提取 studentId,不接受前端传入 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §21) --- ## §3 异议状态汇总 -| 编号 | 类型 | 标题 | 状态 | -| ------------ | ---------- | ------------------------------------------------------ | ------------- | -| ISSUE-014-01 | 契约不明确 | GraphQL endpoint 路径不一致 | 待 coord 仲裁 | -| ISSUE-014-02 | 契约不明确 | student-bff GraphQL schema 存放位置不一致 | 待 coord 仲裁 | -| ISSUE-014-03 | 契约不明确 | 考试作答页全屏策略与防作弊检测边界 | 待 coord 仲裁 | -| ISSUE-014-04 | 契约不明确 | 主观题粘贴策略(防作弊 vs 学生体验) | 待 coord 仲裁 | -| ISSUE-014-05 | 契约不明确 | 作业附件上传协议(GraphQL mutation vs REST multipart) | 待 coord 仲裁 | -| ISSUE-014-06 | 契约不明确 | 考试延长/题目重排等实时事件命名未确认 | 待 coord 仲裁 | -| ISSUE-014-07 | 契约不明确 | 学生端 DataScope L0 边界的强制执行层 | 待 coord 仲裁 | +| 编号 | 类型 | 标题 | 状态 | +| ------------ | ---------- | ------------------------------------------------------ | ------ | +| ISSUE-014-01 | 契约不明确 | GraphQL endpoint 路径不一致 | 已裁决 | +| ISSUE-014-02 | 契约不明确 | student-bff GraphQL schema 存放位置不一致 | 已裁决 | +| ISSUE-014-03 | 契约不明确 | 考试作答页全屏策略与防作弊检测边界 | 已裁决 | +| ISSUE-014-04 | 契约不明确 | 主观题粘贴策略(防作弊 vs 学生体验) | 已裁决 | +| ISSUE-014-05 | 契约不明确 | 作业附件上传协议(GraphQL mutation vs REST multipart) | 已裁决 | +| ISSUE-014-06 | 契约不明确 | 考试延长/题目重排等实时事件命名未确认 | 已裁决 | +| ISSUE-014-07 | 契约不明确 | 学生端 DataScope L0 边界的强制执行层 | 已裁决 | --- @@ -214,5 +214,5 @@ - **类型**:契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他 - **描述**:[详细描述问题] - **建议方案**:[AI 的建议] -- **状态**:待 coord 仲裁 / 已裁决(见 coord.md §X) +- **状态**:已裁决(见 coord.md §X) --> diff --git a/docs/architecture/issues/objections/teacher-bff_issue.md b/docs/architecture/issues/objections/teacher-bff_issue.md index 24146bc..6fde585 100644 --- a/docs/architecture/issues/objections/teacher-bff_issue.md +++ b/docs/architecture/issues/objections/teacher-bff_issue.md @@ -18,7 +18,7 @@ - **类型**:契约不明确 / 工作量超批 / 前置依赖缺失 / 编号冲突 / 其他 - **描述**:[详细描述问题] - **建议方案**:[AI 的建议] -- **状态**:待 coord 仲裁 / 已裁决(见 coord.md §X) +- **状态**:已裁决(见 coord.md §X) --> ### ISSUE-001-ai03:admin 命名空间 P2 预留与 ARB-001 "P2 不包含" 冲突 @@ -28,7 +28,7 @@ - **类型**:契约不明确 - **描述**:coord.md ARB-001 §1.3 关键裁决表写 "admin 命名空间 | **P2 不包含**,P6 admin-portal 阶段新增 `admin` 命名空间";但 president-final-rulings.md §5.1(ISSUE-044)裁决 "ai03 P2 预留 admin schema 命名空间(如 `admin.*` Query/Mutation)",且 §7.3 ai03 工作清单明确 "批次 1(P2):Must Have 13 项 + DownstreamClient 抽象 + admin schema 命名空间预留"。两处对 P2 admin 命名空间的要求不一致——总裁裁决要求 P2 预留(schema 中声明占位),coord 仲裁说 P2 不包含。 - **建议方案**:以总裁裁决为准(裁决优先级 president > coord),修正 ARB-001 §1.3 为 "P2 预留 admin 命名空间占位(schema 中声明 `admin` Query/Mutation 类型骨架,无实际 Resolver),P6 admin-portal 阶段实现具体 Resolver"。ai03 在 P2 schema 第一版中预留 `admin` 命名空间类型声明。 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §18) ### ISSUE-002-ai03:P2 dashboard classes 数据来源与 ARB-001 §1.4 调用链冲突 @@ -40,7 +40,7 @@ 2. **B2 裁决约束**:coord-final-decisions.md B2 裁决 "首次实现即 gRPC 调用下游",若 classes P2 无 gRPC,teacher-bff 不能用 REST 调 classes(B2 禁止 REST 过渡)。 3. **president §3.5 功能范围**:president-final-rulings.md §3.5 裁决 P2 实现 "班级列表(iam 数据)",即 P2 班级列表数据来自 iam,不是 classes 服务。 - **建议方案**:采纳 president §3.5,P2 dashboard 的 classes 数据从 iam gRPC 获取(iam `GetEffectiveAccess` 或 `GetViewports` 返回的关联班级),不调 classes 服务。ARB-001 §1.4 第 4 条修正为 "dashboard Resolver 并行调用 iam gRPC(GetUserInfo + GetViewports + GetEffectiveAccess),classes 列表从 iam 返回数据推导,P3 core-edu gRPC 就绪后切换为 `GetClassesByTeacher` RPC"。这样 P2 不依赖 classes gRPC,与 B2 + president §3.5 一致。 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §18) ### ISSUE-003-ai03:GraphQL schema 文件命名不一致(ARB-001 vs president §2.17) @@ -54,6 +54,6 @@ ai03 创建文件时无法确定用哪个文件名。 - **建议方案**:以 president §2.17 为准(裁决优先级 president > coord),统一为 `teacher-bff.schema.graphql`。coord 修正 ARB-001 §1.3/§1.4 文件名。 -- **状态**:待 coord 仲裁 +- **状态**:已裁决(见 coord.md §18) --- diff --git a/docs/architecture/roadmap/integration-test-phase.md b/docs/architecture/roadmap/integration-test-phase.md new file mode 100644 index 0000000..9009bd5 --- /dev/null +++ b/docs/architecture/roadmap/integration-test-phase.md @@ -0,0 +1,160 @@ +# 集成测试与部署验证阶段(P7) + +> 日期:2026-07-10 +> 前置条件:所有模块 P2-P6 代码完成,lint/typecheck/go vet/ruff 全通过,ARB-001~022 全部已裁决 +> 目标:从"代码完成"到"系统可用",验证端到端功能链路 + +--- + +## 1. 阶段概述 + +15 AI 全并行开发模式下,各模块独立编码,使用 mock 桩进行本地验证。本阶段目标是**将所有模块集成到真实基础设施中,验证端到端功能链路**。 + +### 前置状态 + +| 检查项 | 状态 | +| ------------------------------------ | --------------------------- | +| lint(pnpm run lint) | ✅ 全通过 | +| typecheck(pnpm run typecheck) | ✅ 16 包/服务全通过 | +| go vet(api-gateway + push-gateway) | ✅ 全通过 | +| ruff check(ai + data-ana) | ✅ 全通过 | +| proto 契约(buf lint) | ✅ 通过 | +| 仲裁(ARB-001~022) | ✅ 95 条全部已裁决 | +| packages/contracts | ✅ 已建立(ADMIN_* 权限点) | + +### 当前差距 + +- 各模块使用 mock 桩,尚未在真实 gRPC/MySQL/Redis/Kafka 环境中验证 +- 服务间 gRPC 调用链路未实际跑通 +- 前端与 BFF 的 GraphQL 通信未端到端验证 +- Docker Compose 全量部署未验证 +- 健康检查端点(/healthz + /readyz)未在容器环境验证 + +--- + +## 2. 阶段任务分解 + +### 批次 0:基础设施就绪 + +**目标**:确保 Docker Compose 全量基础设施可启动。 + +| 任务 | 验证标准 | +| -------------------------------------------------------- | ----------------------------------------- | +| MySQL + Redis + Kafka + Neo4j + ClickHouse + ES 容器健康 | `docker compose up -d` 全量容器 `healthy` | +| 数据库 schema 初始化脚本 | 各服务 schema 迁移脚本可执行 | +| Kafka topic 创建脚本 | 全部 topic(ARB-013 命名)可创建 | +| Debezium CDC connector 配置 | MySQL → Kafka CDC 链路通畅 | + +### 批次 1:后端服务启动 + +**目标**:每个后端服务能在 Docker 环境中启动并通过健康检查。 + +| 服务 | 端口 | 验证标准 | +| ----------------------------- | ---- | ---------------------- | +| api-gateway(Go) | 8080 | /healthz 返回 200 | +| push-gateway(Go) | 8081 | /healthz 返回 200 | +| iam(TS/gRPC 50052) | 3001 | /healthz + gRPC 可连接 | +| classes(TS) | 3002 | /healthz 返回 200 | +| core-edu(TS/gRPC 50053) | 3004 | /healthz + gRPC 可连接 | +| content(TS/gRPC 50054) | 3005 | /healthz + gRPC 可连接 | +| msg(TS/gRPC 50056) | 3006 | /healthz + gRPC 可连接 | +| data-ana(Python/gRPC 50055) | 3007 | /healthz + gRPC 可连接 | +| ai(Python/gRPC 50058) | 3008 | /healthz + gRPC 可连接 | + +### 批次 2:BFF 层启动 + +**目标**:3 个 BFF 能启动并连接下游 gRPC 服务。 + +| 服务 | 端口 | 验证标准 | +| ---------------------- | ---- | -------------------------- | +| teacher-bff(GraphQL) | 3003 | /graphql Playground 可访问 | +| student-bff(GraphQL) | 3009 | /graphql Playground 可访问 | +| parent-bff(GraphQL) | 3010 | /graphql Playground 可访问 | + +### 批次 3:前端启动 + +**目标**:4 个前端能启动并连接对应 BFF。 + +| 应用 | 端口 | 验证标准 | +| -------------- | ---- | ------------ | +| teacher-portal | 4000 | 登录页可访问 | +| student-portal | 4001 | 登录页可访问 | +| parent-portal | 4002 | 登录页可访问 | +| admin-portal | 4003 | 登录页可访问 | + +### 批次 4:端到端功能验证 + +**目标**:核心业务链路端到端跑通。 + +| 链路 | 涉及服务 | 验证标准 | +| -------- | --------------------------------------- | ------------------------------ | +| 教师登录 | teacher-portal → api-gateway → iam | 获取 JWT → 侧边栏按角色渲染 | +| 创建考试 | teacher-portal → teacher-bff → core-edu | 考试落库 → Outbox 事件 → Kafka | +| 学生作答 | student-portal → student-bff → core-edu | 提交落库 → 事件发布 | +| 教师批改 | teacher-portal → teacher-bff → core-edu | 成绩落库 → GradeReleased 事件 | +| 学情分析 | student-portal → student-bff → data-ana | ClickHouse 宽表查询 < 5s | +| 知识图谱 | teacher-portal → teacher-bff → content | Neo4j 查询秒级返回 | +| 消息推送 | msg → push-gateway → WebSocket | 在线学生实时收到通知 | +| AI 辅助 | teacher-portal → teacher-bff → ai | 流式 SSE 正常返回 | + +### 批次 5:可观测性验证 + +**目标**:三支柱(日志 + 指标 + 链路)在集成环境中可用。 + +| 检查项 | 验证标准 | +| --------------- | --------------------------------------- | +| Prometheus 抓取 | 所有服务 /metrics 端点可抓取 | +| Grafana 面板 | 核心指标面板可查看 | +| 全链路 trace | 一个请求的 trace 可在 Jaeger 追踪全链路 | +| 结构化日志 | 所有服务日志 JSON 格式输出到 stdout | + +--- + +## 3. 执行策略 + +### 并行度 + +``` +批次 0(基础设施) → 批次 1(后端) → 批次 2(BFF) → 批次 3(前端) → 批次 4(E2E) → 批次 5(可观测性) + | | | | | | + 独立 9 服务并行 3 BFF 并行 4 前端并行 8 链路并行 独立 +``` + +### 问题修复策略 + +- 发现的问题记录到 `docs/troubleshooting/known-issues.md` 对应模块分区 +- 跨模块问题通过 `docs/architecture/issues/objections/[模块名]_issue.md` 提请仲裁 +- coord 负责仲裁,开发 AI 在各自分支修复 + +### 风险点 + +| 风险 | 影响 | 缓解策略 | +| ----------------------------- | ---------------- | ---------------------------- | +| gRPC proto 生成代码版本不一致 | 服务间调用失败 | 批次 1 统一 `buf generate` | +| MySQL schema 冲突 | 数据库初始化失败 | 批次 0 逐服务验证 schema | +| Kafka topic 命名不一致 | 消费者收不到事件 | 对照 ARB-013 统一检查 | +| 端口冲突 | 服务无法启动 | 对照 port-allocation.md 检查 | +| 前端 MF 配置不匹配 | 微前端加载失败 | 批次 3 验证 MF config | + +--- + +## 4. 验收标准 + +| 验收项 | 标准 | +| ----------------------- | -------------------------------------- | +| Docker Compose 全量启动 | 所有容器 `healthy` | +| 核心链路 E2E | 8 条核心链路全部跑通 | +| 健康检查 | 所有服务 /healthz + /readyz 返回 200 | +| 可观测性 | Prometheus + Grafana + Jaeger 数据可见 | +| 错误处理 | ActionState 信封格式一致 | +| 权限校验 | 未授权请求返回 401/403 | + +--- + +## 5. 退出标准 + +- 全量 Docker Compose 启动成功 +- 8 条核心业务链路端到端跑通 +- 三支柱可观测性可用 +- 无阻塞性 bug +- 打 tag `v0.6.0-integration`