ADR-017: RPT 以參數介面作為對外契約
ADR 編號: 017 狀態: 已採納 (Accepted) 提案日期: 2026-10-01 決策日期: 2026-10-01 最後修訂: 2026-10-04 決策者: 團隊 peer review：兩輪通過（第 1 輪 3 條 major，第 2 輪全數落實） 範圍: RPT 報表規格、
/report、/us引用 RPT 的方式、報表與 US 的測試分工
摘要
RPT 與 US 的責任原本已經分開：US 以 depends_on 單向引用 RPT，範本與合成資料驗證不需要 US。但 RPT 範本只在「輸入與資料來源」以一段敘述帶過「參數」，沒有可對接的介面。US 引用報表時只能自行理解 RPT 內部，兩者因此容易耦合；同一份報表也難以給排程或對外 API 重用。
本決策讓 RPT 以參數介面作為唯一對外契約。US 與其他呼叫端只依參數介面產生文件，不依賴報表內部的資料取得與排版。
決策
依賴分層
| 層 | 依賴 | 測試方式 |
|---|---|---|
| 範本 | 只依賴輸入模型 | 合成輸入 |
| 資料 adapter | Domain Model 與資料存取 | 可重複的資料庫測試資料 |
| 參數介面 | 呼叫端唯一依賴的契約 | 參數規則、範圍、容量、錯誤契約 |
| 引用的 US | 只依賴參數介面 | 畫面操作到參數的對應、授權、job／下載流程 |
參數分兩類
- 業務參數：使用者或呼叫流程選擇，例如期間、客戶、狀態、排序。
- 呼叫情境：呼叫端依授權結果填入，使用者不能直接指定，包括可見資料範圍、快照時點、時區、語系、請求者。
RPT 不判斷誰有權限，只輸出呼叫情境給定範圍內的資料；缺少範圍時拒絕產生，不以「全部」代替。快照時點與時區一律為明確參數，不隱含使用伺服器時鐘或使用者語系。
資料範圍的驗證責任
- 範本階段以合成輸入驗證輸出。
- 接入正式資料 adapter 後，由 RPT verify 以同時含範圍內外資料的可重複資料庫測試資料，經 adapter 實際查詢，驗證範圍條件確實套用於查詢。只驗證傳入的範圍值或已篩好的 fixtures 不能證明。
- 引用的 US 只驗證呼叫情境填入正確，不重驗查詢與文件內容。
容量分三層
| 層 | 判定時點 |
|---|---|
| 參數上限（期間長度、選取數量） | 產生前 |
| 取數上限（實際筆數） | adapter 受限取數，例如最多取上限加一筆 |
| 輸出上限（頁數、檔案大小） | 排版時 |
另區分處理門檻（超過時改走非同步）與硬上限（同步或非同步都拒絕）；改走非同步不能突破硬上限。
2026-10-04 修訂：明訂執行方式（已採納）
以上保留 2026-10-01 的決策歷史。本次修訂將處理門檻限定於 RPT 已宣告雙模式且自動選擇的情況；
每份 RPT 明訂 execution_modes、execution_default 與選擇規則，僅同步／僅非同步不設切換門檻。
允許更嚴格的模式專屬上限，超出只拒絕本次指定模式，不視為自動選擇或已建立 job；
共同硬上限仍對所有模式生效。可改選 async 的拒絕代碼只適用規格確實支援且符合 async 限制的情況。
容量硬上限對所有模式生效；等待逾時不自動授權建立 job、改模式或重試。
欄位及交付／取消責任的權威定義見報表規格指南「執行方式」
（docs-methodology/specs/report-specification.md）。產品 API 承接路由、授權及工作生命週期；HTML＋CSS 繼續定義版面。
考量的方案：沿用隱含「超門檻必須非同步」會讓單一同步報表被迫建立背景流程； 把模式只留給產品 API 又使 RPT 無法表達支援邊界。因此由 RPT 定義允許的方式，由產品契約承接操作。 未採 US 流程時沿用專案既有產品需求與 API 規格，不虛構 US／Epic／SBE。
版次
revision 是表單內容版次，涵蓋整份 RPT 契約：參數介面、計算、輸出內容或版面任一改變都遞增，並以 /impact 檢視引用的 US。是否修訂 US 依影響分析判定，不因參數形狀不變就推定無影響：
- 參數介面不相容：修訂 US 的參數對應。
- 呼叫端依賴的輸出語意改變（計算、欄位意義）：修訂 US，並依
m-change-management.md處理。 - 分析後無影響：US 只更新記錄的
revision，屬追溯更新，不重述或重驗 RPT 內容、不觸發階段回退。
考量的方案
| 方案 | 結論 | 理由 |
|---|---|---|
| A. 維持現狀：參數只在「輸入與資料來源」敘述 | 不採用 | US 沒有可對接的契約，只能理解 RPT 內部；變更影響無從判定 |
| B. 參數介面作為 RPT 的正式一節（本決策） | 採用 | 契約集中在權威指南與範本，不新增 rule 檔；rules 只加交叉引用 |
| C. 另立獨立的報表介面規格文件 | 不採用 | 與 RPT 一對一，拆檔只增加同步負擔 |
| D. 由 RPT 自行判斷權限 | 不採用 | 授權屬產品流程；RPT 判權會把 US 的責任拉回報表，並讓排程等無使用者情境無法表達 |
影響範圍
| 檔案 | 變更 |
|---|---|
docs-methodology/specs/report-specification.md | 「與 US 的責任」以參數介面為分界；新增「參數介面」節；驗證與交付補參數介面與兩段範圍驗證 |
docs-methodology/specs/README.md | RPT 範本新增「參數介面」節 |
.claude/skills/report/SKILL.md | 1.1.0：spec 先定參數介面；impl 入口只接受參數介面、依三層判定容量；verify 涵蓋參數介面與正式 adapter 範圍測試；status 新增該項 |
.claude/skills/us/SKILL.md | 引用 RPT 時記錄驗收時採用的 revision、參數對應與呼叫情境來源 |
.claude/rules/m-dev-guardrails.md、m-methodology.md | 交叉引用 |
非目標
- 不修改
evidence.py：helper 仍只核對指紋與 JUnit 結果，不判斷測試涵蓋的業務語意。 - 不修改
/impl的上游變更偵測。 - 不在本決策中修訂既有 RPT。
審閱裁決
審閱方未裁決以下待決點，已轉為 follow-up：
| 待決點 | 處置 |
|---|---|
| 既有 RPT-001 是否補上參數介面 | FU-111 |
| 參數測試的涵蓋是否由 evidence helper 強制 | FU-112 |
/impl 上游變更偵測是否改為比對 US 記錄的 RPT revision | FU-113 |
相關文檔
變更歷史
| 日期 | 內容 |
|---|---|
| 2026-10-01 | 初版；第 1 輪依 3 條 major 補明正式 adapter 範圍測試責任、容量三層與處理門檻、版次與影響判定；第 2 輪通過 |
| 2026-10-04 | 已採納執行方式修訂：RPT 明訂支援模式、預設、選擇規則與模式專屬上限的拒絕語意；保留原決策歷史。20261004-report-execution-modes 第二輪審閱通過 |