# 待开发功能路线图

> 按 6 阶段组织的功能路线图，每阶段列出关键功能和交付物。
> 阶段依赖：P1 → P2 → P3 → P4/P5（可并行但建议串行） → P6

---

## P1 地基阶段（M1-M3）

**目标**：搭建新仓库地基，多语言 monorepo + Docker 基础设施 + API Gateway + classes 黄金模板服务 + 文档体系 + CI/CD，端到端跑通 classes 域 CRUD。

**退出标准**：classes 域 CRUD 端到端跑通 + 全横切关注点落地 + 30 分钟可复制新服务。

### 关键功能

| 模块 | 功能 |
|------|------|
| 仓库骨架 | 多语言 monorepo（pnpm + go.work + pyproject）+ 大仓文档（LICENSE/CHANGELOG/CONTRIBUTING/SECURITY） |
| Docker 基础设施 | 全量 docker-compose.yml（按 profiles 分阶段启用）+ 最小开发集（MySQL+Redis） |
| API Gateway（Go） | 路由转发 + JWT HS256 校验 + 请求 ID 注入 + 健康检查 |
| 契约层 | shared-proto 包 + classes.proto + buf lint/breaking + 三端代码生成配置 |
| classes 黄金模板（TS/NestJS） | CRUD + 全横切关注点（错误处理/可观测/安全/契约/测试/文档/配置/i18n/CI/Dockerfile） |
| arch.db 多语言扫描器 | TS 扫描（ts-morph）+ Go 扫描（正则骨架）+ Python 扫描（正则骨架）+ 查询工具 |
| teacher-portal 测试页 | Next.js 单页验证 classes CRUD 端到端链路 |
| CI/CD | 三语言 workflow（ci-go.yml / ci-ts.yml / ci-py.yml） |

### 交付物

- `docker-compose up -d` 全量容器健康
- 浏览器创建班级 → MySQL 落库 → 列表显示
- `buf lint` + `buf breaking` 通过，三端代码生成成功
- 三语言 CI workflow 全绿（lint+test+build）
- 单元 + 集成 + 契约 + E2E 四类测试齐备，覆盖率达标
- 004 + 2 个模块 README + known-issues + project_rules 齐全
- `npm run arch:query -- violations` 输出 0
- 30 分钟内复制 classes 模板跑起新服务
- 打 tag `v0.1.0-p1`

---

## P2 身份阶段（M4-M6）

**目标**：建 IAM 服务替换 P1 Gateway 内置鉴权；建首个完整 BFF（Teacher）与微前端骨架。

**退出标准**：教师登录 → 获取 JWT → 访问 teacher-portal → 侧边栏按 `viewports.L1` 渲染 → 看到空白 Dashboard。

### 关键功能

| 模块 | 功能 |
|------|------|
| IAM 服务（TS/NestJS） | 认证（登录/登出/JWT/2FA）+ RBAC（角色/权限/角色-权限 CRUD）+ 视口配置（4 层模型）+ DataScope 解析 + `getEffectivePermissions(userId)` |
| MySQL schema | users / roles / permissions / role_permissions / role_viewports / parent_student_relations / class_subject_teachers |
| JWT RS256 | IAM 私钥签发，Gateway/服务公钥校验，access 15min / refresh 7day |
| 权限缓存 | `getEffectivePermissions` 结果 Redis 缓存 TTL 5 分钟，角色变更主动失效 |
| Teacher BFF（TS/GraphQL） | GraphQL Yoga + DataLoader（防 N+1）+ 调 IAM 注入视口 |
| teacher-portal（微前端宿主） | Module Federation + 路由骨架 + 侧边栏（viewports.L1 驱动）+ 登录页 |
| API Gateway 升级 | 移除内置 JWT，改调 IAM 校验；路由表扩展 `/api/v1/iam/*` |

### 交付物

- IAM 服务完整实现认证 + RBAC + 视口 + DataScope
- JWT RS256 非对称签名链路通畅
- Teacher BFF GraphQL 接口可用
- teacher-portal 微前端骨架 + 登录流程
- 教师登录后侧边栏按角色渲染
- 打 tag `v0.2.0-p2`

---

## P3 核心教学阶段（M7-M10）

**目标**：建 CoreEdu 服务实现考试全生命周期；落地 Outbox + Kafka 事件模式。

**退出标准**：教师创建考试 → 发布 → 学生作答提交 → 教师批改 → 事件发到 Kafka → 成绩统计更新 → 全链路可观测。

### 关键功能

| 模块 | 功能 |
|------|------|
| CoreEdu 服务（TS/NestJS） | 考试/作业/成绩域 CRUD + 批改业务编排 + Outbox 事件发布 |
| MySQL schema | exams / exam_questions / homework_assignments / homework_submissions / homework_answers / grade_records / outbox_events |
| Outbox 模式 | 业务事务同写 outbox_events 表；后台 relay worker 投递 Kafka |
| Outbox relay（Go） | 独立服务 `services/outbox-relay/`，轻量高吞吐 |
| Kafka | 启用业务 topic：exam.published / homework.graded / grade.recorded |
| Teacher BFF 扩展 | 考试/作业/成绩的 GraphQL 查询与 mutation |
| teacher-portal 扩展 | 考试创建/作业批改/成绩查看页面 |
| student-portal（微前端） | 学生作答作业页面（Module Federation 子应用） |
| Temporal | 引入但仅做 1 个工作流（考试发布编排：创建作业→通知）试点 |

### 交付物

