# GOV-003　開發流程與品質關卡

| 項目 | 內容 |
|---|---|
| 文件編號 | GOV-003 |
| 版本 | 1.1 |
| 狀態 | 已核定 |
| 撰寫者 | PM / QA Lead |
| 審查者 | SA / TL |
| 對應需求 | FR 9.x（測試品質）、NFR 品質類 |

---

## 1. 流程總覽

本專案採「**文件先行、關卡把關、程式後進**」之開發流程。
每一關卡（Gate）均有**量化通過標準**與**指定裁決人**；未通過不得進入下一階段。

```mermaid
flowchart TD
  G0["G0 需求基線<br/>BRD 核定"] --> G1["G1 架構基線<br/>SAD 核定"]
  G1 --> G2["G2 設計基線<br/>SDD 核定"]
  G2 --> G3["G3 規範基線<br/>CSP + TRP 核定"]
  G3 --> C["★ 程式撰寫階段<br/>（第一檢核點）"]
  C --> G4["G4 單元測試准出<br/>TRR-001"]
  G4 --> G5["G5 整合／POC 驗收<br/>TRR-002 + BRD-004"]
  G5 --> R["交付"]
```

| 關卡 | 名稱 | 裁決人 | 通過標準（摘要） |
|---|---|---|---|
| G0 | 需求基線 | PM | BRD-001~004 核定；範圍 R1/R2/R3 明確 |
| G1 | 架構基線 | SA | SAD-001~006 核定；服務邊界凍結 |
| G2 | 設計基線 | SA | SDD-000~007 核定；ER 與 API Contract 凍結 |
| G3 | 規範基線 | PM | CSP-001~005、TRP-001 核定；骨架可建置 |
| **★** | **程式撰寫（第一檢核點）** | — | 本文件 §4 之進入條件全數成立 |
| G4 | 單元測試准出 | QA Lead | 見 §5.1 |
| G5 | 整合／POC 驗收 | PM | 見 §5.2 |

---

## 2. 每個階段的工作循環

所有階段一律採下列循環，**不得跳步**：

```mermaid
flowchart LR
  A["① 產出<br/>Draft"] --> B["② 自我檢核<br/>作者自查"]
  B --> C["③ 同儕審查<br/>Peer Review"]
  C --> D{"④ 缺失?"}
  D -->|是| A
  D -->|否| E["⑤ 關卡檢核<br/>Gate Check"]
  E --> F{"⑥ 達標?"}
  F -->|否| A
  F -->|是| G["⑦ 核定<br/>Baseline"]
```

**同儕審查規則**：
- 需求／設計文件：至少 1 名非同作者的對應角色審查（如 BA 文件由 SA 審）。
- 程式碼：**每次合併至少 1 名 Reviewer 核准**；涉及金額計算、授權決策、狀態機轉換者
  須由 TL 或 SA 審查。
- 資安相關（身分、加密、日誌遮罩）：須 SEC 審查。

---

## 3. 品質關卡的量化標準

### 3.1 文件類（G0–G3）

| 檢查項 | 標準 | 自動化 |
|---|---|---|
| 文件表頭完整 | 6 個必要欄位齊備 | ✅ |
| 檔名合規 | 100% 符合 GOV-001 §3 | ✅ |
| Mermaid 語法 | 0 錯誤 | ✅ |
| 需求覆蓋 | RTM 四問覆蓋率 100% | ✅ |
| 禁止字樣 | 無 `TODO`／`TBD`／`待補`／`mock`／`stub` 於**規格內容** | ✅ |
| 交叉引用有效 | 引用之文件編號均存在 | ✅ |
| 術語一致 | 與建議書術語表一致（iECS／BASE24-mas／MAS） | ✅ |

### 3.2 程式類（G4–G5）

| 檢查項 | 標準 | 自動化 |
|---|---|---|
| 編譯／型別檢查 | 0 error（strict 模式） | ✅ |
| 靜態分析 | 0 blocker、0 critical | ✅ |
| 單元測試 | 全數通過 | ✅ |
| 覆蓋率（整體） | 行覆蓋率 ≥ 80% | ✅ |
| 覆蓋率（領域層） | 行覆蓋率 ≥ 90% | ✅ |
| 分支覆蓋率（金額／授權決策） | ≥ 90% | ✅ |
| 架構依賴規則 | 無逆向依賴、無跨服務直接呼叫 | ✅ |
| 反模式掃描 | 0 筆（見 §6） | ✅ |

---

## 4. 程式撰寫階段之進入條件（第一檢核點）

