docs: summarize migration status and architecture advantages

2026-07-26 15:00:21 +08:00
parent 06471151cd
commit fc80176a90
1 changed files with 117 additions and 225 deletions
--- a/README.md
+++ b/README.md
@@ -1,241 +1,167 @@
 # TIKU Backend

-题库 SaaS 后端，当前目标是从旧 PocketBase / Supabase 方案迁移到可控的 ASP.NET Core + PostgreSQL 架构。
+题库 SaaS 新后端。目标是从旧 PocketBase / Supabase / Nest 方案迁到更可控的 ASP.NET Core + PostgreSQL 架构。

-这个仓库目前处在新后端初始化和安全底座建设阶段：Domain 实体、EF Core Fluent 配置、PostgreSQL 初始建库 migration、模型约束测试已经建立；API 层已经开始接入 ASP.NET Core 认证授权、本地登录、数据库 Session 和当前租户上下文。
+当前判断很明确：现在团队已经有后端开发，继续把核心认证、权限、多租户隔离、业务一致性交给 BaaS 规则，会让复杂度藏在平台、SQL policy 和前端约定之间。新后端把这些东西收回应用层和数据库约束里，开发、排查、审计都会更直接。

-## 为什么换掉 Supabase
+## 技术栈与分层

-旧方案的问题不只是“用了 Supabase”，而是安全、权限、业务约束分散在太多地方：
-
- 应用代码、Supabase RLS、SQL policy、Edge/脚本、前端约定之间边界不清。
- 多租户业务复杂后，RLS policy 会越来越难审查，调试成本高。
- 团队现在已经有后端开发，继续把核心权限和业务一致性绑在 BaaS 规则上，反而增加维护难度。
- 复杂导入、对账、退款、CRM、资产安全扫描、平台账单等后台任务，更适合由明确的 Worker + 应用层权限 + 数据库约束来承载。
- 新系统需要长期演进，直接掌控 PostgreSQL schema、迁移、索引、FK、事务边界，会比依赖 Supabase 平台约束更可控。
-
-新的方向不是“数据库裸奔”，而是把职责重新分层：
-
- ASP.NET Core 负责认证、授权、租户上下文、业务流程、审计记录。
- PostgreSQL 负责数据完整性、外键、唯一约束、检查约束、索引、JSONB/数组/ltree/citext 等原生能力。
- Worker 负责导入、对账、退款、通知、资产扫描、统计等后台任务。
- 测试负责持续验证 EF 模型和数据库约束没有退化。
-
-## 技术栈
-
- .NET / ASP.NET Core
- Entity Framework Core
+- ASP.NET Core Controller API
+- Entity Framework Core + Npgsql
 - PostgreSQL
- Npgsql
 - Serilog
 - ZLinq
+- AlibabaCloud.OSS.V2
 - xUnit

-项目分层：
-
 ```text
-Tiku.Api              # HTTP API 入口
-Tiku.Application      # 应用服务、用例编排
+Tiku.Api              # HTTP API、认证授权、OpenAPI/Scalar
+Tiku.Application      # 应用服务、用例编排、接口抽象
 Tiku.Domain           # 领域实体、枚举、基础类型
-Tiku.Infrastructure   # EF Core、PostgreSQL 持久化配置、migration
+Tiku.Infrastructure   # EF Core、PostgreSQL、外部服务实现
 Tiku.DbMigrator       # 数据库迁移启动项目
-Tiku.Worker           # 后台任务
+Tiku.Worker           # 后台任务入口
 Tiku.UnitTests        # 单元测试
-Tiku.IntegrationTests # EF 模型/持久化约束测试
+Tiku.IntegrationTests # API / EF 模型集成测试
 ```

-## 运行时地基
+## 相比原版的主要优势

-这次迁移不只是把 Node/Nest/Supabase 换成 C#，而是把旧系统没有认真处理的运行时基础补起来。
+### 1. 安全边界更清楚

-### 数据库连接
+旧版把安全逻辑分散在 Nest API、Supabase Auth/RLS、SQL policy、脚本和前端约定里。新后端改为：

- API 通过单例 `NpgsqlDataSource` 管理 PostgreSQL 连接池。
- EF Core 使用 `AddDbContextPool<TikuDbContext>`，避免每个请求重复构造完整 DbContext 依赖图。
- 连接池参数继续交给 PostgreSQL/Npgsql connection string 配置，例如 `Maximum Pool Size`、`Minimum Pool Size`、`Timeout`、`Command Timeout`。
- 业务代码不直接 new 连接，不绕过统一的 EF / Npgsql 配置入口。
+- ASP.NET Authentication 负责身份认证。
+- ASP.NET Authorization 负责权限策略。
+- JWT + 数据库 `auth_sessions` 负责 access/refresh/session 闭环。
+- `ICurrentUser` / `ICurrentTenant` 统一当前用户和租户上下文。
+- PostgreSQL FK / unique / check / index 负责数据完整性底线。
+- 审计事件表记录关键行为。

