Edu/services/classes/docs/02-architecture-design.md

# 模块架构设计文档 — classes

> AI：ai07（TS / 教学组织 · 黄金模板）
> 阶段：阶段 2 交付物
> 日期：2026-07-10
> 关联：[阶段 1 理解确认书](./01-understanding.md)、[004 架构影响地图](../../../docs/architecture/004_architecture_impact_map.md)、[pending-features](../../../docs/architecture/roadmap/pending-features.md)、[项目规则](../../../.trae/rules/project_rules.md)
> 状态：待 coord 交叉审查
>
> **设计原则**：classes 是黄金模板，本架构设计同时服务于两个目标：
>
> 1. **当前目标**：D2 教学组织域班级 CRUD 端到端跑通 + 全横切关注点落地 + 30 分钟可复制新服务
> 2. **长远目标**：为 P3 合并入 core-edu 做无痕准备 + 为其余 8 个 TS 服务输出对照标准 + 为未来事件驱动 / gRPC / DataScope / 缓存 / 多租户 / 软删除等演进预留接口
>
> **架构通用标准对齐**：本设计遵循 IEEE/ThoughtWorks/Stitch 架构评估维度——功能正确性、可维护性、可测试性、可扩展性、可观测性、安全性、可部署性、容错性，每个设计决策均标注其服务的标准维度。

---

## 目录

