lingxi/docs/工程规范/06-测试与CI规范.md

06 · 测试与 CI 规范

项	内容
文档版本	V1.0（2026-11-02）
依据	技术架构 §10.4（测试策略）、§4.6（CI/CD）、§4.1.1（本地环境）
适用范围	全仓库
强制级别	强制

---

1　测试分层

层级	工具	范围	运行时机
单元	Vitest	Service、工具函数、状态机、命名 / 表单引擎	每次提交（CI + 本地）
集成	Vitest + Testcontainers（PG 18 / Redis 7.4 / MinIO）	Repository、队列、迁移、事务	每次 push main（CI）
契约	OpenAPI + oasdiff	接口兼容性	每次 push main
E2E	Playwright	主链路（登录 → 生成 → 预览 → 勾选 → 导出）	主干 + 发布前
性能	k6	列表 / 任务提交 / SSE	发布前（仅 staging）
视觉回归	图片像素比对	PSD 合成产物	改动 packages/render 时

• TST-01 单测与源码同目录，命名 <name>.spec.ts；集成 *.int.spec.ts；E2E 放 e2e/。
• TST-02 关键包（shared / form-engine / render / ai-sdk）行覆盖率 ≥ 70%；整体基线只升不降。
• TST-03 禁止提交 .skip / .only；CI 检测到即失败。
• TST-04 禁止依赖执行顺序；每个测试自建数据、自清理（用独立 customer_id 前缀）。

---

2　必测清单（缺一项即 Review 不通过）

编号	场景
TST-05	权限三态：每个端点至少「有权限 / 无权限 / 范围外」3 条用例
TST-06	客户隔离：跨客户读取必须 403 或空集，且不得泄漏存在性
TST-07	状态机：合法迁移 + 非法迁移（返回 409）各一条
TST-08	幂等：同 Idempotency-Key 重复提交只产生一次副作用
TST-09	成本前置：任务提交未带预估成本 / 超预算时被拒
TST-10	审计：导出、权限变更、AI 配置变更均落审计
TST-11	降级路径：抠图失败 → 原图 + low_quality 标记；AI 内容违规 → 不重试
TST-12	迁移：升级后可回滚；expand 阶段旧代码仍可用
TST-13	任务断点：SSE 断线后 Last-Event-ID 可续推
TST-14	命名规则：非法字符、超长、同名重名各一条（PRD R-01）

---

3　测试数据与环境

• TST-15 禁止连接生产库 / 生产对象存储；CI 用 Testcontainers 起同版本依赖。
• TST-16 测试数据用 factory 构造，禁止依赖线上导出数据。
• TST-17 测试内置时钟可注入（clock 包），禁止 new Date() 直接断言时间。
• TST-18 AI 调用在测试中一律 mock Provider，禁止真实外网调用（防止费用与不稳定）。
• TST-19 涉及文件的测试用内存 / 临时目录，结束后清理。

---

4　CI 流水线

install --frozen-lockfile
  → format:check → lint --max-warnings=0 → typecheck
  → unit test（coverage）→ build
  → integration（Testcontainers）→ openapi:diff
  → e2e（main）→ 镜像构建 + 漏洞扫描

阶段	阻断条件
安装	lock 文件与 package.json 不一致
格式 / Lint	任一错误或警告
类型	任一错误
单测	失败或覆盖率低于基线
集成	失败或超时（单测总时长 ≤ 10 分钟）
契约	oasdiff 检出破坏性变更但未升版本
构建	失败
安全	高危漏洞 > 0

• TST-20 流水线并行化按包拆分（Turborepo），但门禁结论必须在聚合 job 上判定。
• TST-21 禁止通过 --passWithNoTests、跳过集成测试等方式「修绿」；豁免须技术负责人批准并留提交说明记录。
• TST-22 flaky 测试 24 小时内修复或移除并登记，禁止重试 3 次掩盖。

---

5　特性开关与灰度

变量	用途
FEATURE_VIDEO	视频线开关（未完成不得外露）
其他 FEATURE_*	按里程碑临时开关，上线稳定后删除

• TST-23 未完成功能必须藏在开关后，禁止半成品直接可见。
• TST-24 开关必须有默认值、有 owner、有清理期限（写进提交说明或配置注释）。
• TST-25 开关组合不得导致数据不一致（关闭后已产生的数据仍可读）。

---

6　发布与回滚

staging 部署 → 冒烟（登录 / 生成 / 预览 / 导出）
  → 生产迁移（expand）→ 灰度 10% → 观察 30 分钟 → 全量 → 收缩（contract，下个版本）

• TST-26 迁移先行、代码后行；收缩步骤必须在确认无旧版本流量后执行。
• TST-27 每次发布必须有回滚预案：代码回滚 + 数据回滚（或前向修复）分别说明。
• TST-28 发布后观察：错误率、P95、队列积压、AI 费用；异常 15 分钟内决策回滚。
• TST-29 发布记录写入 docs/releases/（版本、变更、影响面、回滚方式）。

---

7　检查清单

• 新增 / 修改逻辑有对应单测，关键包覆盖率达标
• 端点有权限三态用例，客户隔离用例存在
• 状态机非法迁移、幂等、成本前置已覆盖
• 集成测试用 Testcontainers，无外网依赖
• CI 全绿且未使用豁免
• 迁移可回滚，staging 已演练
• 未完成功能藏开关，开关有清理期限
• 发布记录与回滚预案已写