universal-dev-standards 5.17.0 → 6.1.0

package/bundled/locales/zh-TW/core/data-contract.md

@@ -0,0 +1,101 @@
+---
+source: ../../../core/data-contract.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-17
+source_hash: ef59d3f2e128
+status: current
+---
+
+# Data Contract 標準
+
+> **Language**: [English](../../../core/data-contract.md) | 繁體中文
+
+> **版本**: 1.0.0 | **狀態**: Active | **更新日期**: 2026-06-17
+> **AI 最佳化版本**: `ai/standards/data-contract.ai.yaml`
+> **規格**: XSPEC-068（cross-project/specs/XSPEC-068-uds-data-engineering-pack.md）
+
+## 概觀
+
+本標準定義資料生產者與消費者之間如何建立、版本化與強制 **data contract**。data
+contract 是一份正式協議，明定某資料集或資料流的 schema、品質保證、SLA 與所有權。
+涵蓋 contract 規格格式、freshness 與品質 SLO、破壞性變更治理、消費者註冊／通知，
+以及自動化 contract 測試。可降低因未被發現的上游變更所致的管線失敗。
+
+本標準屬於**資料工程標準包**（XSPEC-068），並為既有 `contract-test-assistant`
+skill 的**錨點標準**（資料側 contract）。
+
+> **範圍**：本標準定義 *contract 產物*（格式、SLO、治理、註冊）。具體資料品質引擎
+> （Great Expectations）與目錄（DataHub/Amundsen）屬採用者的選擇。
+
+## 需求
+
+| ID | 規則 | 等級 |
+|----|------|------|
+| REQ-001 | Data contract 規格格式 | MUST |
+| REQ-002 | 資料品質 SLO | MUST |
+| REQ-003 | Contract 版本化與破壞性變更治理 | MUST |
+| REQ-004 | 自動化 contract 測試 | MUST |
+| REQ-005 | 消費者註冊與通知 | MUST |
+| REQ-006 | Contract 可發現性 | SHOULD |
+
+### REQ-001 — Data Contract 規格格式
+
+每個共享資料集或資料流 MUST 具備機器可讀 YAML 檔（`data-contract.yaml`）的 data
+contract，與生產者程式碼一同提交版控。contract MUST 包含：`contract_id`、
+`version`、`owner`（team + 聯絡窗口）、description、`schema`（欄位名、型別、
+nullability）、`data_quality` SLO（completeness、freshness、uniqueness）、`sla`
+（交付時間）與消費者清單。
+
+### REQ-002 — 資料品質 SLO
+
+每個 contract MUST 定義跨下列維度的明確資料品質 SLO：**completeness**（必填欄位
+非 null 比例 ≥ 門檻）、**freshness**（來源後 N 分鐘／小時內更新）、**uniqueness**
+（關鍵欄位 distinct 比例）與 **validity**（符合所定義格式／範圍的比例）。品質 SLO
+違規 MUST 同時告警生產者與已註冊消費者。
+
+### REQ-003 — Contract 版本化與破壞性變更治理
+
+contract MUST 使用語意版本。**PATCH**（向後相容新增、文件）僅需生產者核准。
+**MINOR**（新可選欄位、放寬限制）需提前 7 天通知消費者。**MAJOR**（欄位移除、
+型別／語意變更）需消費者核准，且在所有已註冊消費者確認就緒前 MUST NOT 部署。
+
+### REQ-004 — 自動化 Contract 測試
+
+contract 合規 MUST 自動驗證。生產者 MUST 在每次管線執行時跑 contract 測試，以所
+宣告 schema 與品質 SLO 驗證輸出：schema 一致性（無非預期 null、型別正確）、
+freshness 在 SLO 窗內、關鍵欄位 uniqueness，以及 row count 在範圍內。contract 測試
+失敗 MUST 中止管線並呼叫（page）資料 owner。
+
+### REQ-005 — 消費者註冊與通知
+
+消費共享資料集的團隊 MUST 在生產者的 `data-contract.yaml` 中註冊為消費者，含團隊
+名稱、聯絡方式、用例描述與所消費欄位。已註冊消費者 MUST 在下列情況收到自動通知：
+contract 被修改、品質 SLO 被違反、資料集被棄用，或計劃性維護將影響可用性。
+
+### REQ-006 — Contract 可發現性
+
+組織內所有 data contract SHOULD 可透過中央資料目錄發現，目錄 SHOULD 提供：依
+team／domain 的可搜尋索引、目前健康狀態（SLO 合規）、schema 瀏覽、血緣視覺化
+（哪些管線生產／消費各資料集），以及自助式消費者註冊工作流程。
+
+## 與既有標準的整合
+
+- **`contract-test-assistant`（skill）**——本標準為其資料側錨點；該 skill 的 data
+  contract 指引引用這些需求。
+- **`data-pipeline`**——管線在每次執行時跑 contract 測試（REQ-004）。
+- **`schema-evolution`**——MAJOR contract 版本對應由 expand-contract 治理的破壞性
+  schema 變更。
+- **`audit-trail` / `pii-classification`**——contract 保留與欄位層級敏感度對齊合規
+  標準包（XSPEC-066）。
+
+## 相關規格
+
+- XSPEC-068 — UDS 資料工程標準包（本標準來源）
+- XSPEC-066 — 合規與稽核標準包（保留、PII 分級）
+
+## 變更紀錄
+
+| 版本 | 日期 | 變更 |
+|------|------|------|
+| v1.0.0 | 2026-06-17 | 初版——REQ-001~006：規格格式、品質 SLO、版本化／治理、自動化測試、消費者註冊、可發現性（XSPEC-068） |