1. [模块内部分层图](#1-模块内部分层图)
2. [领域模型](#2-领域模型)
3. [数据模型](#3-数据模型)
4. [API 设计](#4-api-设计)
5. [事件设计](#5-事件设计)
6. [横切关注点对齐清单](#6-横切关注点对齐清单)
7. [与其他模块的交互点（契约清单）](#7-与其他模块的交互点契约清单)
8. [风险与假设](#8-风险与假设)
9. [长远架构与未来铺垫](#9-长远架构与未来铺垫)
10. [黄金模板对照 checklist（供其他 TS 服务自检）](#10-黄金模板对照-checklist供其他-ts-服务自检)
11. [整改清单与里程碑](#11-整改清单与里程碑)
12. [AI 身份标注](#12-ai-身份标注)

---

## 1. 模块内部分层图

### 1.1 调用链总览

```mermaid
flowchart TB
    subgraph Client["客户端 / Gateway / BFF"]
        Req[HTTP 请求<br/>带 x-user-id / x-user-roles 头]
    end

    subgraph NestJS["classes 服务（NestJS）"]
        direction TB
        MW[AuthMiddleware<br/>⚠️ 已定义未注册，P3 接入]
        Guard[PermissionGuard<br/>APP_GUARD 全局守卫]
        Filter[GlobalErrorFilter<br/>全局异常过滤器]

        subgraph Controllers["Controller 层"]
            ClassCtl[ClassesController<br/>/classes CRUD]
            HealthCtl[HealthController<br/>/healthz /readyz]
        end

        subgraph Services["Application Service 层"]
            ClassSvc[ClassesService<br/>班级领域编排 + 业务校验]
        end

        subgraph Repo["Repository 层"]
            ClassRepo[ClassesRepository<br/>Drizzle 查询]
        end

        subgraph Shared["Shared 横切"]
            Logger[pino logger]
            Metrics[prom-client registry]
            Tracer[OTel SDK]
            Errors[ApplicationError 体系]
        end

        subgraph Outbox["Outbox 模块（P3 补齐）"]
            OutboxTbl[(classes_outbox 表)]
            Relay[OutboxRelayWorker<br/>轮询 + Kafka 投递]
        end

        subgraph Infra["基础设施"]
            Db[(MySQL<br/>classes_db)]
            Redis[(Redis<br/>P3 班级列表缓存)]
            Kafka[(Kafka<br/>edu.org.class.* topic)]
        end
    end

    Req --> Guard
    Guard --> ClassCtl
    ClassCtl --> ClassSvc
    ClassSvc --> ClassRepo
    ClassRepo --> Db
    ClassSvc -.P3.-> OutboxTbl
    OutboxTbl --> Relay
    Relay --> Kafka
    Filter -.捕获异常.-> ClassCtl
```

### 1.2 分层职责

| 层         | 文件                                                                                                                      | 职责                                                   | 依赖方向     |
| ---------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------ |
| Controller | [classes.controller.ts](../src/classes/classes.controller.ts)                                                             | HTTP 入口、Zod 校验、权限声明、响应信封封装            | → Service    |
| Service    | [classes.service.ts](../src/classes/classes.service.ts)                                                                   | 领域编排、业务规则校验（空 body、存在性检查）、ID 生成 | → Repository |
| Repository | [classes.repository.ts](../src/classes/classes.repository.ts)                                                             | Drizzle ORM 数据访问、参数化查询                       | → DB         |
| Middleware | [auth.middleware.ts](../src/middleware/auth.middleware.ts) / [permission.guard.ts](../src/middleware/permission.guard.ts) | 身份解析（读 header）、权限校验（APP_GUARD 全局）      | 横切         |
| Shared     | shared/observability、shared/errors、shared/health、shared/lifecycle                                                      | 可观测三支柱、错误体系、健康检查、优雅关闭             | 横切         |
| Config     | [env.ts](../src/config/env.ts) / [database.ts](../src/config/database.ts)                                                 | Zod 环境校验、Drizzle 连接池                           | 基础设施     |

> **依赖方向单向**：Controller → Service → Repository → DB，禁止反向依赖（project_rules §3.2）。

### 1.3 中间件 / Guard / Filter 拦截顺序

```mermaid
sequenceDiagram
    participant GW as API Gateway
    participant MW as AuthMiddleware
    participant Guard as PermissionGuard
    participant Ctl as Controller
    participant Svc as Service
    participant Repo as Repository
    participant DB as MySQL
    participant Filter as GlobalErrorFilter

    GW->>MW: HTTP + x-user-id/roles 头
    Note over MW: 当前未注册，Guard 直接读 header
    MW->>Guard: req.userId / req.userRoles
    Guard->>Guard: DEV_MODE=true 跳过<br/>否则按 ROLE_PERMISSIONS 校验
    Guard->>Ctl: 通过 / 抛 PermissionDeniedError
    Ctl->>Ctl: Zod schema.parse(body)
    Ctl->>Svc: 调用 Service
    Svc->>Repo: 调用 Repository
    Repo->>DB: Drizzle 查询
    DB-->>Repo: 结果
    Repo-->>Svc: Class / undefined
    Svc-->>Ctl: Class / 抛 NotFoundError
    Ctl-->>GW: {success:true, data}
    Note over Filter: 任意层抛错被 GlobalErrorFilter 捕获
    Filter-->>GW: {success:false, error:{code,message,traceId}}
```

---

## 2. 领域模型

### 2.1 聚合根与实体

classes 当前是**轻量领域模型**（CRUD 为主，无复杂业务规则），但为 P3 合并后承载更多业务预留扩展点。

```mermaid
graph LR
    subgraph ClassAggregate["Class 聚合根"]
        Class[Class<br/>id, name, gradeId,<br/>headTeacherId, description]
        ClassStatus[ClassStatus<br/>值对象: active/archived/graduated]
    end

    subgraph 未来扩展["P3+ 合并后扩展（core-edu 承载）"]
        Subject[Subject 聚合<br/>学科]
        Enrollment[Enrollment 聚合<br/>选课/分班]
        StudentRoster[StudentRoster<br/>值对象: 班级花名册]
    end

    Class -.归属.-> Subject
    Class -.包含.-> StudentRoster
    StudentRoster -.关联.-> Enrollment
```

| 聚合根    | 字段                                                                | 业务不变量（当前 + 预留）                                                                                                           |
| --------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Class** | id, name, gradeId, headTeacherId, description, createdAt, updatedAt | 当前：name 非空、gradeId 必填、headTeacherId 可空；预留：status 状态机（active→archived→graduated）、capacity 上限、schoolId 多租户 |

### 2.2 聚合间通信

- **当前**：classes 仅一个聚合，无聚合间通信
- **P3 合并后**：Class 与 Subject、Enrollment 同属 core-edu，**同服务内直接调用**（非跨服务事件）
- **跨服务**：Class 变更通过 Kafka 事件通知 data-ana / msg（见 §5）

### 2.3 领域服务（预留）

当前无独立领域服务（ClassesService 兼任应用服务 + 领域编排）。P3 合并后建议拆分：

| 服务               | 职责                                       | 触发时机            |
| ------------------ | ------------------------------------------ | ------------------- |
| ClassDomainService | 班级状态机转换、容量校验、班主任变更合法性 | P3 业务规则复杂化时 |

---

## 3. 数据模型

### 3.1 表结构（当前）

`classes` 表（见 [classes.schema.ts](../src/classes/classes.schema.ts)）：

| 字段            | 类型         | 约束                                   | 说明                       |
| --------------- | ------------ | -------------------------------------- | -------------------------- |
| id              | char(36)     | PK, NOT NULL                           | 当前 uuid v4，待迁移 cuid2 |
| name            | varchar(100) | NOT NULL                               | 班级名称                   |
| grade_id        | char(36)     | NOT NULL                               | 年级外键（年级表归属待定） |
| head_teacher_id | char(36)     | NULL                                   | 班主任外键（iam user）     |
| description     | text         | NULL                                   | 描述                       |
| created_at      | timestamp    | NOT NULL DEFAULT NOW()                 | 创建时间                   |
| updated_at      | timestamp    | NOT NULL DEFAULT NOW() ON UPDATE NOW() | 更新时间                   |

### 3.2 索引策略

| 索引                        | 字段            | 类型             | 用途                                  |
| --------------------------- | --------------- | ---------------- | ------------------------------------- |
| PRIMARY                     | id              | 主键             | 单条查询、更新、删除                  |
| idx_classes_grade_id        | grade_id        | 普通索引         | 按年级过滤（list 方法高频查询）       |
| idx_classes_head_teacher_id | head_teacher_id | 普通索引（预留） | P3 教师查询所属班级（高频，BFF 聚合） |

> **当前缺失**：grade_id 与 head_teacher_id 索引未在 schema 中声明（Drizzle schema 未显式定义索引），需在迁移脚本中补齐。

### 3.3 读写分离策略

| 场景                       | 路径                             | 说明                                                                     |
| -------------------------- | -------------------------------- | ------------------------------------------------------------------------ |
| 写（create/update/delete） | MySQL 主库（Drizzle）            | 当前唯一写路径                                                           |
| 读（list/getById）         | MySQL 主库（Drizzle）            | 当前唯一读路径                                                           |
| 读（P3 起，高频列表）      | Redis 缓存（TTL 5 分钟）         | 班级列表低频变更，适合缓存；事件驱动失效（ClassCreated/Updated/Deleted） |
| 读（P4 起，分析聚合）      | ClickHouse 宽表（data-ana 投影） | 班级维度统计走宽表，不走主库                                             |

### 3.4 数据模型演进路线（长远铺垫）

| 阶段 | 演进项     | schema 变更                                         | 兼容策略                                                     |
| ---- | ---------- | --------------------------------------------------- | ------------------------------------------------------------ |
| P3   | 软删除     | 新增 `deleted_at timestamp NULL`                    | 查询加 `WHERE deleted_at IS NULL`，Drizzle 封装软删除 filter |
| P3   | 状态机     | 新增 `status enum('active','archived','graduated')` | 默认 active，状态转换由 ClassDomainService 校验              |
| P3   | 多租户预留 | 新增 `school_id char(36)`                           | 为 SaaS 化预留，当前单租户填默认值                           |
| P3   | 容量限制   | 新增 `capacity int` + `current_count int`           | 分班时校验，current_count 由 enrollment 聚合维护             |
| P3+  | cuid2 迁移 | id 类型 char(36)→varchar(30)                        | 数据迁移脚本 + 双写过渡期                                    |
| P6   | 审计字段   | 新增 `created_by` / `updated_by`                    | 从 `x-user-id` 头注入                                        |

---

## 4. API 设计

### 4.1 REST API 端点（已实现）

| Method | Path           | 权限             | 请求                                                | 响应                               | HTTP 状态             | 说明                               |
| ------ | -------------- | ---------------- | --------------------------------------------------- | ---------------------------------- | --------------------- | ---------------------------------- |
| POST   | `/classes`     | `CLASSES_CREATE` | `{name, gradeId, headTeacherId?, description?}`     | `{success, data: ClassResponse}`   | 201 / 400 / 403       | 创建                               |
| GET    | `/classes`     | `CLASSES_READ`   | `?gradeId=<uuid>`                                   | `{success, data: ClassResponse[]}` | 200 / 403             | 列表，可选年级过滤                 |
| GET    | `/classes/:id` | `CLASSES_READ`   | path: `id`                                          | `{success, data: ClassResponse}`   | 200 / 404 / 403       | 单条                               |
| PUT    | `/classes/:id` | `CLASSES_UPDATE` | path:`id` + `{name?, headTeacherId?, description?}` | `{success, data: ClassResponse}`   | 200 / 400 / 404 / 403 | 更新（空 body 抛 ValidationError） |
| DELETE | `/classes/:id` | `CLASSES_DELETE` | path: `id`                                          | `{success: true}`                  | 200 / 404 / 403       | 删除（先校验存在）                 |

### 4.2 ClassResponse 结构

```typescript
interface ClassResponse {
  id: string;
  name: string;
  gradeId: string;
  headTeacherId: string | null;
  description: string | null;
  createdAt: number; // epoch ms（Drizzle timestamp → getTime()）
  updatedAt: number;
}
```

### 4.3 错误响应（ActionState 失败信封）

| 错误码                      | 触发条件                         | HTTP 状态 |
| --------------------------- | -------------------------------- | --------- |
| `CLASSES_VALIDATION_ERROR`  | Zod 校验失败 / 空 update body    | 400       |
| `CLASSES_NOT_FOUND`         | getById/update/delete 找不到资源 | 404       |
| `CLASSES_PERMISSION_DENIED` | PermissionGuard 校验失败         | 403       |
| `CLASSES_CONFLICT`          | 并发冲突（预留，当前未触发）     | 409       |
| `CLASSES_BUSINESS_ERROR`    | 业务规则违反（预留）             | 422       |
| `CLASSES_DATABASE_ERROR`    | DB 操作失败                      | 500       |
| `CLASSES_INTERNAL_ERROR`    | 未预期异常                       | 500       |

### 4.4 API 演进路线

| 阶段 | 演进项         | 兼容策略                                                                                       |
| ---- | -------------- | ---------------------------------------------------------------------------------------------- |
| P3   | 分页           | proto 已定义 `page_size` / `page_token`；REST 落地 `?pageSize=20&pageToken=<cursor>`，游标分页 |
| P3   | 软删除         | DELETE 改为软删除（写 deleted_at），新增 `?includeDeleted=true` 管理端查询                     |
| P3   | 批量查询       | 新增 `POST /classes/batch`（body: `{ids: string[]}`），供 BFF DataLoader 批量去重              |
| P3   | DataScope 注入 | list 方法根据 `x-user-datascope` 头注入 WHERE（见 §9.4）                                       |
| P3   | gRPC 启用      | proto `ClassService` 5 RPC 落地，REST 与 gRPC 并存过渡期                                       |
| P4   | 字段投影       | 支持 `?fields=id,name` 减少响应体积（GraphQL 替代后废弃）                                      |

---

## 5. 事件设计

### 5.1 我发布的领域事件（P3 由 core-edu 接管实现）

> **当前状态**：未实现。`shared/outbox/` 目录缺失，P3 合并后由 core-edu 统一补齐 Outbox 模式。

| 事件               | 触发时机           | Topic（004 §7.2）           | 消费者             | 消费者动作                            |
| ------------------ | ------------------ | --------------------------- | ------------------ | ------------------------------------- |
| `ClassCreated`     | create 成功后      | `edu.org.class.created`     | data-ana           | 建班级维度宽表行                      |
| `ClassUpdated`     | update 成功后      | `edu.org.class.updated`     | data-ana、msg      | 更新宽表；班主任变更通知新旧班主任    |
| `ClassDeleted`     | delete 成功后      | `edu.org.class.deleted`     | data-ana、core-edu | 删除宽表行；关联检查（考试/作业引用） |
| `ClassTransferred` | headTeacherId 变更 | `edu.org.class.transferred` | msg                | 通知新/旧班主任                       |

### 5.2 事件 message 契约

使用 `events.proto` 的 `ClassEvent`（见 [events.proto](../../../packages/shared-proto/proto/events.proto) 第 15-24 行）：

```protobuf
message ClassEvent {
  string event_id = 1;        // 幂等去重 ID（cuid2）
  string aggregate_id = 2;    // = class_id
  string event_type = 3;      // ClassCreated / ClassUpdated / ClassDeleted / ClassTransferred
  int64 occurred_at = 4;       // 事件发生时间（epoch ms）
  string class_id = 5;
  string name = 6;
  string action = 7;           // created / updated / deleted / transferred
  map<string, string> metadata = 8;  // 扩展字段：旧班主任 ID、变更字段列表等
}
```

### 5.3 Outbox 模式实现（P3 设计，供 core-edu 落地）

```mermaid
flowchart LR
    Cmd[ClassService.create] --> Repo[Repository.write]
    Repo --> BizT[(classes 表)]
    Repo --> OutT[(classes_outbox 表<br/>同事务)]
    OutT --> Relay[OutboxRelayWorker<br/>每 100ms 轮询]
    Relay --> Kafka[(Kafka<br/>edu.org.class.* topic)]
    Kafka --> Proj[data-ana Projection<br/>更新宽表]
    Kafka --> MsgC[msg 消费者<br/>通知投递]
```

**Outbox 表结构**（P3 补齐 `shared/outbox/`）：

| 字段         | 类型                        | 说明                  |
| ------------ | --------------------------- | --------------------- |
| event_id     | varchar(30) PK              | cuid2，幂等去重       |
| aggregate_id | varchar(30)                 | class_id              |
| event_type   | varchar(50)                 | ClassCreated 等       |
| payload      | json                        | ClassEvent 序列化     |
| topic        | varchar(100)                | edu.org.class.created |
| status       | enum('pending','published') | 投递状态              |
| created_at   | timestamp                   | 入库时间              |
| published_at | timestamp NULL              | 投递成功时间          |

### 5.4 我消费的外部事件（P3+）

| 事件          | 来源 | Topic                       | 消费动作                                                 |
| ------------- | ---- | --------------------------- | -------------------------------------------------------- |
| `UserDeleted` | iam  | `edu.identity.user.deleted` | 若 deleted user 是班主任，置空 headTeacherId（最终一致） |
| `UserUpdated` | iam  | `edu.identity.user.updated` | 班主任姓名变更无需同步（classes 仅存 id）                |

### 5.5 幂等性设计

- **Producer（Outbox Relay）**：Kafka `idempotent=true` + `transactionalId=classes-outbox-relay`
- **Consumer**：基于 `event_id` 去重（DB 唯一索引 `idx_outbox_event_id` 或 Redis SETNX，TTL 7 天）

---

## 6. 横切关注点对齐清单

### 6.1 权限装饰器（端点 × 权限常量）

| 端点                | 权限常量         | 装饰器                                           |
| ------------------- | ---------------- | ------------------------------------------------ |
| POST /classes       | `CLASSES_CREATE` | `@RequirePermission(Permissions.CLASSES_CREATE)` |
| GET /classes        | `CLASSES_READ`   | `@RequirePermission(Permissions.CLASSES_READ)`   |
| GET /classes/:id    | `CLASSES_READ`   | `@RequirePermission(Permissions.CLASSES_READ)`   |
| PUT /classes/:id    | `CLASSES_UPDATE` | `@RequirePermission(Permissions.CLASSES_UPDATE)` |
| DELETE /classes/:id | `CLASSES_DELETE` | `@RequirePermission(Permissions.CLASSES_DELETE)` |
| GET /healthz        | 无               | 无（白名单）                                     |
| GET /readyz         | 无               | 无（白名单）                                     |
| GET /metrics        | 无               | 无（Prometheus 抓取）                            |

**角色-权限映射**（[permission.guard.ts](../src/middleware/permission.guard.ts) 第 25-39 行）：

| 角色    | 权限                            |
| ------- | ------------------------------- |
| admin   | CREATE / READ / UPDATE / DELETE |
| teacher | CREATE / READ / UPDATE          |
| student | READ                            |
| parent  | READ                            |

> **演进**：P3 起由 iam 提供 `getEffectivePermissions(userId)` 动态查询，PermissionGuard 改为调用 iam 而非硬编码 ROLE_PERMISSIONS（project_memory 已记录该约束）。

### 6.2 错误码清单

见 [§4.3](#43-错误响应actionstate-失败信封）。前缀 `CLASSES_`（004 §11.4 确认保留，P3 合并入 core-edu 后保留历史遗留前缀）。

### 6.3 Logger

| 项        | 配置                                                          |
| --------- | ------------------------------------------------------------- |
| 库        | pino 9 + pino-pretty（dev）                                   |
| 初始化    | [logger.ts](../src/shared/observability/logger.ts) 模块级单例 |
| base 字段 | `{service: 'classes', version: '0.1.0'}`                      |
| level     | env.LOG_LEVEL（默认 info）                                    |
| 规则      | 禁止 `console.*`；tracer.ts 第 20 行待整改                    |

### 6.4 Metrics 指标清单

| 指标名                             | 类型                  | 标签                     | 描述                                                      |
| ---------------------------------- | --------------------- | ------------------------ | --------------------------------------------------------- |
| `classes_requests_total`           | Counter               | method, endpoint, status | 请求总数                                                  |
| `classes_request_duration_seconds` | Histogram             | method, endpoint         | 请求延迟分布                                              |
| 默认进程指标                       | Counter/Gauge/Summary | —                        | prom-client collectDefaultMetrics（CPU/内存/GC/事件循环） |

> **指标命名规范**（project_rules §12）：`<service>_<module>_<operation>_<unit>`，classes 已遵循。

### 6.5 Tracer

| 项          | 配置                                                                                |
| ----------- | ----------------------------------------------------------------------------------- |
| SDK         | @opentelemetry/sdk-node + auto-instrumentations                                     |
| exporter    | OTLP HTTP → `${OTEL_EXPORTER_OTLP_ENDPOINT}/v1/traces`                              |
| serviceName | `classes`                                                                           |
| 初始化      | [tracer.ts](../src/shared/observability/tracer.ts) `initTracer()` 在 bootstrap 调用 |
| 关闭        | `shutdownTracer()` 在 SIGTERM 钩子                                                  |
| 整改        | 第 20 行 `console.log` → `logger.info`                                              |

### 6.6 健康检查

| 端点       | 检查逻辑               | 失败行为                                              |
| ---------- | ---------------------- | ----------------------------------------------------- |
| `/healthz` | 进程存活（无依赖检查） | 200 `{status:"ok", service, timestamp}`               |
| `/readyz`  | DB `SELECT 1`          | 成功 200；失败 503 `{status:"error", service, error}` |

> **/readyz 演进**：P3 起补充 Redis PING、Kafka 连接检查（project_memory 约束：/readyz 必须检查所有下游依赖）。

### 6.7 优雅关闭

关闭顺序（见 [lifecycle.service.ts](../src/shared/lifecycle/lifecycle.service.ts)）：

1. NestJS `app.enableShutdownHooks()` 捕获 SIGTERM/SIGINT
2. `OnApplicationShutdown` 钩子触发
3. `closeDb()` 关闭 MySQL 连接池
4. `shutdownTracer()` 刷新 OTel span
5. K8s `terminationGracePeriodSeconds=60` 兜底

> **演进**：P3 起增加 Kafka consumer graceful drain（消费完 inflight 消息再退出）、Redis 连接关闭。

---

## 7. 与其他模块的交互点（契约清单）

| 方向   | 对方服务    | 协议                   | 接口/事件                                           | 用途             | 阶段  |
| ------ | ----------- | ---------------------- | --------------------------------------------------- | ---------------- | ----- |
| 被调用 | api-gateway | HTTP                   | `/classes/*` 路由转发                               | Gateway 反向代理 | P1 ✅ |
| 被调用 | teacher-bff | HTTP（P2）/ gRPC（P3） | `GET /classes` 或 `ClassService.ListClasses`        | BFF 聚合班级列表 | P2    |
| 调用   | MySQL       | TCP                    | mysql2 连接池                                       | 数据读写         | P1 ✅ |
| 调用   | Redis       | TCP（P3）              | ioredis                                             | 班级列表缓存     | P3    |
| 发布   | —           | Kafka（P3）            | `edu.org.class.created/updated/deleted/transferred` | 领域事件         | P3    |
| 消费   | iam         | Kafka（P3）            | `edu.identity.user.deleted`                         | 班主任置空       | P3    |
| 被调用 | core-edu    | gRPC（P3）             | `ClassService.GetClassesByTeacher`                  | 教师所属班级查询 | P3    |

> **P3 合并边界**：classes 合并入 core-edu 后，"被调用"方从 classes 改为 core-edu，端口从 3001 改为 3004，gRPC 50053。proto 契约 `ClassService` 迁移至 `core_edu.proto` 或保留 `classes.proto` 由 core-edu 实现。

---

## 8. 风险与假设

### 8.1 技术风险

| 风险                                         | 影响                 | 缓解措施                                                   |
| -------------------------------------------- | -------------------- | ---------------------------------------------------------- |
| uuid v4 → cuid2 迁移涉及主键变更             | 数据迁移风险         | P3 合并时统一迁移，双写过渡期 + 迁移脚本 + 回滚预案        |
| PermissionGuard 硬编码 ROLE_PERMISSIONS      | 角色变更需改代码重启 | P3 改为调用 iam `getEffectivePermissions` 动态查询         |
| 无 Outbox 能力                               | P3 事件驱动基础缺失  | P3 补齐 `shared/outbox/`，复用 iam shared-ts Outbox 工具包 |
| 无 DataScope 注入                            | 数据越权风险         | P3 Repository 层注入 WHERE 条件（见 §9.4）                 |
| Dockerfile node:20 与项目规则 node:22 不一致 | 镜像基准不统一       | P1 立即升级                                                |

### 8.2 假设

- 假设 api-gateway 已注入 `x-user-id` / `x-user-roles` 头（project_memory 确认）
- 假设 `gradeId` 引用的年级实体由管理端/前端维护，classes 不校验其存在性（无外键约束）
- 假设 P3 合并时 classes 表结构可无损迁移至 core-edu 库

### 8.3 未决决策（提请 coord 仲裁）

| #   | 议题                            | 选项                                                              | 我的倾向            |
| --- | ------------------------------- | ----------------------------------------------------------------- | ------------------- |
| 1   | P3 合并后 classes 目录保留方式  | A. 删除目录 / B. 保留只读对照 / C. 改为 shared-ts 模板            | B（保留对照基准）   |
| 2   | cuid2 迁移时机                  | A. P1 黄金模板立即 / B. P3 合并时统一                             | A（黄金模板先行）   |
| 3   | proto `ClassService` 合并后归属 | A. 迁移到 core_edu.proto / B. 保留 classes.proto 由 core-edu 实现 | B（保留契约稳定性） |

---

## 9. 长远架构与未来铺垫

> 本节是黄金模板的核心增值部分，为 classes 当前 CRUD 之外的未来演进预留接口，同时作为其他 TS 服务的"长远设计范例"。

### 9.1 事件驱动演进（EDA 铺垫）

**当前**：纯同步 CRUD，无事件。
**P3 目标**：Outbox + Kafka 全链路。
**设计预留**：

- `shared/outbox/` 目录结构标准化（outbox.repository / outbox.publisher / outbox.relay-worker），供 core-edu 直接复用
- TOPIC_MAP 集中管理 `事件 → topic` 映射，遵循 004 §7.2 命名规范
- 事件 schema 版本化：`event_type` 字段带 `v1` 后缀，演进时 `v2` 共存
- 幂等去重表设计标准化（event_id 唯一索引）

### 9.2 gRPC 演进铺垫

**当前**：仅 REST。
**P3 目标**：REST + gRPC 并存，BFF 切换 gRPC。
**设计预留**：

- proto 已定义 `ClassService` 5 RPC，与 REST 端点一一对应
- Controller 层保持薄，业务逻辑在 Service，gRPC 实现可直接复用 Service
- 响应信封 ActionState 在 gRPC 侧用 metadata 传递 error（gRPC status code + details）

### 9.3 缓存策略铺垫

**当前**：无缓存。
**P3 目标**：Redis 班级列表缓存（TTL 5 分钟）。
**设计预留**：

- 依赖 ioredis 已声明
- env 已留 `REDIS_URL`
- Repository 层封装 `cachedList` 方法，缓存 key 设计：`classes:list:gradeId={gradeId|all}`
- 失效策略：ClassCreated/Updated/Deleted 事件触发 `DEL classes:list:*`（模式删除）+ 短 TTL 兜底

### 9.4 DataScope 数据范围注入（安全铺垫）

**当前**：PermissionGuard 仅角色级校验，无数据行级过滤。
**P3 目标**：6 级 DataScope WHERE 注入（004 §5.3）。

**设计预留**：

| DataScope | WHERE 注入                                                               | 适用角色                |
| --------- | ------------------------------------------------------------------------ | ----------------------- |
| L0 SELF   | `WHERE head_teacher_id = :userId`                                        | 教师（仅看自己班级）    |
| L1 CLASS  | `WHERE id IN (SELECT class_id FROM enrollment WHERE student_id=:userId)` | 学生                    |
| L2 GRADE  | `WHERE grade_id IN (:managedGradeIds)`                                   | 年级组长                |
| L3 SCHOOL | `WHERE school_id = :schoolId`                                            | 校管理员（P3 多租户后） |
| L5 ALL    | 无过滤                                                                   | admin                   |

**实现**：Repository `list` 方法接收 `dataScope` 参数，动态构建 Drizzle WHERE；dataScope 从 `x-user-datascope` 头解析。

### 9.5 软删除与审计（可维护性铺垫）

**当前**：物理删除。
**P3 目标**：软删除 + 审计字段。

**设计预留**：

- schema 新增 `deleted_at timestamp NULL`
- Repository 封装 `withSoftDelete` 查询包装器，自动加 `WHERE deleted_at IS NULL`
- 新增 `created_by` / `updated_by`，从 `x-user-id` 头注入
- DELETE 端点改为写 `deleted_at = NOW()`，新增管理端 `?includeDeleted=true`

### 9.6 多租户 SaaS 演进（可扩展性铺垫）

**当前**：单租户。
**未来目标**：SaaS 多校隔离。

**设计预留**：

- schema 新增 `school_id`（默认填单租户 ID）
- Repository 所有查询注入 `WHERE school_id = :currentSchoolId`
- `school_id` 从 JWT claim 或 `x-school-id` 头解析
- 索引 `idx_classes_school_id_grade_id` 复合索引

### 9.7 分页与批量查询（性能铺垫）

**当前**：list 全量返回。
**P3 目标**：游标分页 + 批量查询。

**设计预留**：

- proto 已定义 `page_size` / `page_token`
- 游标分页：`page_token = base64(last_id)`，查询 `WHERE id > :lastId LIMIT :pageSize`
- 批量查询 `POST /classes/batch` body `{ids: string[]}`，供 BFF DataLoader 批量去重（防 N+1）

### 9.8 测试策略（可测试性铺垫）

**当前**：单元测试覆盖率 60%，仅 Service 层。
**目标**：80% 覆盖率 + 集成测试 + 契约测试。

| 测试类型 | 范围                                         | 工具                    | 目标覆盖率 |
| -------- | -------------------------------------------- | ----------------------- | ---------- |
| 单元测试 | Service（mock repo）                         | Vitest                  | 80%        |
| 集成测试 | Controller + Service + Repository（test DB） | Vitest + testcontainers | 关键路径   |
| 契约测试 | proto ↔ REST 一致性                          | buf breaking            | 100%       |
| E2E      | 端到端 CRUD                                  | docker-compose          | 冒烟       |

### 9.9 可观测性增强（可观测性铺垫）

**当前**：基础 metrics + tracer。
**目标**：结构化日志 + trace 关联 + 告警规则。

**设计预留**：

- 日志注入 `traceId` / `spanId` / `userId`（从 header 提取）
- metrics 增加 `classes_outbox_pending_total`（Outbox 积压告警）
- Grafana 面板模板化，供其他服务复用
- 告警规则：5xx 错误率 > 1% / p99 延迟 > 500ms / outbox 积压 > 100

### 9.10 配置管理演进（可部署性铺垫）

**当前**：env 环境变量（Zod 校验）。
**P6 目标**：配置中心热更新。

**设计预留**：

- 三层配置：env（环境变量）< yaml（业务参数）< 配置中心（P6 Consul）
- 业务参数（如分页默认值、缓存 TTL）抽离为 yaml，P6 接入 Consul 热更新

---

## 10. 黄金模板对照 checklist（供其他 TS 服务自检）

> 本 checklist 是 classes 作为黄金模板的核心产出，供 ai01-ai10 的 TS 服务在实现前自检对齐。

### 10.1 目录结构

```
services/<service>/src/
├─ <domain>/                  # 限界上下文
│  ├─ <domain>.controller.ts  # Controller（HTTP/gRPC 入口）
│  ├─ <domain>.service.ts     # Application Service（编排层）
│  ├─ <domain>.repository.ts   # Repository（数据访问）
│  ├─ <domain>.schema.ts      # Drizzle schema（表定义）
│  └─ <domain>.dto.ts         # Zod schema + DTO 类型
├─ config/                    # env.ts + database.ts
├─ middleware/                # auth.middleware.ts + permission.guard.ts
├─ shared/
│  ├─ errors/                 # application-error.ts + global-error.filter.ts
│  ├─ health/                 # health.controller.ts + health.module.ts
│  ├─ lifecycle/              # lifecycle.service.ts（优雅关闭）
│  ├─ observability/          # logger.ts + metrics.ts + tracer.ts
│  └─ outbox/                 # （P3 补齐）
├─ app.module.ts
└─ main.ts
```

### 10.2 横切关注点 checklist

| #   | 检查项                                        | 验证方式                        | 参考文件                                                              |
| --- | --------------------------------------------- | ------------------------------- | --------------------------------------------------------------------- |
| 1   | `@RequirePermission` 覆盖全部 Controller 方法 | grep `@RequirePermission`       | [classes.controller.ts](../src/classes/classes.controller.ts)         |
| 2   | 错误码前缀统一 `<SERVICE>_`                   | grep 错误码常量                 | [application-error.ts](../src/shared/errors/application-error.ts)     |
| 3   | pino logger，禁止 `console.*`                 | grep `console.log`              | [logger.ts](../src/shared/observability/logger.ts)                    |
| 4   | prom-client metrics + `/metrics` 端点         | 访问 `/metrics`                 | [metrics.ts](../src/shared/observability/metrics.ts)                  |
| 5   | OTel tracer 初始化 + 关闭                     | main.ts 调用 initTracer         | [tracer.ts](../src/shared/observability/tracer.ts)                    |
| 6   | `/healthz` liveness                           | GET 200                         | [health.controller.ts](../src/shared/health/health.controller.ts)     |
| 7   | `/readyz` 检查 DB 依赖                        | GET 200 / 503                   | 同上                                                                  |
| 8   | 优雅关闭 SIGTERM                              | LifecycleService                | [lifecycle.service.ts](../src/shared/lifecycle/lifecycle.service.ts)  |
| 9   | Zod 输入校验                                  | controller `schema.parse(body)` | [classes.dto.ts](../src/classes/classes.dto.ts)                       |
| 10  | GlobalErrorFilter 注册                        | app.useGlobalFilters            | [global-error.filter.ts](../src/shared/errors/global-error.filter.ts) |
| 11  | ActionState 响应信封                          | `{success, data/error}`         | controller 返回类型                                                   |
| 12  | Dockerfile 多阶段（builder + runtime）        | Dockerfile 检查                 | [Dockerfile](../Dockerfile)                                           |
| 13  | env Zod 校验                                  | envSchema.safeParse             | [env.ts](../src/config/env.ts)                                        |
| 14  | Drizzle ORM（禁止 TypeORM）                   | package.json 无 typeorm         | [package.json](../package.json)                                       |
| 15  | 测试覆盖率 ≥ 80%                              | vitest --coverage               | [vitest.config.ts](../vitest.config.ts)                               |
| 16  | ESM `.js` 后缀 import                         | grep `from "./xxx.js"`          | 全部源码                                                              |
| 17  | `import type` 用于类型导入                    | grep `import type`              | 全部源码                                                              |
| 18  | 无 `any` / 无 `as` 断言（除 unknown）         | tsc + eslint                    | —                                                                     |

### 10.3 复制黄金模板步骤（30 分钟可复制）

1. 复制 `services/classes/` 目录为 `services/<new-service>/`
2. 全局替换 `classes` → `<new-service>`（目录名、文件名、类名、错误码前缀、serviceName、metrics 指标名）
3. 修改 `<domain>/` 为新限界上下文，替换 schema / dto / controller / service / repository
4. 修改 `env.ts` 端口（按 [port-allocation.md](../../../infra/port-allocation.md)）
5. 修改 `Dockerfile` EXPOSE 端口
6. `pnpm install` + `pnpm lint` + `pnpm typecheck` + `pnpm test`
7. 运行 `pnpm run arch:scan` 更新 arch.db

---

## 11. 整改清单与里程碑

### 11.1 P1 立即整改（黄金模板对齐）

| #   | 整改项                                            | 文件                                                                      | 优先级 |
| --- | ------------------------------------------------- | ------------------------------------------------------------------------- | ------ |
| 1   | 移除 typeorm 冗余依赖                             | [package.json](../package.json) 第 33 行                                  | 高     |
| 2   | `console.log` → `logger.info`（tracer.ts）        | [tracer.ts](../src/shared/observability/tracer.ts) 第 20 行               | 高     |
| 3   | `@Req()` → `@Query('gradeId')`（controller list） | [classes.controller.ts](../src/classes/classes.controller.ts) 第 49-53 行 | 高     |
| 4   | 测试覆盖率阈值 60% → 80%                          | [vitest.config.ts](../vitest.config.ts)                                   | 中     |
| 5   | Dockerfile node:20 → node:22                      | [Dockerfile](../Dockerfile)                                               | 中     |
| 6   | 补齐 grade_id / head_teacher_id 索引              | schema 迁移                                                               | 中     |

### 11.2 P3 演进（合并入 core-edu 时落地）

| #   | 演进项                     | 说明                                       |
| --- | -------------------------- | ------------------------------------------ |
| 1   | 补齐 `shared/outbox/` 目录 | 事件发布能力，复用 shared-ts Outbox 工具包 |
| 2   | cuid2 迁移                 | 主键 uuid v4 → cuid2                       |
| 3   | DataScope 6 级 WHERE 注入  | Repository 层动态过滤                      |
| 4   | Redis 班级列表缓存         | TTL 5 分钟 + 事件驱动失效                  |
| 5   | 软删除 + 审计字段          | deleted_at / created_by / updated_by       |
| 6   | 分页 + 批量查询            | 游标分页 + POST /classes/batch             |
| 7   | gRPC server 启用           | proto ClassService 落地，端口 50053        |
| 8   | PermissionGuard 改调 iam   | 动态权限查询                               |

### 11.3 里程碑

| 里程碑        | 交付物                  | 验收标准                                          |
| ------------- | ----------------------- | ------------------------------------------------- |
| M1（P1）      | 黄金模板整改完成        | 6 项 P1 整改全部完成 + lint/typecheck/test 零错误 |
| M2（P1）      | 黄金模板 checklist 产出 | 本文档 §10 + 其他 AI 自检通过                     |
| M3（P3 交接） | classes 合并入 core-edu | ai08 接收，表结构 + proto + 事件能力迁移          |

---

## 12. AI 身份标注

**AI Agent**: ai07 (classes · 黄金模板)
**Branch**: docs/classes-architecture-design-ai07
**Coordinator**: coord

---

> 本架构设计文档遵循架构通用标准（功能正确性 / 可维护性 / 可测试性 / 可扩展性 / 可观测性 / 安全性 / 可部署性 / 容错性），既实现 P1 当前目标（班级 CRUD + 黄金模板），又为 P3+ 演进（事件驱动 / gRPC / DataScope / 缓存 / 软删除 / 多租户 / SaaS）铺设接口。待 coord 交叉审查通过后，§10 黄金模板 checklist 作为其余 8 个 TS 服务的强制对齐基准。