# 迁移路线与剩余范围

本文档是旧 PocketBase / Supabase / NestJS 后端迁移到 ASP.NET Core + PostgreSQL 后端的状态入口。

## 固定原则

- 新前端按新 REST API 对接；旧 URL 默认不兼容。
- 旧 NestJS 只作为行为清单和验收参考。
- 不保留 Supabase 运行时依赖、Auth/Storage provider 或 RLS 模型。
- 数据一致性优先落 PostgreSQL FK / unique / check / index；跨表租户不变量用集中 PostgreSQL guard。
- 外部身份、短信、对象存储、支付、通知和 AI 都通过 Application 接口与 `TenantExternalProvider` 配置解耦。
- 新功能按业务闭环验收，不按 endpoint 数量验收。

## 已完成主线

- 仓库转正：本仓库是唯一目标后端，见 [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 对话存储方向；业务功能仍待实现。
- SaaS 商城：可售卖 Feature、不可变套餐版本、独立 PlatformBilling、租户自助账务、业务额度、订阅周期 Worker 和 onboarding 已落地。

阶段归档：

- [第一阶段：仓库转正基线](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)
- [第九阶段：SaaS 模块商城与租户交付闭环](migration/phase-9-saas-marketplace-and-onboarding.md)
- [API 契约基线](migration/contracts/README.md)

后续产品化开发统一按 [SaaS 题库产品边界与后续接口路线](architecture/saas-product-and-api-roadmap.md) 执行。该文档定义三端边界、平台 SaaS 商城与租户学生商城的双交易域、套餐能力与 RBAC 分层，以及阶段 9A～9F。

## 剩余范围

### 1. AI 教师端对话与反馈审核

- 租户教师后台基础对话。
- function calling 只允许调用受审计的后端业务函数。
- AI 审核题目反馈只生成建议、风险等级和人工复核标记，不直接改业务状态。
- 租户 AI Provider 配置、API Key 托管、调用审计和成本记录。
- 后续再做推荐报告、导出、RAG 和多模型路由。

### 2. 内容导出与导入增强

- 内容导出任务创建、查询和下载。
- 题库、题目、学生数据导出到对象存储。
- 导入 preview/result/issue 更细化。
- 大文件导入进度、失败行回放和重试。

### 3. Worker 实处理器补强

- `content_export` 完整导出。
- `asset_security_scan` 接真实扫描 provider。
- `statistics_aggregation` 增量聚合。
- `commerce_reconciliation` 接真实 provider bill downloader。
- `tenant_domain_recheck` 周期调度和告警联动。

### 4. 教师教学闭环

- 作业、考试、班级发布、批阅和教学报告。
- 学生断点续答、自动交卷、主观题复核和成绩分析。
- 教学导出通过 Worker 和对象存储交付。

### 5. 后台运营细化

- 租户 secrets 通用后台管理。
- 租户监督规则、跟进报表和洞察报表。
- 更细粒度 RBAC 权限点。
- 操作审计覆盖率补齐。
- 发票、催缴、佣金联动调账。

### 6. 旧路径兼容评估

只有前端明确依赖且重写成本高时，才增加薄兼容 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`

## 每批验收

```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
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
```
