tiku-backend.net/docs/migration-roadmap.md

旧后端迁移路线

本文档用于记录从旧 PocketBase / Supabase / NestJS 后端迁移到新 ASP.NET Core + PostgreSQL 后端的阶段性状态和后续优先级。

迁移原则：

• 不追求旧接口逐字兼容，新前端按新 REST API 对接。
• 不照搬 Supabase Auth/RLS，权限在 ASP.NET Authentication / Authorization 和应用服务里收口。
• 数据一致性落 PostgreSQL FK / unique / check / index 约束。
• 多租户数据默认带 TenantId，跨租户引用优先使用 composite FK。
• JSON 字段使用 C# JsonElement + PostgreSQL jsonb，不落字符串。
• 旧版明显是占位、临时脚本或平台自动化的部分，不直接硬搬，先重新设计边界。

当前已完成

基础设施

• ASP.NET Core Controller API。
• EF Core + Npgsql + PostgreSQL。
• 单例 NpgsqlDataSource + AddDbContextPool<TikuDbContext>。
• Serilog 结构化日志。
• CORS / RateLimiter / Options 校验。
• Scalar / OpenAPI 基础入口。
• 阿里云 OSS V2 资源存储抽象。
• Senparc 微信登录与小程序码生成边界。

数据库

已完成 greenfield 初始 schema，并持续追加必要 migration。当前数据库模型已经覆盖：

• 租户、用户、成员、认证、Session、短信验证码。
• 题库、题目、题目版本、内容树、题集、练习蓝图。
• 词汇、手册、分数线动态字段与记录。
• 资源、图片、App 资源、视频解析、导入任务。
• 学习记录、答题、收藏、错题、报告、统计。
• 商品、订单、支付、权益、兑换码、优惠券。
• 积分任务、积分兑换。
• 推广、邀请码、归因、CRM 队列、佣金结算。
• 运营内容、通知、徽章、审计。
• 平台账单、催缴、审计告警、对账/退款相关模型。
• PocketBase 导入审计。

已迁移业务闭环

• 安全底座、JWT、数据库 Session、当前用户和当前租户。
• 手机号密码登录、短信登录、微信网页登录、微信小程序登录。
• 公开 catalog：Banner、FAQ、公告、考试日期、商品、SVIP 套餐等。
• 内容导航、题库、词汇、手册、视频、资源公开查询。
• 资源上传签名、确认、下载/预览签名。
• 学生个人中心、通知、徽章、反馈。
• 学习统计、排行榜、错题/单词复习。
• 题目管理、内容导入骨架、词汇/手册/分数线/视频后台管理。
• 商品下单、微信/支付宝/manual 支付、支付回调、权益发放。
• 积分任务、积分领取、积分兑换。
• 优惠券领取、校验、下单抵扣、零元订单发权益。
• 租户后台商品、订单、支付、兑换码、积分、优惠券基础运营。
• 推广邀请码、归因、埋点、二维码生成 provider。
• 推荐管理、CRM 配置/队列/死信处理。
• 佣金配置、来源查询、结算生成、状态流转、凭证、导出。

剩余迁移范围

剩余部分不建议再按“旧接口数量”机械推进。旧 NestJS 里还有大量平台运营、自动化、审计、对账、AI 推荐等后段能力，应该按业务风险和依赖关系分批迁移。

1. 高级交易运营

建议下一批优先迁移。

旧版相关模块：

• commerce-adjustments.module.ts
• commerce-reconciliation.module.ts
• 部分 commerce-payments.module.ts

目标能力：

• 退款申请、审核、处理、退款事件。
• 支付/订单调账凭证。
• 对账批次、对账明细、对账异常。
• 对账问题创建、分配、状态流转、处理事件。
• provider bill jobs 账单下载任务骨架。
• 管理侧交易异常报表。

为什么优先：

• 当前系统已经能下单、支付、发权益、算佣金。
• 真实运营里最先遇到的是退款、支付差异、人工调账。
• 相关数据库模型基本已经存在，适合继续在交易边界内补完整。

建议提交拆分：

1. feat: add commerce refund operations
2. feat: add commerce reconciliation queries
3. feat: add commerce reconciliation issue workflow
4. feat: add commerce adjustment voucher operations