| # | 條件 | 負責 | 驗證 |
|---|---|---|---|
| 1 | 所有文件狀態為「已核定」 | PM | 文件表頭 |
| 2 | Mermaid 0 語法錯誤 | SD | 自動化腳本 |
| 3 | ER-Diagram 可轉為 DDL 且語法正確 | DA | 腳本試建 |
| 4 | API Contract 通過 OpenAPI 3.1 schema 驗證 | SD | 自動化腳本 |
| 5 | 反模式掃描：文件中無 mock／stub 佔位設計 | TL | 自動化腳本 |
| 6 | 專案骨架可建置（`npm ci && npm run build` 成功） | TL | CI |
| 7 | 測試框架可執行（空測試集亦能跑通） | QA | CI |
| 8 | 開發環境確認（由業主指定） | 業主 | 書面確認 |

| 9 | **每個待開發服務／功能已有 `SCS-00x`（服務程式設計規格）且狀態為「已核定」** | **SA / Tech Lead** | **`docs/07-scs/` 文件存在且完整（10 章節）** |

> **條件 9 於 2026-09-19 新增**（依 `GOV-005`）。

> 緣由：BEAM PMO 指出既有文件只有架構層級，缺服務／程式層級 Coding Spec，等於邊做邊想、追溯斷裂。
> **無 SCS 不寫程式**——程式之領域模型、狀態機、程式結構、資料模型、錯誤碼須先於 SCS 定義，
> 程式碼實作時須與 SCS 一致（SCS 之資料表約束須為**實測值**）。


> **條件 8 待業主裁定**：本階段文件之技術棧以 **TypeScript / Node.js 22 / PostgreSQL 16**
> 為參考實作棧（理由見 `CSP-002 §2`）；若業主指定 Java 21 / Spring Boot 3，
> 領域層與契約層之設計**不需變更**（詳 `SAD-001 §7` 之埠／轉接器對照表）。

---

## 5. 測試准出標準

### 5.1 G4　單元測試准出

| 指標 | 門檻 |
|---|---|
| 測試案例通過率 | 100% |
| 行覆蓋率（整體） | ≥ 80% |
| 行覆蓋率（`domain/`） | ≥ 90% |
| 分支覆蓋率（金額計算、授權決策、狀態機） | ≥ 90% |
| Severity 1／2 缺陷未關閉數 | 0 |
| Severity 3 缺陷未關閉數 | ≤ 5，且均有排程 |
| 缺陷修復後回歸 | 100% 通過 |

### 5.2 G5　整合／POC 驗收准出

| 指標 | 門檻 |
|---|---|
| POC 17 項情境 | 全部通過並留存證據 |
| 端到端流程（BRD-001 §4 之 12 條） | 全部通過 |
| 效能（對應 NFR） | 授權 P99 ≤ 200 ms、路由 P99 ≤ 5 ms |
| 併發正確性（重複入帳防範） | 併發 200 筆同鍵請求 → 僅 1 筆成功入帳 |
| 缺陷 | Severity 1／2／3 全部關閉 |

---

## 6. 反模式禁令（本專案列為關卡項目）

業主明確要求：**不得有「塞框架」與「mock data」的行為**。定義與偵測方式如下。

### 6.1 「塞框架」之定義

指**以假的實作滿足介面，使系統看似可運行但實際不具業務能力**。包含但不限於：

| 反模式 | 具體樣態 |
|---|---|
| 空殼實作 | 方法直接 `return null` / `return []` / `return true` 而不實作規則 |
| 假成功 | 呼叫外部系統失敗仍回傳成功，或無條件回 `OK` |
| 規則硬寫死 | 將應參數化的業務規則（利率、費率、額度上限）寫死於程式碼 |
| 假例外處理 | `catch` 後吞掉例外且不記錄、不補償 |
| 假非同步 | 宣告為事件驅動但實際同步呼叫，或事件發布後無人消費 |
| 假持久化 | 資料只存在記憶體，重啟即遺失（**除經核可的快取**） |
| 假認證 | 略過權杖驗證、以固定角色取代真實授權判斷 |

### 6.2 「mock data」之定義

指**以隨機或固定假資料填充，使畫面或報表看似有內容**。包含但不限於：

| 反模式 | 具體樣態 |
|---|---|
| 前端假資料 | 前端內建 `DATA['/path'] = { gen: () => [...] }` 之類假資料產生器 |
| 後端假資料 | 啟動時插入非屬參數／主檔的假交易、假持卡人 |
| 假統計 | 儀表板數字寫死或隨機產生 |
| 假外部回應 | 以寫死的卡組織回應取代真實介接（**除契約測試之沙箱，且須標記**） |

> **允許的例外（白名單）**：① 經核可之**參數類主檔**（產品、費率、MCC、卡組織代碼）
> 之初始資料；② 測試專用之**合成測試資料**，且僅存在於測試程式碼與測試資料庫中，
> **不得進入生產路徑**。白名單項目須於 `CSP-005 §5` 明列。

