Clarify Flow Description
目的
將模糊、口語化或結構鬆散的流程說明，重寫為精確、結構化、可直接對應 Mermaid 流程圖節點的格式，確保每個步驟、判斷、分支都清晰可追蹤。
適用情境
- 從會議紀錄或需求訪談中整理出的粗略流程說明
- 口語化描述的業務邏輯，需轉為正式規格
- 準備繪製 Mermaid 流程圖前的前置整理
- 流程說明需要讓非原作者也能看懂
優化原則
1. 結構化分區
每個流程必須包含以下區塊：
| 區塊 | 說明 | 對應 Mermaid 元素 |
|---|---|---|
| 比對條件 | 列出該流程用來匹配資料的關鍵欄位 | 流程起始節點的輸入條件 |
| 處理流程 | 以編號步驟描述完整邏輯 | 流程圖中的處理節點與判斷菱形 |
2. 步驟撰寫規範
每個編號步驟應遵循以下原則：
| 原則 | 說明 | 範例 |
|---|---|---|
| 明確資料來源 | 說明從哪張表或哪個服務取得資料 | 「查詢 InsertAlert 資料表中…」 |
| 列舉篩選條件 | 逐一列出 include / exclude 條件 | 「排除 SendDeadline 小於當前主機時間的資料」 |
| Null 值處理 | 明確說明 NULL 或空值時的行為 | 「SendDeadline 為 NULL 時，視為無截止時間限制，不排除」 |
| 排序規則 | 指定排序欄位與方向 | 「符合條件的資料依 pk Id 由小到大排序」 |
| 欄位名稱反引號 | 欄位名稱使用反引號標記 | MainCategory、SubCategory |
3. 判斷分支撰寫規範
遇到 if / else 邏輯時：
| 原則 | 說明 | 範例 |
|---|---|---|
| 粗體標記分支 | 用粗體標示每個分支的條件 | Key 存在時（快取期間內）： |
| 縮排呈現層級 | 子分支用縮排或清單表示 | - **未過期：** 將該筆資料加入待發送清單 |
| 明確結束點 | 說明何時結束遍歷或跳出流程 | 「結束遍歷」、「繼續往下遍歷下一筆資料」 |
| 無符合結果 | 說明全部不符合時的行為 | 「遍歷完該批次所有資料，本次無符合條件資料」 |
4. 迴圈/遍歷撰寫規範
| 原則 | 說明 |
|---|---|
| 明確遍歷對象 | 說明遍歷的資料集合是什麼 |
| 迴圈內判斷 | 每次迭代要檢查什麼條件 |
| 提前退出 | 滿足什麼條件時結束遍歷 |
| 遍歷完畢 | 全部遍歷完無符合時的處理 |
邊界補全（輸出前必做）
結構化完成後，在寫回檔案前先做一次邊界檢查。目的是讓輸出文檔足夠完整。
檢查清單
逐一掃描以下常見缺漏，若需求文檔未提及，則列為待確認項：
| 類別 | 檢查問題 |
|---|---|
| 空值 / 無資料 | 查詢結果為空時怎麼辦？輸入為空或 null 時怎麼辦？ |
| 邊界數值 | 有沒有最小值、最大值、門檻限制？臨界值時的行為？ |
| 資源不存在 | 對象不存在（找不到 ID）時怎麼辦？ |
| 狀態衝突 | 資料已過期、已使用、已刪除時怎麼辦？ |
| 權限 / 身份 | 未登入、無權限、角色不符時怎麼辦？ |
| 重複操作 | 重複提交、重複觸發會怎樣？有冪等保護嗎？ |
| 外部依賴失敗 | 第三方 API 或服務掛掉時的降級行為？ |
互動流程
-
列出在需求中未被提及的邊界項目，格式如下：
以下邊界情境需求中未提到，請確認或補充： 1. 查詢結果為空時，系統應如何回應？ 2. 折價券已使用過是否需要阻擋？預期錯誤碼為何？ -
等使用者回覆後，將補充的邊界條件合併進結構化文檔
-
若使用者明確表示「不需要考慮」某項，也在文檔中標注「Out of Scope」
若需求已明確涵蓋所有邊界，直接進入輸出流程，不需詢問。
優化前後對照範例
若輸入的流程屬於以下任一情況，才需要讀取 references/example.md：
- 多層巢狀判斷（if 裡面還有 if）
- 包含迴圈或遍歷邏輯
- 分支超過 3 條且各有不同結束點
簡單的線性流程或單層判斷不需要讀取範例，依規則直接輸出即可。
輸出規範
- 保留原始語意：不改變業務邏輯，只改善表達方式
- 一個流程一個區塊：每種策略或流程獨立一個小節，包含比對條件與處理流程
- 步驟連貫可追蹤：步驟之間可用「承接第 N 點」串接，確保讀者能追蹤上下文
- 可直接對應 Mermaid：每個步驟對應一個處理節點，每個判斷對應一個菱形節點，每個分支對應一條連線
- 邊界確認後才寫回：完成邊界補全互動後，才將最終結構化文檔寫回指定路徑