0a71b02e04
NestJS (6 services): implement @RequirePermission decorator with SetMetadata+Reflector, register APP_GUARD globally, fix as assertions to type guards, add explicit return types, fix import type for express, fix /metrics implicit any, replace native Error with ApplicationError, remove typeorm remnants, register LifecycleService. teacher-bff: add logger, ApplicationError, GlobalErrorFilter, forward real userId to downstream, log downstream failures, migrate health controller to shared/health. Go (2 services): interface to any, doc comments, CORS dev whitelist, JWT secret fail-fast, push-gateway internal API auth, metrics and readyz endpoints, remove dead code. Python (2 services): lifespan return type, dev_mode to bool, data-ana APIRouter, ai POST body model, ClickHouse async wrapping.
5.3 KiB
5.3 KiB
ai04 工作经验日志
AI 标识：ai04（student-bff + parent-bff） 阶段：阶段 1（全局理解） 日期：2026-07-09 待 coord 合并到
docs/troubleshooting/known-issues.md"工作经验日志"区
2026-07-09 阶段 1 上下文加载
模块：student-bff（P3 待实现）、parent-bff（P4 待实现）
做了什么：
- 运行
pnpm run arch:scan更新 arch.db（10 TS / 2 Go / 2 Python / 138 proto 契约，12 模块 342 符号） - 通过 3 个 search subagent 并行探索：classes/teacher-bff/iam 三个 TS NestJS 模板服务结构、shared-proto 全部 8 个 .proto 契约、student-bff/parent-bff 现状与端口/路由预留
- 阅读 README、MIGRATION_GUIDE、004 架构影响地图、pending-features 路线图
- 产出两份模块理解确认书 + 一份服务审计表
学到什么：
-
teacher-bff 实际实现与设计意图存在差距：
- 004 §11.3 设计意图为 GraphQL + DataLoader，pending-features P2 明确"Teacher BFF（TS/GraphQL）"
- 实际 teacher-bff 是纯 REST + 原生 fetch + Promise.allSettled，无 GraphQL、无 DataLoader
- ai04 建议 student-bff/parent-bff 先对齐 teacher-bff 现状（REST），避免技术栈分裂，待 coord 仲裁是否统一升级
-
shared-proto 契约与实际 REST 实现存在显著缺口：
- proto 包名用
next_edu_cloud.*而非项目规则要求的edu.*（8 个文件全不合规） - buf.gen.yaml 只配置了 protocolbuffers 序列化插件，无 gRPC 插件，proto 目前仅作"契约文档"
- iam REST 已暴露 viewports/permissions/effective/roles 端点，但 proto 完全缺失
- content REST 已实现 chapters/questions CRUD，但 proto 完全缺失
- data-ana/ai 服务的 proto 已定义但 REST 端点未实现
- proto 包名用
-
parent-bff 存在 P0 阻塞项：
- iam 缺失"家长-学生关联查询"接口（proto + REST + schema 三缺失）
- pending-features P2 提到
parent_student_relations表，但 iam.schema.ts 未实现 - 需 coord 协调 ai02 在 P3 阶段补全，否则 P4 parent-bff 无法启动
-
004 §4 服务依赖图与实际场景存在偏差：
- 004 列 parent-bff 仅依赖 iam + core-edu
- 但家长通知、学情诊断场景需要 msg + data-ana
- 需 coord 仲裁是否扩展 parent-bff 依赖
-
端口/路由预留情况：
- student-bff=3009、parent-bff=3010 可用（3001-3008 已用）
- api-gateway 未预留
/student、/parent路由（需 ai01 协调） - pnpm-workspace.yaml glob
services/*自动覆盖新目录 - commitlint scope-enum + CODEOWNERS 已预留 student-bff/parent-bff
-
BFF 克隆模板策略：
- teacher-bff 是最小 BFF 模板，shared/ 目录结构与 classes 完全一致
- BFF 特征：无 DB、无 repository/schema/dto、无 PermissionGuard、无 LifecycleService
- student-bff/parent-bff 可 1:1 克隆 teacher-bff 后改造（11 处需改名）
下次注意：
- 阶段 2 设计文档需等 coord 审核阶段 1 后再产出
- 实施前需推动 coord 协调 ai02 补全 iam 家长-学生关联接口（P0 阻塞）
- 实施前需推动 coord 协调 ai01 在 api-gateway 预留
/student、/parent路由 - proto 包名合规性（
next_edu_cloud.*→edu.*）需 coord 仲裁是否迁移 - buf.gen.yaml 是否补 gRPC 插件需 coord 决策
待 coord 合并到 known-issues.md "场景→技术"映射
| 场景 | 技术/规则 |
|---|---|
| BFF 服务克隆 teacher-bff 模板 | 复制 shared/ + 改 11 处命名（package.json/env.ts/Controller/SERVICE_NAME/错误码前缀/指标名前缀/tracer serviceName/logger service/Dockerfile EXPOSE） |
| BFF 不做权限校验 | 透传 x-user-id 给下游服务校验（对齐 teacher-bff），BFF 无 PermissionGuard |
| BFF 聚合用 Promise.allSettled | Dashboard 类聚合容错（部分失败返回 null）；单依赖查询用 throw BadGatewayError 快速失败 |
| BFF 无 DB 依赖 | /readyz 直接返回 ok，无 LifecycleService，无 closeDb() |
| 新服务端口分配 | NestJS 服务按 3001-3008 顺序分配，student-bff=3009、parent-bff=3010 |
| api-gateway 路由前缀命名 | BFF 用角色单数无 -bff 后缀（teacher-bff → /teacher，student-bff → /student） |
| proto 包名不合规 | 当前用 next_edu_cloud.*，规则要求 edu.*，8 个文件全不合规，待 coord 仲裁迁移 |
| buf.gen.yaml 缺 gRPC 插件 | 当前只配置 protocolbuffers 序列化，proto 仅作"契约文档"，gRPC 通信未落地 |