規格撰寫指南

本指南定義專案開發所需的各類文檔撰寫規範與範本，涵蓋從產品規劃到技術規格的完整文檔體系。

實際案例參考: 花店管理系統規格 包含完整的開發文檔，可作為撰寫參考。

---

文檔層級架構

{docsRoot}/docs/
├── requirements/                  # 第一部分，選用、按需要建立
│   ├── research/                  # 研究資料
│   ├── interviews/                # 需求訪談及逐字稿
│   ├── meetings/                  # 需求討論、範圍會議
│   ├── agreements/                # SOW／報價功能項目與範圍約定
│   └── business-requirements/     # BR-{NNN}.md
├── specs/                         # 第二部分：開發規格及其管理
│   ├── roadmap.md
│   ├── feature-list.md
│   ├── epics/
│   ├── user-stories/
│   ├── reports/                    # 獨立報表規格（RPT）
│   ├── sbe/
│   ├── checklists/
│   └── progress/
├── design/                        # 設計與決策
│   ├── domain-model.md            # 領域模型（大型專案為 domain-model/ 目錄）
│   ├── api-specs/
│   └── decision-records/
└── testing/                       # 測試規格與驗證證據

---

命名規範

類型	格式	範例
Feature ID	F-{NN}	F-01
領域模型	design/domain-model.md（多檔：design/domain-model/）	design/domain-model.md
Epic 文檔	epic-{N}-{kebab-case}.md	epic-2-order-lifecycle.md
User Story ID	US-{Epic編號}{流水號}	US-201
User Story 文檔	US-{ID}-{kebab-case}.md	US-201-create-order.md
SBE Scenario 目錄	US-{ID}-{kebab-case}/	US-201-create-order/
SBE Scenario 文檔	scenario-{N}-{description}.md	scenario-1-individual-customer.md
API 文檔	{domain}.md	orders.md
數據模型	{entity}.md	order.md
ADR	{NNN}-{description}.md	002-state-machine-for-orders.md
訪談紀錄	interview-{N}-{kebab-case}.md	interview-1-shop-owner.md
調查報告	survey-{N}-{kebab-case}.md	survey-1-order-workflow.md
競品分析	competitive-analysis.md	competitive-analysis.md

---

選用 BR 模板（ADR-014；ADR-015 目錄修訂已採納）

BR 是概略業務需求的來源層，不是所有專案的前置文件。以下模板由 /br 與共用 parser 使用；實作已通過 P4 成果審閱。 文件與 sidecar 欄位、語意指紋及確認流程的權威契約為 workspace .claude/rules/m-business-requirements.md；設計理由見 ADR-014 （docs-methodology/decision-records/014-optional-business-requirements-traceability.md）。

BR 最小模板

產出路徑：{docsRoot}/docs/requirements/business-requirements/BR-{NNN}.md。 填入穩定編號與標題；來源尚不明確可保留「待補」，不必先補齊 Use Case 或驗收標準。 sidebar_position 為 BR 的整數編號；其餘可選區段按需增加，不生成空清單。

---
kind: business-requirement
br_schema: 1
id: "BR-{NNN}"
sidebar_position: {整數編號}
sidebar_label: "BR-{NNN} {業務需求標題}"
version: draft
confirmation: pending
sources:
  - key: "SRC-001"
    identity: "待補"
    revision: "待補"
    locator: "待補"
---

# BR-{NNN}：{業務需求標題}

## 需求陳述

{保留來源原意的需求陳述；可概略、不完整。}

選用的語意區段為「業務規則」「已採用澄清」「範圍與承諾」「待澄清事項」； metadata 區段為「來源說明」「確認紀錄」「變更紀錄」。待澄清問題納入指紋， 但問題不等於已採用的要求；只補頁碼／時間戳與換掉來源文件版本有不同影響。 定案或業務確認時才追加以下表格，digest 必須由工具計算，不手填假值：

## 確認紀錄

| 事件 | 操作者 | 時間 | 依據 | 語意 SHA-256 |
|---|---|---|---|---|
| {document-finalized 或 business-confirmed} | {操作者} | {UTC RFC3339} | {明示確認依據} | {工具計算值} |

內部規格引用模板

在既有 US frontmatter 的 depends_on 清單追加直接 BR 路徑，保留 Epic 等既有依賴； 不複製整份 frontmatter 取代原內容，不在每個 US 強制加入 BR。BR 引用第一版採整檔，不使用 fragment。

depends_on:
  - "specs/epics/epic-{N}-{name}.md"
  - "requirements/business-requirements/BR-{NNN}.md"

## BR 涵蓋說明

