xiner/Edu

Files

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

2026-07-14 08:43:45 +08:00

20 KiB

Raw Blame History

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

1. student-bff 严重装配缺口（ai04 修复）

问题描述

student-bff 的 src/student/resolvers/index.ts 只装配了 11 个基础 resolver 文件，未导入 extended-queries.resolver.ts（22 个 Query）和 extended-mutations.resolver.ts（21 个 Mutation）。

影响范围

57 个 GraphQL 操作中：

✅ 14 个可用（基础 resolver 已装配）
⚠️ 42 个已实现但未生效（代码写在 extended-*.ts 中，但 index.ts 未装配 + schema 未声明）
❌ 1 个完全缺失（myAttendance，需 core-edu AttendanceService）

42 个未装配操作清单

未装配的 Query（22 个）： examDetail, homeworkDetail, serverTime, mySchedule, studentGrowth, assignmentAnalysis, myProfile, myMasterySummary, myDiagnosticReports, myErrorBook, announcements, announcementDetail, myLeaveRequests, myElectiveSelections, availableElectiveCourses, myLessonPlans, lessonPlanDetail, myCoursePlans, coursePlanDetail, myReportCard, myPracticeSessions, startPracticeSession

未装配的 Mutation（20 个）： submitExam, saveExamDraft, recordExamViolation, recordPasteEvent, markAsRead, markAllAsRead, updateNotificationPreference, updateProfile, changePassword, requestExtension, joinClass, leaveClass, addErrorBookItem, updateErrorBookItem, deleteErrorBookItem, markAnnouncementRead, createLeaveRequest, cancelLeaveRequest, selectElectiveCourse, dropElectiveCourse, submitPracticeAnswer

修复方法（ai04 执行）

在 services/student-bff/src/student/resolvers/index.ts 追加：

import { extendedQueriesResolvers } from "./extended-queries.resolver";
import { extendedMutationsResolvers } from "./extended-mutations.resolver";

// 在 studentBffResolvers 中合并
Query: { ...extendedQueriesResolvers.Query },
Mutation: { ...extendedMutationsResolvers.Mutation },

在 packages/shared-ts/contracts/graphql/student-bff.schema.graphql 补全 43 个操作的 SDL 定义
实现 myAttendance resolver（调用 core-edu ListAttendanceByStudent）
修正 startPracticeSession 类型不一致（v1 列为 mutation，代码实现为 query）

2. docker-compose 部署缺失（SRE AI 修复）

问题描述

infra/docker-compose.deploy.yml 中完全缺失 student-bff 和 student-portal 服务定义，且 api-gateway 的 environment 缺少 STUDENT_BFF_URL。

需要新增的服务

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
    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 块中追加：

STUDENT_BFF_URL: http://student-bff:3009

3. api-gateway 路由（ai01 已完成）

核查结果：✅ 路由已注册

services/api-gateway/main.go:84 — registerProxy(api, "student", cfg.StudentBffURL)
services/api-gateway/internal/config/config.go:81 — StudentBffURL: getEnv("STUDENT_BFF_URL", "http://localhost:3009")
路径前缀改写：/api/v1/student/* → /v1/student/*（proxy.go:24）

待修复

deploy.yml 中 api-gateway 的 environment 缺少 STUDENT_BFF_URL，会回退到 http://localhost:3009，容器内无法访问。

4. push-gateway 事件（ai10 已完成）

核查结果：✅ 全部就绪

push-gateway 采用通用事件透传机制，不硬编码事件类型。Kafka 消息中的 event_type 字段被原样作为 WebSocket 消息的 event 字段投递。

三个事件均已 Docker 验证通过：

ExamExtended ✅
ExamForceSubmitted ✅
ExamQuestionReordered ✅

上游事件生产缺失（ai08 修复）

core-edu 源码中尚未实现发布 ExamExtended/ExamForceSubmitted 事件到 Kafka topic edu.exam.events（仲裁文档 coord.md §21.11 ai08 执行项）。事件名仅存在于文档中，未在任何 .ts/.go/.py 源码或 .proto 中找到字面量定义。

5. MF Shell 集成（ai02 已完成，有限制）

核查结果：⚠️ 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

修复建议

MF 模式下复用 Shell client 只能通过 <GraphQLProvider client={shellClient}> 显式注入，不能运行时动态加载。当前独立壳模式（NEXT_PUBLIC_MF_ENABLED=false）完全可用，无需修复。

6. shared-ts GraphQL Schema（ai04 修复）

核查结果：⚠️ 文件存在但不完整

文件路径：packages/shared-ts/contracts/graphql/student-bff.schema.graphql（822 行）
与 v1 约定路径不一致（v1 写的是 student-bff.graphql，实际是 student-bff.schema.graphql）
schema 仅定义 15 Query + 2 Mutation + 1 Subscription，缺少 43 个操作的 SDL 定义

待修复

补全 43 个操作的 type/field/input SDL 定义
统一命名规则（与 parent-bff.graphql / teacher-bff.schema.graphql 对齐）

7. student-portal 自身状态（ai14 已完成）

✅ 已完成项

项目	状态	说明
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	✅	完整下游依赖清单

⚠️ 待下游就绪后验证

切换 NEXT_PUBLIC_API_MOCKING=disabled 后真实 API 调用
端到端 Docker Compose 联调（需 student-bff + api-gateway + 下游微服务全部就绪）
MF Shell 模式联调（需 teacher-portal MF 启用）

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	命名不一致，非阻断

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 追加：

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 装配完成即可联调。

20 KiB Raw Blame History Unescape Escape

Student Portal — 下游依赖工作 V2（Next Steps v2）

0. 核查总结

1. student-bff 严重装配缺口（ai04 修复）

问题描述

影响范围

42 个未装配操作清单

修复方法（ai04 执行）

2. docker-compose 部署缺失（SRE AI 修复）

问题描述

需要新增的服务

api-gateway 环境变量补充

3. api-gateway 路由（ai01 已完成）

核查结果：✅ 路由已注册

待修复

4. push-gateway 事件（ai10 已完成）

核查结果：✅ 全部就绪

上游事件生产缺失（ai08 修复）

5. MF Shell 集成（ai02 已完成，有限制）

核查结果：⚠️ Shell 已暴露，但运行时探测无效

修复建议

6. shared-ts GraphQL Schema（ai04 修复）

核查结果：⚠️ 文件存在但不完整

待修复

7. student-portal 自身状态（ai14 已完成）

✅ 已完成项

⚠️ 待下游就绪后验证

8. 优先级排序

9. 二次核查结果（2026-07-14）

9.1 核查总结

9.2 student-bff 装配缺口仍未修复（P0）

9.3 shared-ts schema 仍未补全（P0）

9.4 docker-compose 仍缺失 student-bff + student-portal（P0）

9.5 core-edu gRPC 已全部就绪（✅ 改善）

9.6 iam gRPC 已全部就绪（✅ 新发现）

9.7 msg gRPC + REST 已就绪（✅ 新发现）

9.8 api-gateway 路由已修复（✅ 改善）

9.9 core-edu 事件发布仍未实现（P1）

9.10 更新后的优先级排序

9.11 student-portal 自身状态（✅ 确认完成）

9.12 联调就绪状态

20 KiB

Raw Blame History