# GOV-001　交付物清冊與命名規範 | 項目 | 內容 | |---|---| | 文件編號 | GOV-001 | | 版本 | **1.3**（2026-10-01，`CR-028`：§4.4 事件命名**範例**由 `authorization.hold.created.v1` 改為 `limit.hold.created.v1`——前者已廢除。前版 **1.2**） | | 狀態 | 已核定（Baseline） | | 專案 | BEAM 信用卡核心現代化 — 微服務系統建置 | | 依據文件 | `BEAM_核心現代化_信用卡核心_Proposal_V2_SoW.docx`（SoW 等級建議書） | | 交付物根目錄 | `cardcore/` | --- ## 1. 目的 本文件定義本專案**所有交付物的存放位置、編號規則、命名慣例與版本規則**。 專案成員（含 BA、DA、SA、SD、Security Architect、Coder、Tester／TestBOT） 產出任何文件或程式碼前，均須依本規範命名與歸位。 > **一句話原則**：看到檔名就要知道「這是什麼類型的文件、屬於哪個階段、第幾份」； > 看到程式路徑就要知道「它屬於哪個 bounded context、是第幾層」。 --- ## 2. 交付物根目錄結構 ``` cardcore/ ├── README.md 交付物導覽（入口文件） ├── docs/ 文件交付物（本階段主體） │ ├── 00-governance/ 治理類：規範、任務分派、流程、追溯 │ ├── 01-brd/ 業務需求類 │ ├── 02-sad/ 系統架構類 │ ├── 03-sdd/ 系統設計類 │ ├── 04-coding-spec/ 程式規範類 │ ├── 05-change-requests/ 契約／規格變更單（CR） │ ├── 05-test/ 測試類 │ ├── 06-test/ 測試類（續） │ ├── 07-scs/ 程式設計規格（SCS） │ └── 08-evidence/ 實測證據（截圖／錄檔）—管理規範見 §6.9 ├── backend/ 後端程式（程式撰寫階段產出） │ ├── services/ 各微服務（一個 bounded context 一個服務） │ └── platform/ 跨服務共用平台（common、gateway、bff） ├── frontend/ 前端程式（React 18 + Vite） └── ops/ 部署與維運（IaC、K8s manifest、CI 管線） ``` --- ## 3. 文件命名規範 ### 3.1 檔名格式 ``` -_<中文標題>.md ``` | 欄位 | 規則 | 範例 | |---|---|---| | `TYPE` | 3 碼大寫文件類型代碼，見 §3.2 | `SDD` | | `-` | 固定連字號 | | | `NNN` | 3 碼流水號，由 `001` 起，**同一 TYPE 內連續、不跳號** | `006` | | `_` | 固定底線 | | | `<中文標題>` | 繁體中文，不含空白與標點；標題內可用 `-` 連接英文詞 | `API-Contract` | 完整範例：`SDD-006_API-Contract.md` > **禁止**：`final`、`v2`、`新版`、`暫存`、`copy`、`(1)` 等字樣出現在檔名中。 > **禁止**：`final`、`v2`、`新版`、`暫存`、`copy`、`(1)` 等字樣出現在檔名中。 ### 3.4 證據檔命名規範（`docs/08-evidence/`） ``` <來源>--<簡述>. ``` | 欄位 | 規則 | 範例 | |---|---|---| | `<來源>` | 頁面／功能之英文識別，小寫、以 `-` 連接 | `webui-applications` | | `` | **2 碼**流水號，同一來源內由 `01` 起**連續不跳號** | `03` | | `<簡述>` | 繁體中文，描述該證據**證明什麼** | `送徵信後轉人工核決` | 完整範例：`webui-applications-03-送徵信後轉人工核決.png` > 命名須能**直接看出結論**（如「轉人工核決」而非「畫面3」）—— > 證據是給人驗收看的，不是給程式讀的。 > 版本以文件**內部的「版本」欄位**表達，不以檔名表達。 ### 3.2 文件類型代碼 | TYPE | 全稱 | 階段 | 主要產出角色 | |---|---|---|---| | `GOV` | Governance（治理） | 全期 | PM / SA | | `BRD` | Business Requirements Document | 需求 | BA | | `SAD` | System Architecture Document | 架構 | SA / Security Architect | | `SDD` | System Design Document | 設計 | SD / Data Analyst | | `CSP` | Coding Specification | 設計 | SA / Tech Lead | | `TRP` | Test Plan | 測試 | QA Lead | | `TRR` | Test Report | 測試 | Tester / TestBOT | | `OPS` | Operations Runbook | 維運 | SRE / Ops | ### 3.3 文件內部必要欄位 每份文件開頭**必須**有下列表格（缺一不可，供追溯與版控）： ```markdown | 項目 | 內容 | |---|---| | 文件編號 | SDD-006 | | 版本 | 1.0 | | 狀態 | 草稿 / 審查中 / 已核定 | | 撰寫者 | <角色> | | 審查者 | <角色> | | 對應需求 | FR 1.1、FR 1.2（可留空） | ``` --- ## 4. 程式命名規範 ### 4.1 微服務命名 ``` -service # kebab-case、單數名詞 ``` 範例：`authorization-service`、`card-service`、`posting-service`、`limit-service` - **不使用** `ms-`、`svc-` 前綴（冗餘）。 - 一個 bounded context **只對應一個服務**，不得一名多服務或一服務多名。 - 服務目錄內固定結構見 `CSP-002`。 ### 4.2 API 路徑 ``` /api/v1/ # 資源複數、kebab-case /api/v1//{id}/ ``` 範例：`/api/v1/cards/{cardId}/limits`、`/api/v1/authorizations` - 動詞不入路徑；狀態轉換以子資源或動作子路徑表達，例如 `POST /api/v1/cards/{cardId}/lifecycle-transitions`。 - 版本只在**大版**變動時升（`v1` → `v2`），欄位新增不升版。 ### 4.3 資料庫命名 ``` . # schema = bounded context 名（snake_case） ``` - 表名：**複數、snake_case**，例如 `authorization.authorizations`、`card.cards`。 - 欄位：`snake_case`；主鍵一律 `id`；外鍵 `_id`。 - 時間欄位：`*_at`（timestamptz）、日期欄位 `*_date`（date）。 - 金額欄位：`_amount` + 幣別欄位 `_currency`；**金額一律整數最小單位（分）**， **禁止使用浮點數**。 - 布林欄位：`is_*` / `has_*`。 ### 4.4 領域事件命名 ``` ...v ``` 範例：`posting.transaction.posted.v1`、`limit.hold.created.v1`、 `card.card.status-changed.v1` - 事件名稱使用**過去式**（事件是既成事實）。 - 事件 payload **只增不減**；破壞性變更須升 `v2` 並雙軌發布至少一個 release。 ### 4.5 錯誤碼命名 ``` CC-- ``` - `SERVICE`：4 碼大寫服務縮寫（見 `CSP-003` 對照表），例如 `AUTH`、`CARD`、`POST`。 - `NNN`：4 碼數字，**一碼一義**（首位＝類別，見 `CSP-003`）。 範例：`CC-AUTH-1001`（授權額度不足）、`CC-POST-4001`（請款重複入帳） ### 4.6 程式檔案命名 | 語言 | 檔案 | 型別／類別 | 函式／變數 | |---|---|---|---| | TypeScript | `kebab-case.ts` | `PascalCase` | `camelCase` | | Java | `PascalCase.java` | `PascalCase` | `camelCase` | | SQL | `NNN_<描述>.sql`（migration） | — | — | | 測試 | `<被測檔名>.spec.ts` | — | — | --- ## 5. 版本與狀態規則 | 版本 | 時機 | |---|---| | `0.x` | 草稿，尚未經審查 | | `1.0` | 首次核定（Baseline） | | `1.x` | 核定後之修訂（不改變對外承諾） | | `2.0` | 改變對外承諾（API 破壞性變更、範圍變更） | 文件狀態流轉：`草稿 → 審查中 → 已核定`（可退回 `草稿`）。 **程式撰寫階段不得引用「草稿」狀態的設計文件**。 --- ## 6. 交付物清冊 ### 6.1 治理類（`docs/00-governance/`） | 編號 | 文件名稱 | 產出角色 | 狀態 | |---|---|---|---| | GOV-001 | 交付物清冊與命名規範 | PM | 已核定 | | GOV-002 | 任務分派與 RACI | PM | 已核定 | | GOV-003 | 開發流程與品質關卡 | PM / QA Lead | 已核定 | | GOV-004 | 需求追溯矩陣（RTM） | BA | 已核定 | ### 6.2 業務需求類（`docs/01-brd/`） | 編號 | 文件名稱 | 產出角色 | 狀態 | |---|---|---|---| | BRD-001 | 業務需求規格書 | BA | 已核定 | | BRD-002 | FR 功能需求追蹤清單 | BA | 已核定 | | BRD-003 | NFR 非功能需求追蹤清單 | BA / SA | 已核定 | | BRD-004 | POC 驗收情境清單 | BA / QA | 已核定 | ### 6.3 系統架構類（`docs/02-sad/`） | 編號 | 文件名稱 | 產出角色 | 狀態 | |---|---|---|---| | SAD-001 | 系統架構總覽 | SA | 已核定 | | SAD-002 | 微服務劃分與 DDD 邊界 | SA | 已核定 | | SAD-003 | 資料架構與 CQRS | SA / DA | 已核定 | | SAD-004 | 整合架構與 API 治理 | SA | 已核定 | | SAD-005 | 安全架構與個資保護 | Security Architect | 已核定 | | SAD-006 | 部署架構與可觀測性 | SA / SRE | 已核定 | ### 6.4 系統設計類（`docs/03-sdd/`） | 編號 | 文件名稱 | 產出角色 | 狀態 | |---|---|---|---| | SDD-000 | 設計總覽與通用規範 | SD | 已核定 | | SDD-001 | 領域模型與 ER-Diagram | SD / DA | 已核定 | | SDD-002 | DFD 與流程分解 | SD | 已核定 | | SDD-003 | Sequence Diagrams | SD | 已核定 | | SDD-004 | Conflict Handling 與一致性設計 | SD / SA | 已核定 | | SDD-005 | 狀態機設計 | SD | 已核定 | | SDD-006 | API Contract | SD | 已核定 | | SDD-007 | WebUI 設計規範 | SD / UX | 已核定 | ### 6.5 程式規範類（`docs/04-coding-spec/`） | 編號 | 文件名稱 | 產出角色 | 狀態 | |---|---|---|---| | CSP-001 | Coding Standard | Tech Lead | 已核定 | | CSP-002 | 專案骨架與模組結構 | Tech Lead | 已核定 | | CSP-003 | 錯誤處理與回應碼規範 | Tech Lead | 已核定 | | CSP-004 | 可觀測性與日誌規範 | SRE / Tech Lead | 已核定 | | CSP-005 | 單元測試與品質規範 | QA Lead | 已核定 | ### 6.6 測試類（`docs/05-test/`） | 編號 | 文件名稱 | 產出角色 | 狀態 | |---|---|---|---| | TRP-001 | 測試計畫與准入准出標準 | QA Lead | 已核定 | | TRP-002 | NFR 驗證計畫 | QA Lead | ★ **`#A-159` 產出**（2026-10-02） | | TRP-003 | 覆蓋率提升計畫 | QA Lead | ★ **`#A-166` 起產出**（v2.9） | | TRP-004 | 覆蓋率提升總結報告 | QA Lead | ★ **`#A-204` 產出**（v1.0，2026-10-06） | | TRR-001 | 單元測試報告 | Tester / TestBOT | 程式階段產出 | | TRR-002 | 缺陷追蹤表 | QA | 程式階段產出 | --- ### 6.9 實測證據類（`docs/08-evidence/`） **性質**：實測過程之截圖／錄檔，用以**證明功能確實可運作**， 非裝飾性附件——客戶驗收與 POC 答詢時直接引用。 > ⚠️ **本表於 2026-09-30 更正**（`HANDOVER #A-105`）——原表僅列 **3 組 10 張**， > 與目錄**實有 40 張**不符。**逐張之索引以 `docs/08-evidence/README.md` 為準** > （`§6.9` 要求 1「索引必備」）；本表僅列**組別彙總**。 | 來源 | 張數 | 對應頁面 | 對應規格 | |---|---:|---|---| | `webui-applications` | 5 | 進件作業台 | `SCS-024 §11.2`／`SDD-007 §5.4.9` | | `webui-installments` | 8 | 分期作業台 | `SCS-009`（含 `CR-008` 雙軸） | | `webui-rewards` | 4 | 紅利點數作業台 | `SCS-010` | | `webui-clearing` | 1 | 清算與請款 | `SCS-013` | | `webui-dispute` | 1 | 爭議款處理 | `SCS-012` | | `webui-cr020` | 3 | 卡片生命週期（`CR-020` 解鎖後） | `CR-020`／`SCS-003` | | `webui-lifecycle` | 2 | 卡片生命週期管理 | `SCS-003` | | `webui-limit` | 2 | 額度控管 | `SCS-002` | | `webui-merchant` | 1 | 商店管理與請款 | `SCS-014` | | `webui-migration` | 2 | 資料遷移作業 | `SCS-015` | | `webui-parameters` | 1 | 參數設定 | `SCS-005` | | `webui-policy` | 1 | 授權策略檢核 | `SCS-001` | | `webui-product` | 1 | 產品與費率設定 | `SCS-005` | | `webui-reports` | 1 | 報表作業 | `SCS-017` | | `webui-reversal` | 2 | 沖正機制 | `SCS-001` | | `webui-token` | 2 | 虛擬卡與 Token 管理 | `SCS-003` | | `A-99` | 1 | 離線授權與代授權 | `SCS-001`／`CR-022` | | `A-101` | 1 | 健康檢查與監控 | `SCS-020 §9.8` | | `A-102` | 1 | 稽核軌跡查詢 | `SCS-001 §7.9`／`CR-025` | | **合計** | **40** | | | > ⭐ **代表性命中**：`webui-applications-03`（徵審未接上時顯示「轉人工核決」而非核准） > 為 **fail-closed 之畫面證明**——POC 被問「徵審沒接上會不會偷核准」時的直接佐證。 **管理要求（系統性）**： 1. **索引必備**：目錄下須有 `README.md`（清冊），逐張列 「檔名／對應規格章節／產生方式／日期／證明之結論」。 **無索引者視同未納管**，Code Review 應退件。 2. **一證一結論**：每張證據須能說明「證明什麼」； 無法對應到任何規格章節或驗收情境者，不得放入。 3. **禁含個資**：截圖前須確認畫面無真實卡號／身分證／手機 （測試資料亦應遮蔽，見 `CSP-004 §4`）。 4. **版本隨規格**：證據所屬規格升版且畫面行為改變時， **須重截並更新索引**，不得留存與現行規格不符之舊證據。 5. **命名依 §3.4**，流水號**不跳號**。 --- ## 7. 需求追溯鏈 所有交付物必須可回溯到需求，鏈路固定為： ```mermaid flowchart LR A["FR / NFR / POC
（客戶需求）"] --> B["BRD-002/003/004
需求追蹤清單"] B --> C["SAD-002
服務邊界"] C --> D["SDD-001~006
設計規格"] D --> E["CSP-001~005
程式規範"] E --> F["backend / frontend
程式碼"] F --> G["TRR-001
單元測試報告"] G --> H["BRD-004
POC 驗收情境"] H --> I["GOV-004
RTM 三向追溯"] ``` **追溯規則**：任一 `FR` 必須能回答四個問題—— ① 由哪個服務承作？② 在哪份設計文件被定義？③ 由哪支 API 實作？④ 由哪個測試案例驗證？ 答不出來的需求，不得進入程式撰寫階段。 --- ## 8. 修訂記錄 | 版本 | 日期 | 修訂者 | 說明 | |---|---|---|---| | **1.2** | 2026-09-30 | WorkBuddy AI | **§6.9 證據清冊更正（`HANDOVER #A-105`）**——⚠️ 原表僅列 **3 組 10 張**，與 `docs/08-evidence/` **實有 40 張（19 組）**不符（違反本節要求 4「版本隨規格」）。本版改列**組別彙總 19 列**，並明訂**逐張索引以 `docs/08-evidence/README.md` 為準**（該索引亦已於同日重建）。**併載教訓**：證據「產出時」即須同輪更新索引，不得事後補（本目錄曾累積 30 張未登錄） | | 1.0 | 2026-09-17 | PM | 初版 | | 1.1 | 2026-09-20 | WorkBuddy AI | **將 `docs/08-evidence/` 正式納入交付物管制（BEAM PMO 2026-09-20 裁定「要，且要有系統性管理」）**：①§2 補全目錄結構——原只列至 `05-test/`，實物已另有 `05-change-requests`／`06-test`／`07-scs`／`08-evidence`（**文件與實物不符**）；②新增 **§3.4 證據檔命名規範**（`<來源>--<簡述>`，2 碼流水不跳號，簡述須能直接看出結論）；③新增 **§6.9 實測證據類**，載明 10 張現有證據之對應規格與證明結論，並立五項管理要求：**索引必備（無索引視同未納管）／一證一結論／禁含個資／版本隨規格（行為改變須重截）／命名依 §3.4** | --- ## 8. 本規範之檢查方式 | 檢查項 | 方法 | 通過標準 | |---|---|---| | 檔名合規 | 以正則掃描 `docs/**/*.md` | 100% 符合 `-_<標題>.md` | | 編號連續 | 同 TYPE 之 NNN 排序 | 由 001 起連續、無跳號 | | 文件表頭 | 檢查每份文件首個表格含 6 個必要欄位 | 100% 具備 | | Mermaid 語法 | 逐區塊解析 | 0 語法錯誤 | | 禁止字樣 | 掃描檔名 | 0 筆 |