universal-dev-standards 6.8.0 → 6.9.0

package/bundled/templates/requirement-document-template.md

@@ -0,0 +1,591 @@
+# 需求確認書格式規範
+
+**版本**: 1.0.1
+**建立日期**: 2025-01-13
+**適用專案**: All software projects | 所有軟體專案
+**文件類型**: 開發規範
+
+---
+
+## 一、文件目的
+
+本規範定義軟體專案的**需求確認書標準格式**,確保:
+
+1. **格式一致性** - 所有需求文件結構統一
+2. **內容完整性** - 涵蓋所有必要資訊
+3. **可執行性** - 包含足夠的實作細節
+4. **可追蹤性** - 版本控制與變更歷史清晰
+5. **客戶導向** - 便於客戶理解與確認
+
+## 二、何時使用此範本
+
+以下情況應建立需求確認書:
+
+- ✅ **新增重大功能** (預估工時 > 16 小時)
+- ✅ **架構變更** (影響多個模組或層級)
+- ✅ **外部 API 整合** (第三方服務或新 API 端點)
+- ✅ **效能優化專案** (需要演算法或架構調整)
+- ✅ **客戶需求確認** (需要正式文件與簽核)
+- ✅ **資料庫結構變更** (新增表、欄位或索引)
+
+以下情況可使用簡化文件:
+
+- ⚠️ **小型功能調整** (< 8 小時) - 可使用 Issue 或簡短技術文件
+- ⚠️ **Bug 修復** - 使用 Bug Report 格式
+- ⚠️ **文件更新** - 直接修改相關文件
+
+## 三、標準文件結構
+
+### 3.1 文件標頭 (必填)
+
+```markdown
+# [功能名稱] - 需求確認書
+
+**文件版本**: 1.0
+**建立日期**: YYYY-MM-DD
+**最後更新**: YYYY-MM-DD
+**專案名稱**: [YourProject]
+**功能名稱**: [英文功能名稱]
+```
+
+**說明**:
+- 文件標題使用繁體中文
+- 版本號遵循 SemVer (1.0 為初版)
+- 日期格式: YYYY-MM-DD
+
+---
+
+### 3.2 核心章節 (14 章 - 必填)
+
+#### 第一章: 功能概述
+
+**用途**: 簡要說明「為什麼」需要此功能、「做什麼」
+
+**必填內容**:
+- 1-2 段功能說明
+- 核心價值主張
+- 與現有系統的關係
+
+**範例**:
+```markdown
+## 一、功能概述
+
+在現有的「白名單規則檢查」（Regex 模式匹配）之前，新增「白名單字串檢查」功能，
+訊息必須包含白名單字串資料庫中的任一字串才能通過初步檢查。
+
+此功能可快速過濾大量安全訊息,減少進入人工審核的訊息量,提升整體處理效率。
+```
+
+---
+
+#### 第二章: 核心需求確認
+
+**用途**: 詳細定義功能需求,避免需求模糊
+
+**必填內容**:
+- 功能需求清單 (FR1, FR2, ...)
+- 非功能需求 (效能、安全、可用性)
+- 使用者故事 (可選)
+- 資料流程圖
+
+**撰寫技巧**:
+- 使用「必須」、「應該」、「可以」區分優先級
+- 每個需求可驗證、可測試
+- 包含具體數字 (如「支援 10,000+ 筆字串」)
+
+---
+
+#### 第三章: 技術方案概要
+
+**用途**: 說明「如何」實現需求 (高層次設計)
+
+**必填內容**:
+- 核心技術選型 (演算法、框架、套件)
+- 資料庫設計 (新增表、索引)
+- 架構設計 (分層架構、元件關係)
+- 資料流程圖
+
+**範例結構**:
+```markdown
+### 3.1 資料庫設計
+- WhitelistString 表
+- WhitelistStringMatchLog 表
+
+### 3.2 核心演算法
+- Aho-Corasick 多模式字串匹配
+
+### 3.3 資料流程
+[流程圖]
+```
+
+---
+
+#### 第四章: 新舊架構比較 (新功能必填)
+
+**用途**: 清楚呈現變更影響範圍
+
+**必填內容**:
+- 4.1 現有架構 (舊版)
+  - 架構圖
+  - 元件清單
+  - 現有邏輯程式碼片段
+- 4.2 新架構 (新版)
+  - 新架構圖
+  - 新增元件清單
+  - 新邏輯程式碼片段
+- 4.3 新舊架構對比表
+- 4.4 記憶體/效能影響對比
+
+**撰寫技巧**:
+- 使用表格呈現對比
+- 標註 [NEW] / [MODIFIED] / [DEPRECATED]
+- 量化影響 (如記憶體增加 12 MB)
+
+---
+
+#### 第五章: 新舊流程比較 (新功能必填)
+
+**用途**: 說明業務流程變化
+
+**必填內容**:
+- 5.1 現有流程 (舊版) - 流程圖 + 時間點
+- 5.2 新流程 (新版) - 流程圖 + 時間點
+- 5.3 流程對比表
+- 5.4 多種模式的流程比較 (如有)
+- 5.5 效能影響分析
+
+---
+
+#### 第六章: API 介面
+
+**用途**: 定義 API 規格 (如有 API 變更)
+
+**必填內容**:
+- 每個 API 端點的詳細定義:
+  - HTTP Method + Path
+  - 請求參數 / Body
+  - 回應格式 (JSON 範例)
+  - 錯誤代碼說明
+  - 權限要求
+
+**範例**:
+```markdown
+### 6.1 查詢白名單字串
+
+**端點**: `GET /WhitelistString/{dbName}/GetWhitelistStrings/{pageSize}`
+
+**查詢參數**:
+- `moreID` (optional): 分頁 cursor
+
+**回應**:
+\```json
+{
+  "strings": [...],
+  "hasMore": true
+}
+\```
+```
+
+---
+
+#### 第七章: 設定參數
+
+**用途**: 定義新增的設定項目
+
+**必填內容**:
+- appsettings.json 新增項目
+- 參數說明表 (名稱、可選值、預設值、說明)
+- 設定模式說明 (如有多種模式)
+
+---
+
+#### 第八章: 實作範圍
+
+**用途**: 明確列出所有程式碼變更
+
+**必填內容**:
+- 8.1 新增檔案清單 (依層級分類)
+- 8.2 修改檔案清單 (說明修改內容)
+- 8.3 依賴套件 (新增 NuGet/npm 套件)
+
+**撰寫技巧**:
+- 依照 Clean Architecture 分層
+- 標註每個檔案的用途
+- 列出套件版本與授權
+
+---
+
+#### 第九章: 測試計畫
+
+**用途**: 定義測試策略與驗收標準
+
+**必填內容**:
+- 9.1 單元測試 (測試案例清單)
+- 9.2 效能測試 (目標效能指標)
+- 9.3 整合測試 (端到端流程)
+- 9.4 壓力測試 (可選)
+
+**撰寫技巧**:
+- 使用表格呈現測試案例
+- 明確定義「通過」標準
+- 包含效能基準 (如「< 5ms」)
+
+---
+
+#### 第十章: 預期效益
+
+**用途**: 說明投資報酬率 (ROI)
+
+**必填內容**:
+- 10.1 業務效益 (質化描述)
+- 10.2 技術效益 (質化描述)
+- 10.3 可量化指標 (量化數據)
+
+**撰寫技巧**:
+- 使用對比表呈現改善幅度
+- 標註「預估值」vs「實際值」
+- 包含假設條件
+
+---
+
+#### 第十一章: 風險與限制
+
+**用途**: 誠實揭露技術限制與業務風險
+
+**必填內容**:
+- 11.1 技術限制 (5 項以內)
+- 11.2 業務風險 (3 項以內)
+- 11.3 緩解措施 (每個風險的對策)
+
+**撰寫技巧**:
+- 具體說明限制條件 (如「不支援正則表達式」)
+- 提供可行的緩解方案
+- 誠實面對技術債
+
+---
+
+#### 第十二章: 實作時程估算
+
+**用途**: 提供工時估算與里程碑
+
+**必填內容**:
+- 12.1 分階段工時估算 (表格)
+- 12.2 里程碑規劃 (完成標準 + 日期)
+
+**撰寫技巧**:
+- 依照開發階段分解工時
+- 包含測試與文件時間
+- 預留 buffer (建議 20%)
+
+---
+
+#### 第十三章: 待客戶確認事項
+
+**用途**: 收集客戶決策與回饋
+
+**必填內容**:
+- 已確認需求勾選清單
+- 待決策問題 (6-10 個)
+- 其他建議或疑慮欄位
+
+**撰寫技巧**:
+- 使用 Checkbox `- [ ]` 格式
+- 每個問題提供選項
+- 預留客戶填寫空間
+
+---
+
+#### 第十四章: 客戶簽核
+
+**用途**: 正式簽核欄位
+
+**必填內容**:
+- 需求確認聲明勾選清單
+- 變更管理條款
+- 簽核資訊 (簽核人、日期、公司)
+
+---
+
+### 3.3 附錄章節 (選填)
+
+#### 附錄 A: 資料表結構
+
+**條件**: 有新增或修改資料表時
+
+**內容**: 完整的 DDL (CREATE TABLE 語法)
+
+---
+
+#### 附錄 B: DTO 定義
+
+**條件**: 有新增 API 或資料傳輸物件時
+
+**內容**: C# class 定義 (含 XML 註解)
+
+---
+
+#### 附錄 C: 列舉型別定義
+
+**條件**: 有新增 enum 時
+
+**內容**: C# enum 定義
+
+---
+
+#### 附錄 D: 演算法說明
+
+**條件**: 使用複雜演算法時
+
+**內容**: 演算法原理、時間複雜度、空間複雜度
+
+---
+
+## 四、Markdown 格式規範
+
+### 4.1 標題層級
+
+```markdown
+# 文件標題 (H1 - 僅用於文件標題)
+## 一、章節標題 (H2 - 用於章節)
+### 1.1 小節標題 (H3 - 用於小節)
+#### 細項標題 (H4 - 用於細項)
+```
+
+### 4.2 表格格式
+
+```markdown
+| 欄位名稱 | 資料類型 | 說明 |
+|---------|---------|------|
+| ID | INTEGER | 主鍵 |
+| Name | TEXT | 名稱 |
+```
+
+**要求**:
+- 表頭使用 `|---|` 分隔線
+- 欄位對齊使用空格調整
+- 中文表格使用全形標點
+
+### 4.3 程式碼區塊
+
+````markdown
+```csharp
+// C# 程式碼
+public class Example {
+    // ...
+}
+```
+
+```json
+// JSON 範例
+{
+  "key": "value"
+}
+```
+````
+
+**要求**:
+- 指定語言類型 (csharp, json, sql, bash, etc.)
+- 加入註解說明關鍵邏輯
+- 縮排使用 4 個空格
+
+### 4.4 清單格式
+
+```markdown
+- 無序清單項目 1
+- 無序清單項目 2
+  - 子項目 2.1
+  - 子項目 2.2
+
+1. 有序清單項目 1
+2. 有序清單項目 2
+
+- [ ] 待辦事項 (未完成)
+- [x] 待辦事項 (已完成)
+```
+
+### 4.5 強調與標記
+
+```markdown
+**粗體** - 用於重要關鍵字
+*斜體* - 用於強調
+`程式碼` - 用於 inline code
+[連結文字](URL) - 用於超連結
+```
+
+### 4.6 流程圖與架構圖
+
+使用 ASCII 藝術圖:
+
+```markdown
+┌─────────────┐
+│   Box 1     │
+└──────┬──────┘
+       ↓
+┌─────────────┐
+│   Box 2     │
+└─────────────┘
+```
+
+**符號表**:
+- `┌ └ ┐ ┘` - 方框角落
+- `─ │` - 水平與垂直線
+- `├ ┤ ┬ ┴ ┼` - 連接點
+- `↓ ↑ → ←` - 箭頭
+
+---
+
+## 五、版本控制規範
+
+### 5.1 版本號規則
+
+- **v1.0** - 初版發行
+- **v1.1** - 新增章節或大幅修改 (如新增「新舊架構比較」)
+- **v1.0.1** - 小幅修正 (錯字、格式調整)
+
+### 5.2 版本歷史格式
+
+```markdown
+**版本歷史**:
+- v1.1 (2025-01-13): 新增「新舊架構比較」與「新舊流程比較」章節
+- v1.0 (2025-01-12): 初版發行
+```
+
+### 5.3 文件更新流程
+
+1. 修改文件內容
+2. 更新文件標頭的「最後更新」日期
+3. 更新版本號 (依修改程度)
+4. 新增版本歷史記錄
+5. Commit 時使用 `文件(需求): [修改說明]` 格式
+
+---
+
+## 六、撰寫技巧與最佳實踐
+
+### 6.1 語言使用
+
+- **文件內容**: 繁體中文 (遵循 [extensions/locales/zh-tw.md](../extensions/locales/zh-tw.md))
+- **程式碼**: 英文命名
+- **專有名詞**: 保留英文 (如 API, Regex, JSON)
+- **混合使用**: 「白名單字串檢查（Whitelist String Check）」
+
+### 6.2 數字與單位
+
+- **時間**: 使用「秒」、「毫秒 (ms)」、「分鐘」
+- **容量**: 使用「MB」、「GB」
+- **數量**: 使用「筆」、「則」、「個」
+- **百分比**: 使用「%」或「↓ 50%」
+
+### 6.3 引用程式碼
+
+使用檔名:行號格式:
+
+```markdown
+現有檢查邏輯位於 `PlatformContainer.cs:1307-1352`:
+```
+
+### 6.4 架構圖繪製原則
+
+- 由上而下 (資料流向)
+- 方框內包含元件名稱
+- 箭頭表示資料流或呼叫關係
+- 標註關鍵步驟說明
+
+### 6.5 對比表撰寫原則
+
+- 第一欄: 比較項目
+- 第二欄: 舊版
+- 第三欄: 新版
+- 第四欄: 差異 (使用 ✅ ❌ ⚠️ 標記)
+
+---
+
+## 七、品質檢查清單
+
+完成需求確認書後,使用以下檢查清單自我檢查:
+
+### 7.1 完整性檢查
+
+- [ ] 14 個核心章節全部完成
+- [ ] 文件標頭資訊完整
+- [ ] 版本歷史記錄正確
+- [ ] 必要的附錄已加入
+
+### 7.2 技術準確性檢查
+
+- [ ] 架構圖與程式碼一致
+- [ ] API 規格可實作
+- [ ] 資料表結構完整
+- [ ] 效能指標合理
+- [ ] 工時估算有依據
+
+### 7.3 客戶可讀性檢查
+
+- [ ] 避免過度技術術語
+- [ ] 關鍵概念有說明
+- [ ] 流程圖易於理解
+- [ ] 客戶確認事項明確
+- [ ] 預期效益清楚
+
+### 7.4 格式一致性檢查
+
+- [ ] Markdown 格式正確
+- [ ] 表格對齊美觀
+- [ ] 程式碼區塊有語言標記
+- [ ] 超連結有效
+- [ ] 中英文標點符號正確
+
+---
+
+## 八、範本使用流程
+
+### 步驟 1: 複製範本
+
+```bash
+cp .standards/templates/requirement-template.md docs/[feature-name]-requirement.md
+```
+
+### 步驟 2: 填寫文件標頭
+
+更新版本、日期、功能名稱
+
+### 步驟 3: 依序撰寫章節
+
+按照本規範的章節說明逐一填寫
+
+### 步驟 4: 自我檢查
+
+使用 [requirement-checklist.md](requirement-checklist.md) 檢查
+
+### 步驟 5: 版本控制
+
+```bash
+git add docs/[feature-name]-requirement.md
+git commit -m "文件(需求): 新增 [功能名稱] 需求確認書 v1.0"
+```
+
+---
+
+## 九、相關規範文件
+
+- [Commit 訊息規範](../core/commit-message-guide.md) - 簽入需求文件時使用
+- [繁體中文語言規範](../extensions/locales/zh-tw.md) - 文件撰寫語言指引
+- [文件結構標準](../core/documentation-structure.md) - 整體文件組織
+- [Code Review 檢查清單](../core/code-review-checklist.md) - 實作完成後使用
+
+---
+
+## 十、參考文件
+
+本格式規範參考以下最佳實踐:
+
+- **ISO/IEC/IEEE 29148:2018** - 系統與軟體需求工程
+- **軟體需求規格書 (SRS)** - 業界標準結構
+- **實用導向設計** - 強調可執行性與完整性
+- **實務專案經驗** - 基於實際需求文件優化
+
+---
+
+**文件版本**: 1.0.1
+**最後更新**: 2025-12-05
+**維護者**: Universal Doc Standards Community