200 lines
9.8 KiB
Markdown
200 lines
9.8 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)
|
||
- [`docs/migration/phase-7-student-experience-and-content-consumption.md`](migration/phase-7-student-experience-and-content-consumption.md)
|
||
- [`docs/migration/phase-8-ai-foundation.md`](migration/phase-8-ai-foundation.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 配置/队列/死信处理。
|
||
- 佣金配置、来源查询、结算生成、状态流转、凭证、导出。
|
||
|
||
## 剩余迁移范围
|
||
|
||
剩余部分不建议再按“旧接口数量”机械推进。第六阶段已经把平台后台、租户后台、交易运营和 Worker 最小闭环打通；第七阶段补齐了学生端视频、签到积分流水和内容导入异步化。后续应按“能上线运营”和“体验增强”拆分。
|
||
|
||
### 1. AI 底座与教师端对话，独立阶段
|
||
|
||
旧版相关模块：
|
||
|
||
- `ai.module.ts`
|
||
|
||
目标能力：
|
||
|
||
- 租户教师后台基础 AI 对话。
|
||
- 对话 function calling 能力预留，但只允许调用受审计的后端业务函数。
|
||
- AI 审核题目反馈，输出审核建议和风险等级，不直接改业务状态。
|
||
- 学校推荐报告列表。
|
||
- 推荐详情。
|
||
- 推荐报告导出。
|
||
- 推荐生成任务。
|
||
- 租户级 AI Provider 配置、API Key 密钥托管和调用审计。
|
||
|
||
阶段约定：
|
||
|
||
- 默认基于 Microsoft Semantic Kernel 设计 Kernel / Plugin / AI Service 编排。
|
||
- AI Provider 使用 `TenantExternalProvider(capability=ai)`。
|
||
- 租户 API Key 存入 `TenantSecret`，不进入业务 DTO。
|
||
- `Microsoft.SemanticKernel` 只允许出现在 Infrastructure AI provider 实现中。
|
||
- Application 层只暴露业务抽象，例如 `IAiRecommendationProvider` / `IAiKernelFactory`。
|
||
- 教师对话先做基础能力；推荐报告不直接照搬旧 prompt 或推荐算法，后续结合分数线动态字段、用户画像、目标院校和志愿规则重新设计。
|
||
|
||
### 2. 内容导出和导入处理器增强
|
||
|
||
当前已经支持导入预览、同步小批量导入、异步 `content_import` job 和导入详情查询。后续增强：
|
||
|
||
- 内容导出任务查询和创建。
|
||
- 题库、题目、学生数据导出到对象存储。
|
||
- 导入 preview/result/issue 更细化。
|
||
- 大文件导入解析进度、失败行回放和重试。
|
||
- 导入、导出输出资产统一走对象存储 provider，不暴露 bucket/key。
|
||
|
||
### 3. Worker 处理器补强
|
||
|
||
当前 Worker 已有统一任务模型、租户 scope 和部分实处理器。后续增强：
|
||
|
||
- `content_export` 完整导出。
|
||
- `asset_security_scan` 接真实扫描 provider。
|
||
- `statistics_aggregation` 增量聚合。
|
||
- `commerce_reconciliation` 接真实 provider bill downloader。
|
||
- `tenant_domain_recheck` 增加周期调度和告警联动。
|
||
|
||
### 4. 后台运营细化
|
||
|
||
平台后台、租户后台和交易运营已有主线能力，后续按运营优先级补：
|
||
|
||
- 租户 secrets 通用后台管理。
|
||
- 租户监督规则和跟进报表细化。
|
||
- 租户洞察报表。
|
||
- 更细粒度 RBAC 权限点。
|
||
- 管理后台操作审计覆盖率补齐。
|
||
- 发票、催缴、佣金联动调账。
|
||
|
||
### 5. 旧路径兼容评估
|
||
|
||
默认不迁旧 URL，只迁行为能力。只有前端明确依赖且重写成本高时，才增加薄兼容 Controller；兼容层不得恢复旧 Supabase、旧 grant/adoption 公共题库授权模型、旧 `QuestionIds` JSON 或旧 Provider 配置表。
|
||
|
||
明确不再迁移为主接口：
|
||
|
||
- `/api/profile/activity-tasks`，由 `/api/points/tasks` 替代。
|
||
- `/api/profile/exchange-items` 和 `/api/profile/exchange-items/redeem`，由 `/api/points/exchange-items`、`/api/points/exchange-orders` 替代。
|
||
- 公共题库 adopt/sync/grant，已被平台公共题库所有权 + `TenantQuestionReference` 模型替代。
|
||
- Supabase 相关任何路径。
|
||
|
||
## 推荐后续顺序
|
||
|
||
```text
|
||
1. AI 底座独立阶段：Semantic Kernel + 租户自带 API Key + 教师端对话
|
||
2. 内容导出 + 导入处理器增强
|
||
3. Worker 统计、扫描、对账、域名复验处理器补强
|
||
4. 后台运营细化：secrets、监督、洞察、审计、发票/催缴
|
||
5. 按前端实际依赖做旧路径兼容评估
|
||
```
|
||
|
||
## 每批固定验收
|
||
|
||
每批迁移完成后都必须：
|
||
|
||
```bash
|
||
dotnet restore TIKU-BACKEND.slnx
|
||
dotnet build TIKU-BACKEND.slnx --no-restore
|
||
dotnet test Tiku.UnitTests/Tiku.UnitTests.csproj --no-build
|
||
dotnet test Tiku.IntegrationTests/Tiku.IntegrationTests.csproj --no-build
|
||
git diff --check
|
||
dotnet ef migrations script \
|
||
--project Tiku.Infrastructure \
|
||
--startup-project Tiku.DbMigrator
|
||
dotnet ef migrations has-pending-model-changes \
|
||
--project Tiku.Infrastructure \
|
||
--startup-project Tiku.DbMigrator
|
||
```
|
||
|
||
如果某批不涉及数据库 migration，也仍然运行 migration script，确认当前模型快照和迁移链没有损坏。
|
||
|
||
## 下一批建议
|
||
|
||
下一批建议执行独立 AI 阶段，但先只做架构底座和一个最小推荐报告闭环，不直接接生产模型：
|
||
|
||
- 增加 `TenantExternalProviderCapability.Ai` 和密钥配置校验。
|
||
- 增加 Application AI 抽象，不让 Controller 直接接触 SK。
|
||
- Infrastructure 引入 Semantic Kernel provider，实现 fake/local stub 和真实 provider 边界。
|
||
- 设计推荐报告数据模型、任务模型、调用审计和成本记录。
|
||
- 完成报告生成任务、列表、详情和导出骨架。
|
||
|
||
建议暂缓：
|
||
|
||
- 复杂 RAG。
|
||
- 自动志愿填报决策。
|
||
- 多模型路由优化。
|
||
- 生产 API Key 托管 UI 之外的手工配置方案。
|