# TIKU Backend 后续开发计划

## 1. 计划目标

后续开发围绕教育业务闭环、SaaS 产品化、可靠性、性能和可运营性推进。每个阶段必须形成可独立验收的业务结果，不以接口数量或数据表数量作为完成标准。

总体目标：

- 建立服务端可信的练习、评分、报告和学习分析链路。
- 完成内容生产、教学组织、学生学习和教师干预闭环。
- 打通套餐、权益、商品、订单、支付和教育资源访问。
- 提供平台端、租户端、教师端和学生端可实际使用的工作流。
- 建立真实 PostgreSQL、Redis 和对象存储路径下的质量与性能门禁。
- 保持模块化单体边界，在明确出现独立扩缩容需求前不拆分微服务。

## 2. 实施原则

- PostgreSQL 是业务状态、权限、权益、余额、订单和任务状态的权威来源。
- Redis 只用于缓存、限流和可重建的加速数据，不作为授权或交易事实来源。
- 客户端提交的用户、租户、角色、正确性、价格、权益和状态均不可信，必须由服务端解析或计算。
- 所有可能被网络重试的写操作必须具备幂等语义。
- 所有状态转换必须定义合法前置状态，并通过事务或比较并交换更新保证并发安全。
- 所有租户数据访问必须同时满足租户隔离、操作权限、DataScope、套餐权益和资源可见性规则。
- 导入、导出、聚合、提醒、扫描等长任务统一进入 `background_jobs`。
- 前端接口以实时 OpenAPI 为唯一契约来源，不维护第二套手写接口模型。
- 每个行为变更都要有回归测试；PostgreSQL 特有约束必须使用真实 PostgreSQL 验证。

## 3. 阶段总览

| 阶段 | 主题 | 建议周期 | 主要结果 |
| --- | --- | ---: | --- |
| P0 | 学习核心链路可信化 | 2 个迭代 | 服务端判分、幂等答题、并发安全交卷、不可变报告 |
| P1 | 内容生产与练习编排 | 2 个迭代 | 题目生命周期、题集、练习蓝图、导入发布闭环 |
| P2 | 教学组织与教师运营 | 2～3 个迭代 | 班级、任务、提醒、学情和学生干预 |
| P3 | 学生学习与个性化 | 2～3 个迭代 | 错题复习、间隔学习、自适应练习和成长激励 |
| P4 | SaaS 权益与商业闭环 | 2 个迭代 | 套餐权益、教育商品、支付、退款和激活码联动 |
| P5 | 产品界面与契约交付 | 持续并行 | 四类用户拥有完整可操作工作流 |
| P6 | 性能、扩展与可观测性 | 持续并行 | 业务压测、聚合读模型、多实例安全和 SLO 告警 |

周期用于安排依赖关系，不作为压缩验收范围的依据。阶段可以并行准备，但不得越过前置发布门禁。

## 4. P0：学习核心链路可信化

### 4.1 题目与评分快照

- 为练习会话题目保存题目 ID、版本 ID、题型、题干、选项、标准答案、解析、分值和评分规则快照。
- 会话创建后不得因题库后续编辑而改变本次练习的评分结果。
- 学生会话详情只能返回安全投影，不返回标准答案、解析或选项正确标记。
- 为单选、多选、判断、填空建立独立服务端评分器。
- 主观题支持 `PendingReview`、`TeacherReviewed` 和 `SelfPractice` 等明确状态。
- 自评结果只能用于练习反馈，不计入权威成绩、积分和排行榜。

### 4.2 答题幂等与并发控制

- 答题 DTO 增加 `IdempotencyKey`、`ExpectedSessionVersion` 和 `ClientSequence`。
- 建立答题幂等记录，保存操作类型、请求哈希、响应快照和完成状态。
- 相同幂等键与相同请求体必须重放原响应。
- 相同幂等键与不同请求体必须返回明确冲突。
- 练习会话增加并发版本和最后客户端序列。
- 使用数据库唯一约束和比较并交换更新阻止重复答案、乱序写入和多设备并发覆盖。
- 明确答案修改策略：允许覆盖时保留版本历史；不允许覆盖时返回稳定错误码。

### 4.3 交卷与报告状态机

