tiku-backend.net/docs/development-plan.md

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. 统一发布门禁

发布候选必须满足：

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