# 旧后端迁移路线 本文档用于记录从旧 PocketBase / Supabase / NestJS 后端迁移到新 ASP.NET Core + PostgreSQL 后端的阶段性状态和后续优先级。 仓库转正决策和第一阶段基线分别见： - [`docs/adr/0001-authoritative-dotnet-backend.md`](adr/0001-authoritative-dotnet-backend.md) - [`docs/migration/phase-1-repository-baseline.md`](migration/phase-1-repository-baseline.md) - [`docs/migration/phase-2-engineering-foundation.md`](migration/phase-2-engineering-foundation.md) 迁移原则： - 不追求旧接口逐字兼容，新前端按新 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`。 - 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 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 git diff --check dotnet ef migrations script \ --project Tiku.Infrastructure \ --startup-project Tiku.DbMigrator ``` 如果某批不涉及数据库 migration，也仍然运行 migration script，确认当前模型快照和迁移链没有损坏。 ## 下一批建议 下一批建议执行： ```text 高级交易运营：退款、对账、调账 ``` 建议目标： - 学生/管理员可查询退款状态。 - 租户管理员可创建、审核、处理退款申请。 - 支付回调和退款事件保持幂等。 - 对账批次、明细、异常问题可查询。 - 对账异常可创建 issue、流转状态、记录事件。 - 调账凭证可创建、审核、作废，并影响后续报表口径。 建议暂缓： - 自动下载真实微信/支付宝账单。 - 自动退款真实网关请求。 - 平台级财务审批流。 - 发票、催缴、佣金联动调账。