- 定义 `Active → Scoring → Submitted`、`Active → Expired`、`Active → Cancelled` 状态转换。
- 交卷请求增加幂等键，并保证同一会话只能生成一份权威报告。
- 评分、错题更新、积分事件和报告生成在同一事务边界内提交，或通过同事务创建的后台任务可靠续办。
- 报告发布后保持不可变；重新评分必须生成新版本并记录原因、操作者和审计事件。
- 处理评分中断、任务重试和超时租约回收。

### 4.4 P0 测试与发布门禁

- 覆盖重复答题、幂等冲突、旧版本、乱序序列、双设备并发和重复交卷。
- 覆盖跨租户、非本人会话、过期会话、已提交会话和未授权题目。
- 覆盖学生响应不泄露答案及解析。
- 覆盖各客观题型的服务端判分和边界输入。
- 使用真实 PostgreSQL 验证唯一约束、事务竞争和失败回滚。
- 完成迁移首次执行及幂等第二次执行验证。

完成标准：客户端无法伪造成绩；网络重试不会产生重复答案、重复报告、重复积分或重复错题计数。

## 5. P1：内容生产与练习编排

### 5.1 内容生命周期

- 统一题目、目录节点、题集和练习蓝图的 `Draft → Review → Published → Archived` 生命周期。
- 增加乐观版本、状态前置校验、发布审计和归档恢复规则。
- 支持题目版本对比、引用关系查看和安全回滚。
- 发布前校验题干、选项、答案、解析、分类、资源和题型结构完整性。
- 已被历史练习引用的版本不得物理删除。

### 5.2 题集与练习蓝图

- 支持人工题集、动态规则题集和固定快照题集。
- 练习蓝图支持知识点、题型、难度、题量、分值、随机种子和去重规则。
- 创建练习时记录蓝图版本、抽题结果和随机种子，确保结果可重放。
- 增加题量不足、资源不可见、跨租户引用和已归档内容的失败关闭规则。

### 5.3 导入与批量运营

- 导入流程拆分为上传、解析、预检、确认、执行和结果下载。
- 预检结果精确到行、字段和错误代码。
- 导入支持幂等键、来源哈希和重复内容策略。
- 批量发布、归档和分类必须提供影响范围预览。
- 大批量任务进入后台任务系统，并支持进度、取消、重试和结果资产。

### 5.4 内容质量指标

- 记录题目使用次数、作答人数、正确率、平均耗时、跳过率和争议率。
- 为低质量、异常高正确率、异常低正确率和长期未使用题目提供运营筛选。
- 质量指标采用异步增量聚合，不在学生提交请求中执行大范围统计。

完成标准：运营人员可以从草稿创建到发布、组卷、导入和质量复盘完成完整工作流。

## 6. P2：教学组织与教师运营

### 6.1 班级与成员

- 完善班级、教师、助教、学生和分组模型。
- 支持邀请、批量导入、转班、退班、冻结和历史成员查询。
- 所有成员变更记录操作者、原因、时间和前后状态。
- DataScope 支持按校区、部门、班级和本人范围过滤。

### 6.2 学习任务

- 支持练习、每日一练、作业和考试任务。
- 支持目标班级、分组、指定学生、发布时间、截止时间、补交和重做策略。
- 发布任务时固定内容或蓝图版本，避免后续编辑改变已发布任务。
- 学生任务列表明确返回未开始、进行中、已提交、已逾期和已批改状态。

### 6.3 提醒与通知

- 支持任务发布、即将截止、逾期、批改完成和权益到期提醒。
- 提醒任务使用幂等键和领取租约，防止多实例重复发送。
- 通知记录渠道、模板版本、发送状态、失败原因和重试次数。
- 支持租户级通知策略、免打扰时段和渠道开关。

### 6.4 学情与干预

- 建立学生、班级、知识点和任务维度的学习统计。
- 支持未完成、连续退步、薄弱知识点和异常作答行为规则。
- 风险命中后生成教师待办，可记录联系、备注、处理结果和下次跟进时间。
- 教师只能查看 DataScope 允许的学生和班级。

完成标准：教师能够发布任务、查看进度、完成批改、识别风险并记录干预结果。

## 7. P3：学生学习与个性化

### 7.1 错题复习

