# 服务审计表 — ai04

> AI 标识：ai04
> 阶段：阶段 1（自检）
> 日期：2026-07-09
> 审计对象：student-bff（P3 待实现）、parent-bff（P4 待实现）
> 对照基准：classes 黄金模板（已实现）+ teacher-bff BFF 模板（已实现）
> 模板来源：[ai-allocation.md §10](../../docs/architecture/ai-allocation.md)

---

## 1. 审计状态说明

| 标记 | 含义                                                |
| ---- | --------------------------------------------------- |
| ✅   | 已对齐黄金模板（实施时复制 + 改名即可）             |
| ⚠️   | 有差异但已识别缓解方案（需 coord 仲裁或实施时调整） |
| ❌   | 未对齐，需补齐                                      |
| 🆕   | 全新服务，尚未实现，审计结果为"设计目标"            |

由于 student-bff 和 parent-bff 均为**全新服务（未实现）**，本审计表为**设计目标审计**，列出实施时需对齐的各项。

---

## 2. ai04 服务审计表

| 服务                         | 权限装饰器 | 错误码前缀        | logger  | metrics        | tracer  | /healthz | /readyz | 优雅关闭   | 测试覆盖率   | Dockerfile |
| ---------------------------- | ---------- | ----------------- | ------- | -------------- | ------- | -------- | ------- | ---------- | ------------ | ---------- |
| **student-bff**（P3 待实现） | ⚠️ 不对齐  | ✅ `STUDENT_BFF_` | ✅ pino | ✅ prom-client | ✅ OTel | ✅       | ✅      | ✅ SIGTERM | 🆕 目标 ≥80% | ✅ 多阶段  |
| **parent-bff**（P4 待实现）  | ⚠️ 不对齐  | ✅ `PARENT_BFF_`  | ✅ pino | ✅ prom-client | ✅ OTel | ✅       | ✅      | ✅ SIGTERM | 🆕 目标 ≥80% | ✅ 多阶段  |

---

## 3. 审计项详解

### 3.1 权限装饰器 `@RequirePermission` — ⚠️ 不对齐

**classes 黄金模板**：全部 Controller 方法用 `@RequirePermission(Permissions.XXX)` 装饰，全局 `PermissionGuard` 校验。

**ai04 服务决策**：**不对齐**。理由：

- BFF 是纯聚合层，权限由下游业务服务校验（对齐 teacher-bff 现状）
- BFF 透传 `x-user-id` 头给下游，下游 Repository 按 DataScope 过滤
- parent-bff 在 BFF 层做"DataScope=CHILDREN 越权校验"（家长查询的 childId 必须在绑定列表内），但用普通 Service 层校验，不用装饰器

**风险**：若 coord 要求 BFF 也加权限装饰器（双重校验），需在 student-bff/parent-bff 引入 `middleware/permission.guard.ts`（复制 classes 实现）。

### 3.2 错误码前缀 — ✅ 对齐

| 服务        | 前缀           | 示例                                                                              |
| ----------- | -------------- | --------------------------------------------------------------------------------- |
| student-bff | `STUDENT_BFF_` | `STUDENT_BFF_UNAUTHORIZED`、`STUDENT_BFF_BAD_GATEWAY`                             |
| parent-bff  | `PARENT_BFF_`  | `PARENT_BFF_UNAUTHORIZED`、`PARENT_BFF_BAD_GATEWAY`、`PARENT_BFF_CHILD_NOT_BOUND` |

对齐 teacher-bff 的 `TEACHER_BFF_` 模式。

### 3.3 logger — ✅ 对齐

复制 teacher-bff `shared/observability/logger.ts`，仅改 `service` 字段：

- student-bff: `service: 'student-bff'`
- parent-bff: `service: 'parent-bff'`

### 3.4 metrics — ✅ 对齐

复制 teacher-bff `shared/observability/metrics.ts` + `main.ts` 中 `/metrics` 端点注册，仅改指标名前缀：

- student-bff: `student_bff_requests_total`、`student_bff_request_duration_seconds`
- parent-bff: `parent_bff_requests_total`、`parent_bff_request_duration_seconds`

### 3.5 tracer — ✅ 对齐

复制 teacher-bff `shared/observability/tracer.ts`，仅改 `serviceName`：

- student-bff: `serviceName: 'student-bff'`
- parent-bff: `serviceName: 'parent-bff'`

### 3.6 /healthz — ✅ 对齐

复制 teacher-bff `shared/health/health.controller.ts`，仅改 `SERVICE_NAME`：

- student-bff: `service: 'student-bff'`
- parent-bff: `service: 'parent-bff'`

### 3.7 /readyz — ✅ 对齐

BFF 不查 DB，`/readyz` 直接返回 ok（对齐 teacher-bff）。

