架構決策紀錄範本(ADR, Architecture Decision Record Template)

架構決策紀錄範本(Architecture Decision Record, ADR) 參照標準:MADR 4.0.0(Markdown Architectural Decision Records)/ ISO/IEC/IEEE 42010:2022 文件用途:記錄一個重要技術決策的背景、考慮過的選項、取捨與後果 適用階段:系統設計階段(Design Phase)起,貫穿整個生命週期 範本版本:v2.0(2026-10-06)|對應《軟體開發標準程序教學手冊》v2.0 第 4.6 節 📋 章節目錄 何時必須寫 ADR 檔案命名與存放 ADR 主體(MADR 格式) 狀態與生命週期 審查與驗證 1. 何時必須寫 ADR 📝 範本 情境 是否必須寫 ADR 本案判定 選用或更換框架、資料庫、訊息系統 必須 {是/否} 改變系統間的整合方式(同步改非同步、新增閘道) 必須 {是/否} 偏離公司標準或《軟體開發標準程序教學手冊》 必須 {是/否} 難以反悔(回頭成本高)的決策 必須 {是/否} 只影響單一類別的實作細節 不需要 {是/否} 📖 使用說明 ADR 是「決策的快照」,回答半年後有人問「為什麼當初這樣做?」 判斷原則:如果這個決策錯了,修正成本是否超過一個 Sprint?是 → 寫 ADR ADR 要短(一到兩頁),長篇設計放在 SDD,ADR 只記錄決策本身 💡 範例 情境 是否必須寫 ADR 本案判定 請假事件通知由同步 REST 改為 Kafka 事件 必須 是 → ADR-0007 請假服務的 DTO 改用 Java record 不需要 否(屬《程式寫作指引》範圍) 2. 檔案命名與存放 📝 範本 docs/decisions/ ├── 0001-{決策標題-kebab-case}.md ├── 0002-{決策標題}.md └── README.md # ADR 索引:編號、標題、狀態、日期 📖 使用說明 ADR 與程式碼放在同一個 Repository,走同一個 PR 審查流程(Docs-as-Code) 編號遞增、不重用;標題用動詞開頭描述決策(例:「採用 Kafka 作為訂單事件骨幹」) 索引檔讓新人快速找到所有決策 💡 範例 docs/decisions/ ├── 0001-use-postgresql-as-primary-database.md ├── 0006-adopt-rfc9457-problem-details.md ├── 0007-use-kafka-for-leave-events.md └── README.md 3. ADR 主體(MADR 格式) 📝 範本 --- status: {proposed | accepted | rejected | deprecated | superseded by NNNN} date: {YYYY-MM-DD} decision-makers: {決策者姓名與角色} consulted: {諮詢對象} informed: {知會對象} --- # {NNNN} {決策標題} ## Context and Problem Statement {兩到三句描述背景與要解決的問題;可附事件編號、數據} ## Decision Drivers * {驅動因素 1,例:下游故障不得影響主流程} * {驅動因素 2,例:尖峰 N 筆/秒} ## Considered Options * {選項 1} * {選項 2} * {選項 3(含「維持現狀」)} ## Decision Outcome 選擇「{選項}」,因為 {對照 Decision Drivers 說明理由}。 ### Consequences * Good:{正面影響} * Bad:{負面影響與需要處理的新問題} ### Confirmation {如何確認決策被正確實作,例:整合測試、ArchUnit 規則、上線後監控指標} ## Pros and Cons of the Options ### {選項 2} * Good:{優點} * Bad:{缺點} 📖 使用說明 必填段落:Context、Considered Options(至少兩個,含「維持現狀」)、Decision Outcome、Consequences Bad 後果必須寫:沒有缺點的決策通常代表分析不完整 Confirmation 段落讓決策可驗證,例如用 ArchUnit 測試確保「訂單服務不得直接呼叫點數服務」 引用的效能數據、事件編號需可查證 💡 範例 --- status: accepted date: 2026-09-20 decision-makers: 架構師 林志明、Tech Lead 陳大文 consulted: DBA 王小美、資安 李小華 informed: HRMS 開發團隊 --- # 0007 請假事件改用 Kafka 通知下游 ## Context and Problem Statement 請假核准後需通知薪資、出勤、Email 三個服務。目前以同步 REST 呼叫, 2026 Q3 薪資服務維護期間造成請假核准失敗 3 次(INC-20260712-002)。 ## Decision Drivers * 下游服務故障不得影響請假核准 * 事件需可重播 7 天,以便薪資重算 * 維運團隊已有 Kafka 叢集與維運經驗 ## Considered Options * Apache Kafka * RabbitMQ * 維持同步 REST + 重試 ## Decision Outcome 選擇 Apache Kafka,因為它是唯一同時滿足「下游故障不影響核准」與「事件可重播 7 天」的選項,且不需新增維運技能。 ### Consequences * Good:下游故障不再影響核准;新服務可自行訂閱事件 * Bad:事件可能重複投遞,消費端必須冪等;需監控 consumer lag ### Confirmation 整合測試驗證「薪資服務停止時仍可核准請假」;上線後監控 consumer lag < 1,000。 ## Pros and Cons of the Options ### RabbitMQ * Good:團隊熟悉 AMQP 路由 * Bad:訊息消費後即刪除,不支援 7 天重播 ### 維持同步 REST + 重試 * Good:不需新元件 * Bad:重試會延長核准回應時間,且下游長時間故障時仍會失敗 4. 狀態與生命週期 📝 範本 stateDiagram-v2 [*] --> proposed: 提出 proposed --> accepted: 審查通過 proposed --> rejected: 審查否決 accepted --> deprecated: 不再適用 accepted --> superseded: 被新 ADR 取代 rejected --> [*] deprecated --> [*] superseded --> [*] 📖 使用說明 ADR 一經 accepted 就不修改內容(錯字除外);決策改變時新增一份 ADR,舊 ADR 的 status 改為 superseded by NNNN rejected 的 ADR 也要保留,避免同樣的提案反覆討論 💡 範例 編號 標題 狀態 日期 0003 請假通知使用同步 REST superseded by 0007 2025-11-02 0007 請假事件改用 Kafka 通知下游 accepted 2026-09-20 5. 審查與驗證 本節供審查者使用,也用來檢查 AI 依本範本產出的 ADR 是否正確。 ...