### 6.3 偵測方式（自動化）

| 掃描項 | 方法 | 適用 |
|---|---|---|
| 前端假資料產生器 | 掃描 `frontend/src` 內 `mock`／`fixture`／`gen(`／`randomData` 字樣 | 前端 |
| 空殼回傳 | 掃描 `return null;`／`return [];`／`return true;` 且函式體 ≤ 2 行 | 後端 |
| 吞例外 | 掃描 `catch` 區塊無 `throw`／`logger`／補償呼叫 | 後端 |
| 寫死規則 | 掃描 `domain/` 內出現具體數值常數（利率、費率、上限） | 後端 |
| 假認證 | 掃描路由未掛載授權中介層 | 後端 |
| 假統計 | 掃描前端儀表板元件內數值字面量 | 前端 |

掃描結果為 **0 筆** 方得通過 G3（文件）與 G4（程式）。
實作方式見 `CSP-005 §6`。

---

## 7. 變更控制

| 變更類型 | 影響 | 程序 |
|---|---|---|
| 需求變更 | BRD / RTM | 提變更單 → BA 評估 → PM 核可 → 客戶確認 |
| 服務邊界變更 | SAD / SDD / API | 提變更單 → SA 評估 → PM 核可 |
| 資料模型變更 | SDD-001 / DDL | 提變更單 → DA + SA 評估 → PM 核可 |
| API 破壞性變更 | SDD-006 | 須升版（v1→v2）並雙軌至少一個 release |
| 缺陷修復 | 程式 | 不走變更控制，但須登錄 TRR-002 |

**凍結（Freeze）規則**：關卡通過後即凍結；凍結後之變更一律走變更控制，
且須重新執行受影響範圍的關卡檢查。

---

## 8. 缺陷管理

### 8.1 嚴重度定義

| 級別 | 定義 | 修復時限 | 關卡影響 |
|---|---|---|---|
| S1 阻斷 | 系統無法啟動／核心流程完全不可用／金額計算錯誤 | 立即 | G4／G5 不得放行 |
| S2 嚴重 | 主要功能不可用或結果錯誤，無替代路徑 | 2 工作日 | G4／G5 不得放行 |
| S3 一般 | 功能可用但有錯誤，有替代路徑 | 5 工作日 | 可放行，須排程 |
| S4 輕微 | 文案、樣式、體驗問題 | 下一個 release | 不影響 |

### 8.2 缺陷生命週期

```mermaid
stateDiagram-v2
  [*] --> New: 發現並登錄
  New --> Assigned: QA Lead 分派
  Assigned --> InProgress: 開發者受理
  InProgress --> Fixed: 修復並自測
  Fixed --> InVerification: 提交驗證
  InVerification --> Closed: 驗證通過
  InVerification --> Reopened: 驗證不通過
  Reopened --> InProgress: 重新受理
  New --> Rejected: 非缺陷
  Rejected --> Closed: 提報者確認
  Closed --> [*]
```

**規則**：缺陷**只能由提報者或 QA 關閉**，開發者不得自行關閉。

---

## 9. 本階段（文件備審）之產出順序

依關鍵路徑執行，**不停下來等待指示**（依業主指示：文件階段連續產出至程式撰寫檢核點）：

| 序 | 工作 | 產出 | 負責 |
|---|---|---|---|
| 1 | 治理基線 | GOV-001~004 | PM |
| 2 | 需求基線 | BRD-001~004 | BA |
| 3 | 架構基線 | SAD-001~006 | SA / SEC |
| 4 | 設計基線 | SDD-000~007 | SD / DA |
| 5 | 規範基線 | CSP-001~005 | TL |
| 6 | 測試計畫 | TRP-001 | QA Lead |
| 7 | 全文件自動化檢核 | 檢核報告 | TL |
| 8 | **交付業主備審（第一檢核點）** | — | PM |

---

## 9. 修訂記錄

| 版本 | 說明 |
|---|---|
| 1.0 | 初版：流程總覽、關卡量化標準、反模式禁令 |
| 1.1 | 2026-09-19｜SA / Tech Lead｜**§4 新增條件 9：待開發服務／功能須先有 `SCS-00x`（服務程式設計規格，狀態「已核定」）始得撰寫程式**。緣由：BEAM PMO 指出現有文件僅架構層級，缺服務／程式層級 Coding Spec，等於邊做邊想、追溯斷裂（詳 `GOV-005`）。配套：新增 `docs/07-scs/` 目錄與 `SCS-000`（總覽與模板）、`SCS-001`～`003`（授權／額度／卡片服務，回溯補建）。 |

> **本文件原無修訂記錄區**（追溯缺口），於 1.1 補建。