-### 日志
+新系统不照搬 Supabase RLS、`app_private` schema 和生产防护 SQL，权限主要在应用层实现，数据库负责硬约束。

- API 接入 Serilog 结构化日志。
- 启动阶段使用 bootstrap logger，避免应用启动失败时完全没有日志。
- 请求日志统一记录 HTTP method、path、status code、elapsed 等基础字段。
- 请求日志会补充当前用户、租户、Session、租户角色、TraceId 等上下文，后续排查“某个机构某个用户某次请求”会比旧方案清楚很多。
- EF SQL、Microsoft 框架日志默认降噪；开发环境可提高 EF command 日志等级。
+### 2. 多租户约束不再靠“大家小心”

-### 跨域
+新库以多租户为一等设计：

- CORS 作为 API 安全边界配置，不在 Controller 里散写。
- 生产默认不放行任何 Origin，避免开发便利配置意外带到线上。
- 开发环境默认允许本地前端常用端口：
-  - `http://localhost:5173`
-  - `http://127.0.0.1:5173`
-  - `http://localhost:3000`
-  - `http://127.0.0.1:3000`
- 不默认允许 credentials；如果后续需要 cookie 模式或管理后台单独域名，需要显式配置。
- 多租户正式域名确定后，可以把 CORS 白名单从静态配置升级为“租户域名 + 平台管理域名”的集中策略。
+- 租户数据表默认带 `TenantId`。
+- 跨租户引用优先使用 composite FK，例如 `(tenant_id, id)`。
+- 业务 API 默认从当前请求上下文解析租户，不信任请求 body 里的 `tenantId`。
+- 租户域名、品牌、设置、角色、班级、学生运营都已经有独立模型。

-### 限流
+这比旧版在 API、RLS、前端之间反复拼 tenant 条件更可控。

- API 接入 ASP.NET Core RateLimiter，作为全局兜底防线。
- 匿名请求按 IP 分桶，已登录请求按用户分桶，减少同学校/同机构出口 NAT 下的误伤。
- 默认使用固定窗口限流：
-  - 生产默认 `600 / minute`
-  - 开发默认 `1200 / minute`
- 被限流时返回标准 `429 Too Many Requests`，响应体包含 `code = rate_limited` 和 `traceId`。
- 当前先使用进程内限流；多实例部署时，需要上移到网关/负载均衡层，或接入 Redis 等集中式限流状态。
+### 3. PostgreSQL 能力被正经使用

-### 配置校验
+- JSON 字段统一使用 C# `JsonElement`，映射 PostgreSQL `jsonb`。
+- 内容树路径使用 `ltree`。
+- 域名、兑换码等大小写不敏感字段使用 `citext`。
+- 数组使用 PostgreSQL array，不塞字符串。
+- 钱相关字段使用 cents 或明确 decimal precision。
+- 关键唯一性和状态底线落数据库约束。

- 关键配置使用 Options validation，并在启动阶段 `ValidateOnStart()`。
- JWT 配置会校验 issuer、audience、签名密钥长度、access/refresh token 有效期范围。
- CORS 配置会校验 Origin 必须是绝对 `http/https` origin；开启 credentials 时必须显式配置 origin。
- RateLimit 配置会校验 permit/window/queue 范围，避免错误配置在运行时才暴露。
+### 4. 运行时地基补齐

-### 热路径集合处理
+旧版对连接池、日志、跨域、限流、配置校验这些工程底座比较薄。新后端已经补上：

- API 项目引入 ZLinq，作为低分配集合处理工具。
- 当前先在小范围权限判断里落模板，后续题库筛选、权限集合、菜单/内容树投影等热路径再逐步使用。
- 不是为了炫技替换所有 LINQ；只在明确高频、低收益分配明显的路径使用。
+- 单例 `NpgsqlDataSource` + `AddDbContextPool<TikuDbContext>`。
+- Serilog 结构化日志和请求上下文日志。
+- 集中 CORS 配置，生产默认不放开 Origin。
+- ASP.NET RateLimiter 全局限流。
+- Options `ValidateOnStart()` 启动校验。
+- ZLinq 作为后续热路径低分配工具。

