SDD(系統設計文件|System Design Document)範本

範本版本:v2.0(2026-10-06)|對應《軟體開發標準程序教學手冊》v2.0 第 4.1–4.8 節

參照標準:ISO/IEC/IEEE 42010:2022、ISO/IEC 25010:2023、ISO/IEC/IEEE 15288:2023

適用對象:系統架構師、資深開發工程師、技術主管

文件性質:系統技術架構與設計決策文件


📑 章節目錄

  1. 文件資訊
  2. 系統概述
  3. 系統架構
  4. 模組劃分(Module Decomposition)
  5. 資料庫綱要設計(Database Schema)
  6. API 介面規格(API Specification)
  7. 資安規範(Security Design)
  8. 非功能性設計
  9. 整合設計(Integration Design)
  10. 錯誤處理與容錯設計
  11. 可觀測性設計(Observability)
  12. 設計決策記錄(ADR)
  13. 審查與驗證

📋 使用說明

SDD 用於制定技術解決方案,規劃「系統要如何實作」。內容涵蓋系統架構、資料庫綱要(Schema)、API 介面規格、模組劃分與資安規範,確保系統具備擴展性與穩定性。

何時使用本範本

  • 系統設計階段,將需求(PRD/FRD/SRD)轉化為技術方案
  • 重大架構變更前的設計評審
  • 跨團隊技術溝通的基準文件

與其他文件的關係

PRD(做什麼) → SDD(如何設計) → TSD(如何實作)
     ↑                ↑                ↑
   產品經理          架構師           開發工程師

填寫原則

  1. 決策可追溯:每個設計決策需記錄原因與替代方案
  2. 圖文並茂:架構圖、序列圖、ER 圖等應完整呈現
  3. 安全優先:每個模組需考慮資安面向
  4. 可演進:設計應預留擴展空間

📄 範本正文


[系統/模組名稱] 系統設計文件(SDD)

1. 文件資訊

項目內容
文件編號SDD-[專案代碼]-[序號]
版本v0.1
建立日期YYYY-MM-DD
最後更新YYYY-MM-DD
撰寫者[架構師姓名]
審核者[審核者姓名 / 角色]
核准者[核准者姓名 / 角色]
狀態草稿 / 審查中 / 已核准

版本歷程

版本日期修改人修改內容摘要
v0.1YYYY-MM-DD[姓名]初版建立

審核紀錄

審核者角色審核日期結果備註
通過 / 有條件通過 / 退回

關聯文件

文件名稱文件編號版本關聯性
產品需求文件(PRD)PRD-XXX-001v1.0需求來源
功能需求文件(FRD)FRD-XXX-001v1.0功能規格
系統需求規格書(SRD)SRD-XXX-001v1.0系統規格

2. 系統概述

2.1 系統背景與目標

簡述本系統的業務背景、核心問題,以及本設計文件欲達成的技術目標。

系統名稱:[系統名稱]
系統簡述:[一段話描述系統用途]
設計目標:

  1. [技術目標 1,例:支援每秒 1,000 筆交易處理]
  2. [技術目標 2,例:系統可用率 ≥ 99.99%]
  3. [技術目標 3,例:水平擴展能力,支援 10 倍流量成長]

2.2 設計約束

約束類型描述影響範圍
技術約束例:須使用企業標準技術棧(Java 21/25 + Spring Boot 4.x)開發框架選型
合規約束例:須符合 PCI DSS 及個資法要求資料處理與儲存
基礎設施約束例:部署於企業私有雲 Kubernetes 環境部署架構
整合約束例:須整合現有 SAP ERP 系統介面設計
效能約束例:回應時間 95th percentile < 200ms架構與技術選型

2.3 利害關係人與關注面向

利害關係人角色主要關注面向
業務部門產品擁有者功能完整性、使用體驗
維運團隊SRE可觀測性、自動化部署
資安團隊資安官資安合規、弱點管理
開發團隊工程師可維護性、開發效率
DBA資料庫管理資料一致性、效能

3. 系統架構

3.1 架構風格

說明選用的架構風格與理由。

選用架構:[微服務架構 / 單體架構 / 模組化單體 / 事件驅動架構 / …]

