# SaaS 题库生产地基基线（2026-07-12）

## 决策

当前仓库的后端代码、数据库迁移、租户隔离和三类角色业务契约可以进入受控冻结，前端可以在现有 `apps/taro` 上开始正式重构。

这不等于已经可以直接切生产流量。正式上线仍以目标云服务器上的真实配置、真实 provider、真实数据迁移和 `production-launch-evidence.json` 全量通过为准。任何本地 mock、clean-room 或预览构建都不能替代生产证据。

## 已验证的地基

- 官方 Supabase PostgreSQL 15.8 空库中，特权 bootstrap 后由非 superuser migration role 成功应用全部 78 个 migration；未执行 seed，后期安全迁移重放幂等，官方 schema lint 通过。详见 `clean-room-migration-audit-20260712.md`。
- 140 张 `public` 表全部启用 RLS；134 张包含 `tenant_id` 的业务表全部启用 RLS。`anon/authenticated` 无 `public` RPC 或扩展函数执行权。
- `tiku_api/tiku_worker` 是独立最小权限运行角色；均不能直接读取 `auth.users`，只有 API 可通过 `app.auth_user_exists(uuid)` 获得布尔存在性。
- Data API、动态 CORS、短信限流、审计容量索引、导入 Worker lease/fencing、租户外键与关键查询索引已经进入 readiness 门禁。
- 单租户 100,000 学生容量证据通过：首屏查询 P95 `11.245ms`，深游标 P95 `3.114ms`，关键 keyset/trigram 索引被使用并完成清理。
- `npm run test:readiness`、API TypeScript 检查、后端生产依赖审计和仓库自带安全扫描通过；仓库扫描结果为 0 findings。
- API Docker 运行镜像已锁定 Node `20.20.2`/Alpine `3.23` 多架构摘要，以 `node` 用户运行，只含生产依赖和编译产物；本机验证镜像约 `53 MB`，`node_modules` 约 `24.3 MB`，不含 `typescript/tsx`，并连接 `55432` 隔离库通过 `/health`。
- Taro 固定稳定版 `4.2.0`；两项 H5 运行时补丁由 workspace postinstall 原子应用并按源码 hash fail closed。仓库外干净 `npm ci`、供应链门禁和补丁契约均通过。
- 学生端、租户后台、平台后台三套 H5 production 构建、静态烟测 `25/25` 和真实 Chrome 业务交互烟测 `33/33` 通过；Input 挂载前后值同步和 Button loading 200 次稳定节点探针通过。
- 三端桌面 `1440x900` 与移动 `390x844` 浏览器验收通过，无控制台 error/warn、无页面级横向溢出，并验证每个门户至少一个主入口。详见 `taro-h5-browser-qa-20260712.md`。

## API 冻结边界

前端重构默认只能消费现有契约，以下内容从本基线起视为兼容性边界：

- 路由、HTTP method、状态码、错误 `code` 和分页 cursor 语义。
- `GET /api/tenant/resolve` 的 Origin/tenantCode 解析规则和公开配置字段。
- Supabase access token、迁移期 `tk_` session、`Authorization` 与 `x-tenant-id` 的统一 client 行为。
- 学生、租户成员、平台员工三类身份和权限目录；页面可隐藏入口，但后端仍是最终授权源。
- 练习 session、导入 job、导出 job、支付/退款、CRM、账单和 Worker 状态机。
- 私有资料、图片、PDF、视频的短签名、水印和访问审计结果。

需要修改上述契约时，必须同时更新后端注册表、Taro service、类型、route/API/persona contract test、交接文档和版本说明。破坏性字段变更应采用新增字段、双读/双写或版本化接口，不允许直接让已有三端同时失效。

当前冻结属于受控兼容基线，不是覆盖全部请求/响应字段的完整 OpenAPI v1 冻结。仓库已机器锁定 method/path、统一 `meta.requestId`、错误 `code`、租户解析、认证头、十万学生 keyset 分页和订单/退款/导入/CRM/佣金等核心状态值；开发新垂直切片时，还必须为本切片的请求字段、响应字段、HTTP 状态和业务错误码补 contract snapshot，直到这些 snapshot 汇总为完整 schema。

页面不得直接写 Supabase 业务表，不得自行拼接对象存储 URL，也不得在页面层手写身份头或长期保存另一套租户/会话状态。

## 多端产品边界

