CR #201 » GOV-001_交付物清冊與命名規範.md
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 檔名格式
<TYPE>-<NNN>_<中文標題>.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/）
<來源>-<NN>-<簡述>.<ext>
| 欄位 | 規則 | 範例 |
|---|---|---|
<來源> |
頁面／功能之英文識別，小寫、以 - 連接 |
webui-applications |
<NN> |
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 文件內部必要欄位
每份文件開頭必須有下列表格（缺一不可，供追溯與版控）：
| 項目 | 內容 |
|---|---|
| 文件編號 | SDD-006 |
| 版本 | 1.0 |
| 狀態 | 草稿 / 審查中 / 已核定 |
| 撰寫者 | <角色> |
| 審查者 | <角色> |
| 對應需求 | FR 1.1、FR 1.2（可留空） |
4. 程式命名規範
4.1 微服務命名
<bounded-context>-service # kebab-case、單數名詞
範例：authorization-service、card-service、posting-service、limit-service
-
不使用
ms-、svc-前綴（冗餘）。 - 一個 bounded context 只對應一個服務，不得一名多服務或一服務多名。
- 服務目錄內固定結構見
CSP-002。
4.2 API 路徑
/api/v1/<resource-plural> # 資源複數、kebab-case
/api/v1/<resource-plural>/{id}/<sub-resource>
範例：/api/v1/cards/{cardId}/limits、/api/v1/authorizations
- 動詞不入路徑；狀態轉換以子資源或動作子路徑表達，例如
POST /api/v1/cards/{cardId}/lifecycle-transitions。 - 版本只在大版變動時升（
v1→v2），欄位新增不升版。
4.3 資料庫命名
<schema>.<table> # schema = bounded context 名（snake_case）
- 表名：複數、snake_case，例如
authorization.authorizations、card.cards。 - 欄位：
snake_case；主鍵一律id；外鍵<entity>_id。 - 時間欄位：
*_at（timestamptz）、日期欄位*_date（date）。 - 金額欄位：
<name>_amount+ 幣別欄位<name>_currency；金額一律整數最小單位（分），
禁止使用浮點數。 - 布林欄位：
is_*/has_*。
4.4 領域事件命名
<context>.<aggregate>.<past-tense-verb>.v<major>
範例：posting.transaction.posted.v1、limit.hold.created.v1、
card.card.status-changed.v1
- 事件名稱使用過去式（事件是既成事實）。
- 事件 payload 只增不減；破壞性變更須升
v2並雙軌發布至少一個 release。
4.5 錯誤碼命名
CC-<SERVICE>-<NNN>
-
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 被問「徵審沒接上會不會偷核准」時的直接佐證。
管理要求（系統性）：
-
索引必備：目錄下須有
README.md（清冊），逐張列
「檔名／對應規格章節／產生方式／日期／證明之結論」。
無索引者視同未納管，Code Review 應退件。 -
一證一結論：每張證據須能說明「證明什麼」；
無法對應到任何規格章節或驗收情境者，不得放入。 -
禁含個資：截圖前須確認畫面無真實卡號／身分證／手機
（測試資料亦應遮蔽，見CSP-004 §4）。 -
版本隨規格：證據所屬規格升版且畫面行為改變時，
須重截並更新索引，不得留存與現行規格不符之舊證據。 - 命名依 §3.4，流水號不跳號。
7. 需求追溯鏈
所有交付物必須可回溯到需求，鏈路固定為：
flowchart LR
A["FR / NFR / POC<br/>（客戶需求）"] --> B["BRD-002/003/004<br/>需求追蹤清單"]
B --> C["SAD-002<br/>服務邊界"]
C --> D["SDD-001~006<br/>設計規格"]
D --> E["CSP-001~005<br/>程式規範"]
E --> F["backend / frontend<br/>程式碼"]
F --> G["TRR-001<br/>單元測試報告"]
G --> H["BRD-004<br/>POC 驗收情境"]
H --> I["GOV-004<br/>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 證據檔命名規範（<來源>-<NN>-<簡述>，2 碼流水不跳號，簡述須能直接看出結論）；③新增 §6.9 實測證據類，載明 10 張現有證據之對應規格與證明結論，並立五項管理要求：索引必備（無索引視同未納管）／一證一結論／禁含個資／版本隨規格（行為改變須重截）／命名依 §3.4
|
8. 本規範之檢查方式
| 檢查項 | 方法 | 通過標準 |
|---|---|---|
| 檔名合規 | 以正則掃描 docs/**/*.md
|
100% 符合 <TYPE>-<NNN>_<標題>.md
|
| 編號連續 | 同 TYPE 之 NNN 排序 | 由 001 起連續、無跳號 |
| 文件表頭 | 檢查每份文件首個表格含 6 個必要欄位 | 100% 具備 |
| Mermaid 語法 | 逐區塊解析 | 0 語法錯誤 |
| 禁止字樣 | 掃描檔名 | 0 筆 |