選型理由:

評估面向替代方案 A替代方案 B選定方案
開發複雜度低高中
擴展能力低高高
維運成本低高中
團隊熟悉度高低中
綜合評分✅

3.2 系統架構圖(System Architecture Diagram)

繪製系統整體架構圖,展示各元件之間的關係。

[提供架構圖,建議使用 Mermaid、C4 Model 或 draw.io]

範例(C4 Context Diagram):

┌──────────────────────────────────────────────┐
│              [System Name]                    │
│                                               │
│  ┌─────────┐  ┌──────────┐  ┌────────────┐  │
│  │ Web App │  │ API GW   │  │ Admin App  │  │
│  └────┬────┘  └────┬─────┘  └─────┬──────┘  │
│       │            │              │          │
│  ┌────▼────────────▼──────────────▼──────┐   │
│  │         Backend Services              │   │
│  │  ┌──────┐ ┌──────┐ ┌──────────────┐  │   │
│  │  │User  │ │Order │ │Notification  │  │   │
│  │  │Svc   │ │Svc   │ │Service       │  │   │
│  │  └──┬───┘ └──┬───┘ └──────┬───────┘  │   │
│  └─────┼────────┼────────────┼───────────┘   │
│        │        │            │               │
│  ┌─────▼────────▼────────────▼───────────┐   │
│  │         Data Layer                    │   │
│  │  ┌──────┐ ┌──────┐ ┌──────────────┐  │   │
│  │  │RDB   │ │Redis │ │Message Queue │  │   │
│  │  └──────┘ └──────┘ └──────────────┘  │   │
│  └───────────────────────────────────────┘   │
└──────────────────────────────────────────────┘

3.3 部署架構圖(Deployment Diagram)

繪製實際部署拓撲,包含網路區段、伺服器規格、叢集配置。

環境配置用途
開發環境(DEV)單節點開發測試
測試環境(SIT)雙節點整合測試
預生產環境(UAT)與 PRD 同規格使用者驗收
生產環境(PRD)多節點叢集、HA 配置正式服務

3.4 技術棧(Technology Stack)

層級技術選型版本選型理由
前端React / Vue.js18.x / 3.x元件化、生態系成熟
後端Java + Spring Boot21 + 3.4.x企業標準、效能穩定
API GatewayKong / Spring Cloud Gateway3.x流量控制、認證整合
資料庫PostgreSQL16.xACID、JSONB 支援
快取Redis7.x高效能、叢集支援
訊息佇列Apache Kafka3.7.x高吞吐、事件溯源
容器編排Kubernetes1.30.x自動擴展、自癒
CI/CDGitHub Actions / GitLab CI—自動化建置部署
監控Prometheus + Grafana—指標收集與視覺化
日誌ELK Stack8.x集中式日誌管理

4. 模組劃分(Module Decomposition)

4.1 模組清單

模組編號模組名稱職責描述負責團隊
M-001使用者管理模組使用者註冊、登入、權限管理帳戶團隊
M-002訂單處理模組訂單建立、狀態管理、取消交易團隊
M-003通知服務模組Email、SMS、推播通知平台團隊
M-004報表分析模組資料統計、報表產出數據團隊

4.2 模組依賴關係

[使用依賴關係圖呈現各模組之間的依賴]

M-002(訂單) ──依賴──► M-001(使用者)
M-003(通知) ◄──被調用── M-002(訂單)
M-004(報表) ──讀取──► M-001, M-002

4.3 模組詳細設計

M-001:使用者管理模組

職責:

  • 使用者註冊與身分驗證
  • 角色與權限管理(RBAC)
  • 個人資料維護

對外介面:

API方法描述
/api/v1/usersPOST建立使用者
/api/v1/users/{id}GET查詢使用者
/api/v1/auth/loginPOST登入驗證
/api/v1/auth/token/refreshPOSTToken 續期

內部類別結構:

user-service/
├── controller/
│   ├── UserController
│   └── AuthController
├── service/
│   ├── UserService
│   ├── AuthService
│   └── RoleService
├── repository/
│   ├── UserRepository
│   └── RoleRepository
├── domain/
│   ├── User
│   ├── Role
│   └── Permission
└── config/
    └── SecurityConfig

