報表與固定版面表單規格
報表規格（RPT）同時涵蓋流式報表與固定版面表單；可獨立建立、實作與驗證。 共用範本在 規格總覽。本指南定義需填寫的契約，不表示所有能力已由目前發布的程式庫支援。
HTML 版面規格機制已經 peer review 通過並採納，決策與受控包登錄的工具缺口見 ADR-020。
與 US 的責任
RPT 以參數介面對外：US 與其他呼叫端（排程、對外 API）只依參數介面產生文件，不依賴報表內部的資料取得與排版。
| RPT | 引用 RPT 的 US |
|---|---|
| 參數介面與執行契約：參數、呼叫情境、支援模式、預設與選擇規則、容量及錯誤契約 | 畫面操作如何對應到參數與支援模式；呼叫情境由誰、依何授權填入；實際 API 交付 |
| 用途、資料來源、計算及快照語意 | 誰在何時以什麼操作產生文件 |
| 格式、位置、分頁、列印及文件內容驗收 | 權限、可見資料範圍的決定、job／下載／重印流程 |
| 給定參數與範圍時的輸出正確性：合成資料、樣張、內容及版面證據；接入正式資料 adapter 後的範圍查詢整合測試 | 使用者取得正確範圍（呼叫情境填入正確）、參數對應及生命週期整合驗收；不重驗文件內容 |
US 在 depends_on 引用 specs/reports/RPT-…md，並記錄驗收時採用的 RPT revision 與參數對應。
RPT 不必反向依賴引用它的 US，避免循環；資料 adapter 依賴 Domain Model，範本只依賴輸入模型。
只有範本與合成資料驗證時，不能宣稱正式資料授權或產品流程已驗收。
未採 US 流程的專案，以既有產品需求及 API 規格承接操作、授權與交付；不為報表虛構 US／Epic／SBE，也不能只憑 RPT 宣稱產品流程已驗收。
程式責任分區
report 集中 RPT 的參數契約、純值模型、計算、範本與 generator；資料來源介面由 report 擁有，
正式 DB adapter 放 repository，service 承接授權範圍、一致性讀取交易及產品流程。
沿專案 businessLayout 使用 report/{domain}/ 或 {domain}/report/。
完整依賴與搬移要求見 報表責任分區；HTML＋CSS 是溝通及確認版面的規格，Java 負責實作。
參數介面
參數介面是 RPT 的對外契約（決策見 ADR-017）。依呼叫端是否可自由選擇，分成兩類：
| 類別 | 由誰決定 | 例子 |
|---|---|---|
| 業務參數 | 使用者或呼叫流程選擇 | 期間、客戶、狀態、排序、聯別 |
| 呼叫情境 | 呼叫端依授權結果填入，使用者不能直接指定 | 可見資料範圍、快照時點、時區、語系、請求者（稽核用） |
逐項定義於參數表：
| 參數 ID | 類別 | 型別 | 必填／預設 | 合法值與單位 | 語意 |
|---|
另須明定：
- 參數規則：跨參數條件（如
from <= to、期間上限、互斥或必須同時出現的參數）。 - 資料範圍：報表只輸出呼叫情境所給範圍內的資料；缺少範圍時拒絕產生，不以「全部」代替。RPT 不判斷誰有權限。
- 時間語意：快照時點與時區一律為明確參數，不隱含使用伺服器時鐘或使用者語系（見
m-date-time.md）。 - 容量：依可判定的時點分三層，各自定義上限與超出時的錯誤：
- 參數上限：期間長度、選取數量等，產生前即可檢查。
- 取數上限：實際資料筆數，由 adapter 以受限取數判定（例如最多取上限加一筆），不先查全部再計數。
- 輸出上限：頁數、檔案大小等，於排版時判定。 共同容量硬上限獨立於執行方式；超過時所有支援模式都拒絕。可另外明訂模式專屬上限，及雙模式自動選擇的處理門檻，三者不能混用；模式專屬上限不得放寬共同硬上限。產品流程依參數上限限制畫面輸入，並處理取數與輸出上限的錯誤。
- 錯誤契約：參數不合法、缺少或越界的範圍、各層容量超出、查無資料各自的結果與錯誤代碼，供呼叫端對應到畫面訊息。
- 版次：
revision是表單內容版次，涵蓋整份 RPT 契約。參數介面、執行契約、計算、輸出欄位或內容、版面任一改變都遞增revision，並檢視引用的產品需求與 API；採 US 流程時以/impact檢視引用的 US。 是否修訂 US 依影響分析判定，不因參數形狀不變就推定無影響：參數介面不相容時須修訂參數對應；呼叫端依賴的輸出語意改變（例如計算、欄位意義）時須修訂 US 並依m-change-management.md處理。 分析後無影響者，US 只更新記錄的revision，屬追溯更新，不重述或重驗 RPT 內容、不觸發階段回退。
執行方式
每份 RPT 必須明訂支援的執行方式。權威欄位為 frontmatter 的 execution_modes 與 execution_default，選擇及交付規則寫在本節；兩處須一致。
| 支援方式 | execution_modes | execution_default | 選擇規則 |
|---|---|---|---|
| 僅同步 | [sync] | sync | 同一次請求完成產生並交付 PDF；不切換背景工作 |
| 僅非同步 | [async] | async | 接受工作後取得工作識別碼，再依產品 API 查詢及取得 PDF |
| 兩者皆支援 | [sync, async] | sync 或 async | 明訂由呼叫端選擇或依條件自動選擇，不能只列兩種模式 |
模式清單必須非空、無重複且只含 sync／async；預設必須在支援清單內，單一模式的預設就是該模式。
模式順序不表示優先序，也不採 both 作為第三個模式值。新建或修訂 RPT 時先取得決策，不以範本示例、預估速度或框架已安裝 job 能力推定預設。
本節另須定義：
- 選擇與切換：未指定模式時由產品呼叫端套用預設；不代表 Java 入口必須接受 null。明訂產品 API 是否允許呼叫端指定模式，以及不支援模式的拒絕結果與錯誤代碼。雙模式若自動選擇，明訂判定時點、條件／門檻單位、等於邊界的結果、與明示模式／預設的優先序及如何通知呼叫端實際採用的模式。單一模式不設切換門檻。
- 交付與失敗：各支援模式的成功、空資料及失敗結果；同步交付 PDF，非同步交付工作識別碼及後續結果。路由、HTTP 狀態、job 擁有者授權、保存／下載／重試流程由產品需求與 API 規格承接，引用本 RPT 的規則，不在範本內管理 job。
- 等待與取消：記錄產品 API 所採用的等待／逾時與取消語意、單位及適用層。前端停止等待不等於伺服器已取消；逾時不自動授權切換非同步、建立 job 或重試。未實作伺服器取消時明示此界線。
- 容量與輸出：三層共同硬上限分別定義，不將「超過某筆數」直接等同必須非同步。允許更嚴格的模式專屬上限，須列模式、適用範圍、數值／單位、判定時點、等於邊界與拒絕代碼；未列即不另設。超過模式專屬上限只拒絕該次要求，不自動改送另一模式。只有 RPT 支援 async 且符合其限制時，才能回「可改選非同步」的錯誤（例如
async-required）；這是拒絕及建議，不代表已建立 job，改送須由產品流程另行決定。僅同步時不能用該錯誤暗示未支援模式。雙模式共用同一輸出內容與已確認的 HTML 版面；若有允許差異，必須在 RPT 明列並驗證。
規格欄位是契約，不代表 evidence helper 或框架已提供模式校驗、排程或取消功能。實作前按責任核對產品 API 與 renderer 的實際能力。 缺少欄位的規格不推定支援模式；先核對原決策及產品契約，再完成修訂。方法論更新本身不批次改既有 RPT、版次或接受帳本；實際修訂仍依既有 HTML／PDF 指紋及接受規則處理。
效能風險預測與查詢預算
效能分析是每份 RPT 的開發與交付要求，不以專用測試資料齊備、測試人員回報耗時或線上事故作為啟動前提。 靜態分析預測的是查詢成本的成長與設計風險，不能精確預測秒數；SQL 次數符合預算也不代表查詢、記憶體或排版一定夠快。
容量與成本契約
每份 RPT 在實作前宣告以下契約；範本階段尚未接入正式來源者，也須宣告預期容量與查詢預算，將正式來源分析／量測列為未完成。
| 項目 | 必填內容 |
|---|---|
| 最大資料量 | 頂層紀錄數（個案數）N、總明細數 D、每個頂層紀錄的明細上限及其他會放大成本的維度、單位與適用模式；各自對應三層容量硬上限與超量錯誤代碼 |
| 查詢預算 | 一次執行可接受的 SQL 次數上限或有界公式 Q(N,D)、固定成本、分批大小及理由；適用資料庫／來源、模式與計數範圍 |
| 資料處理界線 | 取數限制與分批／分頁策略、完整純值投影完成時點；處理、排版／繪製不得再讀取業務資料 |
| 驗證計畫 | 基本、增加個案、增加明細、最大容量與超容量的查詢成本預期，以及需要實測的查詢計畫、記憶體或耗時命題 |
N 是報表的頂層紀錄單位，RPT 必須定義其業務粒度：例如每份單據或每個群組主體；fixed 單份單據通常為 1，批量產生則為單據數。彙總型報表以實際取得的群組紀錄數計 N，全體彙總只有一個總計時為 1，無頂層紀錄時為 0；不呈現明細時 D 可為 0。聚合前需處理的來源資料量仍須另列有界維度與驗證，不能以輸出 N=1 或 D=0 掩蓋大量來源成本。
N、D 與每個頂層紀錄的明細數各自是取數層硬上限，由 adapter 受限取數判定；參數中的選取數量、期間等仍屬參數層，頁數／檔案大小屬輸出層，不互相代替。RPT 為每項上限列出判定方法、等於邊界的行為與超量錯誤代碼，並在參數介面的錯誤契約引用同一組定義；可以共用超量代碼，但須能識別超出的維度且不含個案資料。任一取數維度超出時拒絕整次產生，不靜默截斷頂層紀錄或明細、不輸出部分成功文件；上限加一筆等探測資料不得進入正式輸出。版面明細溢位另依版面契約完整續頁或拒絕，不能當作截斷資料的授權。
預算須由資料取得設計推導，不把目前量到的 N+1 成本原樣當作合理預算。預設合理成長為常數或依關聯分批的 ceil(N/B)／ceil(D/B)，其中 B 為有理由且受限的批次大小；多個關聯須合併計算，不能以 B=1 將逐筆查詢改名為批次。含逐案／逐明細線性項者預設不合理，只有在對應取數硬上限下，依「交付前處置」附觸發條件、上界推導、設計理由及驗證案例，且經 verify 證明符合預算才可接受；沒有通用絕對次數門檻。不同模式可有不同預算，但不能放寬共同容量硬上限，也不能以改送非同步免除查詢風險處置。
無 DB 來源者明記 SQL 預算為 0；外部 API／檔案等資料讀取另列呼叫與取數成本，不以 SQL 為 0 推定沒有效能風險。
容量、預算或處理界線的契約變更依既有規則遞增 revision；只更新分析、量測結果或實作而契約未改，不因結果回填而修改 RPT。
開發階段分析與可追溯預測
impl 在設計資料取得時、正式 adapter 接入時及相關來源修正後，沿 generator → Source adapter → query／repository → Entity 映射及純值投影檢查完整路徑。
即使沒有測試資料也先分析；尚未存在的 adapter、映射或執行計畫列為缺口，不推定安全。最低檢查範圍如下：
| 風險 | 檢查重點 |
|---|---|
| 迴圈內查詢 | 每案／每筆明細的 repository、代碼標籤或外部讀取；巢狀迴圈及分批行為 |
| 隱藏關聯載入 | Entity getter、集合走訪、投影／mapper、序列化及 eager／lazy 關聯；不能只搜尋顯式 repository 呼叫 |
| 反向一對一逐筆查詢 | mappedBy 一端的存在性／關聯載入；依實際 ORM 版本、映射、enhancement 與存取方式判定，不因宣告 LAZY 就推定不查詢，也不把所有反向一對一一律判為 N+1 |
| 無界取數 | 無限制查詢、全取後篩選／計數、未限制明細集合、多集合 join 的列數放大；limit 是否真的在資料庫生效 |
| 繪製期間資料讀取 | 未完成物化的 stream／iterator、supplier、代理物件或回呼，在處理、排版／繪製及輸出期間再次讀取資料 |
每條發現有穩定 ID，保存程式相對路徑、類別／方法／行號與來源摘要，列出觸發條件、查詢或映射證據、成本公式／成長趨勢、最大容量下與預算的比較、處置及對應驗證 ID。 區分以下判定，不將推測寫成已量到的事實：
| 判定 | 所需依據 |
|---|---|
| 已確認問題 | 程式路徑與設定足以證明問題，或執行量測已重現；明記是靜態確認或實測確認，不虛構耗時 |
| 可能風險 | 有可定位路徑，但是否觸發仍依 ORM、資料分布、快取或載入狀態；列出假設及確認方式 |
| 尚待實測 | 查詢計畫、索引選擇、I/O、記憶體或耗時等無法靠靜態分析定案；列環境與實測命題 |
以下為成本示意：固定 Q0 次取數後，每案另查一次為 Q0 + N，每筆明細另查一次為 Q0 + D；批次大小為 B 的單一明細批查可為 Q0 + ceil(N/B)，但仍須檢查其他關聯及明細列數成本。
D 已是總明細數時，不再把成本寫成 N × D；只有每案明細數另定為 d 才使用 N × d。這些公式說明 SQL 次數，不換算成精確秒數，也不掩蓋單次昂貴查詢。
交付前處置
預測可能超出預算的已確認問題或可能風險，須修正，或提供可驗證的設計說明：條件、上界推導、避免觸發的機制、來源位置與驗證案例。
「資料應該不多」「已有快取」「等測試人員反映」及只提高預算都不足以結案。設計說明須在 verify 核對；仍未證明符合預算、來源未分析或量測缺失者，標為交付缺口，不能只憑內容／版面通過宣稱整份 RPT 完成。
範本及合成資料工作可先完成並記錄 PDF 版面接受；該接受不解除正式資料成本與產品整合的交付要求。
單次執行量測契約
框架負責提供分析、量測與驗證支援；應用端負責在正式資料 adapter／generator／產品呼叫端接入量測，以及修正業務查詢。 量測須涵蓋一次報表執行自資料取得開始，直到輸出寫入完成；明列與 job 排隊、提交、狀態更新及後續下載的界線。重試以執行／嘗試識別分開，不能只報成功嘗試而隱藏前次成本。
| 指標 | 記錄要求 |
|---|---|
| SQL 計數 | 計數實際執行的 statement，說明 batch 計數方式、資料源及涵蓋讀／寫範圍；列總數與各階段數，不以日誌行數代替 |
| 重複查詢摘要 | 依移除參數、字面常數與註解後的 SQL 結構指紋分組，保存指紋及次數；重複形狀是診斷訊號，不直接等同 N+1 |
| 分段耗時 | 資料讀取、純值處理／計算、排版／繪製、輸出各段與全程時間、單位及量測邊界；使用單調時計，重疊／巢狀階段明記，不能直接相加冒充總耗時 |
| 執行脈絡 | 不含業務識別的 run／attempt ID、實際 N／D、輸出頁數／大小、成功／失敗／取消，以及量測完整性與缺口 |
執行關聯須在工作執行緒／非同步子工作中明確傳遞與清理；並行報表、無關 API 與同一連線被重用時仍須隔離。
執行期或任何可能並行的情境，不得以全域 Hibernate Statistics／資料庫全域計數器的前後差冒充單次報表 SQL 數；無法可靠歸屬時標示量測不完整，不能用該結果判定通過。僅 verify 的獨佔成本回歸測試可採全域差值，條件與證據依下節；該測試不能證明執行期的單次隔離量測已具備。
不得記錄個案資料、業務參數、SQL bind 值或含字面常數的原始 SQL；只保存脫敏結構指紋與統計，例外訊息、診斷附件及測試輸出也遵守此界線。
若 renderer 只能提供合併階段時間，明列不能拆分的能力缺口，不填造分段數字。框架不得自動改寫應用查詢或 Entity 關聯映射而改變報表語意。
查詢成本回歸與證據
verify 以可重複的資料庫合成資料經正式 adapter 執行，將每個確認問題轉為對應風險 ID 的查詢成本回歸測試。
分別增加 N 與 D，涵蓋空資料、基本、最大容量及超量拒絕；資料含有／無關聯與範圍內外條件，依風險選擇適用組合。
斷言總 SQL 次數上界、隨資料增長的預期及處理／排版／繪製／輸出階段業務資料讀取為 0；不能只驗 mock 呼叫次數或只驗一筆資料。
計數排除 seed／fixture 準備，明訂 flush、Persistence Context、二級快取與查詢快取狀態，至少覆蓋不靠既有載入／快取掩蓋問題的情境。
框架尚無隔離計數時，獨佔成本回歸測試可使用全域統計前後差：測試須獨佔受計數的 SessionFactory／資料源及其計數範圍，禁止其他測試、請求、背景工作或非同步殘留在量測期間存取；fixture／必要 flush 完成後清空統計或取得基線，明列每個被測階段的起迄與差值。附件記錄如何確保獨佔、排除準備成本、計數 API 與涵蓋的 statement／batch 語意；無法確保獨佔或統計不能證明某階段業務讀取為 0 時，該斷言仍是未驗證缺口。此例外只驗成本回歸，不替代執行期隔離、重複查詢摘要及分段耗時的交付證據。
量測支援須有並行報表與無關請求的隔離驗證、工作結束／例外後清理及不輸出敏感資料的驗證。
查詢修正後，同時核對排序、分組、計算、空值、範圍、完整明細及已接受 HTML／PDF 版面，避免優化改變語意。
耗時驗證另記 CPU／記憶體、OS、JDK／框架／ORM／renderer、資料庫版本／拓撲／索引、資料規模、快取與暖機、並行負載及重跑次數；有 SLA 時記錄其條件與量測結果。
一般單元測試採確定性的成本／內容斷言，不以不穩定的秒數為門檻；環境受控的效能驗證另行執行，未完成者標為尚待實測。
有對外契約 SLA 或並行負載命題時，由 ADR-008 的 sim 模組／/sim-plan 承接里程碑 NFR 計畫與報告，沿用 SLA 與三面向觀測；本節單次診斷及成本回歸提供定位與回歸證據，不另建一套 SLA／壓測閘門，也不將里程碑壓測改成一般單元測試。
風險分析、處置、量測摘要及測試對照保存於 docs/testing/reports/{RPT-ID}/runs/{runId}/performance-review.md（需要機讀統計時同輪另附 JSON），RPT 只放契約與固定證據目錄連結。
附件記錄 RPT revision、實際框架版本、分析來源摘要與測試／重現命令；重驗使用新 run，不覆寫歷史。
PDF record --source 須涵蓋 query／Entity 映射、adapter／投影、generator、量測接入、成本測試／fixture、相關設定及本輪成本分析／回歸附件 performance-review.md 與必要統計；先完成附件再 record，不將帳本反向納入附件來源造成循環指紋。這使本輪成本結論可追溯到同一來源，附件定稿後不可為更新結論而覆寫。
後續獨立受控耗時驗證可保存於新 runs/{runId}/performance-timing.md 或 sim 報告，不加入已完成的 PDF record 指紋，也不修改舊 performance-review.md。補充結果須引用原成本附件的路徑與 SHA-256、RPT revision、PDF SHA-256、相關實作／設定來源摘要及量測環境／命令；status 核對這些來源仍相符，才可承接「尚待實測」的結論。只增加相符來源的耗時證據不使原 PDF 證據 stale、不要求重新 record／carry-acceptance；若結果引發契約、實作、成本測試或已指紋附件的修改，仍須依既有規則新 run 重驗／重錄，再依精確 PDF bytes 與契約判定是否可 carry-acceptance。補充耗時結果不補造缺少的隔離計數或其他量測能力。
本節是流程與證據契約；現行 evidence helper 只核對已宣告來源／PDF／JUnit 的結果與指紋，不分析查詢、不量測 SQL，也不自動判斷預算或效能附件的語意完整性。impl／verify／status 須另核對本節，verified／layout-accepted 不能代替效能交付結論。
實作前核對已發布框架及應用接入的實際支援；缺少隔離計數、重複摘要或分段量測者列明能力缺口，不宣稱本次方法論修訂已交付量測 API。
框架量測支援缺口於團隊現行 follow-up backlog 追蹤；待辦存在或獨佔成本測試通過都不等於量測能力已交付，下游仍依實際已發布版本核對能力缺口。
方法論更新本身不批次改既有 RPT／接受帳本，也不撤銷已有效的版面接受。新建 RPT 適用本節；更新前已有效接受、正式來源未變且未依本節重新 record 的舊報表，在 status 分開標為「效能流程未導入（既有、來源未變）」，不只因缺效能附件列為「適用但缺口」。既有報表首次正式來源修訂或首次重新 PDF record 時導入本節；已有有效效能證據者持續核對來源，契約實際變更仍沿既有版次與接受規則處理。無法證明原接受有效或來源未變者明列待核對，不能推定豁免或掩蓋原有 stale。
版面模式
| 模式 | 適用 | 必須定義 |
|---|---|---|
flow | 明細、統計、可調整的月結對帳單 | 欄寬、換行、群組、彙總、表頭重複、分頁策略 |
fixed | 繳款單、訂購單、簽收單、預印表單套印 | 實體尺寸、絕對座標、區塊容量、溢位與續頁、列印模式 |
同一固定頁可有文字換行和定量明細，但不能因內容增加把其他欄位往下推移。 固定位置是輸出契約；不是「整張表單永遠只有一頁」。一個業務物件可以輸出多頁、多聯或明確設計的續頁。
共用排版規範與區塊樣式
報表以共用排版規範為起點，依需求覆寫；字型、字級、字重、行高與間距須一起定義。 框架提供建立專案時的推薦起點與樣式合併機制；每個製作報表的專案必須保存自己的完整預設，個別 RPT 記錄採用版本與差異。
規範來源與繼承
- 框架推薦起點：新專案可複製 報表排版推薦起點 的完整值、字型清單與 HTML 展示；該 profile 參考
DocumentStyles.standard()，另補齊區塊角色。記錄推薦 profile revision、已安裝框架版本及來源；它不是執行時的隱含父樣式，也不是所有框架版本的固定值。 - 專案預設：製作首份報表前，依 共用規範範本 建立完整預設，保存於
{docsRoot}/docs/design/report-styles/{styleId}/rev-{styleRevision}.md，同層保存rev-{styleRevision}.json完整值與必要資產。記錄穩定 ID、獨立的style_revision、適用語系／版面模式、初始化來源、API 映射及能力限制，沿設計文檔的 version 生命週期管理。已有等價且完整的專案規範時直接引用，不另建副本；未使用報表的專案不必先建立空文件。 - 個別報表：RPT frontmatter 的
report_style_id、report_style_revision、report_style_source指向同一版共用規範，其路徑相對於docs/，並列入depends_on。來源 frontmatter 的style_id／style_revision必須與 RPT 相符；只列報表層與區塊層的覆寫值、位置及原因。未覆寫的屬性沿用該版規範；0間距或一般字重是明確值，不能當成未指定。目前以人工／專案檢查核對，不宣稱 evidence helper 已解析這些欄位。
建立時複製，執行時不隱含繼承框架預設。 執行時解析順序為專案完整預設 → RPT 整份報表覆寫 → RPT 個別區塊／欄位覆寫，只合併有指定的屬性。 專案可以在自己的固定版本內定義共用角色與變體繼承，但解析後須取得完整值；缺少角色、屬性或字型映射時列為待補，不能自動回退至當時框架預設，也不能帶著未決值確認採用 HTML 或實作 PDF。忠實還原原樣張使用原樣式，不套用專案預設；可先完成還原及理解確認。 這是規格的繼承契約；專案角色由範本映射到實際 authoring API，不表示框架已有樣式規範載入器或 CSS importer。 表格的框架樣式另有表格／列角色合併規則，須在能力對照確認解析後結果，避免較下層的表格字級蓋掉報表層設定。
完整預設與框架升級
專案保存的是完整有效值，不是相對於框架的差異檔。除了下節的角色排版欄位，採用的 authoring API 中會影響版面的文件基底也須明確設定，例如文字色／斜體、標題各層級、段落分頁屬性、表格框線／底色／內距及區塊框樣式；不使用者明記停用或不適用。
Java 共用樣式實作須依這份專案預設完整建構；不能每次以 DocumentStyles.standard() 或以其為基底的 builder 起始、只覆寫少數欄位，讓其他值跟著框架更新。HTML 的有效樣式同樣明確指定，不依賴瀏覽器預設或執行機器字型。
字型檔、字面、fallback 順序及版本／摘要也屬專案預設；不能只凍結 sans 名稱而仍動態使用框架或系統的家族映射。
既有報表專案首次補建完整預設時，以該專案已採用的 RPT、HTML／CSS、範本實作、字型及當時框架版本解析實際有效值，保存為專案初版；不能用框架最新推薦值替換或猜測原設定。未知值列為待補，再以既有合成案例核對補建前後的樣式與版面；原有 RPT 特例保留為個別覆寫。 補建來源與引用仍依既有指紋及接受規則處理，不以「外觀預期不變」跳過來源核對；只有實際採用的版面契約改變時才按規則遞增 RPT revision。
框架升級保留專案預設及其樣式 revision；新版推薦值只供比較，不覆寫專案文件、CSS、字型映射或共用 Java 樣式。 要採用新版推薦樣式時，明確修訂專案樣式 revision、列出差異並檢視引用的 RPT，依「採用、修訂與證據」更新受影響報表及驗收。 若新版 API 新增會影響輸出的樣式屬性，先核對能否沿用原呈現並明確補值，不以新欄位的框架預設自動補完；這是升級相容性工作，不表示已同意採用新版視覺。
驗證須包含「同一份專案預設與 RPT 覆寫，在框架推薦字級、行高或間距改變時，最終解析值仍相同」的情境；例如專案內文固定 10.5 pt，框架推薦改為 11 pt 後仍輸出 10.5 pt 的設定。 此隔離只保證公開 API 可設定的樣式值不因推薦預設變動而改變；renderer 的計算、API 語意或字型環境變更仍須升級驗證，不保證跨框架版本 PDF bytes 或版面自然相同。 公開 API 無法設定的值不能假裝已凍結：專案另保存推薦起點的「不可獨立設定項目」表及實際框架版本，升級時核對常數、衍生規則與樣張。若變更影響已採用版面，須處理相容性或明確修訂，不能靜默採用；需要獨立設定而 API 不支援時列能力缺口。
區塊角色
共用規範至少涵蓋下列角色；報表只使用需要的角色，不適用者明記理由。同一角色可依需求定義具名變體，例如密集明細表，但須列明繼承來源與差異。
| 角色 ID | 區塊 | 排版重點 |
|---|---|---|
report-title | 報表主標題 | 字級與字重突出；明訂與資訊區的距離 |
section-heading | 章節標題 | 明訂 heading 層級、段前／段後間距及與下一區塊同頁的規則 |
metadata | 查詢條件、日期、文件識別資訊 | 明訂標籤／值樣式、換行及與正文的距離 |
body | 一般內文 | 標準字級、行高與段距 |
table-header | 表格表頭 | 字重、對齊、行高、內距與跨頁重複 |
table-body | 表格資料 | 字級、行高、水平／垂直內距、長文字及列高策略 |
table-group-header | 表格群組標題 | 對應 RowRole.GROUP_HEADER，與章節 heading 分開 |
table-subtotal | 群組小計 | 對應 RowRole.GROUP_FOOTER，明訂文字、框線、內距 |
table-total | 整份合計 | 對應 RowRole.TOTAL；與小計共用 totalFill，獨立底色目前是能力缺口 |
note | 註解／說明 | 明訂可讀字級、行高及與所屬區塊的距離 |
page-header／page-footer | 頁首／頁尾／頁碼 | 記錄文件段落基底、行內覆寫、衍生高度及目前固定的內容區距離 |
figure-caption | 圖說（使用圖形時） | 記錄文件字級 × 0.85、置中及固定圖說距離；獨立樣式目前是能力缺口 |
每個角色須能解析成完整的「邏輯字型家族、字級（pt）、字重、行高、段前／段後間距、對齊」；適用表格者另填內距及列高策略，其他角色的表格屬性明記不適用。
字型家族可以共用，區塊差異通常由字級與字重表達；需要不同字型時才覆寫。
邏輯名稱（例如 sans）須映射到明確的中英文字型檔、一般／粗體字面、版次或摘要、fallback 順序及缺字處理，並核對 PDF 嵌入與 HTML 散佈授權；不能只寫「系統預設」或依賴執行機器的字型。
完整推薦值、字型映射、角色 → DocumentStyles／節點樣式／RowRole 落點及已知限制集中於 推薦起點，不在此重複一份數值表。框架沒有替 metadata、note 等提供獨立 API 預設；推薦 profile 明訂專案節點樣式常數。一般表格行高與段距同樣必須明示。
行高與間距
- 行高：同一段的基線間距；flow 預設以字級倍數表達，不使用瀏覽器
normal。fixed 需要精確對位時可明訂固定 pt，並核對 renderer 能力及混合字級／字型的容納方式。 - 段前／段後間距：文字段落與標題前後的距離。共用規範統一以 mm 記錄，來源為 pt 時明列換算（1 pt = 25.4／72 mm）；不能把段距當成行高。
- 儲存格內距：分上／下／左／右（mm）記錄，不能拿空白字元或空白行代替；框架 API 若只支援單一 padding，非等距要求須列能力缺口。
- 區塊間距：條件區、正文、明細表與合計區之間的距離（mm），獨立於儲存格內距。明訂相鄰間距如何合成、頁首是否省略段前間距、頁尾及跨頁如何處理；HTML 與 PDF 不依賴各自不同的 margin collapse 預設。
- 列高／區域高度：區分內容自動撐高、最小高度與固定高度。fixed 的文字換行不能推移其他欄位；超出時沿 RPT 的溢位契約處理。
縮字只在 RPT 明訂允許及最小字級時使用，並核對 renderer 能力；不能為容納資料自行縮小字級、行高或內距。
採用、修訂與證據
RPT 以共用規範加差異表描述契約；layout.json 保存本輪使用的樣式 ID／revision、各區塊最終解析值及字型檔映射，讓 HTML 與 PDF 都依同一組設定實作。
版面包保存本輪所需的 CSS／字型快照，以包內相對路徑引用；共用規範納入 HTML --source，共用 Java 樣式實作及其必要資產清單納入 PDF --source，不能只記版本標籤而未納入內容指紋。
共用規範內容改變即遞增 style_revision：保留 rev-1.md／rev-1.json，新增 rev-2.md／rev-2.json 與必要資產，再明確切換 RPT frontmatter 及 depends_on。已採用的舊版來源不原地改值，latest 或索引只供導覽，不能作為 RPT 的精確來源。
報表實際採用新版或修改覆寫而改變版面時，遞增 RPT revision、更新完整契約與快照、重新確認 HTML 並重驗 PDF，按既有規則取得接受。
共用來源被原地改動時，既有指紋仍會 stale；版本標籤不能豁免。方法論更新本身不批次修改既有 RPT、版面包或接受帳本。
確認與驗證至少核對長中文／英文、粗體與 fallback、多行儲存格、跨頁表頭、合計、註解及頁首尾，檢查可讀性、換行、列高、分頁及溢位；不適用情境明記理由。
HTML＋CSS 版面規格
RPT 由 Markdown 業務契約、HTML＋CSS 版面規格及合成資料共同定義。
HTML 是正式規格的一部分，須納入版控及 revision；PDF 實作與驗收以已確認的採用版面為依據。
Markdown 負責參數、執行方式、來源、欄位語意、計算、容量、錯誤及版面規則；HTML＋CSS 表達可檢視的尺寸、位置及外觀。
兩者衝突時列出差異並取得決策、同步修訂，不能自行以最新修改時間決定優先順序。
樣張還原與採用版面
2026-10-07 修訂：有原樣張時，以下兩個關卡依序完成，分開取得真人確認。
第一關：忠實還原，確認 AI 理解樣張
- 使用可選取的 HTML 文字與實際表格重建原樣張，不能以整頁圖片冒充還原。目標是與原樣張一致，包含版面、原始範例資料、字體、字級、字重、顏色、框線、欄寬、段距、換行與分頁。
- 原值全部保留；即使有錯字、計算錯誤、不合理配置或與規格衝突，也不修正，不套用專案預設。觀察事項另列，不能混入還原結果。原資料不因是否含真實個資而替換、遮蔽或改為合成值。
- 依下方「還原包存放與服務契約」透過 Docusaurus 提供原樣張與還原 HTML＋CSS 對照，核對 HTTP bytes 與本次摘要，讓人類確認 AI 是否正確理解內容與外觀。照片透視、尺寸、字型或文字無法確定時，列明不確定處與實際差異，不能猜測後宣稱完全一致；受控預覽無可執行方式時記為第一關阻塞，不改寫原內容或跳過確認。
- 取得這一版還原的明確確認後，保存下方的還原確認紀錄，再進入第二關。等待時可整理需求及盤點資料，但不提前產出採用設計。還原內容及原樣式獨立保留，後續設計不得覆寫；共用資產需改值時另建採用副本。
第二關：提出採用設計，確認實際製作版面
- 還原確認後，以原樣張、RPT 規格及專案排版樣式提出採用 HTML＋CSS。已確認的業務調整在此階段套用；忠實還原保留原錯誤，不表示實際報表也須採用錯誤。
- 在
differences.json逐項列出還原與採用的差異、理由及需求依據，包含資料替換、欄位增減、日期格式、計算、字型／字級／顏色及分頁。兩者使用不同預覽入口與檔案標示。 - 提供基本、空資料、長文字、跨頁及容量邊界等合成案例，不適用者明記理由；解析專案樣式與 RPT 覆寫，保存最終有效值、字型及版面規則。
- 將採用內容完整寫入 RPT、保存最終版面包並
record-html，再取得人類對採用包與案例的accept-html；取得有效採用確認後才實作 PDF。原樣張還原確認不能代替採用確認。
沒有原樣張時，直接進入第二關，來源註明「無原始樣張」，不補造還原確認。 還原內容的忠實性與保存／提供方式分開處理，依「還原包存放與服務契約」保存完整原內容，不以替換原內容滿足另一份採用版面或發布包的要求。 原樣張的欄位與計數可協助核對需求，但不能推定資料來源、授權、計算或正式業務檢核規則。
還原確認紀錄
有原樣張時，在 docs/testing/reports/{RPT-ID}/restoration-confirmation.json 保存下列欄位；這是作者依實際檔案與真人回覆保存的理解確認附件，現行 evidence helper 不提供此階段的命令或自動核對。
| 欄位 | 內容 |
|---|---|
schema | 1，此附件的格式版本，不是 HTML／PDF 帳本的 schema |
reportId／kind | RPT ID；kind: restoration-confirmation，與採用 HTML 帳本區分 |
originals | 原樣張的來源／版本、可取回位置、路徑基準及完整 SHA-256 |
files | 本次還原 HTML／CSS／原資料／字型與其他必要資產的路徑基準、明確相對路徑及完整 SHA-256 |
entries | 提供給真人的 Docusaurus URL 與原樣張／還原 HTML 的路徑對應；必要資產的 URL、來源路徑及 HTTP 摘要核對結果也記於此附件 |
observations | 已知原錯誤、不合理處、無法確定或無法重現處，以及真人針對差異的處置 |
confirmation | 真人識別、原始確認文字及確認時間；尚未確認時為 null，不填造確認 |
history | 重新還原或確認前保留的舊版本紀錄 |
開始採用設計前，由作者重新核對原樣張與還原檔案摘要、確認所指版本及未決差異；未決差異須由人類處置後才能進入下一關。摘要不符時重新取得對更新還原的確認，不手改舊摘要。採用設計新增的檔案不屬於還原檔案清單，不會自行使還原確認過期。
RPT 只保存此附件的固定相對連結，確認結果不回填 RPT，也不把此確認標成 html-accepted。採用版面仍使用 html-evidence.json 與既有整包指紋。
還原包存放與服務契約
還原包包含本輪原樣張副本、HTML／CSS、原資料、字型及其他必要資產。不得放入採用版面包 static/reports/layouts/{RPT-ID}/ 或其子目錄，避免混入採用整包指紋；兩包即使使用相同資產，也各自保存固定副本。每輪以不可覆寫的 {restorationId} 區分，URL 不改送不同 bytes；修改時建立新輪並保留舊確認紀錄。
團隊內部使用及所需素材可供團隊存取是本方法論的工作前提，直接使用已定位 docs 模組的 Docusaurus 提供包含完整原始樣張的對照。讀者範圍、存取控制及部署設定不另設確認關卡，也不作為另建受控網站的條件。部署方式、環境及交付範圍由人類決定；開發期間先完成可用的瀏覽入口。
| 產物 | 保存位置 | 本站提供方式 |
|---|---|---|
| 原件 | 原定來源；不能提交者保存在專案選定的團隊受控儲存 {controlledRoot} | 提供本輪完整固定副本，原件仍以 originals 記錄來源、取回方式及摘要 |
| 還原包 | docs 模組 static/reports/restorations/{RPT-ID}/{restorationId}/，與採用包分開；以 /static/reports/restorations/ gitignore 規則及 git check-ignore 核對展示副本不進版控 | 同一 docs 模組保留 baseUrl，以 /reports/restorations/{RPT-ID}/{restorationId}/… 提供原樣張、還原 HTML／CSS、原資料、字型及其他必要資產 |
{controlledRoot} 是由專案選定的團隊受控儲存根目錄，可為本機獨立目錄或團隊可取回的儲存；它管理原件保存，不是第二個審閱網站。作者在附件 originals／files 記錄各檔路徑基準、明確相對路徑及取回方式，使用不同基準者逐項標示，不在附件放存取憑證。原件位於此處不免除本站提供完整對照的責任。
展示前由作者完成以下內容核對，記於還原確認附件的 entries：
- 本站完整呈現：實際使用已定位 docs 模組的 Docusaurus，提供原樣張、完整還原與必要資產，不以整頁圖片冒充還原 HTML，不掛整個 workspace 或 testing。保存啟動命令、來源位置、實際服務 origin 與全部入口。
- 本輪內容一致：逐一取得實際 HTTP 原樣張、還原 HTML、CSS、原資料、字型及其他必要資產，核對回應成功、內容種類及完整 SHA-256 與
originals／files相同，排除 SPA fallback、舊建置或缺資產。記錄 URL → 來源路徑 → SHA-256 對應，不能只以 HTTP 200 宣稱一致。 - 可供瀏覽與比較：以瀏覽器核對字型載入、內容、版面及全部分頁，提供原樣張與還原對照的明確連結；逐項列出無法辨識或重現處。不允許網頁使用的字型依實際授權列為差異／能力缺口，不能替換後宣稱原樣一致。
- 審閱入口持續可用：各輪使用不可覆寫識別，進行中的 URL 維持可用；更新內容建立新輪，保留歷史確認。入口或資產有問題時先修復本站，不以未核對部署或存取控制當成第一關阻塞。
符合上述內容及呈現要求即可進行第一關，不必等待框架自動建立工具。現行 helper 對 workspace 外／ignored 採用 HTML 包的登錄限制仍依 ADR-020 保留；還原確認附件由作者依實際檔案與真人回覆保存，不因尚無還原自動化工具而改用另一個網站。
gitignore 只管理版控，Docusaurus build 仍會輸出 static 展示副本。人類另行要求部署時，依其決定的交付範圍及既有部署流程核對實際產物清單與複製／排除設定；不交付展示副本時，使用不含副本的乾淨來源建置，或待審閱結束後移出副本再重建。進行中的審閱入口、原件及歷史確認均須保留；部署工作與版面確認分開。
原件與證據保留
原件以 Git 共享為預設；新建可提交原件及還原來源可保存於 docs 模組的 sources/reports/{report}/{sourceId}/（report-source），不放在 Docusaurus docs 編譯樹或採用 HTML 包，不自動搬移既有來源。依原件契約保留 bytes、來源版次及 metadata；既有明示不能提交者仍依 controlledRoot／evidence-location 保存，Git 保留完整摘要、相對成員、取回資訊與確認附件，不含憑證。人類沿同站逐檔固定副本核對，三個確認命題各自成立。
docs.py retention 只供保存與提交範圍參考，保留整個被引用 run 及完整歷史。未知／失敗／中斷 run、舊來源缺口或 index 差異會列 blocked，仍依原授權精確保存及交付本次原生有效帳本、引用 run 整包及必要快照，揭露 RT 問題並保留未知歷史；不要求先修整池、不自動 stage／刪除。原生 verifier、HTML／PDF 接受與 work 原有閘門照常，不能以 retention 的參考定位豁免。本命令不處理外部採用包或自動還原確認（FU-126／FU-134）；完整規格見證據保留 §6～§8。
版面包與預覽契約
採用版面包置於 docs 模組的 static/reports/layouts/{RPT-ID}/，不放在 Docusaurus docs/ 內容樹；RPT 同時記錄 repository 相對路徑及站台預覽 URL。
包內保存 HTML、CSS、授權允許保存及向站台讀者散佈的字型與圖片、合成資料、differences.json 差異清單及 layout.json（預覽環境與重現方式）。放入 static 的字型授權須允許網頁散佈；可入版控或桌面使用的授權不等同網頁散佈授權。說明用 JSON／HTML，不使用 .md／.mdx 以免誤成站台文件。
採用包會隨文件站輸出，只有對該站台讀者可提供的合成規格及資產可放入；原樣張及原資料放在獨立還原包，依「還原包存放與服務契約」由同一內部專案文檔站提供。內部來源摘要與真人接受帳本仍置於原定來源／testing；需要人類閱讀時依共通規則提供完整瀏覽呈現或逐檔附件，維持來源為唯一可編輯版本。
HTML 在 static 保持獨立頁面，RPT 使用 pathname:// 連結，避免 SPA 路由與 Webpack 重新命名入口；例如 baseUrl 為 / 時連結為 pathname:///reports/layouts/{RPT-ID}/basic.html。baseUrl 非 / 時須在路徑加上實際前綴，pathname:// 不會自動補 baseUrl。來源見 Docusaurus routing。
不能直接以 docs/ 相對 .html 資產連結替代：入口與 CSS 等相對依賴需要保持同一目錄結構。建置後須實查預覽及必要資產存在、連結可取回；建置成功本身不代表 CSS 或字型載入正確。
所有預覽依賴須在包內，以本機相對路徑引用；禁止依賴會變動的 CDN、遠端字型或正式資料 API。成員以 git ls-files --cached --others --exclude-standard 列舉（含尚未暫存的新規格），排除 ignored 殘渣；最後依保存契約將必要成員逐檔納入版控。必要資產若被 ignore，須先處理規則或明確納入版控，不以本機有該檔宣稱其他 clone 可重現。
字型授權不允許網頁散佈時，即使可入版控，也不得放入 static；改用可公開散佈的替代字型，或在授權允許的範圍內將完整版面包改於團隊受控位置保存及預覽，不隨站台發布。受控包的路徑、資產摘要與取回方式須記於 RPT；字型因授權限制無法入版控時亦採此方式。取得相同內容前不能宣稱預覽可重現。
layout.json 至少記錄：
- RPT ID／revision、預覽入口與情境對照、欄位 ID 到 HTML 元件的映射。
- 紙張寬高、方向、邊界（mm）；依「共用排版規範與區塊樣式」記錄樣式來源與版本、區塊最終解析值及字型檔映射；欄寬、框線、頁首尾、頁碼及空資料呈現。
- flow 的表頭重複、雙行紀錄的群組／不拆分、每頁容量、換行、跨頁及合計位置；fixed 的定位表、圖層、溢位、續頁及套印。
- 瀏覽器／排版工具與版本、執行命令、必要設定、字型載入完成條件及列印設定。若螢幕預覽與列印排版不同，明定確認哪一種呈現；不能只確認未分頁的螢幕長表。
- 預覽與 PDF 的尺寸／位置允收容差、可接受的文字描邊差異及實作能力缺口。
至少提供基本、空資料、長文字及跨頁／容量邊界的合成預覽；不適用者寫明理由。 PDF 使用相同案例與顯示資料比對；幾何與內容核對配合全部頁面的視覺檢查，不能要求不同 renderer 的 raster bytes 必須相同。 這些資料與環境設定納入指紋，但 helper 不解析 CSS、檢查資產引用完整性或證明預覽正確；由作者核對實際載入內容與逐頁呈現。
Docusaurus 人類審閱服務
應用文檔站是人類與 AI 共用的內部專案文檔網站，不對外開放。報表製作的過程成果也須透過本站提供瀏覽入口，不能等到最終 PDF 完成才呈現。
| 階段 | 本站瀏覽內容 | 確認命題 |
|---|---|---|
| 樣張還原 | 原樣張、還原 HTML＋CSS、已知差異的對照 | AI 是否正確理解原內容與外觀 |
| 樣板設計 | 擬採用的 HTML＋CSS 樣板、修改理由、基本／空資料／長文字／跨頁等案例 | 實際製作版面是否符合需求 |
| PDF 驗收 | 本輪 PDF 瀏覽／下載、已採用樣板的對照 | 精確 PDF 是否符合已確認版面 |
AI 每次請人類確認時，提供本輪全部必要入口及待確認事項，標明階段與版本，讓人類直接比較與討論。各階段確認分開保存於既有附件／帳本；進行中審閱的 URL 保持可用，展示副本沿本節生命週期清理。完整原樣張與還原、採用版面及 PDF 均由本站呈現，不另設讀者／存取控制核對或獨立受控網站分支；部署另由人類決定。
原審閱服務契約於 2026-10-07 經 20261007-report-docusaurus-review 第二輪通過並採納，由 report skill 2.4.0 提供；report 2.6.0 的還原／採用分流及受控預覽判準經 20261007-report-restoration-confirmation 第三輪通過，決策與後續工具邊界見 ADR-020。
原樣張還原理解確認、採用 HTML 版面確認與 PDF 版面接受統一由已定位 docs 模組的 Docusaurus HTTP 服務提供瀏覽器 URL；還原內容依上節在同一 docs 模組完整提供。三個命題分開記錄，無樣張時略過第一關；本節統一展示與核對方式，不改變採用 HTML／PDF 接受指紋、證據保存或產品報表交付契約。
- 定位與啟動：依
m-skill-execution.md定位 docs 模組，讀取其 package scripts、Docusaurus 設定及預覽環境。先核對現有服務的模組與內容；相符且提供本輪內容才沿用。需啟動時，先判讀 script 的前置工作：必要的既有同步產物已具備時優先用start:skip等略過重建的 script，不能為報表審閱直接使用會sync-static.js --force重建 Javadoc／Storybook／API 文件的 start 或 build。只有目前 docs 啟動必需的產物缺失才補該產物；無關同步或 lint 阻擋包裝 script 時，可用既有docusaurusscript 直接 start，不改 package scripts 或跳過必要預覽檢查。從 docs 模組執行npm run start:skip -- --port {reviewPort}，尾端 CLI 參數覆寫 script 中的預設埠；直接啟動可用npm run docusaurus -- start --port {reviewPort} --no-open。使用 serve 時先選不重建無關資源的 docs-only 建置方式，核對包裝 script 的同步／lint；必要時用既有 Docusaurus CLI build，再npm run serve -- --port {reviewPort}，不能服務舊 build。先選可用埠，啟動後核對日誌與實際 HTTP 埠並記錄完整命令；不停止佔埠的他人服務，也不另起 Python／通用靜態 HTTP server 取代 Docusaurus。直接 CLI／skip 只用於審閱，正式發布仍走既有建置檢核。綁定位址沿用該專案 docs 模組的預設啟動設定；啟動後核對實際 listener 位址，不以 CLI 顯示的 URL 代替。 - URL 推導：以啟動輸出及實際 HTTP 核對取得 review origin，保留 config 的實際
baseUrl。config 的url不保證是本機服務位址；static HTML／PDF URL 不加 docs 的routeBasePath。RPT 的穩定站台路徑沿用pathname://契約；本輪實際 origin、命令與 URL 寫帳本同層結果附件，不在接受後回填 RPT 或 layout.json。 - 還原與採用 HTML 檢查：還原對照依「還原包存放與服務契約」核對原樣張、HTML 及全部必要資產的 HTTP bytes 與
originals／files摘要；原樣張與完整還原由同一內部專案文檔站提供；入口或資產呈現有問題時先修復本站。採用版面逐一取得所有情境的 HTML 與必要資產，核對 HTTP bytes 與本輪版面包中的對應檔案一致，確認不是 SPA fallback 或舊建置；以瀏覽器核對字型載入、紙張尺寸、換行、表頭及全部分頁，按 layout.json 宣告的螢幕／列印呈現審閱。提供各關全部入口及原樣張對照，不以第一關對照代替最終採用包確認。 - PDF 展示副本與清理：證據原檔仍保存在
docs/testing/reports/{RPT-ID}/runs/{runId}/並依保存契約入版控或受控證據包。將本輪全部脫敏合成 PDF 逐檔複製到static/reports/previews/{RPT-ID}/{runId}/；展示副本預設由 docs 模組.gitignore的/static/reports/previews/排除，以 git check-ignore 核對，不另存第二份受版控的同 bytes。副本可依 runs 原檔及帳本 SHA 重建；缺原檔或摘要不符時不能重建為有效預覽。保留案例檔名、完整 bytes 及不可覆寫的 runId，不重產、轉圖、重新壓縮或修改 metadata；同一路徑已有不同 bytes 時停止查明，不覆蓋，重新 verify 的不同輸出使用新 runId。不可覆寫約束該 URL 永遠不換成不同 bytes，不禁止移除展示副本；重新恢復同一 URL 也只能使用原摘要相同的 bytes。作者在結果附件登錄本輪生成副本清單；明示取消或改送新輪後，清除未全數接受且不再供任何進行中審閱使用的輪次副本；部分接受仍保留在證據帳本。新輪待審時仍保留上一輪完整 layout-accepted 的副本；新輪全部接受後保留新輪及其他仍在進行中的審閱副本，清除已被取代的舊輪副本。只清自己登錄的可重建、未追蹤展示檔，不清他人進行中預覽或歷史 runs／帳本；清理時間與路徑寫結果附件。展示副本不放進已接受 HTML 的版面包，以免改變其整包指紋。 - 保存與部署分工：本站逐檔提供人類本輪需要閱讀或確認的完整文件與附件；來源、展示副本、採用包及證據帳本依各自保存契約管理，不掛整個 testing、runs 或 workspace。gitignore 不排除 static 建置輸出；人類另行要求部署時，依「還原包存放與服務契約」及其決定的交付範圍核對產物與實際排除設定。部署核對不阻擋開發期間審閱，也不能中斷進行中的 URL。現行 helper 對 workspace 外／ignored 採用 HTML 包的限制仍有效，本節不宣稱已解決。
- PDF HTTP 核對：逐份下載實際提供的 HTTP PDF，確認回應成功、內容確為 PDF，並核對完整 SHA-256 與本輪 evidence.json 中的證據原檔相同；HTTP 200 或副檔名為
.pdf不足以排除 SPA fallback。不同者修復服務／建置／副本後重查，不能讓人類接受錯誤輪次。HTTP 取得的 bytes 僅作核對，不取代 runs 原檔或改寫帳本摘要。 - 交付與服務生命週期：提供案例名稱、所有 HTML URL、所有 PDF 瀏覽／下載 URL、runId 及驗收範圍；PDF 可由瀏覽器內建 viewer 開啟，同一 URL 可下載精確檔案供閱讀器檢視。站台未列目錄時也須逐檔列連結。記錄 URL → 證據相對路徑 → SHA-256 的映射及核對結果於帳本同層附件，結果不回寫 RPT。服務須保持可用直到本輪 review 結束；連結失效時先恢復同一內容再繼續，停止由本輪啟動的服務時告知使用者，不停止原有服務。
- 接受與發布分離：提供並檢查預覽後，只有真人明確針對本輪 HTML 包或精確 PDF 的確認才記 accept-html／accept；AI 自查、開啟 URL 或提供連結均不構成接受。啟動本機審閱服務不代表授權部署／發布站台。新增流程不批次修改既有 RPT、layout.json 或接受帳本；實際改動仍依指紋與接受承接規則處理。
確認關卡與修訂
| 關卡 | 真人確認的命題 | 案例資料 | 紀錄 | 解鎖 |
|---|---|---|---|---|
| 原樣張還原（有樣張時） | AI 是否正確理解原樣張的內容與外觀 | 完整原始範例資料 | restoration-confirmation.json | 採用版面設計 |
| 採用 HTML＋CSS | 實際要製作的版面與規格是否符合需求 | 基本、空資料、長文、跨頁／邊界等合成案例 | html-evidence.json，accept-html | PDF 實作 |
| 精確 PDF | 本輪實際 PDF 輸出是否接受 | 與採用 HTML 相同的合成案例 | evidence.json，accept | 本輪 PDF 版面接受 |
三個確認命題不同，不互相替代；沒有原樣張時，只有採用 HTML 與 PDF 兩個關卡。
需求調整方向可先在對話中討論，採用設計仍須等待綁定實際檔案摘要、保存於附件的原樣張還原確認；「理解正確」不表示已同意製作版面。正式 record-html／accept-html 前完成 RPT 契約，以最終包及契約取得接受，避免接受後立即修改來源。
HTML 接受綁定 RPT 版次、整個版面包及必要來源的 SHA-256；PDF 驗證保存該已接受快照，不能只引用會被覆寫的帳本路徑。
HTML、CSS、字型、合成資料、環境設定或必要來源變動時，工具回報 stale；重新 record 不沿用舊接受。
版面契約改變須遞增 revision、重新確認 HTML 並重驗 PDF；只有證據格式或環境記錄更新而契約未改時，保留 revision，核對差異後取得更新包的確認。
HTML 可作為現有報表 authoring API 的實作及驗收依據；不代表框架已支援任意 HTML／CSS 直接轉 PDF。 若 renderer 無法符合已確認版面，提出具體能力缺口，經框架既有設計／RFC 流程處理或取得版面調整決策，不能靜默改版。
本次關卡細化適用於後續新建或重新製作原樣張還原；方法論更新本身不批次改既有 RPT、版面包或接受帳本，不補造過往還原確認，也不因此撤銷已有效接受的 HTML／PDF。既有工作開始重新還原原樣張時，依新流程記錄第一關。
固定版面共同設定
| 項目 | 必填內容 |
|---|---|
| 頁面 | 紙張實際寬高、方向、單／雙面、頁面／聯別順序、不可列印區 |
| 座標 | 左上原點、x 向右、y 向下；幾何以 mm，字級以 pt；文字框座標與基線不能混用 |
| 列印模式 | full-form 空白紙完整繪製；overlay 預印紙只印可變內容；必要時另提供校準樣張 |
| 圖層 | 底圖、固定框線／標籤、可變資料、驗證標記的繪製順序；套印時明定哪些層不輸出 |
| 底圖 | 無／圖檔／PDF；來源、授權、檔案摘要、頁碼、尺寸、裁切與旋轉；禁止未記錄的自動縮放 |
| 校準 | 平移 dx／dy、適用設備及紙匣、基準點、允收容差；預設 0，不能把設備誤差烙進欄位座標 |
| 列印 | 100% 實際大小；停用符合頁面、瀏覽器頁首尾；預覽不等於實紙驗收 |
| 字型 | 可嵌入字型與版次／摘要、fallback；缺字處理、字級、行距、對齊 |
定位表
每個元件有穩定 ID；定位表引用欄位字典的 ID，不在座標表重新定義業務計算。
| 元件 ID | 頁型／聯別／圖層 | 類型 | x／y／w／h（mm） | 綁定欄位或固定文字 | 字型／字級／行距 | 對齊 | 容量／溢位 | 條件 |
|---|---|---|---|---|---|---|---|---|
| 由專案填寫 | 指定頁型 | 文字／線／框／圖／條碼／留白 | 明確數值 | 欄位 ID | 明確數值或共用樣式 | 水平／垂直 | 下節策略 | 明確條件 |
線條另定起訖、粗細、顏色、虛線；圖像另定等比縮放／裁切，不能默默拉伸。 留白區也要列入，例如收件人簽名、日期與蓋章空間，其他內容不得侵入。 允許重疊的元件要明示（例如文字在框線內），不能把一切重疊都視為錯誤或一律忽略。
文字與明細容量
逐欄位明定 reject（拒絕輸出）、wrap（框內換行後仍超出則拒絕）、shrink（指定最小字級，仍放不下則拒絕）或 truncate（明示截斷符號與適用理由）。
金額、識別碼、條碼 payload 不可無聲截斷；框內換行不能改變框的尺寸與後續欄位座標。
上述是規格詞彙，只有能力對照確認 renderer 支援後才能採用。
重複明細須定義起點、列高、欄位位置、每頁／每聯最大筆數、空白列、續頁頁型、表頭及小計／總計位置。 第 N+1 筆必須有明確結果（例如續頁或整份拒絕），不得直接漏列；一頁恰好 N 筆也要測試。 續頁須明定單號、頁碼、聯別與關聯；總計按整份、單頁或單聯計算，避免重複加總。
機讀欄位與簽收
條碼／QR 必須指定 symbology、字元集、長度、payload 組合、補零、檢查碼的產生與驗證責任、 模組寬度、條高、靜區、可讀文字、顏色及允收掃讀條件。 程式庫編碼器的符號校驗不等於銀行或代收機構的業務檢核；收款方規格需列來源與版次。 未知規則記為待確認，不從樣張猜出正式條碼。
簽名欄可為紙本留白或已取得的簽名影像；需明定來源與可見範圍。 產生簽名欄位不代表具備數位簽章、身分驗證或法律效力。
驗證與交付
查詢成本與正式來源交付另須符合上節「效能風險預測與查詢預算」；內容、版面與效能證據各自核對，任一缺口都不能由另一項通過代替。 至少涵蓋基本、空資料、最大容量、超容量、長中文／英文、空值、非法值、缺字、跨頁／多聯。 參數介面另涵蓋：每條參數規則、缺少或越界的呼叫情境、三層容量上限，以及錯誤契約的每種結果。 依責任驗證已宣告的模式、預設、拒絕不支援模式的結果及模式專屬上限的邊界／錯誤／未自動改送；只有雙模式自動選擇才驗證切換條件與邊界。產品 API 另驗證同步 PDF 交付或非同步工作生命週期、等待與取消語意；未支援的模式不要求建立實作。兩者皆支援時，以相同輸入核對內容與版面，不能把同步範本測試當成背景流程已驗收。 資料範圍分兩段驗證：範本階段以合成輸入驗證輸出；接入正式資料 adapter 後，由 RPT verify 以可重複的資料庫測試資料（同時含範圍內外資料）經 adapter 實際查詢，驗證範圍條件確實套用於查詢、範圍外資料不被納入。 只驗證呼叫端傳入的範圍值，或使用已篩好的 fixtures，不能證明正式查詢遵守可見範圍。引用的 US 只驗證呼叫情境填入正確，不重驗查詢。 固定版面另檢查頁面尺寸、基準點、欄位及保留區座標、套印層、校準偏移與邊界；條碼須從實際輸出 PDF raster 解碼，並依需求保留實紙掃讀結果。
幾何測試使用規格明定的容差；螢幕 raster 比對不能取代印表機套印驗收。 證據綁定規格版次、已確認 HTML 版面包、程式來源、合成輸入、字型、底圖及 PDF 摘要。 既有樣張的人工接受只適用於該次輸出，不自動接受不同紙張、字型、底圖或續頁。
能力對照必須區分「規格已表達」「框架已實作」「自動驗證通過」「人工版面／實紙接受」「已發布供下游使用」。 新增固定表單支援不把所有既有 flow 報表重新分類，也不宣稱直接完成下游業務報表。
獨立報表工作流程
使用 /report spec RPT-… 建立業務契約草稿；/report layout RPT-… 有原樣張時先忠實還原 HTML＋CSS，保存真人對理解是否正確的第一關確認，才依樣張、規格與樣式提出採用設計及合成案例；無樣張時直接設計採用版面。
完成契約後以 /report accept-html RPT-… 記錄真人對最終採用包的第二關確認，再以 /report impl RPT-… 實作範本與資料 adapter、
/report verify RPT-… 執行測試並檢視產物、/report accept RPT-… 記錄真人對精確 PDF 的接受，
/report status RPT-… 查詢採用 HTML／PDF 證據，還原確認另由作者依附件核對。不建立虛構 US，也不推進 Sprint；等待還原確認時可盤點資料與需求但不製作採用設計，等待採用確認時可整理資料來源與契約但不實作 PDF。
操作入口、資料授權、執行方式的 API 對應及產品整合由引用 RPT 的 US 或專案既有產品需求／API 規格承接。
report/scripts/evidence.py 以 record-html／accept-html 管理 html-evidence.json，以 record／accept 管理 PDF 的 evidence.json。
新 PDF record 必須提供同一份 RPT 的有效已接受 HTML 帳本，產生 schema 2 並保存其快照及來源指紋。
html-recorded 表示已登錄待確認版面，html-accepted 表示該包有真人確認；都不代表 PDF 已驗收。
verified 只表示宣告的自動化證據有效；layout-accepted 另須每份 PDF 都有真人接受紀錄。
來源或產物改變即為 stale，需重驗；重新記錄保留歷史但不沿用舊接受。
2026-10-04 修訂（20261004-report-reproducibility 第二輪通過並完成 close，已採納；操作由 report skill 2.2.0 提供）：證據維護後可另執行 carry-acceptance 明確承接原真人接受：目前證據已重驗且不 stale，
指定歷史紀錄與目前紀錄均為 schema 2、同一 RPT、相同已接受 HTML 整包摘要，
映射的同名案例之完整 PDF SHA-256 相同，並可取回原 PDF bytes 核對。
原 reviewer／statement／acceptedAt 不變，另外保存原紀錄時間戳、原 PDF 路徑、承接理由與操作時間。
未指定、未接受、不同 bytes 或不同契約的 PDF 仍需新真人接受；真人明示重驗或已知驗收誤判時不承接。
不刪除或正規化 /ID 後比較，也不以相同圖像代替原始 bytes。此操作保留的是 PDF 版面接受，
不代表自動證據、正式資料或產品流程驗收；原接受仍須有原始對話或受控紀錄佐證。
工具不代替測試執行、逐頁視覺檢視、真實資料驗證、實紙套印或設備掃讀。
既有 schema 1 PDF 帳本仍可唯讀核對及依原流程記錄精確 PDF 接受；htmlStatus: not-recorded 明列 HTML 證據缺席。
原接受保留其範圍，不追溯改成 HTML 已確認，也不因新增方法論自動撤銷。下一輪改版或重新 record 時補齊 HTML 流程，歷史保留。
既有報表重錄的成本
2.0.0 的新 PDF record 必填 --html-manifest，舊呼叫指令須更新；這是實作前版面規格流程的不相容變更。
尚無 HTML 的既有報表，即使只修取數／計算／排版 bug、預期版面不變，第一次重錄仍需補建合成 HTML 版面包、完成 RPT 引用與來源核對、取得真人對最終包的確認，再重跑 PDF 驗證。這是一次性的補規格成本，不能只改帳本摘要或以舊 PDF 接受代替。
已有有效 HTML 版面包而只修 renderer／adapter／測試實作、RPT 語意與採用版面均未變時，可沿用該 HTML 接受；重驗並重錄 PDF 後，完全相同的輸出可依上述條件明確承接，其他輸出取得新 PDF 接受。HTML --source 只包含 RPT 與決定版面的需求來源；renderer／adapter／測試／建置來源由 PDF 帳本承接。
若修正實際改變 RPT 契約、採用版面或合成展示資料，仍依版次及 stale 規則重新確認，不能以「bug fix」跳過。
保存與來源指紋
RPT 本身只放契約、版面包與預覽路徑、預期及兩個帳本的固定連結；結果／摘要／AI 檢視／真人接受寫帳本及同層附件，避免回寫規格立即使證據 stale。
先完成規格修改，再測試及 record。脫敏合成 PDF 與 JUnit XML 複製至 docs/testing/reports/{RPT-ID}/runs/{runId}/，
與帳本、必要來源明確納入版控；若含敏感資料，改存受控證據包並記載取回方式與摘要，禁止直接提交。
只有相同相對路徑的全部來源與證據均可取得時，才可跨 clone 核對；build／workspace output 是被忽略的本機暫存。
帳本檢查不是防竄改簽章，真人接受仍須原始對話或受控紀錄佐證。
本版 /report 不提供 published 自動定案；RPT-001 刻意維持 draft。/next／/prune-reference 尚無 RPT 庫存整合，
須以 /report status 盤點及人工核對剝離引用。scaffold 後來源／規格變更使舊證據失效，不能沿用來源專案的接受。
登錄前的脫敏與容量
先完成脫敏，再 record；帳本綁定的是脫敏後 PDF／JUnit XML 的 bytes，登錄後不能再修改附件。
JUnit 副本移除 hostname、system-out、system-err、properties，以及測試名稱／訊息中的個資、絕對路徑與憑證；
保留 testcase 身分所需的匿名識別、tests／failures／errors／skipped 計數和結果節點，不能藉脫敏把失敗改成通過。
原始測試輸出留在受控本機／CI，對照原始結果核對脫敏副本。PDF 使用合成資料並檢查可見內容、文字層與 metadata；
不能只蓋白框遮住個資。helper 不自動脫敏，也不保證附件沒有敏感資訊。
每份 PDF 上限 20,000,000 bytes、每份 JUnit XML 上限 5,000,000 bytes；超限拒絕登錄，應拆分驗證情境，不截掉結果。
helper 強制 PDF／XML 位於帳本同層 runs/{runId}/；所有附件仍須依保存契約明確加入版控或受控證據包。
證據包取回資訊使用 evidence-location.json（location、sha256、relativePaths；不得含密鑰），不建立 Docusaurus README 頁面。