ADR-022：報表效能風險預測與查詢成本驗證

狀態：已接受 (Accepted) 提案日期：2026-10-11 決策日期：2026-10-11 審閱：20261011-report-performance-risk，第 3 輪通過；11 條意見均 done，無 open 或 declined；close 結論落點經使用者確認 範圍：報表開發流程、RPT 容量與查詢成本契約、效能驗證及證據管理

問題

僅以報表內容及版面測試通過判定交付，無法揭露正式資料 adapter、查詢及 Entity 映射造成的查詢成本。 若等專用測試資料齊備或測試人員反映耗時才改善，迴圈內查詢、隱藏關聯載入及無界取數可能延後至交付時才被發現。 需要在開發階段提出可追溯的風險預測，再由成本回歸與執行量測確認；靜態分析不能精確預測耗時。

決策

將效能風險分析納入 spec／impl／verify／status，不以專用測試資料或耗時回報為啟動前提。 操作規範與完整證據欄位集中於 報表規格指南， RPT 作者化欄位沿用 權威範本。本 ADR 保存政策及取捨，不另複製完整規範。

分析、容量與交付門檻

分析正式 adapter、查詢、Entity 關聯與 generator／renderer 路徑，包含迴圈查詢、隱藏載入、反向一對一逐筆查詢、 無界取數及繪製期間讀取。各發現記錄程式位置、來源摘要、觸發條件與成本成長，區分已確認問題、可能風險及尚待實測。

每份 RPT 宣告最大資料量與合理查詢預算。N 為明定粒度的頂層紀錄數，D 為總明細數；N、D 及每主體明細數均屬取數層硬上限， 聚合前來源量另設上界，參數及輸出上限另列。超量依錯誤契約拒絕整次執行，不截斷明細或輸出部分成功文件。

查詢次數合理成長預設為常數或依關聯分批的 ceil(N/B)／ceil(D/B)；B=1 不能將逐筆查詢改名為批次。 逐案或逐明細線性項預設不合理，例外須在容量硬上限內列出條件、成本上界、理由與可驗證案例。 預測可能超預算者須修正或提供此種設計說明並經驗證，不能只以內容及版面通過宣告整份交付完成。

量測與修正責任

框架負責分析、量測及驗證支援，應用端負責業務查詢修正；框架不得自動改寫查詢或關聯映射而改變報表語意。 單次 run／attempt 量測涵蓋 SQL 計數、脫敏重複結構摘要與資料讀取、處理、排版／繪製、輸出分段耗時。 不得混入其他請求，也不得記錄個案資料、SQL 參數或可洩漏資料的 literal／註解。

執行期或可能並行時，不能以全域計數差值冒充單次量測。獨佔成本回歸測試可採全域差值， 但須證明計數範圍無其他存取，排除 fixture／flush，記錄基線、階段差值及計數語意；此例外不替代執行期能力。 實際支援須依已發布框架版本及應用接入核對，能力缺口明列，不因方法論通過或待辦存在就宣稱交付。

回歸、耗時與接受證據

確認的問題轉為查詢成本回歸測試，涵蓋 N、D 成長及容量邊界，修正後核對完整內容與已接受版面。 成本分析與回歸附件先定稿，再納入 PDF record --source，與相關實作／設定／測試來源一起追蹤，歷史附件不覆寫。 後續受控耗時另存新 run 的附件或 sim 報告，引用原成本附件 SHA-256、RPT revision、PDF SHA-256、來源及執行環境。 僅增加相符來源的耗時結果不要求重錄 PDF；已指紋來源或成本證據改變，仍依既有規則重驗／重錄及判定接受承接。

耗時驗證記錄執行環境，不以不穩定秒數作一般單元測試門檻。有對外 SLA 或並行負載命題時， 由 ADR-008 的 sim／sim-plan 里程碑 NFR 計畫承接。

考量的方案

方案	取捨
等耗時回報或專用資料才分析	正式查詢風險發現過晚，未採用
主動預測、容量與成本契約，再實測確認（採用）	開發時即可定位風險；須明示證據強度及能力缺口
所有 RPT 套同一絕對 SQL 次數上限	無法反映關聯批次及容量差異，改採成長判準與可驗證上界
全面禁止獨佔測試的全域差值	會阻斷可可靠歸屬的成本回歸，保留嚴格獨佔例外
所有後續耗時證據都綁入原 PDF 指紋	單純補測也會要求重錄；採成本證據固定、後續耗時以來源相容性核對
立即將所有舊 RPT 標為缺口	混淆流程導入與既有接受，改採下述導入時點

相容與遷移

保留 ADR-017 的參數介面及 US／RPT 分工、 ADR-020 的 HTML／PDF 接受與證據契約， 以及 ADR-021 的純值報表與正式資料 adapter 責任分區。

新建 RPT 適用本流程。既有有效接受、正式來源未變且未重新 PDF record 者，status 標示「效能流程未導入（既有、來源未變）」。 既有報表首次正式來源修訂或首次重新 record 時導入；已有有效效能證據者持續核對。 無法證明豁免條件者列為待核對，原有 stale 仍須處理。不批次改寫既有 RPT／帳本、不撤銷原有效接受。

審閱結論落點

本次 20261011-report-performance-risk 第 3 輪通過，11 條意見均已處置，無未結或不採納項目。 使用者以「確認」接受本 ADR、既有操作規範及 FU-138 的結論落點，完成 close 檢核。 政策取捨由本 ADR 保存；操作要求已落於方法論 rule、report skill 2.9.0、報表指南及 RPT 範本，索引同步維護。

執行期量測支援由團隊現行 backlog app-docs/docs/specs/progress/follow-ups.md 的 FU-138 承接。 待辦包含能力盤點、公開 API 設計、並行隔離與清理、脫敏摘要、分段耗時及實際發布版本驗證。 指南只引用現行 backlog 與已發布能力，不綁可隨待辦結案移除的詳述錨點；本 ADR 保留 FU 編號作決策追溯。

本輪僅整合流程與規格，未實作量測 API、修改業務查詢或 evidence helper，無 feature 契約變更，故不新增 FEATURE_CHANGELOG。 本次 close 解鎖 methodology 發布流程；尚未執行 commit、push 或 publish，提交、下游發布及量測能力實作依各自後續授權執行。

變更歷史

日期	內容
2026-10-11	第 3 輪 peer review 通過，11 條意見全數處置；使用者確認 ADR、既有規範與 FU-138 落點後完成 close，採納本決策