tiku-backend.net/docs/migration-roadmap.md

旧后端迁移路线

本文档用于记录从旧 PocketBase / Supabase / NestJS 后端迁移到新 ASP.NET Core + PostgreSQL 后端的阶段性状态和后续优先级。

仓库转正决策和第一阶段基线分别见：

• docs/adr/0001-authoritative-dotnet-backend.md
• docs/migration/phase-1-repository-baseline.md
• docs/migration/phase-2-engineering-foundation.md
• docs/migration/phase-3-tenant-isolation-and-shared-question-bank.md
• docs/migration/phase-4-external-provider-decoupling.md
• docs/migration/phase-5-backoffice-worker-operations.md
• docs/migration/phase-7-student-experience-and-content-consumption.md
• docs/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 相关任何路径。

推荐后续顺序

1. AI 底座独立阶段：Semantic Kernel + 租户自带 API Key + 教师端对话
2. 内容导出 + 导入处理器增强
3. Worker 统计、扫描、对账、域名复验处理器补强
4. 后台运营细化：secrets、监督、洞察、审计、发票/催缴
5. 按前端实际依赖做旧路径兼容评估

每批固定验收

每批迁移完成后都必须：

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 之外的手工配置方案。