# 模块理解确认书 — student-bff > AI 标识：ai04 > 阶段：阶段 1（全局理解） > 日期：2026-07-09 > 状态：已对齐仲裁裁决（coord-final-decisions §2 B1-B8 + president-final-rulings §2.2-2.9） > 关联文档：[ai-allocation §6 模板](../../docs/architecture/ai-allocation.md)、[004 架构影响地图](../../docs/architecture/004_architecture_impact_map.md)、[pending-features P3](../../docs/architecture/roadmap/pending-features.md)、[coord-final-decisions](../../docs/architecture/coord-final-decisions.md)、[president-final-rulings](../../docs/architecture/president-final-rulings.md) > > **仲裁对齐说明（ISSUE-STU-001 修复）**： > - B1: API 风格 = GraphQL Yoga + DataLoader（P2 起直接 GraphQL，禁止 REST 渐进） > - B2: 下游通信 = gRPC 首次实现即用（@grpc/grpc-js + @grpc/proto-loader，禁止 HTTP fetch） > - B5: 错误码前缀 = `BFF_STUDENT_`（BFF 在前，非 `STUDENT_BFF_`） > - B8: DownstreamClient 抽象复用 shared-ts（回写 teacher-bff，3 BFF 统一） > - 本文档中早期将通信方式写为 HTTP REST/fetch、错误码前缀写为 `STUDENT_BFF_` 的部分已修正，以本对齐说明为准。 --- ## 1. 我在架构中的位置 | 维度 | 内容 | | -------------- | ----------------------------------------------------------------------------- | | 层级 | **L4 BFF 聚合层**（004 §3.1 六层架构） | | 上游调用方 | api-gateway（Go Gin，反向代理 `/api/v1/student/*` → student-bff:3009） | | 下游被调用方 | iam、core-edu、content、data-ana（按 004 §4 服务依赖图） | | 通信方式（入） | **GraphQL Yoga over HTTP**（api-gateway → student-bff:3009，B1 裁决：P2 起直接 GraphQL，禁止 REST 渐进） | | 通信方式（出） | **gRPC**（@grpc/grpc-js + @grpc/proto-loader，B2 裁决：首次实现即用 gRPC，禁止 HTTP fetch） | | 微前端对接 | student-portal（ai07 负责，P3 阶段）通过 api-gateway 调用 student-bff | | 推送通道 | push-gateway（P5 阶段，WebSocket/SSE 推送考试通知、成绩发布等） | **架构定位**（004 §1.1a + §5.4）： - 按"使用场景域"分 BFF，student-bff 服务于**学习场景域**，复用角色：学生 - 不按角色分 BFF，新角色复用现有 BFF 通过视口差异化 - DataScope = **SELF（L0）**：学生只能看自己的数据（004 §5.3） --- ## 2. 我的限界上下文 ### 2.1 我负责什么 student-bff 是**纯聚合层**，不持有业务状态、不直接访问 DB（对齐 teacher-bff 模式）。职责： 1. **聚合**：并行调用多个下游业务服务，组装学生视角的复合数据 2. **裁剪**：将下游返回的领域数据裁剪为学生端所需的最小字段集 3. **协议转换**：对外暴露场景化 HTTP/GraphQL 端点，对内调用下游 REST/gRPC 4. **缓存**：聚合结果 Redis 短缓存 5-30s（004 §6.2 BFF 混合读策略） ### 2.2 我的聚合场景（学生视角） | 场景 | 聚合的下游服务 | 用途 | | ------------------ | --------------------------------------------------------------------------- | ------------------------------ | | 学生首页 Dashboard | iam `/iam/me` + core-edu `/homework/class/:classId` + msg `/notifications` | 个人信息 + 待办作业 + 未读消息 | | 即将到来的考试 | core-edu `/exams/class/:classId` | 考试日程提醒 | | 我的作业列表 | core-edu `/homework/class/:classId` | 查看待完成作业 | | 提交作业 | core-edu `/homework/:id/submit` | 学生提交作业答案 | | 我的成绩 | core-edu `/grades/student/:studentId` | 查询历史成绩 | | 消息中心 | msg `/notifications` + `/notifications/:id/read` | 通知列表 + 已读 | | 教材浏览 | content `/textbooks` + `/chapters` | 按章节学习 | | 题库练习 | content `/questions` | 按知识点刷题 | | 学情诊断 | data-ana `/analytics/student/:id/weakness` + `/analytics/student/:id/trend` | 自我掌握度分析 | | AI 答疑 | ai `/ai/chat` + `/ai/stream-chat`（SSE 流式） | 智能答疑辅助 | | 个性化学习路径 | content `/knowledge-points/:id/learning-path` | 基于学情推荐学习路径 | ### 2.3 我不负责什么（明确边界外） | 不负责项 | 归属服务 | 说明 | | -------------- | ------------------------------ | ----------------------------------------------------------------- | | 业务数据持久化 | core-edu / content / msg / iam | BFF 不写 DB | | 权限校验 | 下游业务服务 + iam | BFF 不做权限校验（对齐 teacher-bff），透传 `x-user-id` 让下游校验 | | 用户认证 | iam + api-gateway | JWT 校验在 Gateway，BFF 只读 `x-user-id` 头 | | 领域事件发布 | core-edu / content | BFF 不发布事件，仅可选订阅事件用于实时推送 | | 数据范围过滤 | 下游业务服务 Repository 层 | BFF 透传 userId，下游按 DataScope=SELF 过滤 | | 班级管理 | core-edu（classes 模块） | 学生只读自己所在班级 | | 考试批改 | core-edu | 学生不能批改，只能查看成绩 | --- ## 3. 我与外部的契约 ### 3.1 我消费的 proto message / 下游接口 > ✅ **B2 裁决落地**：BFF→Service 首次实现即用 gRPC（@grpc/grpc-js + @grpc/proto-loader），通过 `DownstreamClient` 抽象（B8 裁决，复用 shared-ts，3 个 BFF 统一）。proto 即契约，不再是"文档"。 | 下游服务 | proto service | gRPC method（B2 裁决） | 用途 | | ------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------ | | iam | `IamService.GetUserInfo` | `iam.GetUserInfo` | 获取学生个人信息 + roles + dataScope | | iam | `IamService.GetViewports`（proto 缺失） | `iam.GetViewports` | 获取学生端导航视口 | | iam | `IamService.GetEffectivePermissions`（proto 缺失） | `iam.GetEffectivePermissions` | 获取有效权限列表 | | classes（core-edu） | `ClassService.GetClass` / `ListClasses` | `classes.GetClass` / `classes.ListClasses` | 查自己所在班级 | | core-edu | `ExamService.GetExam` / `ListExamsByClass` | `core-edu.GetExam` / `core-edu.ListExamsByClass` | 查班级考试 | | core-edu | `HomeworkService.GetHomework` / `ListHomeworkByClass` / `SubmitHomework` | `core-edu.ListHomeworkByStudent` / `core-edu.SubmitHomework` | 查作业 + 提交 | | core-edu | `GradeService.GetGrade` / `ListGradesByStudent` | `core-edu.ListGradesByStudent` | 查自己成绩 | | content | `TextbookService.GetTextbook` / `ListTextbooks` | `content.ListTextbooks` | 查教材 | | content | `ChapterService`（proto 缺失） | `content.ListChapters` | 查章节 | | content | `QuestionService`（proto 缺失） | `content.ListQuestions` | 查题库 | | content | `KnowledgeGraphService.GetLearningPath` | `content.GetLearningPath` | 学习路径 | | msg | `NotificationService.ListNotifications` / `MarkAsRead` / `SearchNotifications` | `msg.ListNotifications` / `msg.MarkAsRead` | 消息中心 | | data-ana | `AnalyticsService.GetStudentWeakness` / `GetLearningTrend` | `data-ana.GetStudentWeakness` / `data-ana.GetLearningTrend` | 学情分析 | | ai | `AiService.Chat` / `StreamChat` / `GenerateQuestion` | `ai.Chat`（同步） / `ai.StreamChat`（server-streaming，B2 裁决） | AI 答疑 | ### 3.2 我暴露的 GraphQL API（student-bff 对外） > ✅ **B1 裁决落地**：P2 起直接 GraphQL Yoga（禁止 REST 渐进），schema 存放于 `packages/shared-ts/contracts/graphql/student-bff.schema.graphql`（president §2.2.1）。 > 网关路径：`/api/v1/student/*` → api-gateway 剥离 `/api/v1` 后代理到 student-bff:3009 GraphQL endpoint。 > 分页采用 Relay Cursor Connections 规范（`{ edges, pageInfo, totalCount }`）。 > 权限点标注于 schema 注释 `# @permission:`，DataScope 固定 `OWN`（学生数据隔离 SELF）。 #### Query（14 个字段） | Query 字段 | 聚合下游 | 权限点（注释标注） | 说明 | | ------------------------- | -------------------- | ----------------------- | -------------------- | | `currentUser` | iam | AUTH_READ | 学生信息 + 权限 + 视口 | | `myClasses` | core-edu | CLASS_READ | 我的班级列表 | | `myExams` | core-edu | EXAM_READ | 即将到来的考试 | | `myHomework` | core-edu | HOMEWORK_READ | 我的作业列表 | | `myGrades` | core-edu | GRADE_READ | 我的成绩（B4 比对） | | `myAttendance` | core-edu | ATTENDANCE_READ | 我的考勤记录 | | `textbooks` | content | TEXTBOOK_READ | 教材列表 | | `chapters` | content | CHAPTER_READ | 章节树 | | `learningPath` | content | LEARNING_PATH_READ | 学习路径推荐 | | `studentDashboard` | data-ana | DASHBOARD_VIEW | 学生仪表盘聚合 | | `myWeakness` | data-ana | WEAKNESS_READ | 学情诊断（薄弱点） | | `myTrend` | data-ana | TREND_READ | 学习趋势 | | `myNotifications` | msg | NOTIFICATION_READ | 通知列表 | | `myNotificationUnreadCount` | msg | NOTIFICATION_READ | 通知未读数 | #### Mutation（2 个字段） | Mutation 字段 | 下游 | 权限点 | 说明 | | ---------------------------- | --------------------- | ------------------- | ---------------------------- | | `submitHomework` | core-edu.SubmitHomework | HOMEWORK_SUBMIT | 提交作业（B4 强制 userId） | | `markNotificationAsRead` | msg.MarkAsRead | NOTIFICATION_UPDATE | 标记通知已读（B4 强制 userId）| #### Subscription（1 个字段，SSE 传输） | Subscription 字段 | 下游 | 权限点 | 说明 | | ----------------- | ------------------- | --------------- | ----------------------------- | | `aiStreamChat` | ai.StreamChat | STUDENT_AI_CHAT | AI 答疑流式响应（gRPC server-streaming 透传） | ### 3.3 错误码前缀 > ✅ **B5 裁决**：BFF 在前，统一 `BFF_STUDENT_` 前缀（非 `STUDENT_BFF_`）。 > **G14 裁决**：服务名大写前缀。**F4 裁决**：i18n key 格式 `error.bffStudent.`。 | 前缀 | 用途 | 示例 | | -------------- | ---------------------- | ------------------------------------------------------------- | | `BFF_STUDENT_` | student-bff 自身错误 | `BFF_STUDENT_UNAUTHORIZED`、`BFF_STUDENT_BAD_GATEWAY` | | 下游错误透传 | 下游服务错误码原样返回 | `CLASSES_NOT_FOUND`、`IAM_USER_NOT_FOUND` | 错误类清单（`shared/errors/application-error.ts`，11 个类，G8 ActionState 信封）： | 错误类 | statusCode | code | 说明 | | ------------------------------ | ---------- | --------------------------------- | ----------------------------- | | `ValidationError` | 400 | `BFF_STUDENT_VALIDATION_ERROR` | Zod 校验失败 | | `UnauthorizedError` | 401 | `BFF_STUDENT_UNAUTHORIZED` | 缺失 `x-user-id` 头 | | `ForbiddenResourceError` | 403 | `BFF_STUDENT_FORBIDDEN_RESOURCE` | 场景 A：资源无归属（president §2.7） | | `IdentityMismatchError` | 403 | `BFF_STUDENT_IDENTITY_MISMATCH` | 场景 B：JWT/body userId 不一致（president §2.7） | | `NotFoundError` | 404 | `BFF_STUDENT_NOT_FOUND` | 资源不存在 | | `ConflictError` | 409 | `BFF_STUDENT_CONFLICT` | 重复提交 / 状态冲突 | | `BusinessError` | 422 | `BFF_STUDENT_BUSINESS_ERROR` | 业务规则违反 | | `BadGatewayError` | 502 | `BFF_STUDENT_BAD_GATEWAY` | 下游 gRPC 失败 | | `ServiceUnavailableError` | 503 | `BFF_STUDENT_SERVICE_UNAVAILABLE` | 熔断器开启（P6） | | `GatewayTimeoutError` | 504 | `BFF_STUDENT_GATEWAY_TIMEOUT` | 下游超时 | | `InternalError` | 500 | `BFF_STUDENT_INTERNAL_ERROR` | 未捕获异常 | ### 3.4 我订阅的 Kafka 事件（P5 起订阅，B7 裁决） > ✅ **B7 裁决**：P2-P4 阶段不订阅 Kafka，P5 起 student-bff 订阅事件用于实时推送。 > 消费者组：`student-bff-event-subscriber`。幂等去重：Redis SETNX `event_id`。 > 推送通道：push-gateway HTTP POST `/push/user/:userId`（失败软处理，仅 warn 日志）。 | Topic | 事件 | 消费动作 | | -------------------------- | --------------------------------------- | ------------------------------ | | `edu.homework.events` | `homework.assigned` / `homework.graded` | 推送给学生（push-gateway） | | `edu.exam.events` | `exam.published` / `exam.updated` | 考试提醒推送 | | `edu.grade.events` | `grade.recorded` | 成绩发布推送 | | `edu.notification.events` | `notification.created` | 通知推送 | | `edu.attendance.events` | `attendance.recorded` | 考勤提醒推送 | | `edu.class.events` | `class.updated` | 班级信息变更推送 | | `edu.content.events` | `content.published` | 教材/章节更新推送 | > ⚠️ P3-P4 阶段 student-bff 不消费事件，仅做同步聚合。事件订阅逻辑在 `src/student/events/event-subscriber.ts`。 --- ## 4. 我的技术栈 | 维度 | 选型 | 依据 | | ------------ | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | | 语言 | TypeScript 5.5+ | 004 §2.1 | | 框架 | NestJS 10 | 004 §2.1，对齐 teacher-bff 模板 | | ORM | **无**（BFF 不访问 DB） | 对齐 teacher-bff，无 repository/schema/dto | | 缓存 | Redis 7（短缓存 5-30s） | 004 §6.2 BFF 混合读策略 | | 可观测性日志 | pino | 对齐 classes/teacher-bff | | 可观测性指标 | prom-client（`/metrics` 端点） | 对齐 teacher-bff main.ts | | 可观测性链路 | OpenTelemetry SDK + OTLP exporter | 对齐 teacher-bff tracer.ts | | API 风格 | **GraphQL Yoga**（B1 裁决） | P2 起直接 GraphQL + DataLoader，禁止 REST 渐进；schema 存放 `packages/shared-ts/contracts/graphql/student-bff.schema.graphql` | | 下游通信 | **gRPC**（B2 裁决） | @grpc/grpc-js + @grpc/proto-loader，DownstreamClient 抽象（B8 复用 shared-ts） | | 输入校验 | Zod | Resolver 层 `schema.safeParse(args.input)`（G7 裁决） | | 错误处理 | GlobalErrorFilter + ApplicationError | 11 个错误类，ActionState 信封（G8 裁决） | | ESM 模式 | NodeNext + `.js` 后缀 import | 对齐 teacher-bff tsconfig | | 测试框架 | **Vitest** | 覆盖率 ≥ 80%（lines/functions），branches ≥ 70% | ### 4.1 GraphQL 设计决策（已裁决 B1） > ✅ **B1 裁决**：student-bff 从 P2 起直接采用 GraphQL Yoga + DataLoader，禁止 REST 渐进。 **裁决结论**： - **API 风格**：GraphQL Yoga over HTTP（SSE 传输 Subscription） - **DataLoader**：解决 N+1 查询问题，按下游服务分批聚合 - **schema 存放**：`packages/shared-ts/contracts/graphql/student-bff.schema.graphql`（president §2.2.1） - **分页规范**：Relay Cursor Connections（`{ edges, pageInfo, totalCount }`） - **降级模式**：方案 B（president §2.6），`success=true + data 内 degraded=true + degradedFields` - **越权防御**：B4 强制自我越权防御，AuthorizationGuard 拦截（president §2.9 方案 D，DEV_MODE 放行） **已落地的 GraphQL 核心文件**： | 文件 | 职责 | | --------------------------------------------- | ------------------------------------------------- | | `src/shared/graphql/yoga.ts` | GraphQL Yoga 实例 + context 构建 | | `src/shared/graphql/dataloader.ts` | DataLoader 工厂（按下游服务分批） | | `src/student/resolvers/*.resolver.ts` | Query/Mutation/Subscription Resolver（6 个文件） | | `src/student/guards/authorization.guard.ts` | B4 越权防御（assertOwnData + assertIdentityMatch）| | `packages/shared-ts/contracts/graphql/student-bff.schema.graphql` | GraphQL schema 定义 | --- ## 5. 我的阶段归属 | 维度 | 内容 | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | 阶段 | **P3 核心教学阶段**（M7-M10） | | 退出标准（pending-features P3） | 教师创建考试 → 发布 → 学生作答提交 → 教师批改 → 事件发到 Kafka → 成绩统计更新 → 全链路可观测 | | student-bff 在 P3 的最小交付 | 学生作答作业页面所需 API：`/student/homework` 列表 + `/student/homework/:id/submit` 提交 + `/student/grades` 成绩查看 | | 依赖上游阶段产出 | P1（api-gateway 路由骨架 + classes 黄金模板 + shared-proto）、P2（iam 认证 + teacher-bff BFF 模板 + teacher-portal 微前端骨架） | | P3 同阶段依赖 | core-edu（考试/作业/成绩域 CRUD + Outbox 事件） | | P4 阶段扩展 | 学情诊断查询（双轨读：实时查 core-edu 主库 + 聚合查 data-ana ClickHouse 宽表） | | P5 阶段扩展 | AI 答疑流式响应 + Kafka 事件订阅推送 | ### 5.1 P3 阶段最小可行集合（MVP） student-bff 在 P3 阶段不一定要实现全部 17 个 GraphQL 字段，优先级： | 优先级 | GraphQL 字段 | P3 必需 | 说明 | | ------ | ------------------------------------------------- | ------- | ------------------------- | | P0 | `Query.myHomework` + `Mutation.submitHomework` | ✅ | 学生作答作业页面核心 | | P0 | `Query.myGrades` | ✅ | 成绩查看 | | P0 | `Query.currentUser` | ✅ | 学生信息 + 权限 + 视口 | | P0 | `Query.studentDashboard` | ✅ | 学生首页聚合 | | P1 | `Query.myExams` | ✅ | 考试日程 | | P1 | `Query.myNotifications` | ⚠️ 可选 | P5 msg 服务落地后才有意义 | | P2 | `Query.textbooks` / `chapters` / `learningPath` | ❌ P4 | content 服务 P4 才落地 | | P2 | `Query.myWeakness` / `myTrend` | ❌ P4 | data-ana 学情诊断 P4 | | P2 | `Subscription.aiStreamChat` | ❌ P5 | ai 服务 P5 | --- ## 6. 我需要对齐的黄金模板项（对照 classes 服务） > 对照 ai-allocation.md §6 模板第 6 节 + §10 审计模板 | 对齐项 | classes 黄金模板 | student-bff 计划 | 备注 | | ------------------------------- | ---------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------- | | 权限装饰器 `@RequirePermission` | ✅ 全部 Controller 方法 | ⚠️ **B3 豁免** | BFF 豁免 `@RequirePermission`（B3 裁决），但强制自我越权防御（B4，AuthorizationGuard） | | 错误码前缀统一 | ✅ `CLASSES_` | ✅ `BFF_STUDENT_` | B5 裁决：BFF 在前，非 `STUDENT_BFF_` | | logger（pino） | ✅ `shared/observability/logger.ts` | ✅ 复制 teacher-bff 实现 | service 名改 `student-bff` | | metrics（prom-client） | ✅ `/metrics` 端点 | ✅ 复制 teacher-bff main.ts 注册方式 | 指标名前缀 `student_bff_` | | tracer（OpenTelemetry） | ✅ OTLP exporter + auto-instrumentations | ✅ 复制 teacher-bff tracer.ts | serviceName 改 `student-bff` | | `/healthz` 健康检查 | ✅ liveness | ✅ 复制 teacher-bff | BFF 不查 DB，直接返回 ok | | `/readyz` 健康检查 | ✅ Drizzle `SELECT 1` | ✅ 检查下游 6 个服务可达性 | 必需失败返回 503，可选软失败返回 200 + degraded=true | | 优雅关闭（SIGTERM） | ✅ LifecycleService 关闭 DB 连接池 | ✅ main.ts 注册 SIGTERM → `app.close()` + `shutdownTracer()` + `circuitBreaker.shutdown()` | BFF 无 DB 连接，关闭 HTTP server + tracer + 熔断器 | | 测试覆盖率 ≥ 80% | ✅ Jest | ✅ **Vitest**（已落地） | 5 个测试文件：action-state / application-error / authorization.guard / homework.resolver / push-gateway.service | | Dockerfile 多阶段构建 | ✅ builder + runtime | ✅ 复制 teacher-bff Dockerfile | EXPOSE 改 3009 | | Zod 输入验证 | ✅ Controller 层 `schema.parse(body)` | ✅ Controller 层校验 | 提交作业 body 需 Zod 校验 | | GlobalErrorFilter | ✅ `@Catch()` 全局过滤器 | ✅ 复制 teacher-bff | 注册到 main.ts | | ESM `.js` 后缀 import | ✅ tsconfig NodeNext | ✅ 复制 teacher-bff tsconfig | 所有相对 import 带 `.js` | | `import type` 纯类型导入 | ✅ | ✅ | 对齐 classes 规范 | | 环境变量 Zod 校验 | ✅ `config/env.ts` | ✅ 复制 teacher-bff env.ts | 下游 URL 配置项扩展 | ### 6.1 与 teacher-bff 模板的差异点（克隆时必须改） | 文件 | teacher-bff 现值 | student-bff 应改为 | | ------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------ | | `package.json` name | `@edu/teacher-bff` | `@edu/student-bff` | | `src/config/env.ts` `PORT` default | `"3003"` | `"3009"` | | `src/config/env.ts` 下游 URL | IamServiceUrl / ClassesServiceUrl / CoreEduServiceUrl | + ContentServiceUrl / DataAnaServiceUrl / MsgServiceUrl / AiServiceUrl（按聚合需求） | | `src/teacher/` 目录名 | `teacher/` | `student/` | | `@Controller("teacher")` | `"teacher"` | `"student"` | | `health.controller.ts` `SERVICE_NAME` | `"teacher-bff"` | `"student-bff"` | | `application-error.ts` 错误码前缀 | `TEACHER_BFF_` | `BFF_STUDENT_`（B5 裁决：BFF 在前） | | `metrics.ts` 指标名前缀 | `teacher_bff_` | `student_bff_` | | `tracer.ts` serviceName | `"teacher-bff"` | `"student-bff"` | | `logger.ts` service | `"teacher-bff"` | `"student-bff"` | | `main.ts` 启动日志 | `"Teacher BFF started"` | `"Student BFF started"` | | `Dockerfile` `EXPOSE` | `3003` | `3009` | --- ## 7. 风险与依赖（待 coord 仲裁） ### 7.1 上游依赖缺口 | 风险 | 影响 | 缓解措施 | | -------------------------------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------- | | data-ana 服务未实现查询 API（analytics.proto 3 个 method 无 REST 端点） | P4 学情诊断端点无法实现 | P3 阶段先不实现 `/student/analytics/*`，等 ai06 在 P4 实现 data-ana 查询 API 后再补 | | ai 服务未实现 REST/gRPC 端点 | P5 AI 答疑端点无法实现 | P3/P4 阶段先不实现 `/student/ai/*`，等 ai06 在 P5 实现 ai 服务后再补 | | content.proto 缺 Chapter/Question 域 | P4 教材/题库端点 proto 契约不全 | 推动 coord 在 shared-proto 补全 content.proto | | iam.proto 缺 Viewport/EffectivePermissions | 学生端导航视口 proto 契约不全 | 当前走 REST `/iam/viewports`，proto 补全后切换 | | 出勤（attendance）全局缺失 | 学生端无法查出勤 | 推动 coord 在 core_edu.proto 补 Attendance 域（P3 后期或 P4） | | 学生-家长关联表缺失（pending-features P2 提到 `parent_student_relations`） | 影响 parent-bff，不影响 student-bff | 报告给 coord，由 ai02 在 iam 或 ai03 在 core-edu 补表 | ### 7.2 设计决策（已裁决 B1-B8） > ✅ 全部 8 项决策已由 coord-final-decisions §2 B1-B8 + president-final-rulings §2.2-2.9 裁决。 | 决策点 | 裁决编号 | 裁决结论 | | ------------------ | -------- | ---------------------------------------------------------------------------------------------- | | BFF API 风格 | **B1** | GraphQL Yoga + DataLoader（P2 起直接 GraphQL，禁止 REST 渐进） | | 下游通信 | **B2** | gRPC 首次实现即用（@grpc/grpc-js + @grpc/proto-loader，禁止 HTTP fetch） | | BFF 权限校验 | **B3** | BFF 豁免 `@RequirePermission`，但透传 `x-user-id` 给下游校验 | | 自我越权防御 | **B4** | 强制 B4 越权防御（AuthorizationGuard，场景 A + 场景 B，president §2.9 方案 D DEV_MODE 放行） | | 错误码前缀 | **B5** | `BFF_STUDENT_`（BFF 在前，非 `STUDENT_BFF_`） | | Redis 缓存 | **B6** | 5-30s 短缓存，TTL ±20% 随机抖动防雪崩 | | Kafka 订阅 | **B7** | P2-P4 不订阅，P5 起订阅 7 个 topic，Redis SETNX `event_id` 幂等去重 | | DownstreamClient | **B8** | 抽象复用 shared-ts，回写 teacher-bff，3 个 BFF 统一使用 | | 降级模式 | president §2.6 | 方案 B：`success=true + data 内 degraded=true + degradedFields` | | 越权防御错误码 | president §2.7 | 3 类：ForbiddenResourceError / IdentityMismatchError / DEV_MODE 放行 | | GraphQL schema 存放 | president §2.2.1 | `packages/shared-ts/contracts/graphql/student-bff.schema.graphql` | | 端口分配 | - | 3009（HTTP），无 gRPC 端口对外 | ### 7.3 跨模块协作需求（需提交 coord 协调） | 需求 | 涉及 AI | 协调内容 | | ------------------------------------------------------------ | -------------- | --------------------------------------------------------- | | api-gateway 新增 `/student` 路由 | ai01 | 在 main.go + config.go 新增 `StudentBffURL` 字段 + 路由块 | | docker-compose.deploy.yml 新增 student-bff 服务定义 | coord（infra） | 端口 3009，加入 edu-net + edu-shared 网络 | | full-stack-runbook 端口矩阵更新 | coord（docs） | 追加 3009 行 | | 004 架构图状态更新 | coord（docs） | student-bff 状态从"📐 需设计"改为"✅ 已实现" | | shared-proto 补全 content.proto（Chapter/Question） | coord | P4 阶段 content 服务落地前补全 | | shared-proto 补全 iam.proto（Viewport/EffectivePermissions） | coord | 推动 ai02 补 proto | | buf.gen.yaml 补 gRPC 插件 | coord | ✅ B2 裁决已落地：TS 走 @grpc/proto-loader 动态加载，无需 buf generate gRPC 插件 | --- ## 8. 阶段 1 自检结论 | 检查项 | 状态 | | ------------------------------------ | --------------------------- | | 已读必读文档清单（ai-allocation §4） | ✅ | | 已运行 arch:scan 更新 arch.db | ✅ | | 已查 arch:query modules / stats | ✅ | | 已读 classes 黄金模板源码 | ✅ | | 已读 teacher-bff BFF 模板源码 | ✅ | | 已读 iam 认证服务源码 | ✅ | | 已读 shared-proto 全部 .proto | ✅ | | 已识别 proto 契约缺口 | ✅（见 §7.1） | | 已识别端口/路由预留情况 | ✅（3009 可用，路由未预留） | | 已识别设计决策待仲裁项 | ✅ → **已裁决**（B1-B8 + president §2.2-2.9，见 §7.2） | | 已识别跨模块协作需求 | ✅（见 §7.3） | **ai04 阶段 1 交付完成，已对齐仲裁裁决（coord-final-decisions B1-B8 + president-final-rulings §2.2-2.9）。P3-P6 全部代码已实现。**