universal-dev-standards 5.17.0 → 6.0.0

package/bundled/locales/zh-CN/core/contract-testing-standards.md

@@ -0,0 +1,191 @@
+---
+source: ../../../core/contract-testing-standards.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-10
+source_hash: b2b6acbac739
+status: current
+---
+
+# 契约测试标准（Contract Testing Standards）
+
+> **语言**: [English](../../../core/contract-testing-standards.md) | [繁體中文](../../zh-TW/core/contract-testing-standards.md) | 简体中文
+
+**版本**：1.0.0
+**最后更新**：2026-05-05
+**适用范围**：具有 API 消费者（服务对服务、前端对后端、公开 API）的项目
+**范围**：universal
+**行业标准**：消费者驱动契约测试（Consumer-Driven Contract Testing, CDCT）、Pact Specification v3
+**参考资料**：[pact.io](https://docs.pact.io/)、[Spring Cloud Contract](https://spring.io/projects/spring-cloud-contract)
+
+---
+
+## 目的
+
+契约测试（Contract testing）验证 provider（API 服务器）与其 consumer（客户端）对于确切接口 —— 请求格式、响应 schema 与状态码 —— 达成共识，且无需双方同时部署。
+
+若缺少契约测试：
+- Provider 的变更会在 production 中悄悄破坏 consumer
+- 服务之间的集成测试需要完整环境
+- API 版本决策在缺乏实际使用证据的情况下做出
+
+本标准将消费者驱动契约测试正式化为一道**发布门禁**（`release-readiness-gate.md` 中的 Dimension 4，Tier-3）。
+
+---
+
+## 消费者驱动契约流程
+
+```
+Consumer 撰写交互预期
+        ↓
+Consumer 将契约发布至 Pact Broker
+        ↓
+Provider CI 获取 consumer 契约
+        ↓
+Provider 验证自身能否满足每一笔交互
+        ↓
+Pact Broker 记录：can-i-deploy 结果
+        ↓
+发布门禁：provider 部署前所有 consumer 契约必须 GREEN
+```
+
+---
+
+## 契约涵盖范围
+
+一份契约涵盖：
+
+| 元素 | 是否必须指定 | 备注 |
+|---------|-------------|-------|
+| 请求方法（Request method） | 是 | GET / POST / PUT / PATCH / DELETE |
+| 请求路径（Request path） | 是 | 包含路径参数（path params） |
+| 请求头（Request headers） | 仅必要者 | 不要过度指定可选请求头 |
+| 请求 body schema | 是（针对写入操作） | schema 层级，而非字面值 |
+| 响应状态（Response status） | 是 | 所有预期的状态码 |
+| 响应 body schema | 是 | schema 层级；使用 matcher 而非字面值 |
+| 响应头（Response headers） | 仅必要者 | 例如 `Content-Type` |
+
+**宁可不足指定，也不要过度指定。** 只断言 consumer 实际使用到的部分。
+
+---
+
+## 向后兼容窗口
+
+| 发布类型 | 兼容性要求 |
+|-------------|--------------------------|
+| Patch | 100% 向后兼容；不预期有契约变更 |
+| Minor | N-1 consumer 契约版本仍须通过 |
+| Major | 需要弃用期；通知 consumer；旧契约归档 |
+
+**破坏性变更政策**：若任何活跃的 consumer 契约呈红色，provider 不得部署（MAY NOT deploy）。破坏性变更需要：
+1. 采用仅新增（additive-only）变更的新 provider 版本
+2. Consumer 迁移至新版本
+3. 旧契约明确标记弃用并归档
+
+---
+
+## 发布门禁准则
+
+| 准则 | 硬性下限 | 警告区间 |
+|-----------|-------------|-----------|
+| 所有活跃的 consumer 契约 | 100% 绿灯 | —（二元：全有或全无） |
+| N-1 向后兼容 | 100% 绿灯 | — |
+| 弃用契约清理 | 旧契约于 30 天内归档 | > 30 天 = WARN |
+
+Pact Broker 中的 `can-i-deploy` 命令封装了这道门禁：
+
+```bash
+pact-broker can-i-deploy \
+  --pacticipant <provider-service> \
+  --version <version> \
+  --to-environment production
+```
+
+退出码（Exit code）0 = PASS；非零 = FAIL（阻断发布）。
+
+---
+
+## 实现指引
+
+### Consumer 端
+
+```typescript
+// Pact consumer test (TypeScript example)
+const interaction = {
+  state: "user 42 exists",
+  uponReceiving: "a request for user 42",
+  withRequest: {
+    method: "GET",
+    path: "/users/42",
+    headers: { Accept: "application/json" },
+  },
+  willRespondWith: {
+    status: 200,
+    headers: { "Content-Type": "application/json" },
+    body: like({           // schema matcher, not literal
+      id: integer(),
+      name: string(),
+      email: email(),
+    }),
+  },
+};
+```
+
+### Provider 端
+
+```bash
+# Provider verification in CI
+PACT_BROKER_BASE_URL=https://pact-broker.internal \
+PACT_PROVIDER_VERSION=$GIT_SHA \
+npm run test:pact:provider
+```
+
+### Pact Broker 标签
+
+| 标签 | 意义 |
+|-----|---------|
+| `main` | main 分支的最新版本 |
+| `production` | 目前部署于 production 的版本 |
+| `<feature-branch>` | 功能分支契约（暂时性） |
+
+---
+
+## 反模式
+
+- **测试整个 API 表面** —— 只测试 consumer 实际使用的部分；过度指定会造成不必要的契约中断
+- **字面值比对** —— 使用 schema matcher（`like()`、`eachLike()`、`integer()`）而非精确值；契约应能容忍实际数据的合理变化
+- **跳过 provider 验证** —— 发布 consumer 契约却不进行 provider 验证，代表该契约毫无强制效力
+- **未执行 `can-i-deploy`** —— 只检查个别契约状态并不足够；`can-i-deploy` 会评估整个部署矩阵
+
+---
+
+## 与其他标准的关系
+
+- **`api-design-standards.md`** —— 契约测试强制执行 API 设计中所声明的向后兼容保证
+- **`release-readiness-gate.md`** —— Dimension 4（Tier-3：当存在 API consumer 时适用）
+- **`integration-testing.md`** —— 契约测试补足但不取代集成测试
+- **`versioning.md`** —— 语义化版本与上述向后兼容窗口互相关联
+
+---
+
+## 另见
+
+- [Pact 文档](https://docs.pact.io/)
+- [Can I Deploy](https://docs.pact.io/pact_broker/can_i_deploy)
+- [消费者驱动契约（Consumer-Driven Contracts）](https://martinfowler.com/articles/consumerDrivenContracts.html) —— Martin Fowler
+
+---
+
+## 版本历史
+
+| 版本 | 日期 | 变更 |
+|---------|------|---------|
+| 1.0.0 | 2026-05-05 | 初版发布：消费者驱动契约流程、向后兼容窗口、发布门禁准则 |
+
+---
+
+## 授权
+
+本标准依 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授权发布。
+
+**来源**：[universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/locales/zh-CN/core/cost-budget-test.md

@@ -0,0 +1,86 @@
+---
+source: ../../../core/cost-budget-test.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-10
+source_hash: 19cf2a8cd706
+status: current
+---
+
+# 成本预算测试标准
+
+> **Language**: [English](../../../core/cost-budget-test.md) | [繁體中文](../../zh-TW/core/cost-budget-test.md) | 简体中文
+
+---
+
+## 概述
+
+调用 LLM API 的 AI 代理系统，若 pipeline 陷入失控循环、遭遇非预期的 token 爆炸，或预算阈值配置错误，成本可能迅速累积。成本预算测试用于验证 zone 分类器、阈值常量与 pipeline 预算保护机制在每个边界上的正确性。
+
+## Zone 分类
+
+大多数 AI 代理 token 预算系统将使用率比例划分为多个 zone。zone 之间的边界是差一错误（off-by-one error）风险最高的地方。
+
+```typescript
+// 使用 TOKEN_BUDGET 常量（而非魔术数字）进行 Vitest 边界测试
+import { classifyTokenZone, TOKEN_BUDGET } from "../types/index.js"
+import { describe, it, expect } from "vitest"
+
+describe("TokenBudgetZone classification boundaries", () => {
+  it.each([
+    [0.0,                                  "safe",     "zero usage"],
+    [TOKEN_BUDGET.WARNING_THRESHOLD - 0.01, "safe",     "just below WARNING"],
+    [TOKEN_BUDGET.WARNING_THRESHOLD,        "warning",  "exactly at WARNING"],
+    [TOKEN_BUDGET.DANGER_THRESHOLD - 0.01,  "warning",  "just below DANGER"],
+    [TOKEN_BUDGET.DANGER_THRESHOLD,         "danger",   "exactly at DANGER"],
+    [TOKEN_BUDGET.BLOCKING_THRESHOLD - 0.01,"danger",   "just below BLOCKING"],
+    [TOKEN_BUDGET.BLOCKING_THRESHOLD,       "blocking", "exactly at BLOCKING"],
+    [1.0,                                  "blocking", "fully exhausted"],
+  ])("ratio=%f → %s (%s)", (ratio, expected) => {
+    expect(classifyTokenZone(ratio)).toBe(expected)
+  })
+
+  it("returns 'blocking' for ratio > 1.0 (over-budget)", () => {
+    expect(classifyTokenZone(1.5)).toBe("blocking")
+  })
+})
+```
+
+## Pipeline 预算配置测试
+
+```typescript
+import type { PipelineBudgetConfig } from "../types/index.js"
+
+describe("PipelineBudgetConfig semantics", () => {
+  it("warningThreshold defaults should be 0-1 range", () => {
+    const config: PipelineBudgetConfig = {
+      maxCostPerRun: 1.0,
+      maxCostPerDay: 10.0,
+      warningThreshold: 0.8,
+      autoDowngrade: true,
+    }
+    expect(config.warningThreshold).toBeGreaterThan(0)
+    expect(config.warningThreshold).toBeLessThan(1)
+  })
+})
+```
+
+## 测试项目
+
+| 测试类别 | 原因 |
+|---------|------|
+| 精确边界值（WARNING/DANGER/BLOCKING） | 差一错误容易潜藏于此 |
+| 每个边界以下的值 | 确认低一级的 zone 正确 |
+| 使用率为零 | 干净初始状态 |
+| 比例 > 1.0 | 超出预算时仍应触发阻断 |
+| 所有 TOKEN_BUDGET 常量均被引用 | 防止突变测试存活 |
+
+## 相关标准
+
+- [突变测试标准](../../../core/mutation-testing.md) — 未有测试覆盖的常量容易在突变测试中存活
+- [测试标准](../../../core/testing-standards.md) — 整体测试金字塔
+- [LLM 输出验证](../../../core/llm-output-validation.md) — 输出层预算约束
+
+---
+
+**Scope**: universal

package/bundled/locales/zh-CN/core/cross-flow-regression.md

@@ -0,0 +1,199 @@
+---
+source: ../../../core/cross-flow-regression.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-10
+source_hash: ac618caf6d7f
+status: stale
+---
+
+# 跨流程回归（Cross-Flow Regression）
+
+> **语言**：[English](../../../core/cross-flow-regression.md) | [繁體中文](../../zh-TW/core/cross-flow-regression.md) | 简体中文
+
+**版本**：1.0.0
+**最后更新**：2026-05-05
+**适用范围**：所有具有多个 user flow 或业务流程的软件项目
+**Scope**：universal
+**业界标准**：ISTQB Advanced Test Analyst（Regression Test Strategy）
+**参考资料**：`core/flow-based-testing.md`、`core/testing-standards.md`
+
+---
+
+## 目的
+
+本标准定义跨流程回归测试（cross-flow regression testing）——验证对某一个 flow 的修改不会破坏其他 flow，并确保**多个 flow 的组合**在依序执行时行为正确。
+
+### 与 `flow-based-testing.md` 的界线
+
+| 标准 | 范围 | 它能捕捉的问题 |
+|----------|-------|----------------|
+| `flow-based-testing.md`（Multi-Gate Model） | 单一 flow：Decision Points、Terminal States、Decision Table | flow 内部的分支覆盖缺口 |
+| **本标准** | 多个 flow：交互、共享状态、依序组合 | flow 之间的污染、累积状态 bug、跨 flow 的回归 |
+
+这两者是互补而非重叠的关系。一个项目两者都需要。
+
+---
+
+## 为何跨流程 bug 与众不同
+
+flow 内部测试（Multi-Gate）能证明「Login」处理了全部 7 种 terminal state。但它无法检测：
+
+- **状态污染（State contamination）**：在一次失败的「Create Order」（FAIL_QUOTA_EXCEEDED）之后，quota 计数器遭到破坏 → 即使 quota 已重置，下一次「Create Order」尝试仍然失败
+- **共享资源冲突（Shared resource conflicts）**：「Report Generation」与「Data Export」同时执行时，破坏了共用的临时目录
+- **依序依赖（Sequential dependency）**：「Cancel Subscription」成功，但后续的「Reactivate」flow 假设订阅仍然存在 → NullPointerException
+
+---
+
+## 跨流程测试套件定义
+
+### Tier-1：Critical User Journeys（CUJ，关键用户旅程）
+
+Critical User Journeys 是横跨 ≥ 2 个 flow 的端到端序列，代表核心业务价值路径。每一次 release 都必须包含一套 CUJ regression suite。
+
+**CUJ 识别**：
+1. 列出所有 flow（来自 requirement-template §2.4）
+2. 找出共享状态或常被依序执行的 pair／triple（成对／三组组合）
+3. 标记业务关键的组合（purchase、onboarding、authentication + 下游流程）
+
+**CUJ 覆盖率要求**：
+
+| 指标 | Tier-2 门槛（默认） | Tier-1 关键路径 |
+|--------|--------------------------|---------------------|
+| CUJ 通过率 | ≥ 95% | 100% |
+| 业务关键 flow 组合 | 100% | 100% |
+
+### Tier-2：flow 变更时的回归
+
+当任何 flow 的 §2.4（Decision Points、Terminal States）被修改时，整套 CUJ suite 必须重新执行——而不只是执行被修改 flow 的测试。触发逻辑：
+
+```bash
+# In CI: detect flow spec changes
+changed_flows=$(git diff origin/main... --name-only | grep -E "requirement-template|SPEC.*\.md")
+if [ -n "$changed_flows" ]; then
+  npm run test:cross-flow-regression
+fi
+```
+
+### Tier-3：并行与共享资源测试
+
+针对具有并行用户操作的项目：
+- 两位用户同时执行相同的 flow
+- Flow A 与 Flow B 共用一个写入资源
+- 长时间运行的 flow（异步）与短 flow 的结果交互
+
+---
+
+## 测试结构
+
+跨流程回归测试采用跨 flow 的**依序状态穿引（sequential state threading）**（延伸自 `flow-based-testing.md` 的 `ctx` 模式）：
+
+```typescript
+describe("CUJ: Register → Verify Email → Create First Order", () => {
+  const ctx: {
+    userId?: string
+    token?: string
+    orderId?: string
+  } = {}
+
+  // Flow 1: Register
+  it("Flow-1 Step 1: Register new user", async () => {
+    ctx.userId = await registerUser({ email: testEmail, plan: "trial" })
+    expect(ctx.userId).toBeDefined()
+  })
+
+  // Flow 2: Email Verification (depends on Flow 1 output)
+  it("Flow-2 Step 1: Verify email token", async () => {
+    const token = await getEmailToken(ctx.userId!)
+    ctx.token = await verifyEmail(token)
+    expect(ctx.token).toBeDefined()
+  })
+
+  // Flow 3: Create Order (depends on Flow 2 auth token)
+  it("Flow-3 Step 1: Create first order", async () => {
+    ctx.orderId = await createOrder(ctx.token!, orderPayload)
+    expect(ctx.orderId).toMatch(/^ord-/)
+  })
+
+  // Cross-flow verification: order state reflects trial plan limits
+  it("Cross-flow: Trial plan quota enforced on first order", async () => {
+    const order = await getOrder(ctx.token!, ctx.orderId!)
+    expect(order.quota_applied).toBe("trial")
+  })
+})
+```
+
+### 跨流程失败隔离
+
+当一个跨流程测试失败时，失败信息必须指出是**哪一个 flow** 引入了状态破坏：
+
+```typescript
+// BAD: generic assertion
+expect(result).toBe("success")
+
+// GOOD: includes flow context
+expect(result).toBe("success")  // Flow-3 depends on Flow-2 token being valid
+                                 // If this fails, check Flow-2 email verification output
+```
+
+---
+
+## 与 Release Gate 的集成
+
+跨流程回归是 `release-readiness-gate.md` 中的 **Dimension 6**（Tier-2）。
+
+### 触发条件
+
+| 触发时机 | 范围 |
+|---------|-------|
+| 每一个 release candidate | 整套 CUJ suite |
+| 修改任何 flow §2.4 的 PR | 整套 CUJ suite（merge 前） |
+| 部署至 staging 后 | CUJ 的 smoke 子集 |
+| 部署至 production 后 | 仅关键路径 CUJ（canary） |
+
+### Sign-off 的证据
+
+```
+| 6 | Cross-flow Regression | PASS | CUJ suite: 47/47 passed; 0 flow-interaction failures | QA Lead |
+```
+
+### WARN 门槛
+
+- CUJ 通过率 ≥ 95% 但 < 100% → WARN，并需记录具体失败的 CUJ 并完成 root-cause（根因分析）
+- CUJ 通过率 < 95% → FAIL（release 被封锁）
+- 业务关键组合失败 → FAIL，无论整体通过率如何
+
+---
+
+## 反模式（Anti-Patterns）
+
+- **只在 CI 缓慢时才跑跨流程测试**——依定义，它们必须在每一个 release candidate 上执行
+- **孤立地测试每个 flow 却称之为「regression」**——flow 的孤立测试已由 Multi-Gate 涵盖；跨流程测试必须具备 flow 之间的状态依赖关系
+- **在不相关的 `describe` 块间复用同一个 `ctx` 对象**——每个 CUJ 都需要干净、隔离的 `ctx`；CUJ 之间的污染会掩盖 bug
+- **失败信息中缺乏 flow 归属（attribution）**——跨流程失败难以调试；务必指出是哪个上游 flow 产生了被破坏的状态
+- **把 CUJ 失败当成 flaky（不稳定）**——跨流程状态 bug 是确定性的；「flaky」的跨流程测试几乎都是共享状态破坏的征兆
+
+---
+
+## 与其他标准的关系
+
+- **`flow-based-testing.md`** —— flow 内部的 gate（跨流程的前置条件）
+- **`testing-standards.md`** —— testing pyramid 中的 regression 层
+- **`release-readiness-gate.md`** —— Dimension 6（Tier-2）
+- **`e2e-testing.md`** —— CUJ 测试通常在 E2E 或 System Test 层级执行
+
+---
+
+## 版本历史
+
+| 版本 | 日期 | 变更 |
+|---------|------|---------|
+| 1.0.0 | 2026-05-05 | 初版发布：CUJ 定义、依序状态穿引、release gate 标准、Tier-1/2/3 分类 |
+
+---
+
+## 授权
+
+本标准依 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授权发布。
+
+**来源**：[universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/locales/zh-CN/core/data-migration-testing.md

@@ -0,0 +1,217 @@
+---
+source: ../../../core/data-migration-testing.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-28
+source_hash: 990309b5e8b1
+status: current
+---
+
+# 数据迁移测试
+
+> **Language**: [English](../../../core/data-migration-testing.md) | [繁體中文](../../zh-TW/core/data-migration-testing.md) | 简体中文
+
+---
+
+## 概述
+
+数据库模式迁移（schema migration）是高风险操作：它以难以轻易恢复的方式改变持久化数据，除非存在经过测试的回滚路径。完整的迁移测试套件需验证三个维度——正确性（up 可干净应用）、安全性（down 能还原状态），以及健壮性（应用两次无害）。
+
+## 需求摘要
+
+| ID | 规则 | 理由 |
+|----|------|------|
+| REQ-DMT-001 | 每个迁移都必须有 up 测试 | 未验证的迁移会损坏生产环境模式 |
+| REQ-DMT-002 | 每个具备 down 函数的迁移都必须有回滚测试 | 未测试的回滚在事故期间会失败 |
+| REQ-DMT-003 | 对同一迁移应用两次不得失败 | CI 重试可能触发重复应用 |
+| REQ-DMT-004 | 变更数据的迁移必须包含数据保存测试 | 模式正确性 ≠ 数据正确性 |
+| REQ-DMT-005 | 每个测试必须使用隔离数据库 | 共享状态会导致非确定性失败 |
+| REQ-DMT-006 | 跨编码或跨数据库引擎的迁移必须包含字节层编码转换测试 | 「看起来相等」会掩盖 codepoint/normalization/collation 的损坏 |
+| REQ-DMT-007 | business-critical 数据的迁移必须包含聚合不变量测试 | 逐行抽样会错过分布层级的偏移 |
+
+## 测试结构
+
+### 隔离
+
+每个迁移测试都在隔离的数据库上执行——无论是内存数据库（SQLite `:memory:`）还是全新的 Docker 容器（PostgreSQL）。绝对不要对共享的开发或预发布数据库执行迁移测试。
+
+```typescript
+// 正确：每个测试文件使用隔离的内存数据库
+const db = new Database(':memory:')
+await applyBaseline(db)
+
+// 错误：测试共享一个开发数据库
+const db = openDatabase(process.env.DATABASE_URL)
+```
+
+### Up 测试
+
+将迁移应用到基准模式，并断言预期的应用后状态。
+
+```typescript
+it('adds email column to users table', async () => {
+  await migrate.up(db)
+  const columns = db.prepare("PRAGMA table_info(users)").all()
+  expect(columns.map(c => c.name)).toContain('email')
+})
+```
+
+### Down 测试（回滚）
+
+先应用 up，再应用 down，并断言模式回到迁移前的状态。
+
+```typescript
+it('rollback removes email column', async () => {
+  await migrate.up(db)
+  await migrate.down(db)
+  const columns = db.prepare("PRAGMA table_info(users)").all()
+  expect(columns.map(c => c.name)).not.toContain('email')
+})
+```
+
+### 幂等性测试
+
+应用迁移两次，第二次应用不得抛出异常。
+
+```typescript
+it('applying migration twice is safe', async () => {
+  await migrate.up(db)
+  await expect(migrate.up(db)).resolves.not.toThrow()
+})
+```
+
+### 数据保存测试
+
+在迁移前先插入数据行，在迁移后断言数据完整性。
+
+```typescript
+it('preserves existing user rows', async () => {
+  db.prepare("INSERT INTO users (id, name) VALUES (1, 'Alice')").run()
+  await migrate.up(db)
+  const user = db.prepare("SELECT * FROM users WHERE id = 1").get()
+  expect(user.name).toBe('Alice')
+})
+```
+
+### 编码转换测试
+
+当字符串「看起来相等」时，模式层与数据行层的测试都会通过——但底层的字节可能已被跨编码或跨引擎的搬移（UTF-8 → UTF-16/`NVARCHAR`、`VARCHAR` → `NVARCHAR`、隐含的 collation 变更）悄悄损坏。跨编码或跨数据库引擎的迁移**必须**在**字节／codepoint／normalization** 层断言相等，而非显示层。
+
+要断言的内容：
+
+- **字节／codepoint 等同**——迁移后的值具有相同的 Unicode codepoint（且在目标以 UTF-16 储存时，具有预期的单元数），而不只是相同的渲染字形。
+- **Normalization 形式**——NFC vs NFD：`"é"`（U+00E9）与 `"e"+◌́`（U+0065 U+0301）渲染相同但字节序列不同；断言形式被保留（或被刻意正规化）。
+- **多字节边界**——在来源依**字符**上限截断的值，不得在目标被依**字节**上限截断（一个 4 字节的 emoji 必须能存活于 `NVARCHAR(n)` 栏位）。
+- **CJK／emoji／组合字**——明确测试辅助平面 codepoint（emoji、罕用 CJK）与组合序列；surrogate-pair 与 collation-folding 的缺陷就藏在这里。
+
+```typescript
+it('preserves bytes across UTF-8 -> target encoding (no display-only equality)', async () => {
+  // 混合 BMP CJK、一个辅助平面 emoji，以及一个 NFD 组合序列
+  const samples = [
+    '繁體中文',           // CJK (BMP)
+    '😀 family 👨‍👩‍👧',     // emoji 含 ZWJ 序列（辅助平面）
+    'é'             // NFD：'e' + 组合锐音符（渲染如 'é'）
+  ]
+  samples.forEach((s, i) =>
+    db.prepare('INSERT INTO notes (id, body) VALUES (?, ?)').run(i, s))
+
+  await migrate.up(db)
+
+  samples.forEach((expected, i) => {
+    const row = db.prepare('SELECT body FROM notes WHERE id = ?').get(i) as { body: string }
+    // ❌ 反模式：expect(row.body).toBe(expected)  // 即使部分损坏，只要两者渲染相同就会通过
+    // ✅ 在字节与 codepoint 层断言：
+    expect(Buffer.from(row.body, 'utf8')).toEqual(Buffer.from(expected, 'utf8'))
+    expect([...row.body]).toEqual([...expected])                 // 逐 codepoint 比对
+    expect(row.body.normalize('NFC')).toBe(expected.normalize('NFC')) // 明确的正规化意图
+  })
+})
+```
+
+> **反模式**：只对解码后的字符串断言 `expect(actual).toBe(expected)`。两个不同的字节／normalization 序列可解码为*看起来*相同的字形，因此显示层断言会通过，而储存的字节（以及任何下游的 `LIKE`／unique-key／collation 行为）却已损坏。
+
+### 聚合不变量测试
+
+数据行抽样能证明个别数据行存活；它**无法**证明*分布*存活。填充有代表性的数据集，在迁移**前**对 business-critical 栏位撷取聚合不变量，并在迁移**后**断言其不变。这与 post-cutover 生产对账所用的 oracle 相同（聚合相等跨越 cutover 边界），只是在迁移测试期就跑。
+
+要撷取的不变量：`COUNT(*)`、`SUM(money_column)`、`COUNT(DISTINCT key)`，以及依业务维度（如 status 或 period）分组的内容 `checksum`（例如哈希总和）。
+
+```typescript
+it('preserves aggregate invariants over financial data', async () => {
+  seedRepresentativeOrders(db) // 各种 status、金额、币别
+
+  const invariantQuery = `
+    SELECT status,
+           COUNT(*)            AS cnt,
+           SUM(amount_cents)   AS total_cents,
+           COUNT(DISTINCT customer_id) AS distinct_customers
+    FROM orders
+    GROUP BY status
+    ORDER BY status`
+  const before = db.prepare(invariantQuery).all()
+
+  await migrate.up(db)
+
+  const after = db.prepare(invariantQuery).all()
+  // 分布必须完全一致——而非只是「还有一些数据行存在」
+  expect(after).toEqual(before)
+})
+```
+
+> 因为聚合把整张表收敛成几个数字，一个不符的 `SUM`／`COUNT` 就能标出偏移；而逐行抽样——只检查你刚好挑到的数据行——会完全错过它。
+
+## 跨方言迁移：SQLite → SQL Server 风险表
+
+当迁移同时改变数据库引擎（不只模式）时，来源与目标方言在型别语义、比较与排序上会分歧。下表每一项分歧都是数据可能悄悄改变意义之处，也是上述编码与聚合测试（以及 reverse-engineering-standards.md 中非 HTTP 隐含规则扫描）的 derive 清单输入。
+
+| 风险点 | SQLite | SQL Server | 迁移须验 |
+|---|---|---|---|
+| **型别系统** | 动态型别（值层 type affinity） | 静态／强型别 | 每栏宣告型别；扫描 SQLite 容忍的越界／混型别值 |
+| **布尔** | 通常存成 `0/1` 整数 | `BIT` | `0/1` ↔ `BIT` 对映；NULL 布尔的处理 |
+| **日期时间** | 常存为 `TEXT`／`REAL`／`INTEGER` | `datetime2`／`datetimeoffset` | 格式解析、时区处理、精度截断 |
+| **自增主键** | `AUTOINCREMENT` | `IDENTITY` | 既有 id 连续性；正确的 seed/reseed 值 |
+| **大小写／collation** | `LIKE` 预设大小写不敏感；`NOCASE` | 由栏位 collation 决定 | 对齐 collation；检查 unique-key 折叠冲突 |
+| **NULL 排序** | NULL 排最前（最小） | 依设定而定 | `ORDER BY` 结果顺序不变量跨引擎 |
+| **浮点精度** | `REAL` | `float`／`decimal` | 金额／精确值改用 `decimal` 避免舍入误差 |
+| **字符串拼接** | `\|\|` | `+`／`CONCAT` | 改写查询；对齐 NULL 拼接语义 |
+| **分页** | `LIMIT`／`OFFSET` | `OFFSET .. FETCH`／`TOP` | 改写 + 保证稳定排序键以取得确定性分页 |
+
+> 每个「查询改写／语义差异」格也可能藏一条**隐含业务规则**——把本表喂入反向工程的隐含规则扫描阶段。
+
+## 工具
+
+### SQLite / Drizzle ORM
+
+```typescript
+import Database from 'better-sqlite3'
+import { drizzle } from 'drizzle-orm/better-sqlite3'
+import { migrate } from 'drizzle-orm/better-sqlite3/migrator'
+
+const sqlite = new Database(':memory:')
+const db = drizzle(sqlite)
+await migrate(db, { migrationsFolder: './drizzle' })
+```
+
+### PostgreSQL
+
+使用 `testcontainers` 为每个测试套件启动一个全新的 PostgreSQL 容器。容器在套件结束后销毁，确保隔离性。
+
+## 反模式
+
+- **对共享数据库进行测试** — 造成跨测试污染、不可重复的构建结果
+- **跳过 down 迁移测试** — 回滚在生产事故中失败
+- **事后编写迁移测试且未预先填充数据** — 完全遗漏数据保存的缺陷
+- **提交迁移却没有对应的测试** — 迁移在进入生产前完全未被测试
+- **只对解码后的值断言字符串相等** — 即使字节、normalization 形式或 codepoint 在跨编码/跨引擎变更中已损坏，显示层相等仍会通过
+- **仅以数据行抽样验证跨引擎迁移** — 分布层级的偏移（错误的 `SUM`／`COUNT`／`DISTINCT`）会逃过任何刚好错过受影响数据行的抽样
+
+## 参见
+
+- `database-standards.ai.yaml` — 模式设计原则
+- `testing.ai.yaml` — 通用测试结构与金字塔
+- `verification-evidence.ai.yaml` — 审计证据需求
+- `behavior-snapshot.ai.yaml` — 同样的「别只比看起来相等」原则，作用于 oracle／序列化层，而非 DB 存储层
+
+---
+
+**Scope**: universal