5. 資料庫綱要設計(Database Schema)

5.1 資料庫選型與策略

決策選擇理由
主要資料庫PostgreSQL 16ACID 事務、JSONB 支援、擴充性
快取層Redis 7.x低延遲讀取、Session 管理
搜尋引擎Elasticsearch 8.x全文搜尋、日誌分析
資料分割策略依租戶分表資料隔離、效能保障

5.2 實體關聯圖(ER Diagram)

[使用 ER 圖工具或 Mermaid 繪製]

範例:
┌─────────────┐       ┌─────────────────┐
│   USERS     │       │  USER_ROLES     │
├─────────────┤       ├─────────────────┤
│ PK user_id  │──────►│ FK user_id      │
│ username    │       │ FK role_id      │
│ email       │       │ assigned_at     │
│ password    │       └────────┬────────┘
│ status      │                │
│ created_at  │       ┌────────▼────────┐
│ updated_at  │       │    ROLES        │
└─────────────┘       ├─────────────────┤
                      │ PK role_id      │
                      │ role_name       │
                      │ description     │
                      └─────────────────┘

5.3 資料表設計

USERS 資料表

欄位名稱資料型別空值預設值說明
user_idBIGSERIALNOT NULLAUTO主鍵
usernameVARCHAR(50)NOT NULL—使用者帳號
emailVARCHAR(254)NOT NULL—電子郵件(唯一)
password_hashVARCHAR(256)NOT NULL—密碼雜湊值(Argon2id,含演算法前綴,例 {argon2}$argon2id$...)
display_nameVARCHAR(100)NULL—顯示名稱
statusVARCHAR(20)NOT NULL‘ACTIVE’帳號狀態
last_login_atTIMESTAMPTZNULL—最後登入時間
created_atTIMESTAMPTZNOT NULLNOW()建立時間
updated_atTIMESTAMPTZNULL—更新時間
created_byVARCHAR(50)NOT NULL—建立者
updated_byVARCHAR(50)NULL—更新者

索引設計:

索引名稱索引欄位類型用途
PK_USERSuser_idPRIMARY KEY主鍵查詢
UQ_USERS_EMAILemailUNIQUE避免重複 Email
IDX_USERS_STATUSstatusB-TREE狀態篩選

5.4 資料遷移策略

策略項目說明
遷移工具Flyway / Liquibase
命名規範V{版本}{日期}{描述}.sql
回滾策略每個遷移腳本需附帶回滾 SQL
資料量評估預估各表資料量,決定是否需分區

6. API 介面規格(API Specification)

6.1 API 設計原則

原則說明
RESTful 風格使用 HTTP Method 表達操作語意
版本控制URI 路徑版本(/api/v1/)
統一回應格式遵循標準 Response Envelope
分頁與篩選統一使用 page/size/sort 參數
冪等性PUT/DELETE 需具備冪等性

6.2 API 清單

API 路徑方法描述認證限流
/api/v1/usersGET查詢使用者清單Bearer Token100/min
/api/v1/usersPOST建立使用者Bearer Token10/min
/api/v1/users/{id}GET查詢單一使用者Bearer Token200/min
/api/v1/users/{id}PUT更新使用者Bearer Token20/min
/api/v1/users/{id}DELETE刪除使用者Bearer Token5/min
/api/v1/auth/loginPOST使用者登入無20/min

6.3 API 詳細規格

POST /api/v1/users

描述:建立新使用者

Request:

{
  "username": "john_doe",
  "email": "john@example.com",
  "password": "SecureP@ss123",
  "displayName": "John Doe"
}

Response(201 Created):

{
  "success": true,
  "code": "0000",
  "message": "使用者建立成功",
  "data": {
    "userId": 12345,
    "username": "john_doe",
    "email": "john@example.com",
    "displayName": "John Doe",
    "status": "PENDING_VERIFICATION",
    "createdAt": "2026-05-19T10:30:00Z"
  },
  "timestamp": "2026-05-19T10:30:00Z",
  "traceId": "abc123-def456"
}

Error Response(409 Conflict):

