# classes 工作排期

> 负责人：ai07
> 关联：[workline.md](../workline.md)、[coord.md](../coord.md)、[contracts/classes_contract.md](../contracts/classes_contract.md)
> 模式：全并行（各 AI 一口气完成 P2-P6 全部代码，最后统一集成测试）
> 特殊说明：classes 是黄金模板（P1 已实现），P3 合并入 core-edu（ai08 接管）

---

## §1 总览

classes 是 Edu 微服务的黄金模板，P1 阶段已实现班级 CRUD + 全横切关注点。P3 阶段合并入 core-edu 后，classes 模块代码由 ai08 接管维护，但黄金模板对照 checklist 由 ai07 持续维护。

**全阶段目标**：

- P1（已完成）：班级 CRUD + 黄金模板 + 6 项整改
- P3：合并入 core-edu + Outbox + gRPC + DataScope + Redis 缓存 + cuid2 迁移
- P6：黄金模板 checklist 持续维护 + 硬化

---

## §2 全阶段甘特图（P1-P6）

```mermaid
gantt
    title ai07 classes 黄金模板全阶段排期
    dateFormat YYYY-MM-DD
    axisFormat %m-%d

    section P1 黄金模板整改
    阶段1+2架构设计文档 :crit, a7a, 2026-07-10, 1d
    typeorm移除+tracer修复+@Query替换 :crit, a7b, 2026-07-10, 1d
    测试覆盖率60→80%+Dockerfile升级 :a7c, 2026-07-11, 1d
    schema索引补齐 :a7d, 2026-07-11, 1d

    section P3 合并入core-edu
    shared/outbox目录补齐 :a7e, 2026-07-14, 2d
    cuid2迁移+DataScope注入 :a7f, 2026-07-15, 2d
    Redis缓存+软删除+分页 :a7g, 2026-07-17, 3d
    gRPC 50053启用+核心edu合并 :a7h, 2026-07-20, 2d

    section P6 硬化
    黄金模板checklist持续维护 :a7i, 2026-07-25, 5d
    可观测性增强+告警规则 :a7j, 2026-07-30, 3d
```

---

## §3 详细任务

### P1：黄金模板整改（立即）

| #   | 任务                                | 交付物                                                                    | 验收标准                          | 状态      |
| --- | ----------------------------------- | ------------------------------------------------------------------------- | --------------------------------- | --------- |
| 1   | 阶段 1+2 架构设计文档               | `services/classes/docs/01-understanding.md` + `02-architecture-design.md` | coord 交叉审查通过                | ✅ 已完成 |
| 2   | 移除 typeorm 冗余依赖               | `package.json` 删除 typeorm 行                                            | `pnpm install` 零错误             | 待执行    |
| 3   | tracer.ts console.log → logger.info | `src/shared/observability/tracer.ts` L20                                  | grep `console.log` 返回 0         | 待执行    |
| 4   | controller list @Req → @Query       | `src/classes/classes.controller.ts` L49-53                                | list 方法用 `@Query('gradeId')`   | 待执行    |
| 5   | 测试覆盖率阈值 60% → 80%            | `vitest.config.ts` + 补测试用例                                           | `pnpm test:coverage` 达 80%       | 待执行    |
| 6   | Dockerfile node:20 → node:22        | `Dockerfile`                                                              | 基础镜像 `node:22-alpine`         | 待执行    |
| 7   | schema 补齐索引                     | `classes.schema.ts` + 迁移脚本                                            | grade_id / head_teacher_id 有索引 | 待执行    |

### P3：合并入 core-edu（交接给 ai08）

| #   | 任务                      | 交付物                                                     | 验收标准                        | 状态   |
| --- | ------------------------- | ---------------------------------------------------------- | ------------------------------- | ------ |
| 1   | `shared/outbox/` 目录补齐 | outbox.repository / outbox.publisher / outbox.relay-worker | 事件可发布到 Kafka              | 待执行 |
| 2   | cuid2 迁移                | id 字段 uuid v4 → cuid2 + 数据迁移脚本                     | 双写过渡期完成                  | 待执行 |
| 3   | DataScope 6 级 WHERE 注入 | Repository list 方法接收 dataScope 参数                    | 6 级过滤生效                    | 待执行 |
| 4   | Redis 班级列表缓存        | cachedList 方法 + TTL 5 分钟 + 事件失效                    | 缓存命中率 > 80%                | 待执行 |
| 5   | 软删除 + 审计字段         | deleted_at / created_by / updated_by                       | DELETE 改软删除                 | 待执行 |
| 6   | 分页 + 批量查询           | 游标分页 + POST /classes/batch                             | proto page_size/page_token 落地 | 待执行 |
| 7   | gRPC server 50053 启用    | ClassService 5 RPC 实现                                    | gRPC health check SERVING       | 待执行 |
| 8   | PermissionGuard 改调 iam  | 动态权限查询 getEffectivePermissions                       | 角色变更无需改代码重启          | 待执行 |

### P6：硬化

| #   | 任务                        | 交付物                             | 验收标准         | 状态   |
| --- | --------------------------- | ---------------------------------- | ---------------- | ------ |
| 1   | 黄金模板 checklist 持续维护 | 02-architecture-design.md §10 更新 | 覆盖全部新模式   | 待执行 |
| 2   | 可观测性增强                | 日志注入 traceId + Outbox 积压告警 | Grafana 面板可用 | 待执行 |

---

## §4 依赖与就绪信号

- **我依赖**：
  - MySQL classes_db（P1 已就绪）
  - api-gateway 路由注册（P1 已就绪）
  - P3：iam `BatchGetUsers` + `getEffectivePermissions`
  - P3：Kafka 基础设施（ai08 启用）
- **我的就绪信号**：
  - P1：REST API 5 端点 + /healthz + /readyz + /metrics 可用（已就绪）
  - P3：gRPC 50053 + Outbox 事件发布 + Redis 缓存可用
- **交接信号**：P3 合并时，ai07 向 ai08 交接 classes 模块，交接清单见 02-architecture-design.md §11

---

## §5 交接计划（ai07 → ai08）

| 交接项             | 内容                                                    | 时间      |
| ------------------ | ------------------------------------------------------- | --------- |
| 源码交接           | `services/classes/src/` 全部源码                        | P3 启动时 |
| 文档交接           | `services/classes/docs/` 2 份设计文档                   | P3 启动时 |
| proto 交接         | `classes.proto` 由 core-edu 实现承载                    | P3 启动时 |
| 黄金模板保留       | `services/classes/` 保留作只读对照基准（待 coord 仲裁） | P3 合并后 |
| checklist 持续维护 | ai07 持续维护 02-architecture-design.md §10             | 跨阶段    |