# 旧后端迁移路线 本文档用于记录从旧 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`。 - `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 之外的手工配置方案。