**可选增强**（P3 后期）：检查下游服务可达性（HEAD 请求 iam/core-edu 的 `/healthz`），但 P3 阶段建议先简单返回 ok，下游可达性由 Prometheus 监控。

### 3.8 优雅关闭 — ✅ 对齐

复制 teacher-bff `main.ts` 中 SIGTERM 处理：

```ts
process.on("SIGTERM", async () => {
  await app.close();
  await shutdownTracer();
});
```

BFF 无 DB 连接需关闭（无 LifecycleService），仅需关闭 HTTP server + tracer。

### 3.9 测试覆盖率 — 🆕 目标 ≥ 80%

**测试重点**：

- Service 层聚合逻辑（mock 下游 fetch，验证 Promise.allSettled 容错）
- Controller 层入参校验（Zod schema）
- 错误处理（BadGatewayError、UnauthorizedError、ValidationError）
- parent-bff 特有：DataScope=CHILDREN 越权校验

**测试框架**：Jest（对齐 classes，待确认 classes 是否已配置 Jest）。

### 3.10 Dockerfile — ✅ 对齐

复制 teacher-bff `Dockerfile`（多阶段构建：builder + runtime），仅改 `EXPOSE`：

- student-bff: `EXPOSE 3009`
- parent-bff: `EXPOSE 3010`

---

## 4. 与 teacher-bff 模板对比（克隆基线）

teacher-bff 是已实现的最小 BFF 模板，student-bff/parent-bff 应 1:1 克隆后改造。

### 4.1 完全复制的部分（无需改动）

| 文件/目录                              | 说明                                |
| -------------------------------------- | ----------------------------------- |
| `shared/errors/global-error.filter.ts` | 全局错误过滤器（仅错误码前缀不同）  |
| `shared/health/health.module.ts`       | 健康检查模块                        |
| `shared/observability/logger.ts`       | pino logger（仅 service 名不同）    |
| `shared/observability/metrics.ts`      | prom-client（仅指标名前缀不同）     |
| `shared/observability/tracer.ts`       | OTel tracer（仅 serviceName 不同）  |
| `app.module.ts`                        | 根模块（仅 imports 的业务模块不同） |
| `main.ts`                              | 启动流程（仅端口和日志不同）        |
| `tsconfig.json`                        | ESM 配置                            |
| `nest-cli.json`                        | NestJS CLI 配置                     |

### 4.2 需要改造的部分

| 文件                                    | 改造点                                                     |
| --------------------------------------- | ---------------------------------------------------------- |
| `package.json`                          | name 字段、dependencies（按下游服务需求扩展）              |
| `src/config/env.ts`                     | PORT default、下游服务 URL 配置项                          |
| `src/<context>/` 目录名                 | teacher → student / parent                                 |
| `src/<context>/<context>.controller.ts` | @Controller 装饰器前缀、端点路由                           |
| `src/<context>/<context>.service.ts`    | 聚合逻辑（按场景域不同）                                   |
| `src/<context>/<context>.module.ts`     | 模块注册                                                   |
| `shared/errors/application-error.ts`    | 错误码前缀、新增错误类（parent-bff 加 ChildNotBoundError） |
| `shared/health/health.controller.ts`    | SERVICE_NAME                                               |
| `Dockerfile`                            | EXPOSE 端口                                                |

### 4.3 teacher-bff 模板的可改进点（ai04 实施时可优化）

| 改进点       | teacher-bff 现状              | ai04 建议改进                                                |
| ------------ | ----------------------------- | ------------------------------------------------------------ |
| 聚合响应类型 | 大量用 `unknown`              | 用 Zod schema 推导强类型响应                                 |
| 下游调用封装 | 原生 `fetch()` 散落在 Service | 抽取 `DownstreamClient` 工具类（带超时、重试、traceId 透传） |
| 错误信封     | 下游错误直接吞掉返回 null     | 下游错误结构化记录（service/endpoint/status），透传 traceId  |
| 缓存         | 无缓存                        | 引入 NestJS CacheInterceptor + Redis（5-30s 短缓存）         |

> ⚠️ 这些改进点需 coord 仲裁是否回写到 teacher-bff（避免技术栈分裂），还是仅用于 student-bff/parent-bff。

---

## 5. 审计结论

| 服务        | 总体对齐度   | 阻塞项                                 | 备注                                                             |
| ----------- | ------------ | -------------------------------------- | ---------------------------------------------------------------- |
| student-bff | 🟢 高（90%） | 无 P0 阻塞                             | P3 阶段可直接克隆 teacher-bff 实施，data-ana/ai 端点延后到 P4/P5 |
| parent-bff  | 🟡 中（70%） | **P0 阻塞：iam 家长-学生关联接口缺失** | 需 coord 协调 ai02 在 P3 阶段补全 iam 接口，否则 P4 无法启动实施 |

**ai04 阶段 1 审计完成。两份理解确认书 + 本审计表已交付，请 coord 审核。**