排程模組規格站 — 五階段可追溯性

output-template

6 min read

Functional Spec 文件輸出模板

寫入 spec/{feature}/{feature}.fp.md 的標準格式。 Partner skill 在步驟 7（最終輸出）時組裝此模板。 對應 product-module-development-workflow.md Stage 2 的必備內容與 Exit Gate。

模板全文

# {功能名稱} Functional Spec
 
> 來源：[requirement/{feature}/](../../requirement/{feature}/index.md)
> 下游：[OOA]({feature}.ooa.md)（尚未建立）
> 性質：{單一 feature／跨 feature 共用模組（Published Language）；一句話講上下游消費關係}
> 驗證：{若有：`{feature}.fp.validate.py` → 執行結果 [output](./{feature}.fp.validate-output.md)；無驗證 script 則整行刪除}
> 狀態：待簽核 / 已簽核（簽核後請更新此欄）
 
---
 
## 概述
 
一句話描述這個功能要解決什麼問題（回貼 requirement 的 Problem statement）。
 
---
 
## Use Cases
 
### UC A1: {use case 名稱}
 
- **Actor**：…
- **觸發條件**：…
- **行為**：
  1. …
  2. …
  3. …
- **預期結果**：…
- **例外路徑**：見 §邊界條件 `§{SHORT}-FS-{x}`、`§{SHORT}-FS-{y}`
- **設計前提**：（可選）此 UC 的職責切線、不做什麼、與相鄰模組哲學一致性。一段平實散文，不堆裝飾粗體。
 
### UC A2: {use case 名稱}
 
（同上格式）
 
---
 
## 流程圖 / 狀態機
 
### 主流程
 
```mermaid
flowchart TD
    Start[起點] --> Step1[步驟 1]
    Step1 --> Decision{條件?}
    Decision -- 是 --> Step2[步驟 2]
    Decision -- 否 --> End[結束]
    Step2 --> End
```
 
### {若有狀態機}
 
```mermaid
stateDiagram-v2
    [*] --> NEW
    NEW --> SCHEDULED: 排程
    SCHEDULED --> DONE: 完工
    SCHEDULED --> CANCELLED: 取消
    DONE --> [*]
    CANCELLED --> [*]
```
 
---
 
## I/O 範例
 
### UC A1
 
#### 正常值
- input:
  ```
  {具體值}
  ```
- output:
  ```
  {具體值}
  ```
 
#### 邊界值
- input:
  ```
  {具體值}
  ```
- output:
  ```
  {具體值}
  ```
 
#### 異常值
- input:
  ```
  {具體值}
  ```
- output:
  ```
  {具體值或例外行為}
  ```
 
### UC A2
 
（同上格式）
 
---
 
## 邊界條件 / 異常情境
 
> 「編號」欄即**全域碼** `§{SHORT}-FS-{N}`（對外項目）。`{SHORT}` 查 [spec-codes.md](../../spec-codes.md)；N 為連續整數。文中其他段落（UC 例外路徑、I/O、流程圖、下游 OOA/PC）引用一律用全域碼。
 
| 編號 | 條件 | 結果 |
|---|---|---|
| §{SHORT}-FS-1 | … | … |
| §{SHORT}-FS-2 | … | … |
| §{SHORT}-FS-3 | … | … |
 
> 編號為 append-only（NUMBER 沿用本地序、不重編）。廢棄條件用 ~~刪除線~~ + 廢棄原因保 tombstone，不重用號碼。
 
---
 
## 驗證 Script（可選）
 
若有，路徑：`spec/{feature}/{feature}.fp.validate.py`
 
腳本用途：驗證 I/O 範例自洽，**非實作雛形**。
 
---
 
## requirement 覆蓋對照
 
| requirement 需求點 | 對應 Use Case / 邊界條件 | 狀態 |
|---|---|---|
| R1 {來源說明} | UC A1 | 已涵蓋 |
| R2 {來源說明} | UC A2 | 已涵蓋 |
| R3 {來源說明} | — | 明確不做（下一期） |
| R4 {來源說明} | — | 待裁定 |
 
> Exit Gate 第 1 條：requirement 中所有列入範圍的 user need 都要在此對齊。
 
---
 
## 待裁定 / 未解問題
 
- Q1：… → 狀態：…
- Q2：… → 狀態：…
 
---
 
## 簽核
 
- **編輯者**：____ / 日期：____
- **Reviewer**：____ / 日期：____
- 簽核完成後，請把上方「狀態」欄改為「已簽核」。

連結慣例（GFM，寫檔時遵循）

完整規則見 product-module-development-workflow.md §可追溯性「連結慣例（GFM）」。本階段重點：

  • breadcrumb / 跨檔：相對路徑 markdown 連結 [文字](../path.md)（本檔在 spec/{feature}/（兩層深），連 requirement 用 ../../；同 feature 的 ooa／pseudo 為同層 sibling、直接用檔名）。
  • 回指 requirement 的未解問題（如覆蓋對照表、待裁定清單裡的 #N）：[#N](../requirement/{feature}/index.md#未解問題)——GitHub 無法逐列，連到區段是可攜最佳解。
  • 同檔 section 跳轉（§概述 / §流程圖 / §待裁定 等）：markdown 連結 [§顯示](#完整標題)。
  • §邊界條件 B{n}：在表內無法逐列定位，行內引用維持純文字即可（讀者一個捲動可達該表）；避免整段變藍字。
  • 標籤一律含非數字字元；純數字 #1 不是合法 tag，編號導航改用上面的連結。

組裝檢查清單

寫檔前確認（對齊 Stage 2 Exit Gate）：

  • 涵蓋 requirement 中所有列入範圍的 user need（§ requirement 覆蓋對照已逐項對齊）
  • 每個 use case 至少有 happy path 與一條主要 alternate path
  • 至少一張流程圖或狀態機
  • 每個 use case 都有 I/O 範例，且為具體值（非型別宣告）
  • 邊界條件用枚舉表，每條都可變成測試
  • 文件頂部 breadcrumb 指向上游 requirement 與下游 ooa
  • 簽核欄位已留空給使用者填

禁區檢查（寫進去就要砍掉）

  • 沒有 class diagram、繼承關係
  • 沒有 DB schema、欄位定義
  • 沒有 API endpoint（URL、HTTP method、payload schema）
  • 沒有套件結構、模組切分
  • 沒有演算法步驟細節（那是 Stage 4）

I/O 範例可以描述「對外觀察的輸入輸出」，但不要寫成 DTO / endpoint schema。

與其他階段的對應

Functional Spec 元素下游對應
Use Case 行為步驟OOA 物件職責 + Pseudo Code §編號
邊界條件 §{SHORT}-FS-{n}Pseudo Code 的分支處理 + 測試案例（下游引用此全域碼）
I/O 範例測試輸入輸出（Stage 5 測試覆蓋來源）
流程圖決策節點OOA Sequence Diagram + Pseudo Code 分支

Graph View