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.
78 lines
5.3 KiB
Markdown
78 lines
5.3 KiB
Markdown
# 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 待实现）
|
||
|
||
**做了什么**：
|
||
|
||
1. 运行 `pnpm run arch:scan` 更新 arch.db（10 TS / 2 Go / 2 Python / 138 proto 契约，12 模块 342 符号）
|
||
2. 通过 3 个 search subagent 并行探索：classes/teacher-bff/iam 三个 TS NestJS 模板服务结构、shared-proto 全部 8 个 .proto 契约、student-bff/parent-bff 现状与端口/路由预留
|
||
3. 阅读 README、MIGRATION_GUIDE、004 架构影响地图、pending-features 路线图
|
||
4. 产出两份模块理解确认书 + 一份服务审计表
|
||
|
||
**学到什么**：
|
||
|
||
1. **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 仲裁是否统一升级
|
||
|
||
2. **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 端点未实现
|
||
|
||
3. **parent-bff 存在 P0 阻塞项**：
|
||
- iam 缺失"家长-学生关联查询"接口（proto + REST + schema 三缺失）
|
||
- pending-features P2 提到 `parent_student_relations` 表，但 iam.schema.ts 未实现
|
||
- 需 coord 协调 ai02 在 P3 阶段补全，否则 P4 parent-bff 无法启动
|
||
|
||
4. **004 §4 服务依赖图与实际场景存在偏差**：
|
||
- 004 列 parent-bff 仅依赖 iam + core-edu
|
||
- 但家长通知、学情诊断场景需要 msg + data-ana
|
||
- 需 coord 仲裁是否扩展 parent-bff 依赖
|
||
|
||
5. **端口/路由预留情况**：
|
||
- 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
|
||
|
||
6. **BFF 克隆模板策略**：
|
||
- teacher-bff 是最小 BFF 模板，shared/ 目录结构与 classes 完全一致
|
||
- BFF 特征：无 DB、无 repository/schema/dto、无 PermissionGuard、无 LifecycleService
|
||
- student-bff/parent-bff 可 1:1 克隆 teacher-bff 后改造（11 处需改名）
|
||
|
||
**下次注意**：
|
||
|
||
1. 阶段 2 设计文档需等 coord 审核阶段 1 后再产出
|
||
2. 实施前需推动 coord 协调 ai02 补全 iam 家长-学生关联接口（P0 阻塞）
|
||
3. 实施前需推动 coord 协调 ai01 在 api-gateway 预留 `/student`、`/parent` 路由
|
||
4. proto 包名合规性（`next_edu_cloud.*` → `edu.*`）需 coord 仲裁是否迁移
|
||
5. 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 通信未落地 |
|