forked from xiongyuxing/tiku-backend.net
docs: simplify migration documentation
This commit is contained in:
@@ -1,199 +1,101 @@
|
||||
# 旧后端迁移路线
|
||||
# 迁移路线与剩余范围
|
||||
|
||||
本文档用于记录从旧 PocketBase / Supabase / NestJS 后端迁移到新 ASP.NET Core + PostgreSQL 后端的阶段性状态和后续优先级。
|
||||
本文档是旧 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 对接；旧 URL 默认不兼容。
|
||||
- 旧 NestJS 只作为行为清单和验收参考。
|
||||
- 不保留 Supabase 运行时依赖、Auth/Storage provider 或 RLS 模型。
|
||||
- 数据一致性优先落 PostgreSQL FK / unique / check / index；跨表租户不变量用集中 PostgreSQL guard。
|
||||
- 外部身份、短信、对象存储、支付、通知和 AI 都通过 Application 接口与 `TenantExternalProvider` 配置解耦。
|
||||
- 新功能按业务闭环验收，不按 endpoint 数量验收。
|
||||
|
||||
迁移原则：
|
||||
## 已完成主线
|
||||
|
||||
- 不追求旧接口逐字兼容，新前端按新 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`，不落字符串。
|
||||
- 旧版明显是占位、临时脚本或平台自动化的部分，不直接硬搬，先重新设计边界。
|
||||
- 仓库转正：本仓库是唯一目标后端，见 [ADR 0001](adr/0001-authoritative-dotnet-backend.md)。
|
||||
- 工程底座：ASP.NET Core、EF Core、Npgsql、PostgreSQL、Serilog、RateLimiter、Options 校验。
|
||||
- 数据库：greenfield `InitialSchema`，真实 PostgreSQL 迁移和集成测试。
|
||||
- 租户隔离：Host 解析、`ITenantContext`、EF Query Filter、SaveChanges 拦截器、组合外键、PostgreSQL guard。
|
||||
- 共享题库：平台公共题库、租户私题、`TenantQuestionReference`、版本锁定练习。
|
||||
- 前端运行时：自定义域名、DNS/TLS 生命周期、`GET /api/runtime/bootstrap`。
|
||||
- 外部服务解耦：`TenantExternalProvider` + `TenantSecret`，身份、短信、OSS、支付、通知 provider 边界。
|
||||
- 后台底座：平台/租户 RBAC、菜单、审计、平台后台、租户后台、交易运营、Worker 任务模型。
|
||||
- 学生体验：视频搜索/播放/进度、题目解析视频、签到、积分流水、内容导入异步化。
|
||||
- AI 基础：已引入 SK 包到 Infrastructure，已固定 provider-neutral 对话存储方向；业务功能仍待实现。
|
||||
|
||||
## 当前已完成
|
||||
阶段归档：
|
||||
|
||||
### 基础设施
|
||||
- [第一阶段：仓库转正基线](migration/phase-1-repository-baseline.md)
|
||||
- [第二阶段：.NET 工程底座](migration/phase-2-engineering-foundation.md)
|
||||
- [第三阶段：强租户隔离、共享题库与租户前端运行时](migration/phase-3-tenant-isolation-and-shared-question-bank.md)
|
||||
- [第四阶段：外部服务解耦](migration/phase-4-external-provider-decoupling.md)
|
||||
- [第五阶段：后台能力与 Worker 基座](migration/phase-5-backoffice-worker-operations.md)
|
||||
- [第七阶段：学生端体验与内容消费闭环](migration/phase-7-student-experience-and-content-consumption.md)
|
||||
- [第八阶段：AI 底座与教师端对话](migration/phase-8-ai-foundation.md)
|
||||
- [API 契约基线](migration/contracts/README.md)
|
||||
|
||||
- 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 与统一后台任务模型。
|
||||
## 剩余范围
|
||||
|
||||
### 数据库
|
||||
### 1. AI 教师端对话与反馈审核
|
||||
|
||||
已按无正式业务数据前提压缩为唯一 greenfield `InitialSchema`。当前数据库模型已经覆盖：
|
||||
- 租户教师后台基础对话。
|
||||
- function calling 只允许调用受审计的后端业务函数。
|
||||
- AI 审核题目反馈只生成建议、风险等级和人工复核标记，不直接改业务状态。
|
||||
- 租户 AI Provider 配置、API Key 托管、调用审计和成本记录。
|
||||
- 后续再做推荐报告、导出、RAG 和多模型路由。
|
||||
|
||||
- 租户、用户、成员、认证、Session、短信验证码。
|
||||
- 平台公共题库、租户私有题库、受控题目引用、题目版本、分类主干、题集和练习蓝图。
|
||||
- 词汇、手册、分数线动态字段与记录。
|
||||
- 资源、图片、App 资源、视频解析、导入任务。
|
||||
- 学习记录、答题、收藏、错题、报告、统计。
|
||||
- 商品、订单、支付、权益、兑换码、优惠券。
|
||||
- 积分任务、积分兑换。
|
||||
- 推广、邀请码、归因、CRM 队列、佣金结算。
|
||||
- 运营内容、通知、徽章、审计。
|
||||
- 平台账单、催缴、审计告警、对账/退款相关模型。
|
||||
- 后台权限、菜单、角色、用户角色绑定和后台任务模型。
|
||||
- PocketBase 导入审计。
|
||||
- 自定义域名 DNS/TLS 生命周期和租户前端运行时配置。
|
||||
### 2. 内容导出与导入增强
|
||||
|
||||
### 已迁移业务闭环
|
||||
|
||||
- 安全底座、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 和部分实处理器。后续增强：
|
||||
### 3. Worker 实处理器补强
|
||||
|
||||
- `content_export` 完整导出。
|
||||
- `asset_security_scan` 接真实扫描 provider。
|
||||
- `statistics_aggregation` 增量聚合。
|
||||
- `commerce_reconciliation` 接真实 provider bill downloader。
|
||||
- `tenant_domain_recheck` 增加周期调度和告警联动。
|
||||
- `tenant_domain_recheck` 周期调度和告警联动。
|
||||
|
||||
### 4. 后台运营细化
|
||||
|
||||
平台后台、租户后台和交易运营已有主线能力，后续按运营优先级补：
|
||||
|
||||
- 租户 secrets 通用后台管理。
|
||||
- 租户监督规则和跟进报表细化。
|
||||
- 租户洞察报表。
|
||||
- 租户监督规则、跟进报表和洞察报表。
|
||||
- 更细粒度 RBAC 权限点。
|
||||
- 管理后台操作审计覆盖率补齐。
|
||||
- 操作审计覆盖率补齐。
|
||||
- 发票、催缴、佣金联动调账。
|
||||
|
||||
### 5. 旧路径兼容评估
|
||||
|
||||
默认不迁旧 URL，只迁行为能力。只有前端明确依赖且重写成本高时，才增加薄兼容 Controller；兼容层不得恢复旧 Supabase、旧 grant/adoption 公共题库授权模型、旧 `QuestionIds` JSON 或旧 Provider 配置表。
|
||||
只有前端明确依赖且重写成本高时，才增加薄兼容 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 相关任何路径。
|
||||
已由新接口替代的旧行为：
|
||||
|
||||
## 推荐后续顺序
|
||||
- `/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`
|
||||
|
||||
```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
|
||||
git diff --check
|
||||
git status --short --branch
|
||||
```
|
||||
|
||||
如果某批不涉及数据库 migration，也仍然运行 migration script，确认当前模型快照和迁移链没有损坏。
|
||||
|
||||
## 下一批建议
|
||||
|
||||
下一批建议执行独立 AI 阶段，但先只做架构底座和一个最小推荐报告闭环，不直接接生产模型：
|
||||
|
||||
- 增加 `TenantExternalProviderCapability.Ai` 和密钥配置校验。
|
||||
- 增加 Application AI 抽象，不让 Controller 直接接触 SK。
|
||||
- Infrastructure 引入 Semantic Kernel provider，实现 fake/local stub 和真实 provider 边界。
|
||||
- 设计推荐报告数据模型、任务模型、调用审计和成本记录。
|
||||
- 完成报告生成任务、列表、详情和导出骨架。
|
||||
|
||||
建议暂缓：
|
||||
|
||||
- 复杂 RAG。
|
||||
- 自动志愿填报决策。
|
||||
- 多模型路由优化。
|
||||
- 生产 API Key 托管 UI 之外的手工配置方案。
|
||||
|
||||
Reference in New Issue
Block a user