# 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 通信未落地                                                                             |