From c2e4cd2a12520f2039f9157ae62d610f39ec3976 Mon Sep 17 00:00:00 2001
From: xiong <xiongyx48@gmail.com>
Date: Sun, 26 Jul 2026 20:56:43 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=E6=97=A7=E5=90=8E?=
 =?UTF-8?q?=E7=AB=AF=E8=BF=81=E7=A7=BB=E8=B7=AF=E7=BA=BF=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/migration-roadmap.md | 241 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 241 insertions(+)
 create mode 100644 docs/migration-roadmap.md

diff --git a/docs/migration-roadmap.md b/docs/migration-roadmap.md
new file mode 100644
index 0000000..b983d4c
--- /dev/null
+++ b/docs/migration-roadmap.md
@@ -0,0 +1,241 @@
+# 旧后端迁移路线
+
+本文档用于记录从旧 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 权限点。
+- 管理后台操作审计补全。
+
+## 推荐后续顺序
+
+```text
+1. 高级交易运营：退款、对账、调账
+2. 租户内容导出 + Worker 骨架
+3. 平台后台基础：总览、租户、平台员工、公库授权
+4. 平台账单/发票/催缴/审计告警
+5. AI 推荐报告
+6. 零散体验与后台增强
+```
+
+## 每批固定验收
+
+每批迁移完成后都必须：
+
+```bash
+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，确认当前模型快照和迁移链没有损坏。
+
+## 下一批建议
+
+下一批建议执行：
+
+```text
+高级交易运营：退款、对账、调账
+```
+
+建议目标：
+
+- 学生/管理员可查询退款状态。
+- 租户管理员可创建、审核、处理退款申请。
+- 支付回调和退款事件保持幂等。
+- 对账批次、明细、异常问题可查询。
+- 对账异常可创建 issue、流转状态、记录事件。
+- 调账凭证可创建、审核、作废，并影响后续报表口径。
+
+建议暂缓：
+
+- 自动下载真实微信/支付宝账单。
+- 自动退款真实网关请求。
+- 平台级财务审批流。
+- 发票、催缴、佣金联动调账。