Edu/docs/architecture/issues/worklines/classes_workline.md

classes 工作排期

负责人：ai07 关联：workline.md、coord.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）

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	跨阶段