{
  "success": false,
  "code": "E2001",
  "message": "Email 已被使用",
  "errors": [
    {
      "field": "email",
      "message": "此 Email 已註冊,請使用其他 Email"
    }
  ],
  "timestamp": "2026-05-19T10:30:00Z",
  "traceId": "abc123-def456"
}

6.4 認證與授權設計

項目設計
認證協定OAuth 2.0 + OpenID Connect
Token 類型JWT (RS256)
Access Token 效期30 分鐘
Refresh Token 效期7 天
Token 儲存HttpOnly Secure Cookie
授權模式RBAC(Role-Based Access Control)

7. 資安規範(Security Design)

7.1 安全架構

安全層級防護措施參照標準
網路層WAF、DDoS 防護、網路區段隔離NIST SP 800-41
傳輸層TLS 1.2 以上(優先 TLS 1.3)、憑證管理NIST SP 800-52、OWASP ASVS 5.0 V12
應用層輸入驗證、CSRF/XSS 防護、API 限流OWASP ASVS v4.0.3
資料層加密儲存、存取控制、資料遮罩NIST SP 800-111
認證層MFA、Token 管理、Session 控制NIST SP 800-63B

7.2 威脅模型摘要

威脅STRIDE 類型風險等級緩解措施
SQL InjectionTampering高Parameterized Query、ORM
XSS 攻擊Spoofing高輸出編碼、CSP Header
未授權存取Elevation of Privilege高RBAC、API Gateway 驗證
資料外洩Information Disclosure高加密、存取日誌、DLP

7.3 敏感資料處理

資料類型分類處理方式
密碼極機密Argon2id 雜湊(m ≥ 19 MiB、t ≥ 2、p = 1,依 OWASP Password Storage Cheat Sheet;既有 bcrypt 可沿用並逐步升級)
個資(身分證、電話)機密AES-256-GCM 加密儲存
API Key / Secret極機密保險箱服務(Vault)
一般業務資料內部存取控制、稽核日誌

7.4 稽核日誌設計

日誌類型記錄內容保留期限
認證日誌登入/登出、驗證失敗1 年
授權日誌權限變更、存取拒絕1 年
資料異動日誌CRUD 操作、異動前後值依法規(3-7 年)
系統日誌錯誤、效能、健康檢查90 天

8. 非功能性設計

8.1 效能設計

指標目標值設計策略
API 回應時間P95 < 200ms快取、索引優化、非同步
吞吐量≥ 1,000 TPS水平擴展、連線池
資料庫查詢P95 < 50ms查詢優化、讀寫分離

8.2 高可用設計

元件HA 策略SLA 目標
應用服務多副本部署 + 負載平衡99.99%
資料庫主從複製 + 自動故障轉移99.99%
快取Redis Sentinel / Cluster99.95%
訊息佇列多 Broker 叢集99.99%

8.3 可擴展性設計

擴展面向策略觸發條件
水平擴展Kubernetes HPACPU > 70% or QPS > 閾值
資料庫擴展讀寫分離 → 分庫分表單表 > 5,000 萬筆
快取擴展Redis Cluster 增加節點記憶體 > 80%

9. 整合設計(Integration Design)

9.1 外部系統整合

外部系統整合方式協定資料格式說明
SSO 服務同步 APIOIDCJSON身分驗證
ERP 系統非同步 MQAMQPJSON訂單同步
金流服務同步 APIRESTJSON付款處理
通知服務非同步 MQKafkaJSON訊息推播

9.2 整合序列圖

[使用 Mermaid Sequence Diagram 呈現關鍵整合流程]

範例:使用者登入流程

Client → API GW: POST /auth/login
API GW → Auth Svc: 驗證憑證
Auth Svc → User DB: 查詢使用者
User DB → Auth Svc: 回傳使用者資料
Auth Svc → SSO: 驗證 Token
SSO → Auth Svc: 驗證結果
Auth Svc → API GW: JWT Token
API GW → Client: 登入成功 + Token

10. 錯誤處理與容錯設計

10.1 錯誤碼規範