package/bundled/locales/zh-TW/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) | 繁體中文
+
+---
+
+## 概述
+
+資料庫綱要遷移（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 的 bug 就藏在這裡。
+
+```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 遷移測試** — 回滾在生產事故中失敗
+- **事後撰寫遷移測試且未預先植入資料** — 完全錯過資料保存的 bug
+- **提交遷移卻沒有對應的測試** — 遷移在進入生產前完全未被測試
+- **只對解碼後的值斷言字串相等** — 即使位元組、normalization 形式或 codepoint 在跨編碼/跨引擎變更中已損壞，顯示層相等仍會通過
+- **僅以資料列抽樣驗證跨引擎遷移** — 分佈層級的偏移（錯誤的 `SUM`／`COUNT`／`DISTINCT`）會逃過任何剛好錯過受影響資料列的抽樣
+
+## 參閱
+
+- `database-standards.ai.yaml` — 綱要設計原則
+- `testing.ai.yaml` — 通用測試結構與金字塔
+- `verification-evidence.ai.yaml` — 稽核證據需求
+- `behavior-snapshot.ai.yaml` — 同樣的「別只比看起來相等」原則，作用於 oracle／序列化層，而非 DB 儲存層
+
+---
+
+**Scope**: universal

package/bundled/locales/zh-TW/core/data-pipeline.md

@@ -0,0 +1,105 @@
+---
+source: ../../../core/data-pipeline.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-06-17
+source_hash: 5a7a49049bd8
+status: current
+---
+
+# 資料管線標準
+
+> **Language**: [English](../../../core/data-pipeline.md) | 繁體中文
+
+> **版本**: 1.0.0 | **狀態**: Active | **更新日期**: 2026-06-17
+> **AI 最佳化版本**: `ai/standards/data-pipeline.ai.yaml`
+> **規格**: XSPEC-068（cross-project/specs/XSPEC-068-uds-data-engineering-pack.md）
+
+## 概觀
+
+本標準定義建構**可靠、可觀測且可維護資料管線**的工程要求。涵蓋 idempotency 與
+exactly-once 語意、錯誤處理與 dead-letter queue、checkpoint 與復原、資料血緣
+（lineage）追蹤、管線可觀測性與 SLO，以及測試要求。適用於批次 ETL、串流管線與
+ML 特徵管線。
+
+本標準屬於**資料工程標準包**（XSPEC-068）。它將 `database-standards`（涵蓋靜態 DB
+schema）延伸至資料的移動與轉換，並複用 SRE 家族的可靠性與可觀測性基本元件
+（`observability-standards`、`slo-sli`）。
+
+> **範圍**：本標準定義*管線設計原則*（idempotency、錯誤處理、復原、血緣、可觀測性、
+> 測試）。具體 orchestrator（Airflow/Dagster）、lineage store（Marquez/DataHub）與
+> DLQ 傳輸屬採用者的選擇。
+
+## 需求
+
+| ID | 規則 | 等級 |
+|----|------|------|
+| REQ-001 | Idempotency 與 exactly-once 處理 | MUST |
+| REQ-002 | 錯誤處理與 dead-letter queue | MUST |
+| REQ-003 | Checkpoint 與復原 | MUST |
+| REQ-004 | 資料血緣追蹤 | MUST |
+| REQ-005 | 管線可觀測性與 SLO | MUST |
+| REQ-006 | 管線測試要求 | MUST |
+
+### REQ-001 — Idempotency 與 Exactly-Once 處理
+
+每條管線 MUST 設計為 **idempotent** 執行：對相同時間窗或批次重跑同一管線，MUST
+產生相同輸出且無重複或資料遺失。管線 MUST 使用確定性鍵去重。批次管線 MUST 支援
+歷史 partition 的乾淨重跑。串流管線 MUST 實作 exactly-once，或以唯一 event ID 去重
+的 at-least-once。批次工作偏好覆寫輸出 partition 而非附加。
+
+### REQ-002 — 錯誤處理與 Dead-Letter Queue
+
+管線 MUST 實作具分類失敗模式的結構化錯誤處理。**Transient** 錯誤（網路逾時、API
+速率限制）MUST 使用指數退避重試（最多 3 次）。**Permanent** 錯誤（schema 違規、
+無效資料）MUST 將紀錄路由至 Dead-Letter Queue（DLQ），帶有原始紀錄、錯誤類型、
+錯誤訊息與處理時間戳。DLQ 紀錄 MUST 受監控並在管線 SLA 內處理。
+
+### REQ-003 — Checkpoint 與復原
+
+長時間批次管線與有狀態串流管線 MUST 實作 **checkpointing**，以在執行中途失敗時
+復原而無需全量重跑。Checkpoint MUST 記錄最後成功處理的 partition/offset/watermark、
+job run ID 與時間戳。復原 MUST 從最後 checkpoint 續跑，而非從頭開始。Checkpoint
+狀態 MUST 儲存於耐久的外部儲存，而非本機磁碟。
+
+### REQ-004 — 資料血緣追蹤
+
+每條管線 MUST 發出**血緣中繼資料**，描述其資料流：來源資料集（含版本／時間戳）、
+所套用的轉換邏輯，以及產出的輸出資料集。血緣 MUST 為機器可讀並匯入中央 lineage
+store 或資料目錄，以支援資料品質問題的根因分析與上游變更的影響評估。
+
+### REQ-005 — 管線可觀測性與 SLO
+
+每條正式管線 MUST 暴露：已處理紀錄數（counter）、處理延遲（histogram）、錯誤率
+（gauge）、DLQ 深度（gauge）與最後成功執行時間戳。管線 MUST 為 **freshness**
+（來源後 N 小時內可用）、**completeness**（≥ X% 紀錄成功處理）與 **latency**
+（p95 在門檻內）定義 SLO。SLO 違規 MUST 觸發告警。
+
+### REQ-006 — 管線測試要求
+
+管線 MUST 具備自動化測試，涵蓋：轉換邏輯的單元測試（樣本輸入／輸出）、以合成資料
+驗證端到端流程的整合測試，以及驗證輸出符合所宣告 data contract（`data-contract`）
+的 schema 一致性測試。管線 SHOULD 對歷史問題邊界案例（關鍵欄位 null、負數金額、
+重複紀錄）具備回歸測試。轉換邏輯的測試覆蓋率 MUST ≥ 80%。
+
+## 與既有標準的整合
+
+- **`data-contract`**——schema 一致性測試以生產者宣告的 contract 與品質 SLO 驗證
+  管線輸出。
+- **`schema-evolution`**——管線須容忍來源的向後相容 schema 變更。
+- **`observability-standards` / `slo-sli`**——管線 metric 與 freshness／completeness
+  SLO 複用 SRE 可觀測性與 SLO 基本元件。
+- **`database-standards`**——將靜態 schema 標準延伸至資料移動。
+- **`audit-trail`**——backfill 與重跑記錄稽核事件（原因）。
+
+## 相關規格
+
+- XSPEC-068 — UDS 資料工程標準包（本標準來源）
+- XSPEC-066 — 合規與稽核標準包（backfill 原因用 `audit-trail`）
+- XSPEC-063 — SRE 標準包（`observability-standards`、`slo-sli`）
+
+## 變更紀錄
+
+| 版本 | 日期 | 變更 |
+|------|------|------|
+| v1.0.0 | 2026-06-17 | 初版——REQ-001~006：idempotency、錯誤處理／DLQ、checkpoint／復原、血緣、可觀測性／SLO、測試（XSPEC-068） |