forked from xiongyuxing/tiku-backend.net
261 lines
9.3 KiB
Markdown
261 lines
9.3 KiB
Markdown
# 旧后端迁移路线
|
||
|
||
本文档用于记录从旧 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)
|
||
- [`docs/migration/phase-3-tenant-isolation-and-shared-question-bank.md`](migration/phase-3-tenant-isolation-and-shared-question-bank.md)
|
||
- [`docs/migration/phase-4-external-provider-decoupling.md`](migration/phase-4-external-provider-decoupling.md)
|
||
- [`docs/migration/phase-5-backoffice-worker-operations.md`](migration/phase-5-backoffice-worker-operations.md)
|
||
|
||
迁移原则：
|
||
|
||
- 不追求旧接口逐字兼容，新前端按新 REST API 对接。
|
||
- 不照搬 Supabase Auth/RLS，权限在 ASP.NET Authentication / Authorization 和应用服务里收口。
|
||
- 不保留 Supabase 运行时依赖、Storage provider 或 Auth 兼容层。
|
||
- 数据一致性落 PostgreSQL FK / unique / check / index 约束。
|
||
- 多租户数据默认带 `TenantId`，跨租户引用优先使用 composite FK。
|
||
- ORM 不能自动表达的跨表租户不变量，使用集中 PostgreSQL trigger / constraint trigger SQL helper，由 EF Core migration 调用并用真实 PostgreSQL 集成测试验证。
|
||
- 外部身份、短信、对象存储、支付和通知都通过 Application 接口与 `TenantExternalProvider` 配置解耦。
|
||
- JSON 字段使用 C# `JsonElement` + PostgreSQL `jsonb`，不落字符串。
|
||
- 旧版明显是占位、临时脚本或平台自动化的部分，不直接硬搬，先重新设计边界。
|
||
|
||
## 当前已完成
|
||
|
||
### 基础设施
|
||
|
||
- ASP.NET Core Controller API。
|
||
- EF Core + Npgsql + PostgreSQL。
|
||
- 单例 `NpgsqlDataSource` + scoped `AddDbContext<TikuDbContext>`。
|
||
- `ITenantContext`、全局 Query Filter、写入拦截器和 PostgreSQL 组合约束。
|
||
- Serilog 结构化日志。
|
||
- CORS / RateLimiter / Options 校验。
|
||
- Scalar / OpenAPI 基础入口。
|
||
- 统一租户外部服务配置：`TenantExternalProvider` + `TenantSecret`。
|
||
- 身份、短信、阿里云 OSS、支付和通知 Provider 抽象，业务层不感知 Supabase Storage、OSS bucket、微信/支付/短信 SDK 或密钥读取细节。
|
||
- Senparc 微信登录、小程序码和微信支付 V3 边界。
|
||
- 后台权限、菜单、平台/租户角色与操作审计底座。
|
||
- `Microsoft.Extensions.Hosting` Worker 与统一后台任务模型。
|
||
|
||
### 数据库
|
||
|
||
已按无正式业务数据前提压缩为唯一 greenfield `InitialSchema`。当前数据库模型已经覆盖：
|
||
|
||
- 租户、用户、成员、认证、Session、短信验证码。
|
||
- 平台公共题库、租户私有题库、受控题目引用、题目版本、分类主干、题集和练习蓝图。
|
||
- 词汇、手册、分数线动态字段与记录。
|
||
- 资源、图片、App 资源、视频解析、导入任务。
|
||
- 学习记录、答题、收藏、错题、报告、统计。
|
||
- 商品、订单、支付、权益、兑换码、优惠券。
|
||
- 积分任务、积分兑换。
|
||
- 推广、邀请码、归因、CRM 队列、佣金结算。
|
||
- 运营内容、通知、徽章、审计。
|
||
- 平台账单、催缴、审计告警、对账/退款相关模型。
|
||
- 后台权限、菜单、角色、用户角色绑定和后台任务模型。
|
||
- PocketBase 导入审计。
|
||
- 自定义域名 DNS/TLS 生命周期和租户前端运行时配置。
|
||
|
||
### 已迁移业务闭环
|
||
|
||
- 安全底座、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、流转状态、记录事件。
|
||
- 调账凭证可创建、审核、作废，并影响后续报表口径。
|
||
|
||
建议暂缓：
|
||
|
||
- 自动下载真实微信/支付宝账单。
|
||
- 自动退款真实网关请求。
|
||
- 平台级财务审批流。
|
||
- 发票、催缴、佣金联动调账。
|