docs(student-portal): contract.md + workline.md 过时待仲裁标注全部更新为已裁决 ARB-019

This commit is contained in:
SpecialX
2026-07-13 10:28:55 +08:00
parent d1db3dfdee
commit 58d0c4758c
2 changed files with 17 additions and 15 deletions

View File

@@ -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 / 考试强制提交ExamForceSubmittedARB-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 /wsWebSocket | 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 Shellai13 P2| exposes AppShell/GraphQLProvider/useGraphQLClient/useAuth/usePermission + shared singleton | P2 启动 | ⏳ 待 ai13 P2 |
| api-gateway HTTP :8080ai01 P3 | `/api/v1/student/*` 反向代理 student-bff 可用 | P3 启动 | ⏳ 待 ai01 P3 |
| student-bff GraphQLai04 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 50053ai08 P3 | ExamService/HomeworkService/GradeService/AttendanceService/ClassService | P3 启动 | ⏳ 待 ai08 P3 |
| iam gRPC 50052ai06 P2 | GetUserInfo + GetEffectivePermissions + GetViewports | P3 启动 | ⏳ 待 ai06 P2 |
| content gRPC 50054ai09 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 + UserInfostudent 角色)由 Shell 处理
- `POST /api/v1/student/upload` → 返回固定 signed URL待 ISSUE-014-05 仲裁后实现
- `POST /api/v1/student/upload` → 返回固定 signed URLARB-019 §21.5 方案 A 已裁决
- 所有 mock 响应定义在 `apps/student-portal/src/mocks/fixtures/*.json`
#### 4.2.2 WebSocket mockmock-socket
- 连接 `ws://localhost:8081/ws` 后每 30 秒推送 1 条 mock 通知
- 通知类型轮询:作业通知 / 考试通知 / 成绩通知 / 系统通知
- 支持模拟考试延长事件(待 ISSUE-014-06 仲裁后实现
- 支持模拟考试延长事件 ExamExtended + 考试强制提交 ExamForceSubmittedARB-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.3auth/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(方案 AResolver 从 JWT 提取) | ✅ 已裁决 |
---

View File

@@ -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 schemaai04 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 schemaai04 P3`packages/shared-ts/contracts/graphql/student-bff.graphql`ARB-019 §21 已裁决
- api-gateway 路由ai01 P3`/api/v1/student/*` 反向代理 student-bffARB-019 §21 已裁决
- core-edu gRPCai08 P3提供 ExamService/HomeworkService/GradeService/AttendanceService/ClassService
- iam gRPCai06 P2GetUserInfo + GetEffectivePermissions + GetViewports
- data-ana gRPCai11 P4但 studentDashboard 聚合需要P3 用 mock
@@ -205,7 +205,7 @@ gantt
| teacher-portal MF Shellai13 P2 | exposes AppShell/GraphQLProvider/useGraphQLClient/useAuth/usePermission + shared singleton | P2 启动 | ⏳ 待 ai13 P2 |
| api-gateway HTTP :8080ai01 P3 | `/api/v1/student/*` 反向代理 student-bff 可用 | P3 启动 | ⏳ 待 ai01 P3 |
| student-bff GraphQLai04 P3 | `POST /graphql` :3009 + 核心 Query/Mutation 可执行 | P3 启动 | ⏳ 待 ai04 P3 |
| student-bff GraphQL schemaai04 + ISSUE-014-02 仲裁) | `packages/shared-ts/contracts/graphql/student-bff.graphql` 创建 | P3 启动 | ⏳ 待仲裁 |
| student-bff GraphQL schemaai04 + ISSUE-014-02 仲裁) | `packages/shared-ts/contracts/graphql/student-bff.graphql` 创建 | P3 启动 | ✅ 已裁决ARB-019 |
| core-edu gRPC 50053ai08 P3 | ExamService/HomeworkService/GradeService/AttendanceService/ClassService 全部 RPC | P3 启动 | ⏳ 待 ai08 P3 |
| iam gRPC 50052ai06 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 裁决)
---