diff --git a/docs/architecture/issues/contracts/student-portal_contract.md b/docs/architecture/issues/contracts/student-portal_contract.md index c30a153..1f74d03 100644 --- a/docs/architecture/issues/contracts/student-portal_contract.md +++ b/docs/architecture/issues/contracts/student-portal_contract.md @@ -41,7 +41,7 @@ 不适用。student-portal 消费 student-bff GraphQL，自身不提供 schema。 -> **消费的 schema 文件**：`packages/shared-ts/contracts/graphql/student-bff.graphql`（待 ISSUE-014-02 仲裁后由 ai04 创建，对齐 ARB-001 §1.3 集中管理原则） +> **消费的 schema 文件**：`packages/shared-ts/contracts/graphql/student-bff.graphql`（已裁决 ARB-019 §21，由 ai04 创建，对齐 ARB-001 §1.3 集中管理原则） ### 1.4 Kafka 事件发布（如有） @@ -67,7 +67,7 @@ | 端点 | 用途 | 认证 | 事件类型 | | --------------------- | ----------------------- | ---- | ------------------------------------------------------------------------ | -| `ws://push-gateway:8081/ws` | 实时通知推送 | JWT | 作业通知 / 考试通知 / 成绩通知 / 系统通知 / 考试延长（待 ISSUE-014-06 仲裁） / 考试强制提交（待 ISSUE-014-06 仲裁） | +| `ws://push-gateway:8081/ws` | 实时通知推送 | JWT | 作业通知 / 考试通知 / 成绩通知 / 系统通知 / 考试延长（ExamExtended） / 考试强制提交（ExamForceSubmitted）（ARB-019 §21.6 已裁决） | --- @@ -87,7 +87,7 @@ | ------------------- | ------------------------------ | --------------------------------------------- | ----------------------------------------------------------------- | | api-gateway (ai01) | POST /api/v1/student/graphql | 学生 GraphQL 查询（经网关代理到 student-bff :3009/graphql） | api-gateway/student-bff 就绪前使用 MSW 拦截返回 mock GraphQL 响应 | | api-gateway (ai01) | POST /api/auth/login | 学生登录（Shell 独占，student-portal 不直接调用，仅跳转） | api-gateway 就绪前由 Shell 处理 | -| api-gateway (ai01) | POST /api/v1/student/upload | 作业附件上传（待 ISSUE-014-05 仲裁） | 待仲裁后实现 | +| api-gateway (ai01) | POST /api/v1/student/upload | 作业附件上传（ARB-019 §21.5 方案 A） | 按方案 A 实现：REST + 对象存储 + GraphQL 提交 URL | | push-gateway (ai02) | GET /ws（WebSocket） | WebSocket 实时通知 | push-gateway 就绪前使用 mock-socket 模拟 WS 推送 | > **路径说明**（ISSUE-014-01）： @@ -129,8 +129,8 @@ | saveExamDraft(input: SaveExamDraftInput!) | 保存考试草稿 | MSW 返回 success=true | | markAsRead(notificationId: ID!) | 标记通知已读 | MSW 返回 success=true | | markAllAsRead | 全部标记已读 | MSW 返回 success=true | -| recordExamViolation(input: RecordExamViolationInput!) | 记录防作弊违规（待 ISSUE-014-03 仲裁） | MSW 返回 success=true | -| recordPasteEvent(input: RecordPasteEventInput!) | 记录粘贴事件（待 ISSUE-014-04 仲裁） | MSW 返回 success=true | +| recordExamViolation(input: RecordExamViolationInput!) | 记录防作弊违规（ARB-019 §21.4） | MSW 返回 success=true | +| recordPasteEvent(input: RecordPasteEventInput!) | 记录粘贴事件（ARB-019 §21.4） | MSW 返回 success=true | | updateNotificationPreference(input: UpdateNotificationPreferenceInput!) | 更新通知偏好（P5） | MSW 返回 success=true | > **DataScope L0 强制执行**（ISSUE-014-07）： @@ -149,7 +149,7 @@ | teacher-portal MF Shell（ai13 P2）| exposes AppShell/GraphQLProvider/useGraphQLClient/useAuth/usePermission + shared singleton | P2 启动 | ⏳ 待 ai13 P2 | | api-gateway HTTP :8080（ai01 P3） | `/api/v1/student/*` 反向代理 student-bff 可用 | P3 启动 | ⏳ 待 ai01 P3 | | student-bff GraphQL（ai04 P3） | `POST /graphql` :3009 + 核心 Query/Mutation 可执行 | P3 启动 | ⏳ 待 ai04 P3 | -| student-bff GraphQL schema | `packages/shared-ts/contracts/graphql/student-bff.graphql` 创建（待 ISSUE-014-02 仲裁） | P3 启动 | ⏳ 待仲裁 | +| student-bff GraphQL schema | `packages/shared-ts/contracts/graphql/student-bff.graphql` 创建（ARB-019 §21 已裁决） | P3 启动 | ✅ 已裁决 | | core-edu gRPC 50053（ai08 P3） | ExamService/HomeworkService/GradeService/AttendanceService/ClassService | P3 启动 | ⏳ 待 ai08 P3 | | iam gRPC 50052（ai06 P2） | GetUserInfo + GetEffectivePermissions + GetViewports | P3 启动 | ⏳ 待 ai06 P2 | | content gRPC 50054（ai09 P4） | TextbookService + ChapterService + KnowledgeGraphService | P4 启动 | ⏳ 待 ai09 P4 | @@ -189,14 +189,14 @@ student-portal 是前端，无下游消费方。但对开发体验提供： - `POST /api/v1/student/graphql` → 按 operationName 返回对应 mock 响应（见 §2.4） - `POST /api/auth/login` → 返回固定 JWT + UserInfo（student 角色）由 Shell 处理 -- `POST /api/v1/student/upload` → 返回固定 signed URL（待 ISSUE-014-05 仲裁后实现） +- `POST /api/v1/student/upload` → 返回固定 signed URL（ARB-019 §21.5 方案 A 已裁决） - 所有 mock 响应定义在 `apps/student-portal/src/mocks/fixtures/*.json` #### 4.2.2 WebSocket mock（mock-socket） - 连接 `ws://localhost:8081/ws` 后每 30 秒推送 1 条 mock 通知 - 通知类型轮询：作业通知 / 考试通知 / 成绩通知 / 系统通知 -- 支持模拟考试延长事件（待 ISSUE-014-06 仲裁后实现） +- 支持模拟考试延长事件 ExamExtended + 考试强制提交 ExamForceSubmitted（ARB-019 §21.6 已裁决） #### 4.2.3 JWT mock @@ -223,13 +223,13 @@ student-portal 是前端，无下游消费方。但对开发体验提供： | 对齐项 | student-portal 期望 | student-bff 提供 | 状态 | | ----------------------- | ---------------------------------------------------- | ----------------------------------------------------------------- | ---- | | GraphQL endpoint | `POST /api/v1/student/graphql`（经 api-gateway 代理）| `POST /graphql` :3009 | ✅ 对齐（api-gateway 代理） | -| GraphQL schema 文件 | `packages/shared-ts/contracts/graphql/student-bff.graphql` | `apps/student-bff/src/schema/*.graphql`（待 ISSUE-014-02 仲裁） | ⏳ 待仲裁 | +| GraphQL schema 文件 | `packages/shared-ts/contracts/graphql/student-bff.graphql` | `apps/student-bff/src/schema/*.graphql`（ARB-019 §21 已裁决，统一为集中管理） | ✅ 已裁决 | | Query 域（16 个） | 见 §2.4.1 | 见 student-bff §1.3（auth/myClasses/myExams/myHomework/myGrades/myAttendance/content/dashboard/weakness/trend/notifications） | ⏳ 待 ai04 确认 serverTime/examDetail/homeworkDetail | | Mutation 域（8 个） | 见 §2.4.2 | student-bff §1.3 仅列 submitHomework + markAsRead | ⏳ 待 ai04 补全 submitExam/saveExamDraft/recordExamViolation/recordPasteEvent/updateNotificationPreference | | 错误码前缀 | 透传 `BFF_STUDENT_*` | `BFF_STUDENT_`（student-bff §1.5） | ✅ 对齐 | | ActionState 信封 | success/errors/data + extensions.degraded | 待 ai04 实现（ARB-001 §1.3 原则） | ⏳ 待 ai04 | | DataLoader 防 N+1 | 依赖 student-bff 实现 | 待 ai04 实现（ARB-001 §1.3 原则） | ⏳ 待 ai04 | -| DataScope L0 强制执行 | student-bff Resolver 层从 JWT 提取 studentId | 待 ISSUE-014-07 仲裁 | ⏳ 待仲裁 | +| DataScope L0 强制执行 | student-bff Resolver 层从 JWT 提取 studentId | 已裁决 ARB-019 §21.7（方案 A：Resolver 从 JWT 提取） | ✅ 已裁决 | --- diff --git a/docs/architecture/issues/worklines/student-portal_workline.md b/docs/architecture/issues/worklines/student-portal_workline.md index 831bc4f..afa91ae 100644 --- a/docs/architecture/issues/worklines/student-portal_workline.md +++ b/docs/architecture/issues/worklines/student-portal_workline.md @@ -111,12 +111,12 @@ gantt - **作业提交页**（`/my-homework/[id]/submit`）： - 消费 `submitHomework` mutation - 乐观更新（useMutation onMutate 回滚 + invalidateQueries） - - 附件上传（待 ISSUE-014-05 仲裁后实现，暂走 mock） + - 附件上传（ARB-019 §21.5 方案 A 已裁决，暂走 mock） - **我的成绩页**（`/my-grades`）：消费 `myGrades` query，成绩列表 + 趋势图 - **我的考勤页**（`/my-attendance`）：消费 `myAttendance` query，考勤日历 - **依赖**： - - student-bff GraphQL schema（ai04 P3，`packages/shared-ts/contracts/graphql/student-bff.graphql`，待 ISSUE-014-02 仲裁） - - api-gateway 路由（ai01 P3，`/api/v1/student/*` 反向代理 student-bff，待 ISSUE-014-01 仲裁） + - student-bff GraphQL schema（ai04 P3，`packages/shared-ts/contracts/graphql/student-bff.graphql`，ARB-019 §21 已裁决） + - api-gateway 路由（ai01 P3，`/api/v1/student/*` 反向代理 student-bff，ARB-019 §21 已裁决） - core-edu gRPC（ai08 P3，提供 ExamService/HomeworkService/GradeService/AttendanceService/ClassService） - iam gRPC（ai06 P2，GetUserInfo + GetEffectivePermissions + GetViewports） - data-ana gRPC（ai11 P4，但 studentDashboard 聚合需要，P3 用 mock） @@ -205,7 +205,7 @@ gantt | teacher-portal MF Shell（ai13 P2） | exposes AppShell/GraphQLProvider/useGraphQLClient/useAuth/usePermission + shared singleton | P2 启动 | ⏳ 待 ai13 P2 | | api-gateway HTTP :8080（ai01 P3） | `/api/v1/student/*` 反向代理 student-bff 可用 | P3 启动 | ⏳ 待 ai01 P3 | | student-bff GraphQL（ai04 P3） | `POST /graphql` :3009 + 核心 Query/Mutation 可执行 | P3 启动 | ⏳ 待 ai04 P3 | -| student-bff GraphQL schema（ai04 + ISSUE-014-02 仲裁） | `packages/shared-ts/contracts/graphql/student-bff.graphql` 创建 | P3 启动 | ⏳ 待仲裁 | +| student-bff GraphQL schema（ai04 + ISSUE-014-02 仲裁） | `packages/shared-ts/contracts/graphql/student-bff.graphql` 创建 | P3 启动 | ✅ 已裁决（ARB-019） | | core-edu gRPC 50053（ai08 P3） | ExamService/HomeworkService/GradeService/AttendanceService/ClassService 全部 RPC | P3 启动 | ⏳ 待 ai08 P3 | | iam gRPC 50052（ai06 P2） | GetUserInfo + GetEffectivePermissions + GetViewports | P3 启动 | ⏳ 待 ai06 P2 | | student-bff content/data-ana 扩展（ai04 P4） | learningPath/myWeakness/myTrend/textbooks/chapters query 可用 | P4 启动 | ⏳ 待 ai04 P4 | @@ -291,13 +291,15 @@ gantt | 6 | §12.3 契约表更新 | WebSocket 事件名已裁决 | | 7 | §11.1 假设 6 更新 | 事件名已由 ARB-019 §21.6 裁决确认 | | 8 | §20.5 技术债务表更新 | WebSocket 事件名已裁决 | +| 9 | contract.md 过时"待仲裁"标注更新 | 10 处"待 ISSUE-014-XX 仲裁"更新为"已裁决 ARB-019 §XX" | +| 10 | workline.md 过时"待仲裁"标注更新 | 4 处"待仲裁"更新为"已裁决 ARB-019" | ### §8.3 当前阶段状态 - **文档阶段**：✅ 完成（01-understanding + 02-architecture-design + contract + workline + issue 全部对齐 ARB-019 裁决） - **代码实现阶段**：✅ 已完成（通过 `606acb6` 合并到 main，包含 P2-P6 全部代码） - **集成测试阶段**：✅ 已完成（通过 `61d8249` + `a6b0c54` 修复全部集成测试 bug） -- **待办**：无未完成的架构工作项 +- **待办**：无未完成的架构工作项（contract.md + workline.md + 02-architecture-design.md 全部对齐 ARB-019 裁决） ---