- 学生端：继续使用 Taro，共享 H5、微信小程序和后续 App 的页面、services、capabilities 与领域类型。
- 租户后台、平台后台：首发只做响应式 H5。批量导入、复杂表格、财务和运营工作流不强行迁入小程序。
- 微信小程序：只发布学生端。数百租户共用包时使用 launch tenant mode，由受控 scene/query 解析租户；缺租户码必须 fail closed。
- 后续 App：优先复用学生端业务组件和 API client，支付、文件、音视频、推送、分享等能力通过 capabilities 层逐项替换并真机验收。

## 前端启动门禁

前端可以开始，但第一阶段必须先完成以下工程约束，再批量做页面视觉：

1. 冻结三类 persona 的信息架构、导航和权限矩阵，不删现有业务入口。
2. 建立跨端设计 token、基础组件和状态规范；租户品牌只能覆盖已批准 token，不允许注入任意 CSS。
3. 保持 `api.ts`、全局 App Provider、租户解析和缓存隔离为唯一基础设施。
4. 每个垂直切片同时完成桌面 H5、移动 H5和学生小程序兼容检查；后台无需小程序化。
5. 把包体和首屏性能设为硬门禁。当前 production 入口约为学生端 `501 KiB`、租户后台 `477 KiB`、平台后台 `450 KiB`；重构前应先规划路由拆包、延迟加载和资源预算，避免继续扩大首包。
6. 每次关键页面改动运行 Taro 类型检查、route/API/persona/compatibility contract、Taro 供应链审计、视觉守卫、三套构建、学生小程序生产构建、静态烟测和交互烟测。

## 生产硬阻断

以下项目只能在目标生产环境完成，未完成前 `launch:gate` 应继续阻断：

- 立即撤销曾在对话中暴露的临时 Git 令牌，并重新生成最小权限凭据。
- 由数据库 superuser 执行 runtime role/extension bootstrap，再由标准 migration role 应用迁移；API/Worker 使用独立强密码运行角色。
- 配置真实 Supabase Auth/JWKS、阿里云 PNVS、微信/QQ OAuth、微信/支付宝支付和回调域名。
- 配置真实对象存储、外部 AV/内容安全扫描、CDN 边界、水印和生命周期策略。
- 在 Supabase Auth 创建或确认首个管理员身份后，通过 `npm run bootstrap:platform-admin` dry-run 和精确确认短语创建唯一首个平台超管，再运行数据库 readiness。
- 在目标 Linux 主机验证 API、Worker target、job service、timer、日志、告警和重启恢复。
- 生成生产备份/快照并完成至少一次隔离恢复演练；保留旧 PocketBase 只读快照和回滚步骤。
- 用真实完整数据执行 PocketBase production dry-run、导入校验和用户/题目/订单/资源抽样。
- 在目标 4C16G 配置收集 PostgreSQL tuning evidence、真实数据 API 读/混合压测和 100k 学生证据。
- 为三套 H5 放置仅含公开值的真实 `runtime-config.json`，生成 release manifest，并校验线上 index/app hash。
- 保持 `swiper@12.1.2`、`lodash-es@4.18.1` 和两个 Taro H5 runtime patch 的精确版本/hash，运行 `npm run audit:taro:supply-chain`；剩余 Taro CLI/构建工具链漏洞必须与已审查 allowlist 一致，不得扩展到 H5/小程序 bundle 运行路径。
- 完成真实 Auth、短信、CORS、三类 persona、支付/退款对账和对象存储抽样。
- 完成真实 Codex Security 扫描。仓库自带扫描不能替代该项，工具不可用时只能保持待补。
- 填写所有 artifact hash 和人工 attestations，最后运行 `npm run launch:gate -- --evidence ... --verify-live-h5`。

## 上线顺序

1. 撤销暴露凭据并冻结候选 commit。
2. 备份、bootstrap、migration、运行角色和数据库 readiness。
3. 配置 Auth/provider/storage，创建首个超管，验证 systemd/Worker。
4. 执行真实数据迁移演练、抽样、目标规格压测和远程安全烟测。
5. 生成三套 production H5、注入真实公开 runtime config、发布候选目录并生成 hash manifest。
6. 填写生产证据和人工签字，通过离线 gate 后灰度发布。
7. 对线上 H5 执行 hash/runtime config 校验，再逐步放量并观察错误率、P95、数据库连接、锁等待和 Worker backlog。