2. 租户内容导出与 Worker 骨架

旧版相关模块：

• tenant-content-exports.module.ts
• 内容导入/统计/资源扫描相关 worker 逻辑。

目标能力：

• 内容导出任务查询。
• 创建导出任务。
• 导出文件落 OSS。
• 导入任务异步化。
• 资源安全扫描任务骨架。
• 统计聚合 worker 骨架。

注意：

• 不要把 worker 和 API 写成一坨。
• API 只负责创建任务、查询状态、下载结果。
• Worker 独立处理重试、幂等、失败记录。

3. 平台后台基础

旧版相关模块：

• platform-admin-overview.module.ts
• platform-admin-tenants.module.ts
• platform-admin-question-banks.module.ts

目标能力：

• 平台总览。
• 平台权限摘要。
• 平台员工查询与状态管理。
• 租户列表、租户状态调整。
• 租户账单资料。
• 公库题库授权/采纳管理。

注意：

• 这块是 SaaS 平台运营，不是学生端主链路。
• 需要先明确平台管理员权限模型，避免继续用粗粒度 TenantAdmin。

4. 平台账单、催缴、审计告警

旧版相关模块：

• platform-admin-billing.module.ts
• platform-admin-dunning.module.ts
• platform-admin-audit.module.ts

目标能力：

• SaaS 套餐和租户订阅。
• 用量记录与账单生成。
• 发票、发票明细、收款记录。
• 催缴提醒与通知渠道。
• 审计告警规则、告警查询、确认、解决。

注意：

• 这块涉及平台财务和自动化，不建议和学生交易混在一起。
• 自动生成账单、催缴、告警扫描应放到 Worker。

5. AI 推荐报告

旧版相关模块：

• ai.module.ts

目标能力：

• 学校推荐报告列表。
• 推荐详情。
• 推荐报告导出。
• 推荐生成任务。

注意：

• 不建议直接照搬旧版。
• 需要结合分数线动态字段、用户画像、目标院校、志愿规则重新设计。
• 应等核心数据和 worker 稳定后再做。

6. 零散补齐项

这些可以穿插迁移，但不建议打断主线：

• 学生端视频搜索、视频观看进度。
• 租户 secrets 通用后台管理。
• 租户监督规则。
• 租户洞察报表。
• 更细粒度 RBAC 权限点。
• 管理后台操作审计补全。

推荐后续顺序

1. 高级交易运营：退款、对账、调账
2. 租户内容导出 + Worker 骨架
3. 平台后台基础：总览、租户、平台员工、公库授权
4. 平台账单/发票/催缴/审计告警
5. AI 推荐报告
6. 零散体验与后台增强

每批固定验收

每批迁移完成后都必须：

dotnet build /home/xiong/Games/Anii/TIKU-BACKEND/TIKU-BACKEND.slnx
dotnet test /home/xiong/Games/Anii/TIKU-BACKEND/TIKU-BACKEND.slnx
dotnet format /home/xiong/Games/Anii/TIKU-BACKEND/TIKU-BACKEND.slnx --verify-no-changes
git -C /home/xiong/Games/Anii/TIKU-BACKEND diff --check
dotnet ef migrations script \
  --project /home/xiong/Games/Anii/TIKU-BACKEND/Tiku.Infrastructure \
  --startup-project /home/xiong/Games/Anii/TIKU-BACKEND/Tiku.DbMigrator

如果某批不涉及数据库 migration，也仍然运行 migration script，确认当前模型快照和迁移链没有损坏。

下一批建议

下一批建议执行：

高级交易运营：退款、对账、调账

建议目标：

• 学生/管理员可查询退款状态。
• 租户管理员可创建、审核、处理退款申请。
• 支付回调和退款事件保持幂等。
• 对账批次、明细、异常问题可查询。
• 对账异常可创建 issue、流转状态、记录事件。
• 调账凭证可创建、审核、作废，并影响后续报表口径。

建议暂缓：

• 自动下载真实微信/支付宝账单。
• 自动退款真实网关请求。
• 平台级财务审批流。
• 发票、催缴、佣金联动调账。