| BR | 承接範圍 | US 段落 | 本 US 未承接部分／待澄清事項 |
|---|---|---|---|
| [BR-{NNN}](../../../requirements/business-requirements/BR-{NNN}.md) | {本 US 回應的要求及邊界} | [{規格段落}](#{fragment}) | {本 US 不承接的要求或待確認內容；無則明記無} |

以上相對連結適用於 docs/specs/user-stories/epic-{N}/；其他層級依文件位置調整。 既有 US 業務規則的 BR 編號不自動指向此需求庫，以完整路徑與 kind 識別。

BR 與 US 是多對多關係，新增／補建引用或修訂承接範圍時，須逐 BR 寫上述說明並對照真實規格段落。 本 US 未承接的部分可能由其他 US 涵蓋，不直接算整體缺口。US 可包含 BR 未要求的額外功能， 有需要時另註其內部需求依據；不要求每項功能都有 BR 來源，但仍須符合適用的 BR 限制。 既有文件不因擴充批次改寫，缺說明的項目在 cover 保留為缺口。

從 BR 展開或回補既有規格

/br expand {BR-ID} 先盤點 Roadmap、Feature List、Epic、US 及相關 SBE／設計／測試文件， 包含尚未引用 BR 的既有 US，再提出承接方案與修改草稿。確認方案後，透過既有規格 skills 補引用、修訂或新增文件；已有符合內容則保留，不重複生成。BR 晚加入時，記錄現在建立的 承接關係，不宣稱它是既有規格最初的來源。

操作	確認的事情
expand	建立或補足規格及承接關係；本身不簽認涵蓋
acknowledge	單一 US 對所有直接 BR 的承接範圍與解讀；不要求單一 US 滿足整項 BR
cover	所有已連結 US 與人選補充證據合計是否涵蓋 BR；不代表交付驗收
progress	唯讀彙整有效涵蓋、整份 US 完成狀態與必要證據，分析 BR 交付進度

建議順序為 expand → acknowledge 各受影響 US → cover 各 BR。cover 發現不足時， 描述為「目前已連結的規格未涵蓋」，交 expand 盤點缺的是引用還是規格，再補足。 current + partial 表示缺口紀錄仍有效；缺口不因接受延後而消失。完全沒有可列入的規格 時只報缺口，不建立空的 coverage sidecar。既有 stale 紀錄只能作重新盤點的線索。

只補引用與如實記錄既有行為不自動回退開發階段，但任何 US bytes 修改仍使來源核對及相關 原始 bytes 證據 stale；實際改變行為／驗收條件時走既有變更管理與 SBE 更新流程。 規格更新授權不等於來源簽認、業務確認或 full 批准，核對仍使用人工確認的快照。

查詢 BR 交付進度

執行 /br progress {BR-ID}，顯示 BR 的規格涵蓋、每份直接承接 US 的範圍、Sprint 階段、 來源核對與必要驗收證據。它是唯讀分析，不寫 BR 完成欄位、不推進或回退 US。

US 是不可拆分計算的交付單位。 US 未完成，它承接的所有 BR 部分都視為未完成， 即使相關場景已實作，或剩下的是 BR 未要求的內部功能。若要分批交付，先拆分 US， 更新承接關係並重新核對，不能從未完成的 US 抽算部分成果。

條件	BR 進度
涵蓋尚未確認／失效，或進度、來源核對與必要證據無法有效判定	待核對
有效涵蓋為 partial	規格待補足；另列 US 進度與資料問題
有效涵蓋為 full，但承接 US 尚未全部 ✅	進行中
有效涵蓋為 full，全部承接 US 均 ✅、來源核對及必要證據有效	已完成

所有已連結 US 完成仍不能彌補 partial 的規格缺口。數量「✅ 1／3」只代表 US 數量， 不代表 BR 完成 33%。只有設計／測試規格而沒有 US 的非功能需求，還須核對實際執行／ 驗收證據，不以 0／0 判完成。reference 或已排除／撤回／取代的 BR 不套用交付完成判定。

原始 ✅ 若缺少有效證據，保留階段並標「證據待核對」。完成 US 依軌道驗證最終 UAT （UI：I.UAT；Headless：S.UAT），補充交付要求另核對其證據；查詢不重跑測試或建立批准。 範圍處置、業務確認另外呈現；「已完成」指開發流程的交付要求，並不自動代表已部署或客戶正式驗收。

US 核對 sidecar 形狀

檔名：US 同目錄的 {usFileStem}.br-sources.json。 以下是佔位模板，未取代佔位值前不是有效證據；由 BR 核對工具根據人類批准的工作區內容生成。

{
  "kind": "br-source-acknowledgement",
  "schemaVersion": 1,
  "algorithm": "sha256",
  "projectionVersion": "br-semantic-v1",
  "generator": {"name": "br-trace", "version": "1.1.0"},
  "subject": {
    "path": "specs/user-stories/epic-{N}/{usFileStem}.md",
    "sha256": "{US 原始 bytes 的 SHA-256}"
  },
  "inputs": [{
    "id": "BR-{NNN}",
    "path": "requirements/business-requirements/BR-{NNN}.md",
    "semanticSha256": "{BR projection 的 SHA-256}"
  }],
  "acknowledgement": {
    "by": "{操作者}",
    "at": "{YYYY-MM-DDTHH:mm:ssZ}",
    "basis": "{明示核對依據}"
  }
}

此檔只證明來源核對，不能表示 BR 全部被涵蓋。整體規格涵蓋的人工確認另放 BR-{NNN}.br-coverage.json，schema 見核心規則；交付證據仍沿既有 US／E2E／UAT， 不由任何 BR sidecar 宣告客戶驗收完成。

---

1. 產品路線圖（roadmap.md）

讀者: 產品經理、技術主管、利害關係人

內容:

• 產品願景（核心問題、市場定位、差異化價值）
• 戰略主題與 Now-Next-Later 路線圖
• 關鍵成功指標 (KPIs)
• 用戶角色與權限矩陣
• 核心 Epics 概覽
• 非功能性需求

更新頻率: 每季度審視一次

實際案例: 花店管理系統 Roadmap

---

2. 功能清單（feature-list.md）

讀者: 客戶、利害關係人、產品經理

內容:

• 系統從使用者角度的功能概覽，按功能領域分組
• 每項功能標註主要角色、交付階段、實作狀態
• 與 Epic/US 的交叉引用

更新頻率: 初始建立時從 Roadmap 衍生，後續每個 Sprint 更新狀態

與 roadmap.md 的關係:

• roadmap.md 回答 "為什麼做"（Why）— 戰略主題、業務目標
• feature-list.md 回答 "使用者能做什麼"（What）— 功能能力清單

與 epics/ 的關係:

• feature-list.md 以使用者視角組織功能（我能做什麼）
• epics/ 以開發視角組織工作（團隊怎麼拆分）
• 兩者是平行關係（M:N 交叉引用），不是上下游

產出方式:

• 有 Roadmap 的專案：由 /roadmap 附帶產出，或用 /feature-list 從 Roadmap 衍生
• 客戶委託專案（無 Roadmap）：用 /feature-list 對話式獨立建立
• 狀態更新：由 /sprint 在 Sprint Review 時更新

Feature List 範本

# {產品名稱}：功能清單

## 概述

本文檔列出{產品名稱}的使用者功能，按功能領域分組。
每項功能標註交付階段與實作狀態，供利害關係人掌握產品能力與開發進度。

**狀態說明**：🔲 待開發 ｜ 🚧 開發中 ｜ ✅ 已完成

## {功能領域 1}

| # | 功能 | 說明 | 主要角色 | 階段 | 狀態 | 相關 Epic | 相關 US |
|---|------|------|---------|------|------|----------|--------|
| F-01 | {功能名稱} | {一句話說明} | {角色} | {Now/Next/Later} | 🔲 | Epic {N} | — |
| F-02 | {功能名稱} | {一句話說明} | {角色} | {Now/Next/Later} | 🔲 | Epic {N}, {M} | US-{NNN} |

## {功能領域 2}

| # | 功能 | 說明 | 主要角色 | 階段 | 狀態 | 相關 Epic | 相關 US |
|---|------|------|---------|------|------|----------|--------|
| F-10 | {功能名稱} | {一句話說明} | {角色} | {Now/Next/Later} | 🔲 | Epic {N} | — |

## 範圍外（Out of Scope）

以下功能已明確排除在目前產品範圍外：

- {排除功能 1} — {排除原因}
- {排除功能 2} — {排除原因}

欄位說明

欄位	說明
#	Feature ID（F-{NN}），在文檔內唯一
功能	使用者可感知的功能名稱
說明	一句話描述功能的業務價值
主要角色	主要使用該功能的角色（參考 Roadmap 角色定義）
階段	交付階段（Now / Next / Later），對應 Roadmap 路線圖
狀態	🔲 待開發 / 🚧 開發中 / ✅ 已完成
相關 Epic	實作該功能的 Epic（可多個，M:N 關係）
相關 US	對應的 User Story（功能尚未拆分 US 時填 —）

分組原則

功能按使用者感知的功能領域分組，而非按 Epic。例如：

功能領域（Feature List）	來源 Epic（開發視角）
訂單管理	Epic 2（訂單生命週期）+ Epic 0（通知）
客戶管理	Epic 3（客戶系統）
財務管理	Epic 4（發票與支付）

同一 Epic 的功能可能分散在多個功能領域中，同一功能也可能關聯多個 Epic。

實際案例: 花店管理系統功能清單

---

3. 領域模型（domain-model.md）

讀者: 客戶、產品經理、開發團隊

內容:

• 概念層級的業務實體定義與關聯關係（Mermaid erDiagram）
• 實體的關鍵屬性與業務約束
• 實體生命週期與狀態機（Mermaid stateDiagram）
• 跨實體的業務規則
• 術語表（Ubiquitous Language）

位置: design/domain-model.md（大型專案拆為 design/domain-model/ 目錄）。早期版本位於 specs/，由 /domain-model 偵測並協助遷移

更新頻率: 初始建模時建立，隨 Epic 撰寫過程迭代更新

與其他文檔的關係:

• domain-model.md 回答 "業務中有什麼"（Static Model）— 實體、關聯、術語
• epics/ 回答 "業務怎麼運作"（Dynamic Model）— 功能、流程、場景
• design/data-models/ 是技術層級的 DB Schema，與 Domain Model 是不同抽象層級

產出方式:

• 使用 /domain-model 對話式建立，始終採用 Level 2 澄清循環

Domain Model 範本摘要

# {產品名稱}：領域模型

## 概述
## 實體關聯圖（Mermaid erDiagram）
## 核心實體
### {實體名稱} ({English Name})
  - 業務描述
  - 關鍵屬性表（屬性、說明、約束）
  - 狀態機（若有，Mermaid stateDiagram）
## 關聯關係（來源、關係類型、目標、說明）
## 業務規則（跨實體規則）
## 術語表 (Ubiquitous Language)
  - 核心術語表（術語、定義、英文對應、相關實體）
  - 易混淆術語對照
## 與其他文檔的關聯

---

4. 軟體開發計畫（development-plan.md）

讀者: 開發團隊、Tech Lead、Scrum Master、QA

內容:

• 專案概覽與成功標準
• 開發階段規劃
• Sprint 規劃與 Backlog
• 技術棧與應用架構
• Git 工作流程與分支策略
• 測試策略
• CI/CD Pipeline
• 部署策略與回滾計畫

更新頻率: 每個 Sprint 檢視並調整

與 roadmap.md 的關係:

• roadmap.md 回答 "為什麼做"（Why）— 產品願景、戰略方向
• feature-list.md 回答 "使用者能做什麼"（What）— 功能能力清單
• development-plan.md 回答 "怎麼做"（How）— 開發流程、技術實作

實際案例: 花店管理系統開發計畫

---

5. 業務需求來源（requirements/）

讀者: 產品經理、開發團隊

用途: 記錄產品發現階段的研究成果，為 Roadmap、Epic、User Story 提供決策依據。

選用性: 此目錄為選用。團隊可在撰寫 Roadmap 或 Epic 前進行研究，也可跳過直接撰寫。AI Skill（/roadmap、/epic）會偵測 requirements/research/、interviews/、meetings/、agreements/ 來源目錄，若存在則讀取作為澄清循環的額外脈絡。

更新頻率: 研究完成時建立，後續作為唯讀參考

原始材料與 BR 都屬第一部分；原始文件可保留原格式或只存受控外部文件的定位，無須套 BR frontmatter。各筆 BR 連回來源，第二部分則以 depends_on 引用 BR。需求材料不必逐份轉成 BR，未建立 BR 仍可直接參考。原始訪談放 docs/requirements/interviews/，研究放 research/，需求會議放 meetings/，SOW／報價放 agreements/；一般進度與技術會議不混入需求來源。

訪談紀錄範本

# 訪談紀錄 {N}: {受訪者描述}

## 基本資訊

| 項目 | 內容 |
|------|------|
| 日期 | YYYY-MM-DD |
| 受訪者 | {角色/職稱}（匿名化） |
| 訪談者 | {姓名} |
| 時長 | {N} 分鐘 |

## 關鍵發現
- {發現 1}
- {發現 2}

## 痛點
- {痛點 1}
- {痛點 2}

## 需求與期望
- {需求 1}

## 代表性引述
> "{受訪者原話}"

## 與產品的關聯
- 相關 Epic: {Epic N}
- 相關面向: {功能/流程}

調查報告範本

# 調查報告 {N}: {調查主題}

## 調查概要

| 項目 | 內容 |
|------|------|
| 調查期間 | YYYY-MM-DD ~ YYYY-MM-DD |
| 樣本數 | {N} |
| 目標族群 | {描述} |
| 方法 | 線上問卷 / 電話 / 面對面 |

## 關鍵數據
- {數據點 1}：{數值與意義}
- {數據點 2}：{數值與意義}

## 分析結論
- {結論 1}
- {結論 2}

## 與產品的關聯
- 相關 Epic: {Epic N}
- 相關面向: {功能/流程}

競品分析範本

# 競品分析

## 分析目的
{為什麼做這個分析、關注哪些面向}

## 競品列表

| 競品 | 類型 | 目標市場 | 定價模式 |
|------|------|---------|---------|
| {名稱} | {類型} | {市場} | {定價} |

## 功能對比矩陣

| 功能 | 我們的產品 | 競品 A | 競品 B |
|------|----------|--------|--------|
| {功能} | {狀態} | {狀態} | {狀態} |

## 差異化分析
- **我們的優勢**：{描述}
- **競品的優勢**：{描述}
- **機會點**：{描述}

## 與產品的關聯
- 相關戰略主題: {主題}
- 差異化策略影響: {說明}

---

6. Epic 文檔

讀者: 產品經理、技術架構師、Team Lead

內容: 從 roadmap 拆分出的詳細 Epic 描述

Epic 範本

# Epic N: {Epic 名稱}

## 業務目標
（為什麼要做這個 Epic？解決什麼問題？）

## 成功指標
（如何衡量 Epic 的成功？）

## 功能範疇
（Epic 包含哪些主要功能？）

## User Stories 列表
（鏈接到 user-stories/ 目錄）

## 技術依賴
（依賴其他 Epic 或外部系統）

## 多租戶考量
（Multi-tenancy 設計要點）

## 安全性考量
（如有特殊安全需求）

實際案例: 花店管理系統 Epics

---

7. User Story 文檔

讀者: 開發人員、測試人員、產品經理

內容: 使用者故事（遵循 INVEST 原則）

INVEST 原則

• Independent: 獨立的（盡量減少依賴）
• Negotiable: 可協商的（非合約，可調整）
• Valuable: 有價值的（對用戶有明確價值）
• Estimable: 可估算的（團隊能估算工作量）
• Small: 小的（1-2 個 Sprint 內可完成）
• Testable: 可測試的（有明確驗收標準）

User Story 範本

完整範本（含所有區段）定義在 User Stories 目錄索引，以下是核心結構摘要：

# US-{NNN}: {User Story 標題}

## User Story
**作為** {角色}
**我想要** {功能}
**以便** {業務價值}

## 驗收標準 (Acceptance Criteria)
### Scenario 1: {場景名稱}
- **Given** {前置條件}
- **When** {執行操作}
- **Then** {預期結果}

## 業務規則
## UI/UX 需求
## 技術規格
## 驗收檢查清單（Prototype 階段 / 整合階段）
## Story Points
## 變更歷史 (Change History)

實際案例: 花店管理系統 User Stories

---

8. SBE 實例化規格 (Specification by Example)

讀者: 開發人員、測試人員

內容: 具體的測試場景與範例數據

格式選擇:

• 使用者互動流程使用 Gherkin (Given-When-Then)
• API 輸入/輸出使用 Markdown 表格

Given-When-Then 格式

• Given: 描述前置條件與系統初始狀態
• When: 描述執行的操作
• Then: 描述預期的結果

SBE 範本

# Scenario N: {場景名稱}

## Given: 系統初始狀態
### 已登入用戶
（JSON 範例數據）

### 現有資料
（資料庫中的預存數據）

## When: 執行操作
### API 請求
（完整的 HTTP 請求範例）

### UI 操作
（如適用，描述用戶介面操作步驟）

## Then: 預期結果
### 系統響應
（API 響應範例）

### 數據庫變更
（哪些表新增/修改了記錄）

### 副作用
（發送通知、觸發事件等）

## 邊界條件
### 錯誤場景 1: {錯誤類型}
（錯誤輸入與預期錯誤響應）

## 自動化測試範例
（可執行的測試代碼片段）

Gherkin 範例

Feature: 建立訂單

  Scenario: 客戶成功建立花束訂單
    Given 客戶已登入系統
    And 購物車中有「經典玫瑰花束」1 件
    When 客戶填寫配送資訊
      | 欄位 | 值 |
      | 收件人 | 王小明 |
      | 電話 | 0912345678 |
      | 地址 | 台北市信義區信義路五段7號 |
      | 配送日期 | 2024-02-14 |
      | 配送時段 | 14:00-16:00 |
    And 客戶點擊「確認訂單」按鈕
    Then 系統顯示訂單確認頁面
    And 訂單狀態為「待確認」

  Scenario: 選擇的配送日期已額滿
    Given 客戶已登入系統
    And 購物車中有商品
    When 客戶選擇配送日期「2024-02-14」
    And 該日期配送名額已滿
    Then 系統顯示「此日期配送已額滿，請選擇其他日期」
    And 客戶無法提交訂單

實際案例: 花店管理系統 SBE

---

9. API 規格文檔

讀者: 前端開發者、後端開發者

內容: REST API 端點詳細規格

格式: 使用 /api-spec Skill 產生 Bruno (.bru) 格式的 API 規格，存放在 api-specs/ 目錄。

API 規格可透過兩種方式產生：

• 正向設計 — 從 US/SBE 設計 API 合約（Prototype 階段）
• 反向萃取 — 從 Spring Controller 提取已實作的 API 規格（整合階段）

實際案例: 花店管理系統 API 規格

---

10. 數據模型文檔

讀者: 後端開發者、DBA

內容: Entity 定義、關聯關係、欄位說明

數據模型範本

# {Entity 名稱}

## 表名
`{table_name}`

## 用途
（這個 Entity 的業務用途）

## 欄位定義

| 欄位名 | 類型 | 必填 | 說明 | 索引 |
|-------|------|------|------|------|
| id | UUID | Yes | 主鍵 | PK |
| tenant_id | UUID | Yes | 租戶 ID | FK, Index |
| ... | ... | ... | ... | ... |

## 關聯關係
- 一對多: Order → OrderItems
- 多對一: Order → Customer

## 約束條件
（Unique、Check、Default 等）

## 多租戶隔離
（如何確保數據隔離）

## 索引策略
（哪些欄位需要索引，為什麼）

## 範例數據
（JSON 格式的範例記錄）

實際案例: 花店管理系統數據模型

---

11. 架構決策記錄 (ADR)

讀者: 技術主管、架構師、資深開發者

內容: 重要的技術決策與取捨理由

ADR 範本（MADR 格式）

# ADR-{NNN}: {決策標題}

## 狀態
{已提議 | 已接受 | 已棄用 | 已取代} (日期)

## 背景
（為什麼需要做這個決策？遇到什麼問題？）

## 決策
（我們決定採用什麼方案？）

## 替代方案
1. 方案 A（為什麼被拒絕）
2. 方案 B（為什麼被拒絕）

## 後果
- 優點
- 缺點/權衡
- 需要注意的事項

## 參考資料
（相關文章、技術文檔鏈接）

實際案例: 花店管理系統架構決策

---

最佳實踐

1. 先寫規格再寫程式碼：確保需求明確再開始開發
2. 保持規格與程式碼同步：API 變更時同步更新 SBE
3. 使用具體範例：避免抽象描述，使用實際的輸入輸出值
4. 涵蓋邊界條件：除了 happy path，也要描述錯誤情境
5. 關聯測試案例：明確標示對應的測試位置
6. 多租戶意識：所有文檔都應考慮數據隔離

---

相關文檔

文檔	說明
開發流程指南	Step 1–4 開發流程、文檔工作流程、SBE 與後端的對應關係
AI 協助規格撰寫指南	AI Skill 的介入模式、蘇格拉底式閉環、Skill 鏈
Claude Code Skills 總覽	所有 Skill 快速參考索引

---

報表規格（RPT）

報表可依「業務契約草稿／原始樣張 → 有樣張時忠實還原 HTML＋CSS 並取得人類理解確認 → 根據樣張、規格與排版樣式設計採用版面／合成案例 → 完成 RPT → 人類確認最終採用 HTML → PDF 實作 → 自動驗證與 HTML 對照 → PDF 版面接受」獨立交付，不以 US 為前置條件。沒有原樣張時直接設計採用版面。 US 引用 RPT 後負責操作入口、流程、授權與交付；RPT 負責資料與印出來的文件。 命名為 docs/specs/reports/RPT-{NNN}-{kebab-case}.md，ID 不依附 Epic。 詳細欄位與固定版面契約見 報表規格指南。以下為共用範本的權威入口；不適用區段填明理由，不留待猜測的空白。

---
sidebar_position: {整數}
version: draft
report_id: RPT-{NNN}
layout_mode: flow # flow | fixed
execution_modes: {已確認的模式清單} # [sync] | [async] | [sync, async]
execution_default: {已確認的預設模式} # sync | async，必須在支援清單內
revision: 1
report_style_id: {專案樣式 ID}
report_style_revision: {正整數}
report_style_source: design/report-styles/{styleId}/rev-{styleRevision}.md
# depends_on 只列實際存在的直接上游，路徑相對於 docs/。
# 必須包含 report_style_source 指向的實際檔案；其他上游依需要列出。
---

# RPT-{NNN}：{名稱}

## 用途與交付邊界
用途、讀者、一份文件代表什麼、輸出格式、版次；引用的產品流程不在本規格授權。

## 執行方式
依指南「執行方式」填寫已確認的支援模式與預設，與 frontmatter 一致；範本沒有預設選擇。
模式如何選擇、不支援模式的拒絕結果；只有雙模式自動選擇時才定義切換條件、判定時點與邊界。
各模式的交付／失敗、等待／逾時及取消語意，引用承接的產品需求與 API 規格；未採 US 流程時沿用既有需求，不虛構 US。
三層共同硬上限獨立定義；需要時另列更嚴格的模式專屬上限及拒絕結果，不自動改送；單一模式不因筆數或逾時改走另一模式。模式專屬上限與自動選擇門檻依指南分開；HTML＋CSS 仍定義共用輸出外觀。

## 參數介面
呼叫端唯一依賴的契約；分業務參數與呼叫情境（可見資料範圍、快照時點、時區、語系、請求者）。

| 參數 ID | 類別 | 型別 | 必填／預設 | 合法值與單位 | 語意 |
|---|---|---|---|---|---|

參數規則、資料範圍（缺少即拒絕）、三層容量硬上限、錯誤契約。選擇模式的處理門檻只在「執行方式」適用時定義；詳見指南「參數介面」。任何契約改變依指南「版次」遞增 `revision`。

## 輸入與資料來源
資料粒度、來源與欄位映射（依 Domain Model）、篩選、排序、分組、幣別、計算、空值及異常；篩選條件引用參數 ID。
資料 adapter 只接受參數介面給定的範圍；不自行指定誰有權限。

## 欄位字典
| 欄位 ID | 業務語意／來源 | 型別／必填 | 格式／單位 | 空值／錯誤 |
|---|---|---|---|---|

## 資料容量與查詢成本契約
依指南「效能風險預測與查詢預算」宣告下表；與參數介面的三層硬上限及支援模式一致，不用測試人員反映耗時才啟動分析。

| 成本維度 | 最大值／單位／適用模式 | 容量層級／限制與判定時點 | 超量錯誤代碼／結果 |
|---|---|---|---|
| 頂層紀錄數（個案數）N | {單據／群組等粒度與上限；彙總型依指南定義} | 取數層；{受限取數策略與等於邊界的行為} | {依錯誤契約拒絕整次產生；不截斷} |
| 總明細數 D | {上限；無明細為 0 並說明} | 取數層；{受限明細取數與判定時點} | {依錯誤契約拒絕整次產生；不截斷明細} |
| 每個頂層紀錄明細數 | {上限} | 取數層；{逐主體受限判定} | {依錯誤契約拒絕整次產生} |
| 其他資料維度 | {含聚合前來源規模；不適用則明記理由} | {所屬容量層級與限制策略} | {對應拒絕代碼／結果} |

參數層的選取數量／期間與輸出層的頁數／檔案大小另列，不代替 N／D 的取數上限；取數超量拒絕、不產生部分成功文件。版面明細溢位只依版面契約完整續頁或拒絕，不授權截斷資料。

| 查詢範圍／模式 | SQL 次數上限或 Q(N,D) | 固定成本／批次大小／設計理由 | 驗證情境與預期 |
|---|---|---|---|
| {正式來源與計數界線} | {有界預算；無 DB 為 0} | {常數／依關聯分批預設；含逐筆線性項須依指南附有上界的設計說明} | {基本、增加 N、增加 D、最大及超容量} |

資料讀取階段完成完整純值投影；處理、排版／繪製及輸出階段業務資料讀取為 0。非 DB 來源另列呼叫／取數成本。
風險分析的位置、觸發條件、成本成長、已確認問題／可能風險／尚待實測、處置設計與執行量測存於證據附件，不將結果回填本契約。
可能超預算者須修正或提供可驗證的設計說明，verify 核對後才結案；容量／預算契約未決與量測缺口明列於能力對照。

## 版面契約
有原樣張時，先以 HTML＋CSS 完整保留原始範例資料與外觀，包含字體、字級及顏色；原錯誤或不合理處也原樣保留、另列觀察，不套用規格或專案樣式、不替換或遮蔽原資料。取得人類理解確認後才設計採用版面；無樣張時填明「無原始樣張」。
原件以 Git 保存為預設；新建可提交來源可放 docs 模組的 `sources/reports/{report}/{sourceId}/`，記錄來源版次、完整 SHA-256 及路徑／取回基準，既有來源不自動搬移。不能提交者依既有受控來源契約保存 locator／摘要；不以 ignored 展示副本作唯一原件，不自動下載或將原件放入採用包。保存與三關確認依指南「原件與證據保留」。
還原與採用入口分開標示，還原包不得放入採用包或被採用設計覆寫；原始樣張與完整還原直接透過同一內部專案文檔站的 `static/reports/restorations/{RPT-ID}/{restorationId}/` 提供。不能提交的原件仍保存於團隊受控儲存，本站使用固定展示副本；不另核對讀者／存取控制或改用另一個網站。原樣張、HTML 與全部必要資產的 HTTP bytes 核對及保存依指南「還原包存放與服務契約」，部署由人類決定，與確認流程分開；還原確認紀錄的固定相對連結見下方「證據與決策」。
採用 HTML＋CSS 是本規格的一部分；docs 模組的版面包 `static/reports/layouts/{RPT-ID}/` repository 相對路徑、各採用 HTML 預覽 URL 及合成情境。
依指南「HTML＋CSS 版面規格」保存 layout.json、CSS、字型、合成資料、differences.json（原樣張還原與採用版面的差異）、預覽環境及重現命令；站台連結使用指南的 pathname 協定與實際 baseUrl。
HTML／PDF 人審入口統一由 docs 模組的 Docusaurus 提供，依指南「Docusaurus 人類審閱服務」啟動／沿用服務並提供瀏覽器 URL；PDF 本輪 URL、runId 與指紋核對結果屬證據附件，不回填本規格。
欄位 ID 對應 HTML 元件；依原樣張、規格與排版樣式提出採用設計，列明相對還原版面的修改理由。提供基本、空資料、長文、跨頁及容量邊界等合成案例；不適用者明記理由。取得最終採用版面確認後才實作 PDF；還原理解確認不代替採用確認。Markdown 與採用 HTML 衝突時列出差異、決策並同步修訂。
共同：紙張、方向、尺寸、字型、頁次／聯別、頁首尾、空資料。
依指南「共用排版規範與區塊樣式」填寫 frontmatter 的樣式 ID、精確 revision 及來源，與來源的 style_id／style_revision 一致，將實際來源列入 depends_on；尚無規範時依下方共用規範範本建立專案草稿，新專案可複製完整推薦起點，既有專案保存已採用值。補齊全部有效值、API 映射、字型及不可獨立設定項目並記錄來源版本，未決設定完成前不確認採用 HTML 或實作 PDF；原樣張還原使用原樣式，可先完成理解確認。
執行時只依專案完整預設 → 本 RPT 覆寫 → 個別區塊／欄位覆寫；缺值不回退至框架預設。框架升級保留專案預設，採用新版樣式須明確修訂與驗證。
共用規範定義各區塊的字型、字級、字重、行高、段前／段後間距、表格內距與區塊間距；不適用屬性明記理由。
本 RPT 只列覆寫及理由，不複製共用規範全文；layout.json 保存各區塊最終解析值，HTML／PDF 使用同一組設定。

| 層級／區塊或欄位 ID | 繼承角色／變體 | 覆寫屬性與值（含單位） | 調整原因 |
|---|---|---|---|
| {整份報表或區塊／欄位 ID} | {共用樣式角色} | {只有差異；無則明記沿用} | {需求依據} |

flow：欄寬、換行、表頭重複、列可拆分性、分組、小計／總計、分頁。
fixed：依指南填寫座標系、列印模式、圖層、定位表、重複明細、溢位、底圖與校準。

## 圖形與機讀欄位
Logo、簽名／蓋章區、圖片；條碼／QR 的格式、payload、來源、校驗責任、尺寸、靜區、掃讀驗收。
未使用時明示「無」；簽名留白不等於電子簽章。

## 驗收案例與預期
| ID | 輸入／情境 | 預期內容與位置 | 驗證方式／容差 |
|---|---|---|---|

成本案例須經正式 adapter 核對預算及成長、後續階段零業務資料讀取，確認問題對應查詢成本回歸測試；修正後核對內容與已接受版面。單次執行 SQL／重複結構摘要及分段耗時依指南，耗時實測記執行環境，不以不穩定秒數作為一般單元測試門檻。

## 實作與能力對照
規格要求 → 框架 API／adapter → 測試 ID；未支援能力標為缺口，不因規格可描述就標成可用。
分開列風險分析、執行隔離量測與成本回歸支援；框架提供支援，應用端修正業務查詢，不自動改寫查詢或 Entity 映射。未接正式來源時明列未分析／未量測，不由範本通過推定完成。

## 證據與決策
只記 restoration-confirmation.json（無樣張時不適用）／html-evidence.json／evidence.json 固定的相對連結及契約決策。原樣張與還原檔案摘要、還原理解確認、採用 HTML 版面包摘要與確認、PDF SHA-256、自動化結果、AI 視覺檢視、PDF 接受、實紙／掃讀結果保存於各自帳本及附件；不將結果回寫本規格，以免改變來源指紋。還原確認由作者依指南保存，現行 helper 只承接採用 HTML 與 PDF。
另連結固定證據目錄 docs/testing/reports/{RPT-ID}/；各輪 runs/{runId}/performance-review.md 保存風險／處置、來源摘要、成本測試與脫敏量測，於 PDF record 前納入宣告來源。helper 不分析效能或自動檢查預算完整性；verified／layout-accepted 不等於正式來源效能交付完成。

RPT 沿用 reference／draft／published 的語意；目前 /report 只建立 draft，沒有自動 published 入口，驗證／版面接受不代表規格定案。revision 是表單內容版次，不是框架套件版本。 現有 US 階段與 skill 不因新增 RPT 自動改變；沒有 US 的報表以自身驗收表追蹤，不虛構 US 或推進 Sprint。

證據保存與跨 clone 條件見 報表規格指南；先改契約、再測試及 record，不在 record 後回填規格進度。

報表共用排版規範範本

保存路徑為 docs/design/report-styles/{styleId}/rev-{styleRevision}.md，同層 rev-{styleRevision}.json 保存完整有效值；字型及資產另保存固定版本與摘要。這裡是欄位格式的權威入口；完整可複製的數值與 API 映射見 報表排版推薦起點。新專案可複製該起點，既有專案以已採用設定回填。

---
sidebar_position: {同目錄不重複整數}
version: draft
style_id: {專案穩定 ID}
style_revision: 1
style_value_schema: 1 # 本範本欄位格式版次，不表示框架有載入器
style_values: design/report-styles/{styleId}/rev-1.json # 相對於 docs/
locales: [zh-TW, en]
layout_modes: [flow]
initialized_from: {推薦 profile ID@revision 或既有已採用來源}
framework_version: {實際已安裝版本}
# depends_on 只列實際存在的直接上游文檔；資產另記清單及摘要。
---

# {styleId} 排版規範：revision 1

## 完整值與初始化來源
引用同版 JSON；保存全部 DocumentStyles.text／paragraph／headings 1–4／table／box 值、所有角色完整值及字型映射，不能只有相對框架的差異。
文字：family、sizePt、weight、italic、color。
段落：align、lineHeight、spaceBeforeMm、spaceAfterMm、firstLineIndentMm、keepWithNext、orphans、widows。
表格：完整文字、headerFill／groupFill／totalFill、rule、cellPadding、continuationLabel、cellBorders；四邊 padding、對齊、列高及角色框線。
區塊框：border、fill、padding。所有幾何值以 mm、字級以 pt、flow 行高以倍數；0／false 是明確值。
不適用欄位明記理由，不以 null 隱含繼承框架；公開 API 無法獨立設定者另列當時值／規則。

## 區塊角色
至少逐列記錄 report-title、section-heading、metadata、body、table-header、table-body、table-group-header、table-subtotal、table-total、note、page-header、page-footer；使用圖形時納入 figure-caption。

| 角色／變體 ID | 字型／字級／字重／斜體／顏色 | 對齊／行高／段距／縮排／分頁屬性 | padding／列高／底色／框線／區塊距離（不適用註明） | API 落點與可設定性 |
|---|---|---|---|---|
| {角色} | {完整值或本固定版次內具名來源；JSON 展開最終值} | {含單位} | {含單位} | {DocumentStyles 欄位、Heading 層級、Paragraph 建構子 style 參數、RowRole 或衍生規則} |

## 字型映射與授權
| 邏輯家族／字面 | 依序 fallback 檔案（相對資產包） | 固定來源版本／URL／SHA-256 | 授權檔／缺字處理 |
|---|---|---|---|
| {sans／regular、bold；不用的字面明記停用} | {不得依賴系統字型} | {每檔摘要} | {授權聲明／必需字元缺字即驗收失敗} |

## 不可獨立設定項目
至少核對推薦起點的頁首尾 gap／樣式／高度／分隔線、圖說 gap／樣式、非明細粗體合併、摘要列填色與區塊段距規則。

| 項目 | 當時有效值／衍生規則 | API／source／框架版本 | 限制、升級比對與必要缺口 |
|---|---|---|---|
| {項目} | {含單位；記錄不代表已可設定} | {實際來源} | {比較常數與輸出；變更影響版面時不得靜默採用} |

## 間距、採用與歷史版本
明定相鄰距離合成、內容頁首省略、跨頁、表內段距與溢位；引用同版 HTML 展示／資產及重現命令。
已採用版次保留原檔；新值新增 rev-2.md／rev-2.json。RPT 以 report_style_id／report_style_revision／report_style_source 及 depends_on 精確引用，來源 frontmatter 必須一致。
框架升級保留完整值；檢查不可設定常數與 renderer 相容性。採用新樣式時明確修訂並依 RPT 流程取得證據與接受。

共用文檔與 JSON 均須納入 HTML --source，字型 manifest 與版面包內字型 bytes 納入包摘要；Java 完整樣式與其資產來源由 PDF --source 承接。上述 frontmatter 是方法論契約，目前 evidence helper 不自動驗證 ID／revision／JSON 完整度；採用時由人工或專案檢查核對。

最後更新: 2026-10-07