docs(student-portal): nextstep-v2 二次核查下游服务实现状态
This commit is contained in:
SpecialX
@@ -1,6 +1,7 @@
|
||||
# Student Portal — 下游依赖工作 V2（Next Steps v2）
|
||||
|
||||
> 生成时间：2026-07-14
|
||||
> 最近更新：2026-07-14（二次核查，§9）
|
||||
> 生成者：ai14（student-portal）
|
||||
> 基于版本：v1（nextstep.md）核查后的更新
|
||||
> 核查方法：拉取 main 最新代码，逐项核查下游服务源码实现状态
|
||||
@@ -8,7 +9,7 @@
|
||||
## 0. 核查总结
|
||||
|
||||
| 下游服务 | 负责人 | v1 状态 | v2 核查结果 | 阻断级别 |
|
||||
|----------|--------|---------|-------------|----------|
|
||||
| ------------------------- | ------ | ---------- | ----------------------------------------------------------------- | -------- |
|
||||
| student-bff | ai04 | 声称已完成 | ❌ **42/57 resolver 未装配** | P0 严重 |
|
||||
| api-gateway | ai01 | 声称已完成 | ⚠️ 路由已注册，deploy.yml 缺 STUDENT_BFF_URL | P1 |
|
||||
| push-gateway | ai10 | 声称已完成 | ✅ 三事件透传已验证 | 无 |
|
||||
@@ -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";
|
||||
@@ -113,7 +116,8 @@ submitExam, saveExamDraft, recordExamViolation, recordPasteEvent, markAsRead, ma
|
||||
api-gateway:
|
||||
condition: service_healthy
|
||||
healthcheck:
|
||||
test: ["CMD", "wget", "--quiet", "--spider", "http://localhost:4001/api/health"]
|
||||
test:
|
||||
["CMD", "wget", "--quiet", "--spider", "http://localhost:4001/api/health"]
|
||||
interval: 30s
|
||||
timeout: 5s
|
||||
start_period: 20s
|
||||
@@ -126,6 +130,7 @@ submitExam, saveExamDraft, recordExamViolation, recordPasteEvent, markAsRead, ma
|
||||
### 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
|
||||
@@ -192,7 +200,7 @@ MF 模式下复用 Shell client 只能通过 `<GraphQLProvider client={shellClie
|
||||
### ✅ 已完成项
|
||||
|
||||
| 项目 | 状态 | 说明 |
|
||||
|------|------|------|
|
||||
| ------------------ | ---- | ------------------------------------------------ |
|
||||
| 57 个 GraphQL 操作 | ✅ | operations.ts 定义完整（35 Query + 22 Mutation） |
|
||||
| 15+ 个 Hook | ✅ | hooks.ts 全部实现 |
|
||||
| 37 个页面 | ✅ | 全部页面路由就绪 |
|
||||
@@ -213,7 +221,7 @@ 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 |
|
||||
@@ -221,3 +229,178 @@ MF 模式下复用 Shell client 只能通过 `<GraphQLProvider client={shellClie
|
||||
| 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 装配完成即可联调。
|
||||
|
||||
Reference in New Issue
Block a user