-### 对象存储
+### 5. 资源存储不绑 Supabase

- 旧 Nest 后端资源层使用 Node `ali-oss`，不是 Supabase Storage 专用模型。
- 新后端使用 `AlibabaCloud.OSS.V2` 作为阿里云 OSS SDK，对齐旧版的 provider / bucket / objectKey / signed URL / HEAD metadata 语义。
- Application 层只依赖 `IObjectStorageService`，不直接依赖阿里云 SDK；SDK 细节收敛在 Infrastructure。
- 默认对象 key 要带租户前缀，例如 `{tenantId}/...`，避免多租户资源混放后靠人工约定隔离。
- 上传签名前会校验 MIME allowlist、文件大小、provider 是否支持托管上传。
- 下载时如果资源已有可信 `cdnUrl`，直接返回 provider-managed URL；否则由后端在通过业务授权后签发临时 URL。
- 上传确认使用 OSS HEAD metadata，后续可用于校验大小、MIME、ETag、SHA256 metadata 和安全扫描状态。
- 不再把 Supabase Storage 作为默认后端存储；如果历史数据里存在 Supabase provider，只作为迁移兼容对象处理，不作为新架构依赖。
+旧版资源层实际使用 Node `ali-oss`。新后端按这个方向迁移到 `AlibabaCloud.OSS.V2`：

-## 数据库策略
+- Application 只依赖 `IObjectStorageService`。
+- Infrastructure 收敛阿里云 OSS SDK 细节。
+- 对象 key 默认要求租户前缀，避免资源混放。
+- 上传签名前校验 MIME、大小和 provider。
+- 下载/预览必须先过业务授权，再签发临时 URL。
+- OSS HEAD metadata 用于上传确认、大小/MIME/ETag/安全扫描校验。

-当前数据库以 PostgreSQL 为核心能力，而不是把 PostgreSQL 当成普通 KV 存储：
+## 当前阶段成果

- JSON 字段统一使用 C# `JsonElement`，映射到 PostgreSQL `jsonb`。
- 树形内容路径使用 `ltree`。
- 大小写不敏感编码/域名/兑换码等使用 `citext`。
- PostgreSQL array 使用 `text[]` / `uuid[]`，不把数组塞成字符串。
- 钱相关字段用整型 cents 或明确 decimal precision，避免浮点误差。
- 多租户表默认有 `TenantId`。
- 租户内跨表引用优先使用 composite FK，例如 `(tenant_id, id)`。
- 关键业务唯一性落数据库唯一索引或过滤唯一索引。
- 用 check constraint 保护金额、数量、状态范围等底线。
+### 数据库

-当前 migration 已压成一个 greenfield baseline：
+数据库模型迁移已经完成到 greenfield 初始 schema：

 ```text
 Tiku.Infrastructure/Persistence/Migrations/20260725220742_InitialSchema.cs
 ```

-因为新库还没正式上线，保留一堆开发过程 migration 意义不大。现在单个初始 migration 更适合作为新后端的起点。
+当前 EF 模型包含 124 个 DbSet，覆盖：

-## 新安全策略
+- 租户、用户、成员、认证、Session、短信验证码
+- 地区、模块、院校、专业、科目、分类
+- 题库、题目、题目版本
+- 内容入口、内容节点、题集、练习蓝图
+- 词汇、手册、用户单词进度
+- 资源、图片、App 资源、视频解析、导入任务
+- 练习、答题、收藏、错题、报告、统计
+- 商品、订单、支付、权益、兑换码、优惠券
+- 推广、CRM、佣金
+- Banner、FAQ、公告、通知、徽章、审计
+- 平台账单、催收、审计告警
+- PocketBase 导入审计

-这次迁移的核心安全思路是：不照搬 Supabase RLS，而是在应用层建立明确、可测试、可审计的安全边界，同时用 PostgreSQL 约束守住数据完整性底线。
+### 安全与认证

-### 已落地
+已完成：

