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,16 +10,16 @@
|
||||
|
||||
### 1.1 ARB-001（teacher-bff GraphQL schema 第一版）对 student-portal 的影响核查
|
||||
|
||||
| 裁决点 | 对 student-portal 的适用性 | ai14 落实方案 | 状态 |
|
||||
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------ |
|
||||
| Schema 存放位置 | ✅ 适用（原则一致）。student-bff GraphQL schema 应存放于 `packages/shared-ts/contracts/graphql/student-bff.graphql`（集中管理，与 teacher-bff 同源） | ai14 在 contract.md §1.3 已标注预期路径；实际由 ai04 创建，ai14 仅消费 | ⏳ 待 ai04 |
|
||||
| P2 Query 范围 | ⚠️ 部分参考。ARB-001 是 teacher-bff 的 P2 范围；student-portal 起步于 P3（不在 P2），因此 student-bff 直接以 P3 全量 Query 起步 | ai14 在 P3 直接消费 student-bff 全量 Query（currentUser/myClasses/myExams/myHomework/myGrades/myAttendance/studentDashboard） | ✅ 已落实 |
|
||||
| P2 Mutation 范围 | ⚠️ 部分参考。student-portal P3 起步即需要 submitHomework mutation（作业提交是 P3 核心场景） | ai14 P3 即消费 submitHomework mutation；ai04 P3 必须提供 | ⏳ 待 ai04 |
|
||||
| DataLoader 防 N+1 | ✅ 适用。student-bff 聚合多 gRPC 时（如 studentDashboard 聚合 iam+core-edu+data-ana）必须使用 DataLoader | ai14 不直接实现，但依赖 student-bff 返回结构稳定（无 N+1 慢查询） | ⏳ 待 ai04 |
|
||||
| 复杂度限制（depth ≤ 7） | ✅ 适用。student-portal 发起的 GraphQL query 深度必须 ≤ 7 | ai14 在 [02-architecture-design.md §4.2](../../../apps/student-portal/docs/02-architecture-design.md) 已设计扁平 query | ✅ 已落实 |
|
||||
| ActionState 信封 | ✅ 适用。student-bff 必须返回 ActionState 信封（success/errors/data） | ai14 在 GraphQL 请求层（02 §3.2）已处理信封解包 + 降级字段识别 | ✅ 已落实 |
|
||||
| 降级模式（方案 B） | ✅ 适用。部分聚合失败时 success=true + data 内 `extensions.degraded: true` | ai14 在 [02 §18.2 降级策略矩阵](../../../apps/student-portal/docs/02-architecture-design.md) 已设计 12 个降级场景 | ✅ 已落实 |
|
||||
| admin 命名空间 | ❌ 不适用。student-portal 不涉及 admin 命名空间 | - | - |
|
||||
| 裁决点 | 对 student-portal 的适用性 | ai14 落实方案 | 状态 |
|
||||
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------- |
|
||||
| Schema 存放位置 | ✅ 适用（原则一致）。student-bff GraphQL schema 应存放于 `packages/shared-ts/contracts/graphql/student-bff.graphql`（集中管理，与 teacher-bff 同源） | ai14 在 contract.md §1.3 已标注预期路径；实际由 ai04 创建，ai14 仅消费 | ⏳ 待 ai04 |
|
||||
| P2 Query 范围 | ⚠️ 部分参考。ARB-001 是 teacher-bff 的 P2 范围；student-portal 起步于 P3（不在 P2），因此 student-bff 直接以 P3 全量 Query 起步 | ai14 在 P3 直接消费 student-bff 全量 Query（currentUser/myClasses/myExams/myHomework/myGrades/myAttendance/studentDashboard） | ✅ 已落实 |
|
||||
| P2 Mutation 范围 | ⚠️ 部分参考。student-portal P3 起步即需要 submitHomework mutation（作业提交是 P3 核心场景） | ai14 P3 即消费 submitHomework mutation；ai04 P3 必须提供 | ⏳ 待 ai04 |
|
||||
| DataLoader 防 N+1 | ✅ 适用。student-bff 聚合多 gRPC 时（如 studentDashboard 聚合 iam+core-edu+data-ana）必须使用 DataLoader | ai14 不直接实现，但依赖 student-bff 返回结构稳定（无 N+1 慢查询） | ⏳ 待 ai04 |
|
||||
| 复杂度限制（depth ≤ 7） | ✅ 适用。student-portal 发起的 GraphQL query 深度必须 ≤ 7 | ai14 在 [02-architecture-design.md §4.2](../../../apps/student-portal/docs/02-architecture-design.md) 已设计扁平 query | ✅ 已落实 |
|
||||
| ActionState 信封 | ✅ 适用。student-bff 必须返回 ActionState 信封（success/errors/data） | ai14 在 GraphQL 请求层（02 §3.2）已处理信封解包 + 降级字段识别 | ✅ 已落实 |
|
||||
| 降级模式（方案 B） | ✅ 适用。部分聚合失败时 success=true + data 内 `extensions.degraded: true` | ai14 在 [02 §18.2 降级策略矩阵](../../../apps/student-portal/docs/02-architecture-design.md) 已设计 12 个降级场景 | ✅ 已落实 |
|
||||
| admin 命名空间 | ❌ 不适用。student-portal 不涉及 admin 命名空间 | - | - |
|
||||
|
||||
**核查结论**：ARB-001 是 teacher-bff 的 P2 仲裁，但其设计原则（Schema 集中管理、ActionState 信封、降级模式方案 B、复杂度限制）适用于所有 BFF，student-portal 已在 02-architecture-design.md v2 中全面落实。
|
||||
|
||||
@@ -27,17 +27,17 @@
|
||||
|
||||
### 1.2 ARB-002（MF Shell 暴露清单）对 student-portal 的影响核查
|
||||
|
||||
| 裁决点 | 对 student-portal 的适用性 | ai14 落实方案 | 状态 |
|
||||
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
|
||||
| Shell 身份 | ✅ 适用。teacher-portal 是 MF Shell，student-portal 是 P3 首个 Remote | ai14 在 [02 §3.2 MF 配置](../../../apps/student-portal/docs/02-architecture-design.md) 已声明 `remotes: { teacher: 'teacher@http://localhost:4000/_next/static/chunks/remoteEntry.js' }` | ✅ 已落实 |
|
||||
| P3 首个 Remote | ✅ 适用。ARB-002 §2.3 明确 P3 首个 Remote 是 student-portal | ai14 P3 任务启动即接入 MF Remote | ✅ 已落实 |
|
||||
| GraphQL client 归属 | ✅ 适用。Shell 暴露 GraphQLProvider，student-portal 复用，**不重复创建 client** | ai14 在 [02 §3.2 GraphQL 请求层](../../../apps/student-portal/docs/02-architecture-design.md) 已使用 `useGraphQLClient()` 从 `@edu/hooks` 获取 | ✅ 已落实 |
|
||||
| MF shared singleton 配置 | ✅ 适用。student-portal 必须将 react/react-dom/urql/graphql/@edu/* 声明为 singleton | ai14 在 [02 §3.2 next.config.js](../../../apps/student-portal/docs/02-architecture-design.md) 已声明全部 singleton | ✅ 已落实 |
|
||||
| AppShell 复用 | ✅ 适用。student-portal 不重复实现 AppShell，复用 Shell 暴露的 AppShell | ai14 在 02 §3.2 已设计 `<AppShell>` 包裹 + 学生端导航覆写 | ✅ 已落实 |
|
||||
| useAuth / usePermission 复用 | ✅ 适用。student-portal 复用 Shell 暴露的 useAuth/usePermission | ai14 在 [01-understanding.md §6](../../../apps/student-portal/docs/01-understanding.md) 已声明权限校验走 usePermission | ✅ 已落实 |
|
||||
| ErrorBoundary / Loading / Empty 复用 | ✅ 适用。student-portal 复用 Shell 暴露的共享 UI 组件 | ai14 在 02 §6 组件设计已使用 `@edu/ui-components` | ✅ 已落实 |
|
||||
| feature flag | ✅ 适用。`NEXT_PUBLIC_MF_ENABLED` 控制是否走 MF；P3 默认 true | ai14 在 02 §3.2 已设计独立壳回退（MF 关闭时独立渲染） | ✅ 已落实 |
|
||||
| 登录页 | ✅ 适用。P2 登录页由 Shell 独占；student-portal 不实现登录页，未登录跳转 Shell `/login` | ai14 在 02 §3.2 已设计未认证 → 跳转 `window.location.href = 'http://localhost:4000/login?redirect=student'` | ✅ 已落实 |
|
||||
| 裁决点 | 对 student-portal 的适用性 | ai14 落实方案 | 状态 |
|
||||
| ------------------------------------ | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
|
||||
| Shell 身份 | ✅ 适用。teacher-portal 是 MF Shell，student-portal 是 P3 首个 Remote | ai14 在 [02 §3.2 MF 配置](../../../apps/student-portal/docs/02-architecture-design.md) 已声明 `remotes: { teacher: 'teacher@http://localhost:4000/_next/static/chunks/remoteEntry.js' }` | ✅ 已落实 |
|
||||
| P3 首个 Remote | ✅ 适用。ARB-002 §2.3 明确 P3 首个 Remote 是 student-portal | ai14 P3 任务启动即接入 MF Remote | ✅ 已落实 |
|
||||
| GraphQL client 归属 | ✅ 适用。Shell 暴露 GraphQLProvider，student-portal 复用，**不重复创建 client** | ai14 在 [02 §3.2 GraphQL 请求层](../../../apps/student-portal/docs/02-architecture-design.md) 已使用 `useGraphQLClient()` 从 `@edu/hooks` 获取 | ✅ 已落实 |
|
||||
| MF shared singleton 配置 | ✅ 适用。student-portal 必须将 react/react-dom/urql/graphql/@edu/* 声明为 singleton | ai14 在 [02 §3.2 next.config.js](../../../apps/student-portal/docs/02-architecture-design.md) 已声明全部 singleton | ✅ 已落实 |
|
||||
| AppShell 复用 | ✅ 适用。student-portal 不重复实现 AppShell，复用 Shell 暴露的 AppShell | ai14 在 02 §3.2 已设计 `<AppShell>` 包裹 + 学生端导航覆写 | ✅ 已落实 |
|
||||
| useAuth / usePermission 复用 | ✅ 适用。student-portal 复用 Shell 暴露的 useAuth/usePermission | ai14 在 [01-understanding.md §6](../../../apps/student-portal/docs/01-understanding.md) 已声明权限校验走 usePermission | ✅ 已落实 |
|
||||
| ErrorBoundary / Loading / Empty 复用 | ✅ 适用。student-portal 复用 Shell 暴露的共享 UI 组件 | ai14 在 02 §6 组件设计已使用 `@edu/ui-components` | ✅ 已落实 |
|
||||
| feature flag | ✅ 适用。`NEXT_PUBLIC_MF_ENABLED` 控制是否走 MF；P3 默认 true | ai14 在 02 §3.2 已设计独立壳回退（MF 关闭时独立渲染） | ✅ 已落实 |
|
||||
| 登录页 | ✅ 适用。P2 登录页由 Shell 独占；student-portal 不实现登录页，未登录跳转 Shell `/login` | ai14 在 02 §3.2 已设计未认证 → 跳转 `window.location.href = 'http://localhost:4000/login?redirect=student'` | ✅ 已落实 |
|
||||
|
||||
**核查结论**：ARB-002 是 student-portal 接入 MF 的直接依据，ai14 已在 02-architecture-design.md v2 中全面落实。无异议。
|
||||
|
||||
@@ -45,8 +45,8 @@
|
||||
|
||||
### 1.3 ARB-001 / ARB-002 核查总结
|
||||
|
||||
| 仲裁 | 对 student-portal 的影响 | ai14 落实情况 | 异议 |
|
||||
| ------ | ------------------------ | ------------- | ---- |
|
||||
| 仲裁 | 对 student-portal 的影响 | ai14 落实情况 | 异议 |
|
||||
| ------- | ------------------------------------------------ | ------------- | ---- |
|
||||
| ARB-001 | 设计原则适用（GraphQL + ActionState + 降级模式） | ✅ 已落实 | 无 |
|
||||
| ARB-002 | 直接适用（P3 首个 Remote + Shell 暴露清单） | ✅ 已落实 | 无 |
|
||||
|
||||
@@ -192,15 +192,31 @@
|
||||
|
||||
## §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 路径不一致 | ✅ 已裁决（见 coord.md §21 ARB-019） |
|
||||
| ISSUE-014-02 | 契约不明确 | student-bff GraphQL schema 存放位置不一致 | ✅ 已裁决（见 coord.md §21 ARB-019） |
|
||||
| ISSUE-014-03 | 契约不明确 | 考试作答页全屏策略与防作弊检测边界 | ✅ 已裁决（见 coord.md §21 ARB-019） |
|
||||
| ISSUE-014-04 | 契约不明确 | 主观题粘贴策略（防作弊 vs 学生体验） | ✅ 已裁决（见 coord.md §21 ARB-019） |
|
||||
| ISSUE-014-05 | 契约不明确 | 作业附件上传协议（GraphQL mutation vs REST multipart） | ✅ 已裁决（见 coord.md §21 ARB-019） |
|
||||
| ISSUE-014-06 | 契约不明确 | 考试延长/题目重排等实时事件命名未确认 | ✅ 已裁决（见 coord.md §21 ARB-019） |
|
||||
| ISSUE-014-07 | 契约不明确 | 学生端 DataScope L0 边界的强制执行层 | ✅ 已裁决（见 coord.md §21 ARB-019） |
|
||||
|
||||
---
|
||||
|
||||
## §4 仲裁结论（coord 2026-07-10）
|
||||
|
||||
> 详见 [coord.md §21 ARB-019](../coord.md) 完整仲裁章节
|
||||
|
||||
| ISSUE | 仲裁结论摘要 | 执行方 |
|
||||
| ------ | ---------------------------------------------------------------------------------------------- | -------------------------------- |
|
||||
| 014-01 | 统一为 `POST /api/v1/student/graphql`（双 /v1 前缀，对齐 ARB-014 方案 A） | ai14 修 contract + ai01 确认路由 |
|
||||
| 014-02 | 统一为 `packages/shared-ts/contracts/graphql/student-bff.schema.graphql` | ai04 创建并维护 |
|
||||
| 014-03 | P3 不强制全屏 + visibilitychange 仅记录 + 多标签警告不阻止 + recordExamViolation mutation | ai14 + ai04 + ai08 补 RPC |
|
||||
| 014-04 | 客观题禁止 / 主观题允许记录 / 作文题允许不记录；复用 recordExamViolation（type=PASTE） | ai14 + ai04 |
|
||||
| 014-05 | 方案 A：api-gateway REST `POST /api/v1/student/upload` → 对象存储 → GraphQL mutation 提交 URL | ai01 路由 + ai04 mutation |
|
||||
| 014-06 | ExamExtended + ExamForceSubmitted（ai08 发布到 `edu.exam.events`）；题目重排 P3 不实现 P4 评估 | ai08 发布 + ai10 推送 |
|
||||
| 014-07 | 方案 A：student-bff Resolver 从 JWT x-user-id 提取 studentId，前端 query 不传 studentId | ai14 修 query 设计 + ai04 实现 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user