xiner/Edu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(student-portal): nextstep-v2 二次核查下游服务实现状态

Browse Source
This commit is contained in:
SpecialX
2026-07-14 08:43:45 +08:00
parent 21f2485749
commit ae6fe23be6
1 changed files with 268 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files

351
apps/student-portal/docs/nextstep-v2.md
View File

@@ -1,21 +1,22 @@
# Student Portal — 下游依赖工作 V2（Next Steps v2）
> 生成时间：2026-07-14
> 最近更新：2026-07-14（二次核查，§9）
> 生成者：ai14（student-portal）
> 基于版本：v1（nextstep.md）核查后的更新
> 核查方法：拉取 main 最新代码，逐项核查下游服务源码实现状态
## 0. 核查总结
| 下游服务 | 负责人 | v1 状态 | v2 核查结果 | 阻断级别 |
|----------|--------|---------|-------------|----------|
| student-bff | ai04 | 声称已完成 | ❌ **42/57 resolver 未装配** | P0 严重 |
| api-gateway | ai01 | 声称已完成 | ⚠️ 路由已注册，deploy.yml 缺 STUDENT_BFF_URL | P1 |
| push-gateway | ai10 | 声称已完成 | ✅ 三事件透传已验证 | 无 |
| MF Shell (teacher-portal) | ai02 | 声称已完成 | ⚠️ Shell 已暴露 client，但 student-portal tryLoadShellClient 无效 | P2 |
| shared-ts schema | ai04 | 声称已完成 | ⚠️ schema 文件存在但仅定义 15 Query + 2 Mutation | P0 |
| docker-compose | SRE AI | 未完成 | ❌ student-bff + student-portal 均缺失 | P0 |
| core-edu 事件发布 | ai08 | 未完成 | ❌ ExamExtended/ExamForceSubmitted 未实现 | P1 |
| 下游服务 | 负责人 | v1 状态 | v2 核查结果 | 阻断级别 |
| ------------------------- | ------ | ---------- | ----------------------------------------------------------------- | -------- |
| student-bff | ai04 | 声称已完成 | ❌ **42/57 resolver 未装配** | P0 严重 |
| api-gateway | ai01 | 声称已完成 | ⚠️ 路由已注册，deploy.yml 缺 STUDENT_BFF_URL | P1 |
| push-gateway | ai10 | 声称已完成 | ✅ 三事件透传已验证 | 无 |
| MF Shell (teacher-portal) | ai02 | 声称已完成 | ⚠️ Shell 已暴露 client，但 student-portal tryLoadShellClient 无效 | P2 |
| shared-ts schema | ai04 | 声称已完成 | ⚠️ schema 文件存在但仅定义 15 Query + 2 Mutation | P0 |
| docker-compose | SRE AI | 未完成 | ❌ student-bff + student-portal 均缺失 | P0 |
| core-edu 事件发布 | ai08 | 未完成 | ❌ ExamExtended/ExamForceSubmitted 未实现 | P1 |
## 1. student-bff 严重装配缺口（ai04 修复）
@@ -26,6 +27,7 @@ student-bff 的 `src/student/resolvers/index.ts` 只装配了 11 个基础 resol
### 影响范围
57 个 GraphQL 操作中：
- ✅ **14 个可用**（基础 resolver 已装配）
- ⚠️ **42 个已实现但未生效**（代码写在 extended-*.ts 中，但 index.ts 未装配 + schema 未声明）
- ❌ **1 个完全缺失**（myAttendance，需 core-edu AttendanceService）
@@ -41,6 +43,7 @@ submitExam, saveExamDraft, recordExamViolation, recordPasteEvent, markAsRead, ma
### 修复方法（ai04 执行）
1. 在 `services/student-bff/src/student/resolvers/index.ts` 追加：
```typescript
import { extendedQueriesResolvers } from "./extended-queries.resolver";
import { extendedMutationsResolvers } from "./extended-mutations.resolver";
@@ -65,67 +68,69 @@ submitExam, saveExamDraft, recordExamViolation, recordPasteEvent, markAsRead, ma
### 需要新增的服务
```yaml
student-bff:
build:
context: ./repo
dockerfile: services/student-bff/Dockerfile
container_name: edu-student-bff
restart: unless-stopped
environment:
NODE_ENV: production
PORT: 3009
# 下游服务 URL
IAM_SERVICE_URL: http://iam:3002
CORE_EDU_SERVICE_URL: http://core-edu:3004
CONTENT_SERVICE_URL: http://content:3005
DATA_ANA_SERVICE_URL: http://data-ana:3006
MSG_SERVICE_URL: http://msg:3007
ports:
- "${STUDENT_BFF_PORT:-3009}:3009"
depends_on:
iam:
condition: service_healthy
core-edu:
condition: service_healthy
networks:
- edu-net
- edu-shared
student-bff:
build:
context: ./repo
dockerfile: services/student-bff/Dockerfile
container_name: edu-student-bff
restart: unless-stopped
environment:
NODE_ENV: production
PORT: 3009
# 下游服务 URL
IAM_SERVICE_URL: http://iam:3002
CORE_EDU_SERVICE_URL: http://core-edu:3004
CONTENT_SERVICE_URL: http://content:3005
DATA_ANA_SERVICE_URL: http://data-ana:3006
MSG_SERVICE_URL: http://msg:3007
ports:
- "${STUDENT_BFF_PORT:-3009}:3009"
depends_on:
iam:
condition: service_healthy
core-edu:
condition: service_healthy
networks:
- edu-net
- edu-shared
student-portal:
build:
context: ./repo
dockerfile: apps/student-portal/Dockerfile
args:
NEXT_PUBLIC_API_MOCKING: "disabled"
container_name: edu-student-portal
restart: unless-stopped
environment:
NODE_ENV: production
PORT: 4001
API_GATEWAY_URL: http://api-gateway:8080
student-portal:
build:
context: ./repo
dockerfile: apps/student-portal/Dockerfile
args:
NEXT_PUBLIC_API_MOCKING: "disabled"
NEXT_PUBLIC_MF_ENABLED: "false"
NEXT_PUBLIC_GRAPHQL_ENDPOINT: /api/v1/student/graphql
NEXT_PUBLIC_PUSH_GATEWAY_URL: ws://push-gateway:8081
ports:
- "${STUDENT_PORTAL_PORT:-4001}:4001"
depends_on:
api-gateway:
condition: service_healthy
healthcheck:
test: ["CMD", "wget", "--quiet", "--spider", "http://localhost:4001/api/health"]
interval: 30s
timeout: 5s
start_period: 20s
retries: 3
networks:
- edu-net
- edu-shared
container_name: edu-student-portal
restart: unless-stopped
environment:
NODE_ENV: production
PORT: 4001
API_GATEWAY_URL: http://api-gateway:8080
NEXT_PUBLIC_API_MOCKING: "disabled"
NEXT_PUBLIC_MF_ENABLED: "false"
NEXT_PUBLIC_GRAPHQL_ENDPOINT: /api/v1/student/graphql
NEXT_PUBLIC_PUSH_GATEWAY_URL: ws://push-gateway:8081
ports:
- "${STUDENT_PORTAL_PORT:-4001}:4001"
depends_on:
api-gateway:
condition: service_healthy
healthcheck:
test:
["CMD", "wget", "--quiet", "--spider", "http://localhost:4001/api/health"]
interval: 30s
timeout: 5s
start_period: 20s
retries: 3
networks:
- edu-net
- edu-shared
```
### api-gateway 环境变量补充
在 api-gateway 的 environment 块中追加：
```yaml
STUDENT_BFF_URL: http://student-bff:3009
```
@@ -149,6 +154,7 @@ deploy.yml 中 api-gateway 的 environment 缺少 `STUDENT_BFF_URL`，会回退
push-gateway 采用通用事件透传机制，不硬编码事件类型。Kafka 消息中的 `event_type` 字段被原样作为 WebSocket 消息的 `event` 字段投递。
三个事件均已 Docker 验证通过：
- `ExamExtended` ✅
- `ExamForceSubmitted` ✅
- `ExamQuestionReordered` ✅
@@ -162,10 +168,12 @@ core-edu 源码中尚未实现发布 `ExamExtended`/`ExamForceSubmitted` 事件
### 核查结果：⚠️ Shell 已暴露，但运行时探测无效
**Shell 侧（teacher-portal）**：✅ 已暴露
- `next.config.js` 暴露 `./GraphQLProvider` 和 `./useGraphQLClient`
- 所有共享包设为 `singleton: true`
**student-portal 侧**：⚠️ tryLoadShellClient 实际无效
- `provider.tsx:51-67` 定义了 `tryLoadShellClient`，但函数注释明确说明 `useGraphQLClient` 是 React Hook，无法在异步上下文调用
- 该函数**永远返回 null**
- 降级逻辑完整：MF 模式下初始用独立 client，`useEffect` 异步探测 Shell 失败后保持独立 client
@@ -191,18 +199,18 @@ MF 模式下复用 Shell client 只能通过 `<GraphQLProvider client={shellClie
### ✅ 已完成项
| 项目 | 状态 | 说明 |
|------|------|------|
| 57 个 GraphQL 操作 | ✅ | operations.ts 定义完整（35 Query + 22 Mutation） |
| 15+ 个 Hook | ✅ | hooks.ts 全部实现 |
| 37 个页面 | ✅ | 全部页面路由就绪 |
| Vitest 测试 | ✅ | 481/481 passed（12 test files） |
| typecheck + lint | ✅ | 0 errors |
| Docker 构建 | ✅ | 镜像构建成功，容器运行正常 |
| MSW 禁用 | ✅ | Dockerfile build-arg 默认 disabled |
| 401 处理 | ✅ | client.ts 自动跳转 /login |
| 降级模式处理 | ✅ | client.ts 检测 degraded 标记并 console.warn |
| nextstep.md v1 | ✅ | 完整下游依赖清单 |
| 项目 | 状态 | 说明 |
| ------------------ | ---- | ------------------------------------------------ |
| 57 个 GraphQL 操作 | ✅ | operations.ts 定义完整（35 Query + 22 Mutation） |
| 15+ 个 Hook | ✅ | hooks.ts 全部实现 |
| 37 个页面 | ✅ | 全部页面路由就绪 |
| Vitest 测试 | ✅ | 481/481 passed（12 test files） |
| typecheck + lint | ✅ | 0 errors |
| Docker 构建 | ✅ | 镜像构建成功，容器运行正常 |
| MSW 禁用 | ✅ | Dockerfile build-arg 默认 disabled |
| 401 处理 | ✅ | client.ts 自动跳转 /login |
| 降级模式处理 | ✅ | client.ts 检测 degraded 标记并 console.warn |
| nextstep.md v1 | ✅ | 完整下游依赖清单 |
### ⚠️ 待下游就绪后验证
@@ -212,12 +220,187 @@ MF 模式下复用 Shell client 只能通过 `<GraphQLProvider client={shellClie
## 8. 优先级排序
| 优先级 | 任务 | 负责人 | 阻断原因 |
|--------|------|--------|----------|
| P0 | 装配 extended resolvers + 补全 schema | ai04 | 42/57 操作不可用 |
| P0 | docker-compose 新增 student-bff + student-portal | SRE AI | 无法部署 |
| P0 | api-gateway environment 补充 STUDENT_BFF_URL | SRE AI | 路由无法到达 student-bff |
| P1 | 实现 myAttendance resolver | ai04 | 考勤功能不可用 |
| P1 | core-edu 发布 ExamExtended/ExamForceSubmitted 事件 | ai08 | 考试实时推送不可用 |
| P2 | MF Shell 运行时 client 注入 | ai02 | MF 模式下无法复用 Shell client |
| P2 | 统一 schema 文件命名 | ai04 | 命名不一致，非阻断 |
| 优先级 | 任务 | 负责人 | 阻断原因 |
| ------ | -------------------------------------------------- | ------ | ------------------------------ |
| P0 | 装配 extended resolvers + 补全 schema | ai04 | 42/57 操作不可用 |
| P0 | docker-compose 新增 student-bff + student-portal | SRE AI | 无法部署 |
| P0 | api-gateway environment 补充 STUDENT_BFF_URL | SRE AI | 路由无法到达 student-bff |
| P1 | 实现 myAttendance resolver | ai04 | 考勤功能不可用 |
| P1 | core-edu 发布 ExamExtended/ExamForceSubmitted 事件 | ai08 | 考试实时推送不可用 |
| P2 | MF Shell 运行时 client 注入 | ai02 | MF 模式下无法复用 Shell client |
| P2 | 统一 schema 文件命名 | ai04 | 命名不一致，非阻断 |
---
## 9. 二次核查结果（2026-07-14）
> 用户通知"所有下游服务已经完成 nextstep.md 工作"后，对 main 分支最新代码（含未提交工作区）进行二次核查。
### 9.1 核查总结
| 下游服务 | 负责人 | 首次核查（§0） | 二次核查结果 | 变化 |
| ---------------------- | ------ | --------------------- | ----------------------------- | ---------------------------------- |
| student-bff | ai04 | ❌ 42/57 未装配 | ❌ **仍未装配** | 无变化（P0 未修复） |
| shared-ts schema | ai04 | ⚠️ 仅 15Q+2M | ⚠️ **仍仅 15Q+2M+1S** | 无变化（P0 未修复） |
| docker-compose | SRE | ❌ 缺失 | ❌ **仍缺失** | 无变化（P0 未修复） |
| api-gateway deploy.yml | SRE | ⚠️ 缺 STUDENT_BFF_URL | ⚠️ **仍缺** | 无变化（P0 未修复） |
| api-gateway 路由 | ai01 | ✅ 已注册 | ✅ **已注册 + 路径重写修复** | ✅ 改善（registerBffProxy） |
| core-edu gRPC | ai08 | ❌ RPC 缺失 | ✅ **40 RPC 全部就绪** | ✅ 改善（24/24 smoke test） |
| iam gRPC | ai06 | 未核查 | ✅ **15 RPC 全部就绪** | ✅ 新发现（含 GetUserProfile 等） |
| msg gRPC + REST | ai10 | 未核查 | ✅ **13 RPC + REST 全部就绪** | ✅ 新发现（含 announcements REST） |
| push-gateway | ai10 | ✅ 已验证 | ✅ **已验证** | 无变化 |
| MF Shell | ai02 | ⚠️ 限制 | ⚠️ **限制仍在** | 无变化（非阻断） |
| core-edu 事件发布 | ai08 | ❌ 未实现 | ❌ **仍未实现** | 无变化（P1 未修复） |
### 9.2 student-bff 装配缺口仍未修复（P0）
**二次核查结果：❌ 未修复**
- `services/student-bff/src/student/resolvers/extended-queries.resolver.ts`：✅ 存在，22 个 Query 已实现
- `services/student-bff/src/student/resolvers/extended-mutations.resolver.ts`：✅ 存在，21 个 Mutation 已实现
- `services/student-bff/src/student/resolvers/index.ts`：❌ **仍未导入** extended-queries 和 extended-mutations
ai04 的 nextstep.md（§4）声称"22 个扩展 Query Resolver ✅"和"21 个扩展 Mutation Resolver ✅"，Docker 测试也声称通过。但 index.ts 未装配这些 resolver，意味着 GraphQL schema 实际不会注册这 43 个操作。
**修复方法（ai04 执行）：**
在 `services/student-bff/src/student/resolvers/index.ts` 追加：
```typescript
import { extendedQueriesResolvers } from "./extended-queries.resolver.js";
import { extendedMutationsResolvers } from "./extended-mutations.resolver.js";
export const studentBffResolvers = {
Query: {
// ... 现有 11 个基础 resolver ...
...(extendedQueriesResolvers.Query ?? {}),
},
Mutation: {
// ... 现有 2 个基础 mutation ...
...(extendedMutationsResolvers.Mutation ?? {}),
},
Subscription: {
...(aiStreamResolvers.Subscription ?? {}),
},
};
```
### 9.3 shared-ts schema 仍未补全（P0）
**二次核查结果：❌ 未修复**
- 文件：`packages/shared-ts/contracts/graphql/student-bff.schema.graphql`（822 行）
- 当前定义：15 Query + 2 Mutation + 1 Subscription = 18 操作
- 缺失：43 个操作的 SDL type/field/input 定义
- 需补全的 43 个操作清单与 §1 一致
### 9.4 docker-compose 仍缺失 student-bff + student-portal（P0）
**二次核查结果：❌ 未修复**
`infra/docker-compose.deploy.yml` 中仍无 student-bff 和 student-portal 服务定义，api-gateway 的 environment 仍缺 `STUDENT_BFF_URL`。需新增的服务定义见 §2。
### 9.5 core-edu gRPC 已全部就绪（✅ 改善）
**二次核查结果：✅ 全部就绪**
ai08 完成了 P3.13 下游缺失 RPC 补全：
- 9 Service / 40 RPC 全部实现
- 24/24 gRPC smoke test 通过
- student-bff 需要的 10 个 RPC 全部就绪：
- `ExamService.GetExam` ✅（examDetail）
- `ExamService.SubmitExam` ✅（submitExam）
- `ExamService.SaveExamDraft` ✅（saveExamDraft）
- `ExamService.RecordExamViolation` ✅（recordExamViolation）
- `HomeworkService.GetHomework` ✅（homeworkDetail）
- `HomeworkService.SubmitHomework` ✅（submitHomework）
- `GradeService.ListGradesByStudent` ✅（myGrades）
- `GradeService.GetReportCard` ✅（myReportCard）
- `ScheduleService.GetScheduleByStudent` ✅（mySchedule）
- `AttendanceService.ListAttendanceByStudent` ✅（myAttendance）
- `LeaveRequestService` 3 RPC ✅（myLeaveRequests/createLeaveRequest/cancelLeaveRequest）
### 9.6 iam gRPC 已全部就绪（✅ 新发现）
**二次核查结果：✅ 全部就绪**
ai06 实现了 15 个 gRPC RPC，包含 student-bff 需要的全部方法：
- `GetUserProfile` ✅（myProfile）
- `UpdateProfile` ✅（updateProfile）
- `ChangePassword` ✅（changePassword）
- `GetUserInfo` ✅（currentUser）
- `GetEffectivePermissions` ✅（currentUser permissions）
- `GetViewports` ✅（currentUser viewport）
- `GetChildrenByParent` ✅（家长端，非学生端）
> 注：ai04 的 nextstep.md §3.1 将 iam 三个 RPC 标记为"❌ 缺失"，但实际 iam 已全部实现。ai04 需更新其 nextstep.md 状态。
### 9.7 msg gRPC + REST 已就绪（✅ 新发现）
**二次核查结果：✅ 就绪（gRPC + REST 混合）**
ai10 实现了 13 个 gRPC RPC + 完整 REST API：
- `NotificationService.ListNotifications` ✅ gRPC（myNotifications）
- `NotificationService.MarkAsRead` ✅ gRPC（markAsRead）
- `NotificationPreferenceService.GetPreferences` ✅ gRPC
- `NotificationPreferenceService.UpdatePreferences` ✅ gRPC（updateNotificationPreference）
- 公告：REST `/announcements` + `/announcements/:id/read` ✅
> 注：ai04 的 nextstep.md §3.5 将 msg 6 个 RPC 标记为"❌ 缺失"，但 msg 已实现核心 RPC。公告相关方法通过 REST 提供，ai04 需确认是否需补 gRPC 或改用 REST 调用。
### 9.8 api-gateway 路由已修复（✅ 改善）
**二次核查结果：✅ 已修复**
ai01 新增 `registerBffProxy` 函数，对 BFF 路由（teacher/student/parent）正确剥离前缀：
- `/api/v1/student/graphql` → `student-bff:3009/graphql` ✅（不再 404）
- JWT 鉴权 + x-user-id/x-user-roles 注入 ✅
### 9.9 core-edu 事件发布仍未实现（P1）
**二次核查结果：❌ 未修复**
`ExamExtended`、`ExamForceSubmitted`、`ExamQuestionReordered` 事件字面量在 core-edu 源码中仍未找到。这三个事件由教师端触发（延长考试/强制收卷/调整题目），需 core-edu 在相应业务操作中通过 Outbox 发布到 Kafka。
### 9.10 更新后的优先级排序
| 优先级 | 任务 | 负责人 | 阻断原因 | 状态变化 |
| ------ | -------------------------------------------------- | -------- | ------------------------ | ------------------ |
| **P0** | student-bff index.ts 装配 extended resolvers | ai04 | 43 个操作不可用 | ❌ 未修复 |
| **P0** | shared-ts schema 补全 43 个操作 SDL | ai04 | GraphQL schema 不完整 | ❌ 未修复 |
| **P0** | docker-compose 新增 student-bff + student-portal | SRE | 无法部署 | ❌ 未修复 |
| **P0** | api-gateway deploy.yml 补充 STUDENT_BFF_URL | SRE | 路由无法到达 student-bff | ❌ 未修复 |
| P1 | core-edu 发布 ExamExtended/ExamForceSubmitted 事件 | ai08 | 考试实时推送不可用 | ❌ 未修复 |
| P2 | MF Shell 运行时 client 注入 | ai02 | MF 模式限制（非阻断） | 无变化 |
| ~~P1~~ | ~~实现 myAttendance resolver~~ | ~~ai04~~ | ~~考勤不可用~~ | ✅ core-edu 已就绪 |
### 9.11 student-portal 自身状态（✅ 确认完成）
二次核查确认 student-portal 自身全部通过：
| 验证项 | 结果 |
| ------------------ | ---------------------------------- |
| `pnpm typecheck` | ✅ 0 errors |
| `pnpm lint` | ✅ 0 errors, 0 warnings |
| `pnpm test` | ✅ 481/481 passed（12 test files） |
| 57 个 GraphQL 操作 | ✅ operations.ts 完整定义 |
| Docker 构建 | ✅ 镜像构建成功（nextstep.md §0） |
### 9.12 联调就绪状态
当前联调就绪状态（student-portal → api-gateway → student-bff → 下游 gRPC）：
```
student-portal ──✅──> api-gateway ──✅──> student-bff ──❌──> [43 个操作未装配]
│
├──✅──> core-edu (40 RPC 就绪)
├──✅──> iam (15 RPC 就绪)
├──✅──> msg (13 RPC + REST 就绪)
└──❌──> docker-compose 未配置
```
**结论：** student-portal 自身已完全就绪。4 个 P0 问题全部集中在下游服务（ai04 装配 + SRE 部署），需 ai04 和 SRE AI 修复后方可端到端联调。core-edu / iam / msg 下游 gRPC 已全部就绪，一旦 student-bff 装配完成即可联调。