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 层逐项替换并真机验收。

前端启动门禁

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

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

上线顺序

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

8.2 KiB Raw Blame History Unescape Escape