- CoreEdu 服务考试全生命周期链路通畅
- Outbox + Kafka 事件模式落地
- Outbox relay worker 稳定投递
- student-portal 微前端子应用接入
- 全链路 trace 可追（OTel）
- Outbox 模式回写黄金模板 README
- 打 tag `v0.3.0-p3`

---

## P4 内容分析阶段（M11-M13）

**目标**：建 Content 服务（Neo4j 知识图谱）+ DataAna 服务（Python+ClickHouse）；落地 CDC 链路。

**退出标准**：教师查看知识图谱前置依赖（Neo4j 秒级返回）→ 学生查看学情诊断（ClickHouse 宽表 5s 内返回）→ CDC 链路延迟 < 5s。

### 关键功能

| 模块 | 功能 |
|------|------|
| Content 服务（TS/NestJS） | 教材/章节/知识点 CRUD（仅 CRUD，不实现检索）+ 知识图谱查询（Neo4j）+ 题库 CRUD（不实现检索） |
| MySQL schema | textbooks / chapters / knowledge_points / questions |
| Neo4j 数据 | 知识点前置依赖图（从 MySQL 同步） |
| DataAna 服务（Python/FastAPI） | 学情诊断 API + 错题本 API + 消费 Kafka 构建宽表 |
| ClickHouse | student_dashboard_view 宽表（DataAna 消费 Kafka 填充） |
| CDC 链路 | Debezium 监听 MySQL binlog → Kafka（mysql.cdc.*）→ DataAna 消费写 ClickHouse |
| BFF 扩展 | Teacher BFF 加知识图谱查询；Student BFF 加学情诊断查询（双轨读） |

### 交付物

- Content 服务知识图谱查询秒级返回
- DataAna 学情诊断宽表 5s 内返回
- CDC 链路延迟 < 5s
- Neo4j 双写避免（消费事件同步）
- 双轨读策略落地（实时查主库 + 聚合查宽表）
- CDC 模式回写黄金模板 README
- 打 tag `v0.4.0-p4`

---

## P5 沟通与 AI 阶段（M14-M16）

**目标**：建 Msg 服务 + Push Gateway + AI 网关；全文检索迁 ES。

**退出标准**：教师发广播通知 → 全在线学生实时收到（Push Gateway）→ AI 辅助出题流式返回 → 题库全文检索 < 200ms。

### 关键功能

| 模块 | 功能 |
|------|------|
| Msg 服务（TS/NestJS） | 会话/消息 CRUD + 调 Push Gateway 推送 + 通知偏好 |
| Push Gateway（Go） | WebSocket 长连接管理 + 消费 Kafka 广播 + Redis PubSub 跨实例同步 |
| AI 网关（Python/FastAPI） | LLM Provider 适配（OpenAI/Anthropic）+ Prompt 模板管理 + 流式 SSE + 用量计费 |
| Elasticsearch | 题库全文检索（从 MySQL 同步）+ 全局搜索 API |
| Notifications 模块 | 多渠道（站内/SMS/邮件/微信），沿用旧项目 dispatcher 模式 |
| BFF/前端扩展 | Teacher BFF 加 AI 辅助出题 mutation；teacher-portal 加 SSE 流式 AI 对话 |

### 交付物

- Msg 服务会话/消息 CRUD + 推送链路
- Push Gateway 单节点支撑 10w+ 连接
- AI 网关流式 SSE 三层透传（AI → BFF → 前端）
- ES 题库全文检索 < 200ms
- 全校广播推送实时到达
- 长连接模式回写黄金模板 README
- 打 tag `v0.5.0-p5`

---

## P6 硬化阶段（M17-M18）

**目标**：生产硬化，达到可部署状态。

**退出标准**：单服务可独立扩缩容（HPA 生效）→ 全链路 trace 可追 → 模拟单服务宕机不影响核心链路 → 99.9% 可用性压测通过。

### 关键功能

| 模块 | 功能 |
|------|------|
| Service Mesh | Istio 服务网格（mTLS + 流量治理 + 可观测） |
| 配置中心 | Consul 接入，配置热更新（限流阈值、功能开关） |
| 全链路可观测 | OpenTelemetry + Jaeger（trace）+ Prometheus（metrics）+ Loki（logs） |
| 限流/熔断 | Gateway 层限流（令牌桶）+ 服务间熔断（Envoy） |
| 灰度发布 | Istio 流量拆分（金丝雀） |
| K8s 部署 | 每服务 K8s manifest + HPA 自动扩缩容 |
| 生产 CI/CD | Git tag 触发镜像构建 + 滚动部署 |
| 灾备 | MySQL 主从 + Redis 哨兵 + Kafka 多副本 |

### 交付物

- Istio Service Mesh 全网格覆盖（mTLS）
- 全链路 trace + Grafana 仪表盘 + Loki 日志查询
- 限流熔断灰度发布可用
- K8s HPA 自动扩缩容生效
- 单服务宕机不影响核心链路
- 99.9% 可用性压测通过
- 降级方案：若时间紧张，Service Mesh 可降级为 K8s 原生 Service + Ingress
- 打 tag `v1.0.0-p6`

---

## 跨阶段不变约束

每阶段都必须遵守：

- 契约先行（先改 proto，后写实现）
- 文档同步（004 + 模块 README + arch.db + known-issues 实时更新）
- CI 全绿才能合入 main
- 每阶段末打 tag
- Server/Handler 接口必须权限校验
- 单文件行数遵循语言规范（TS ≤ 500/800/1000，Go ≤ 800，Python ≤ 800）
- 阶段特有模式实现后回写黄金模板