docs(student-portal): contract.md + workline.md 过时待仲裁标注全部更新为已裁决 ARB-019
This commit is contained in:
@@ -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 提取) | ✅ 已裁决 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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 裁决)
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user