- ASP.NET Core Controller API 已接入统一认证/授权管线。
- 本地认证不依赖 Supabase Auth：
-  - 手机号 + 密码登录
-  - 短信验证码登录
-  - 微信网页 OAuth 登录
-  - 微信小程序 `wx.login` 登录
-  - JWT access token
-  - 数据库 `auth_sessions` refresh/session
-  - `auth_login_events` 登录事件
- JWT 不只验签，也会校验对应 `auth_sessions` 是否仍有效；登出或撤销 session 后，旧 access token 会被拒绝。
- 当前请求上下文已经拆成应用层抽象：
-  - `ICurrentUser`
-  - `ICurrentTenant`
- 第一批授权策略已经建立：
-  - 已登录用户
-  - 当前租户成员
-  - 租户管理员
- 第一批认证/租户接口已经建立：
-  - `GET /api/tenant/resolve`
-  - `GET /api/tenant/current-public`
-  - `POST /api/auth/login/password`
-  - `POST /api/auth/login/sms`
-  - `POST /api/auth/oauth/wechat`
-  - `POST /api/auth/oauth/wechat-miniapp`
-  - `POST /api/auth/refresh`
-  - `POST /api/auth/logout`
-  - `GET /api/me`
-  - `GET /api/tenants/current`
-  - `GET /api/health`
- 多租户数据表普遍包含 `TenantId`。
- 大量租户内关系使用 composite FK，避免只靠应用代码约定租户一致性。
- 不迁移 Supabase RLS、`app_private` schema、生产保护 policy。
- 敏感配置不原样落明文字段，例如 CRM / 支付 / webhook 只保留 `secret_ref` 或公开配置。
- PB 导入有专门审计表：
-  - `pb_import_runs`
-  - `pb_raw_records`
-  - `pb_import_issues`
- 关键业务流保留审计/事件表，例如：
-  - `audit_logs`
-  - `auth_login_events`
-  - `payment_events`
-  - `commerce_refund_events`
-  - `commerce_reconciliation_issue_events`
-  - `content_asset_access_events`
-  - `content_asset_security_scan_events`
-  - `platform_audit_alerts`
- 模型测试覆盖：
-  - 表数量和表名
-  - JSONB 映射
-  - `ltree` 映射
-  - 关键唯一索引
-  - decimal precision
-  - 租户关系 composite FK
-  - PB raw record 可追踪主键
- API / Auth 测试覆盖：
-  - 租户按 `tenantCode` / `host` 解析
-  - 公开品牌、主题、功能开关和 public config 返回
-  - health smoke test
-  - 未登录返回 401
-  - 无权限返回 403
-  - 密码登录成功/失败
-  - 短信验证码登录成功/失败
-  - 微信登录 upsert 用户、身份和租户成员
-  - 登录后访问当前用户和当前租户
-  - 登出后旧 access token / refresh token 被拒绝
+- JWT Bearer 认证。
+- 数据库 Session 校验；登出/撤销后旧 token 会被拒绝。
+- 手机号 + 密码登录。
+- 短信验证码登录。
+- 微信网页 OAuth 登录。
+- 微信小程序登录。
+- 当前用户 `/api/me`。
+- 当前租户 `/api/tenants/current`。
+- 租户公开解析和公开配置。
+- 统一异常响应和请求日志。

-### 计划落地
+### 已迁移 API

-后续 API / Worker 实现时，需要继续把下面这些策略固化成代码和测试：
+当前新后端有 43 个 endpoint，其中 3 个是安全诊断接口。已完成的业务/API 闭环：