- 错题记录包含知识点、错误次数、最近错误、最近复习、掌握状态和下一次复习时间。
- 区分未掌握、学习中、待巩固和已掌握状态。
- 复习结果更新间隔，不以单次答对立即永久解决。
- 错题复习生成稳定会话，并记录生成规则版本。

### 7.2 词汇与间隔学习

- 定义明确的间隔重复算法、等级、下次复习时间和遗忘重置规则。
- 复习计划按到期时间、掌握程度和每日上限生成。
- 算法版本和关键输入写入学习事件，保证结果可解释。

### 7.3 自适应练习

- 建立用户知识点掌握度读模型。
- 根据最近表现、题目难度、重复间隔和任务目标选择题目。
- 推荐结果保存输入快照、算法版本、候选集合和最终选择。
- 提供固定规则回退，推荐服务异常时仍可生成可用练习。

### 7.4 成长与激励

- 徽章、连续学习、积分和阶段目标使用可配置规则。
- 奖励发放必须幂等，并记录触发事件和规则版本。
- 排行榜支持租户、班级、时间范围和隐私开关。
- 防止通过重复提交、回放请求或自评结果刷取奖励。

完成标准：学生可以获得稳定、可解释且不会重复奖励的个性化学习计划。

## 8. P4：SaaS 权益与商业闭环

### 8.1 统一权益判定

- 建立统一权益服务，组合操作权限、DataScope、套餐 Feature、额度、区域策略和灰度状态。
- 统一返回拒绝原因和可观测诊断信息。
- 前端 bootstrap 只展示最终可用能力，但后端仍独立执行完整判定。
- 权益变更后可靠失效本地缓存和 Redis 缓存。

### 8.2 教育商品与权益发放

- 商品可绑定课程、题库、练习次数、有效期和会员等级。
- 支付成功后幂等发放权益。
- 退款、撤销、订单关闭和订阅到期执行明确的权益回收或冻结策略。
- 保留每次权益变更的来源订单、规则、操作者和审计记录。

### 8.3 激活码

- 支持批次、渠道、数量、有效期、领取限制和适用租户。
- 激活过程使用事务和唯一约束，防止重复核销。
- 激活结果与权益服务联动，并支持撤销审计。
- 提供批次使用率、渠道效果和异常核销报表。

### 8.4 租户自助运营

- onboarding 使用可恢复状态机覆盖租户、Owner、域名、品牌、套餐和支付配置。
- 域名验证、证书和网关配置进入后台任务并保留诊断信息。
- 主题、导航和模块配置支持草稿、预览、发布、版本和回滚。
- 平台支持面向指定租户查看能力、用量、账务、任务和配置异常。

完成标准：租户能够完成开通、配置、购买、使用、续费和故障诊断，不依赖人工修改数据库。

## 9. P5：产品界面与契约交付

### 9.1 平台端

- 完成租户 onboarding、域名、套餐、账务、用量、题库和运营任务工作台。
- 所有长任务显示进度、失败原因、重试和结果下载入口。
- 提供租户能力诊断和配置版本回滚入口。

### 9.2 租户管理端与教师端

- 完成员工、角色、学生、班级、内容、任务、学情、商品和订单工作流。
- 页面操作权限与后端权限清单保持一致。
- 批量操作必须先展示影响范围和失败明细。

### 9.3 学生端

- 完成运行时 bootstrap、登录、任务、练习、错题、词汇、视频、权益和订单闭环。
- 网络重试统一携带幂等键和客户端序列。
- 明确处理会话过期、版本冲突、权益不足和任务已结束状态。

### 9.4 契约门禁

- 每次 Controller 变更后重新生成 OpenAPI 和前端类型。
- CI 检查 OpenAPI operation、DTO 和前端生成产物是否同步。
- 禁止前端手写后端枚举值、权限代码和请求模型。

完成标准：每类用户都可以在界面中完成对应业务闭环，且不存在仅有 API、没有可操作入口的已发布能力。

## 10. P6：性能、扩展与可观测性

### 10.1 查询与读模型

- 将学习统计的多次顺序查询改为条件聚合或专用汇总读模型。
- 将趋势按日期、知识点和班级的聚合下推 PostgreSQL。
- 为高频筛选建立与实际查询匹配的复合索引，并使用真实执行计划验证。
- 控制分页上限，避免无界列表和大对象图加载。
- 为核心端点建立单请求数据库命令数预算。