October 6, 2026 · 3 min · 492 words · Eric Cheng

資料分級對照表範本(Data Classification Template)

資料分級對照表範本(Data Classification) 參照標準:OWASP ASVS 5.0.0 V14(Data Protection)/ ISO/IEC 27001:2022 A.5.12(資訊分類)/ 個人資料保護法 文件用途:為每個資料欄位標註分級,作為加密、遮罩、日誌、測試資料與保存期限的唯一依據 適用階段:系統設計階段(Design Phase);Schema 變更時同步更新 範本版本:v2.0(2026-10-06)|對應《軟體開發標準程序教學手冊》v2.0 第 4.4、6.3、9.3 節 📋 章節目錄 分級定義 各級保護要求 欄位分級對照表 保存與銷毀 審查與驗證 1. 分級定義 📝 範本 等級 定義 外洩影響 典型資料 公開 {可對外公開} {無} {產品型錄} 內部 {限公司內部} {輕微} {組織架構} 機密 {限特定角色} {重大:個資、營業秘密} {姓名、Email、薪資} 極機密 {限極少數人,需加密} {嚴重:可直接造成詐騙或法律責任} {身分證字號、銀行帳號、密碼雜湊} 📖 使用說明 分級由資料擁有者(業務單位)核定,IT 負責實作保護 同時屬於多種類別時取最高等級 對應 ASVS 5.0 14.1.1(敏感資料識別與分級) 💡 範例 等級 定義 外洩影響 典型資料 公開 可公開於官網 無 公司地址、職缺 內部 全體員工可見 輕微 部門名稱、分機 機密 限本人、主管與 HR 重大(個資) 姓名、Email、手機、請假紀錄、薪資 極機密 限 HR 薪資組,需加密 嚴重 身分證字號、銀行帳號 2. 各級保護要求 📝 範本 要求 公開 內部 機密 極機密 儲存加密 {} {} {} {} 傳輸加密 {} {} {} {} 畫面顯示 {} {} {} {} 日誌 {} {} {} {} 測試環境 {} {} {} {} 存取紀錄 {} {} {} {} 📖 使用說明 對應 ASVS 5.0 14.1.2:每個等級都要有一組文件化的保護要求 這張表是開發、測試、維運共同的規格:AI 或開發者產生程式時,可直接依此判斷要不要遮罩、能不能寫日誌 💡 範例 要求 公開 內部 機密 極機密 儲存加密 不需 不需 資料庫 TDE TDE + 欄位加密(AES-256-GCM,金鑰存 KMS) 傳輸加密 TLS 1.2+ TLS 1.2+ TLS 1.2+ TLS 1.2+,內部服務間 mTLS 畫面顯示 完整 完整 依權限完整或遮罩 預設遮罩,需「顯示」權限並留紀錄 日誌 可記錄 可記錄 遮罩後記錄 禁止記錄 測試環境 可沿用 可沿用 以假資料替換 以假資料替換 存取紀錄 不需 不需 匯出時記錄 每次讀取都記錄 3. 欄位分級對照表 📝 範本 資料表.欄位 分級 個資類別 儲存 畫面顯示 日誌 測試環境 保存期限 {TABLE.COLUMN} {等級} {是/否:類別} {明文/加密} {遮罩規則} {禁止/遮罩/可} {替換/沿用} {期限與法源} 📖 使用說明 每個欄位都要列,包含「看起來不敏感」的欄位(例如備註欄常被填入個資) 遮罩規則寫成具體格式(例:A12****789),方便直接轉成測試案例 Schema 新增欄位時,PR 必須同時更新本表(Reviewer 檢查) 💡 範例 資料表.欄位 分級 個資類別 儲存 畫面顯示 日誌 測試環境 保存期限 EMPLOYEE.NAME 機密 是:識別類 明文 王○明 禁止 替換 離職後 5 年 EMPLOYEE.ID_NO 極機密 是:識別類 欄位加密 A12****789 禁止 替換 離職後 5 年 EMPLOYEE.BANK_ACCOUNT 極機密 是:財務類 欄位加密 ****-****-1234 禁止 替換 離職後 5 年 EMPLOYEE.EMAIL 機密 是:聯絡類 明文 a***@company.com 遮罩 替換 離職後 2 年 LEAVE_REQUEST.REASON 機密 可能(病假事由) 明文 本人與主管可見 禁止 替換 依勞動法規 DEPARTMENT.NAME 內部 否 明文 完整 可 沿用 永久 4. 保存與銷毀 📝 範本 資料類別 保存期限 法源/依據 到期處理方式 執行方式 {類別} {期限} {法規條號/合約} {刪除/去識別化/封存} {批次程式/人工} 📖 使用說明 保存期限必須寫出法源,並由法遵單位確認 到期處理應自動化並留紀錄(ASVS 5.0 14.2.7) 💡 範例 資料類別 保存期限 法源/依據 到期處理方式 執行方式 員工個資 離職後 5 年 公司人事規章(法遵確認 2026-09) 去識別化 每月批次 BATCH-HR-PURGE-001 稽核日誌 365 天 公司資安政策 v4.0 刪除 日誌平台 ILM 政策 5. 審查與驗證 本節供審查者使用,也用來檢查 AI 依本範本產出的分級表是否正確。 ...

October 6, 2026 · 2 min · 358 words · Eric Cheng