錯誤碼範圍類別範例
0000成功操作成功
E1xxx認證/授權錯誤E1001:未認證
E2xxx業務邏輯錯誤E2001:資料重複
E3xxx資料驗證錯誤E3001:必填欄位缺失
E4xxx外部服務錯誤E4001:第三方服務逾時
E9xxx系統錯誤E9001:未預期錯誤

10.2 容錯模式

模式適用場景實作方式
Circuit Breaker外部服務調用Resilience4j CircuitBreaker
Retry暫態故障指數退避(Exponential Backoff)
Bulkhead資源隔離執行緒池隔離
Fallback服務降級預設值 / 快取資料
Timeout所有外部調用連線 5s、讀取 10s

11. 可觀測性設計(Observability)

11.1 監控指標

指標類型指標名稱告警閾值
RED 指標Request Rate異常波動 > 50%
RED 指標Error Rate> 1%
RED 指標Duration (P95)> 500ms
系統指標CPU Usage> 80%
系統指標Memory Usage> 85%
業務指標交易成功率< 99%

11.2 日誌規範

日誌等級使用情境範例
ERROR需要立即處理的錯誤資料庫連線失敗
WARN潛在問題,需關注重試成功、接近限流
INFO業務流程關鍵節點使用者登入、訂單建立
DEBUG開發除錯資訊方法入參、SQL 語句

11.3 分散式追蹤

項目設計
追蹤框架OpenTelemetry
Trace ID 傳遞HTTP Header(traceparent)
取樣率生產環境 10%、錯誤 100%
視覺化Jaeger / Grafana Tempo

12. 設計決策記錄(ADR)

ADR-001:資料庫選型

項目內容
狀態已接受
日期YYYY-MM-DD
決策者架構師團隊
背景系統需要 ACID 事務支援,同時需處理半結構化資料
決策選用 PostgreSQL 16 作為主資料庫
替代方案MySQL 8.x、MongoDB 7.x
理由1. JSONB 支援半結構化資料
2. 效能優於 MySQL
3. 擴展生態成熟
影響團隊需培訓 PostgreSQL 特有功能

13. 審查與驗證

本節供審查者使用,也用來檢查 AI 依本範本產出的文件是否正確;對應《軟體開發標準程序教學手冊》v2.0 各章的「審查與驗證」。

自動檢查

檢查項目方法
JSON 範例合法python -m json.tool 解析每個 JSON 區塊
API 規格可 lintOpenAPI 檔以 npx @stoplight/spectral-cli lint 檢查
Migration 可執行以 Testcontainers 啟動空資料庫執行 flyway migrate

人工審查問題

  1. 密碼儲存是否採 Argon2id(或有升級計畫的 bcrypt)?
  2. 錯誤處理是否採 RFC 9457 Problem Details?
  3. 資料庫 Schema 變更是否考慮新舊版本並存(Expand/Contract)?
  4. 可觀測性設計是否定義 SLI/SLO 與 traceId 傳遞方式?

AI 常見錯誤

  • 沿用 Spring Boot 3.x、bcrypt、TLS 1.3 only 等舊版或過於絕對的設定。
  • API 設計與 SDD 中的資料模型不一致。
  • 設計決策沒有記錄 ADR。

範例:電商系統 SDD 摘要

架構選型

  • 架構風格:微服務架構
  • 通訊方式:同步 REST + 非同步 Kafka
  • 服務網格:Istio

核心服務

服務技術棧資料庫
使用者服務Spring Boot 4.1PostgreSQL
訂單服務Spring Boot 4.1PostgreSQL + Redis
商品服務Spring Boot 4.1PostgreSQL + Elasticsearch
支付服務Spring Boot 4.1PostgreSQL
通知服務Spring Boot 4.1Redis

資安設計重點

  • API Gateway 統一認證(JWT + OAuth 2.0)
  • 敏感資料 AES-256-GCM 加密
  • 全面稽核日誌,保留 3 年

📌 填寫提醒

  1. SDD 應由架構師主導撰寫,與開發團隊、DBA、資安團隊協同審查
  2. 架構圖建議使用 C4 Model 分層呈現(Context → Container → Component)
  3. 每個設計決策需記錄 ADR(Architecture Decision Record)
  4. 完成後需安排正式的設計審查(Design Review)會議