### 10.2 缓存策略

- 缓存目录、运行时配置、Feature 快照、公共内容和稳定聚合结果。
- 缓存键必须包含租户、资源版本和影响结果的策略版本。
- 写操作提交成功后再执行缓存失效；失效失败必须可重试。
- 记录缓存命中率、回源率、失效延迟和热键。

### 10.3 后台处理与多实例

- 所有任务领取继续使用 PostgreSQL 租约和 `FOR UPDATE SKIP LOCKED`。
- 生命周期扫描和周期性调度增加跨实例互斥或唯一调度记录。
- 任务处理器必须幂等，并区分可重试和永久失败。
- 记录任务排队时间、执行时间、重试次数、租约过期和死任务数量。

### 10.4 业务性能测试

- 保留公共缓存读和依赖就绪场景。
- 增加带 JWT、权限、租户解析和 DataScope 的认证分页读。
- 增加创建练习、并发答题、交卷、报告和排行榜场景。
- 增加下单、支付回调、退款和权益发放场景。
- 增加导入、导出和提醒后台任务积压恢复场景。
- 结果必须报告目标速率、实际 QPS、状态分布、错误率、p95、p99、丢弃迭代和依赖指标。
- 稳态容量测试至少持续 30 分钟，并使用接近生产的数据量和独立发压端。

### 10.5 可观测性与 SLO

- 建立 API 延迟、错误率、数据库命令数、连接池等待和慢 SQL 指标。
- 建立 Redis 延迟、命中率、连接失败和缓存失效指标。
- 建立答题冲突、重复交卷、评分失败、支付回调失败和权益补偿指标。
- 日志统一包含请求 ID、租户 ID、用户 ID、操作、任务 ID 和业务对象 ID，敏感值必须脱敏。
- 为认证、练习、支付、后台任务和数据库连接池设置发布告警门槛。

完成标准：核心业务拥有可重复的容量基线，扩容不会导致重复任务、重复发放或状态竞争。

## 11. 每阶段统一交付物

每个阶段合并前必须同时交付：

- Domain、Application、Infrastructure 和 API 边界清晰的实现。
- 可审查的 EF Core Migration；特殊 PostgreSQL 约束使用手写 SQL。
- DTO、OpenAPI operation、错误码和生成的前端类型。
- 单元测试、API 集成测试和真实 PostgreSQL 集成测试。
- 跨租户、越权、重复请求、并发竞争和失败回滚负向测试。
- 必要的指标、结构化日志和运维配置。
- 对应平台端、租户端、教师端或学生端工作流。
- 发布、回滚、数据兼容和缓存失效说明。

## 12. 统一发布门禁

发布候选必须满足：

```bash
dotnet restore TIKU-BACKEND.slnx
dotnet build TIKU-BACKEND.slnx --no-restore
dotnet test TIKU-BACKEND.slnx --no-build
dotnet format TIKU-BACKEND.slnx --verify-no-changes --no-restore
dotnet ef migrations script --project Tiku.Infrastructure --startup-project Tiku.DbMigrator
git diff --check
```

涉及数据库或种子数据时还必须：

- 在 Development 环境运行真实 `Tiku.DbMigrator`。
- 再运行一次迁移器验证幂等性。
- 验证迁移前后关键数据兼容性。
- 验证真实 PostgreSQL 下的租户隔离、约束和并发行为。

涉及性能敏感路径时还必须：

- 运行对应业务场景压测。
- 对照最近一次有效基线检查吞吐、p95、p99、错误率和数据库命令数。
- 性能退化未解释或超过阶段门槛时不得发布。

## 13. 建议执行顺序

严格按以下顺序启动开发：

1. 服务端评分与题目快照。
2. 答题幂等、会话版本和客户端序列。
3. 并发安全交卷与不可变报告。
4. 内容生命周期、题集和练习蓝图。
5. 班级、任务、提醒、学情和教师干预。
6. 错题间隔复习、词汇学习和自适应练习。
7. 套餐权益、教育商品、支付和激活码联动。
8. 完成各角色产品界面及 OpenAPI 契约门禁。
9. 聚合读模型、业务压测、多实例安全和 SLO 告警。

P0 未通过发布门禁前，不应上线积分奖励、排行榜或基于正确率的推荐；这些能力依赖可信评分结果。