- 业务 API 不直接信任请求 body 的 `tenantId`；登录阶段可选择租户，登录后业务请求以 JWT/session 中解析出的当前租户为准。
- API 层继续基于用户、租户成员、角色模板、权限 JSON 扩展授权策略。
- 平台管理员、租户管理员、教师/运营、学生等权限边界继续细化到业务模块。
- Repository / Query 层默认带租户过滤，平台级查询必须显式声明。
- 所有跨租户资源访问必须走应用服务校验，不允许 controller 直查。
- 审计日志覆盖高风险操作：
-  - 登录、认证失败、短信验证
-  - 订单/支付/退款/对账调整
-  - 题库导入/导出/公库采纳
-  - 资产下载签名和安全扫描
-  - 租户配置、域名、品牌、支付账号变更
-  - 平台账单、催收、告警处理
- Secret 管理独立化，只在应用层通过安全服务解析 `secret_ref`。
- 短信发送目前先完成验证码表、哈希校验和限流模型，真实供应商通过接口适配接入。
- 后台 Worker 使用最小权限的应用服务，不直接绕过业务规则写库。
- 对账、导入、批处理任务要求幂等键和可重跑设计。
- 生产环境连接串、密钥、对象存储凭据不进入仓库。
- OSS 凭据通过配置/环境变量/secret 注入，兼容旧版环境变量：
-  - `STORAGE_DEFAULT_PROVIDER`
-  - `STORAGE_DEFAULT_BUCKET`
-  - `STORAGE_PUBLIC_BASE_URL`
-  - `STORAGE_REQUIRE_TENANT_PREFIX`
-  - `STORAGE_MAX_UPLOAD_BYTES`
-  - `ALIYUN_OSS_REGION`
-  - `ALIYUN_OSS_ENDPOINT`
-  - `ALIYUN_OSS_ACCESS_KEY_ID`
-  - `ALIYUN_OSS_ACCESS_KEY_SECRET`
-  - `ALIYUN_OSS_STS_TOKEN`
-  - `ALIYUN_OSS_INTERNAL`
+- health
+- tenant resolve / current public
+- auth password / sms / wechat / refresh / logout
+- me / current tenant
+- catalog 基础只读
+- content navigation 只读
+- question bank 只读
+- vocabulary / handbook 只读
+- asset / image / app asset / video catalog 只读
+- asset download / preview 授权签名
+
+## 还剩多少待迁移
+
+按旧 Nest API 粗略统计，旧版约 342 个 HTTP endpoint；新后端目前 43 个，其中安全诊断 3 个不算旧业务迁移。按 endpoint 数量估算：
+
+```text
+旧版 endpoint 总量：约 342
+新后端已实现：43
+其中诊断接口：3
+已覆盖旧业务接口：约 40
+待迁移旧业务接口：约 302
+```
+
+这个数字只是迁移工作量参考，不代表 302 个都应该原样照搬。旧版里有不少平台运营、商业化自动化、审计告警、积分、督导、对账等后段能力，应该按新架构重新筛选。
+
+优先级建议：
+
+1. 运营内容只读：Banner、FAQ、公告、考试日期、商品/SVIP 套餐。
+2. 学习闭环：练习会话、提交答案、收藏、错题、单词进度。
+3. 资源管理：上传签名、上传确认、导入任务查询。
+4. 租户后台：角色、班级、学生、域名、品牌、登录 Provider。
+5. 商业化：订单、支付、权益、兑换码、优惠券。
+6. 内容管理：题目、题集、词汇、手册、视频的后台写接口。
+7. 推广/CRM/佣金。
+8. 平台后台：租户、账单、对账、退款、催收、审计告警。
+9. Worker：导入、统计、资产扫描、通知、对账、账单。

 ## 常用命令

@@ -253,37 +179,3 @@ dotnet ef migrations script \
  --project Tiku.Infrastructure \
  --startup-project Tiku.DbMigrator
 ```
-
-## API 迁移模板
-
-后续从旧 Nest/Supabase 迁移 API 时，优先按当前认证和租户接口的模板推进：
-
-1. DTO 放到 `Tiku.Api/Contracts`，只包含 HTTP 输入输出形状、校验属性和 OpenAPI 描述。
-2. Request / Response DTO 字段必须写 XML documentation comments；API 项目生成 XML 文档，内置 OpenAPI 会把注释带到 Scalar schema。
-3. Controller 保持轻量，只做路由、授权、DTO 到 Application request 的映射。
-4. 业务流程放到 `Tiku.Application`，EF/外部服务实现放到 `Tiku.Infrastructure`。
-5. 已登录业务接口默认从 `ICurrentTenant` / `ICurrentUser` 取上下文，不直接信任 body 里的 `tenantId`。
-6. 公开接口只返回 branding、feature flags、public config 等可暴露字段，不泄露 secret/refund/payment/internal metadata。
-7. 每迁一个小闭环就补业务集成测试；OpenAPI 做轻量 smoke，字段注释靠迁移时同步维护，不做逐字段断言。
-
-建议下一批迁移顺序：
-
-```text
-Assets / Video 只读 API
-  -> 内容资源 / 图片 / 视频解析
-Operations Content 只读 API
-  -> 横幅 / FAQ / 公告
-```
-
-## 当前状态
-
- 数据库模型迁移已完成到初始 schema。
- migration 已整理为单个初始建库 migration。
- API 安全底座已建立：JWT、Session、本地登录、当前用户、当前租户、基础授权策略。
- 租户公开入口已建立：tenant resolve、public config、health。
- Catalog 基础只读 API 已建立：地区、地区模块、模块节点、院校、专业、科目、题目分类。
- Content Navigation 只读 API 已建立：内容入口、内容节点、题集、题集题目、练习蓝图。
- Question Bank 只读 API 已建立：题库列表、题目列表、题目详情、题目版本。
- Vocabulary / Handbook 只读 API 已建立：词汇单元、词汇单词、知识手册科目、章节、条目。
- 当前模型测试、认证服务测试、API 认证/租户闭环测试、Catalog / Content Navigation / Question Bank / Study Content 只读测试通过。
- 下一步重点是继续把题库、内容、导入、订单等业务 API 接入这套安全轨道，而不是重新散写权限判断。