跳至主要内容

ADR-021：獨立報表責任分區

狀態：已接受 (Accepted) 提案日期：2026-10-04 決策日期：2026-10-04 審閱：20261004-report-layer，第 2 輪通過；close 結論落點經使用者確認 最後修訂：2026-10-04 範圍：RPT 作者化規範、server practices、應用端報表 package 與架構檢查

問題​

將具體報表的 request、資料來源、計算、範本與產生入口集中在 service 子包，雖可運行， 卻讓產品流程與報表文件組成的責任混在同一層，也使讀取資料庫的 adapter 與純值範本邊界不易辨認。 RPT 已能獨立開發及驗證，需要相應的程式責任分區。

決策​

採 report 責任分區：layer-first 使用 report/{domain}/，package-by-feature 使用 {domain}/report/。 業務 owner 及既有 businessLayout 維持，由 report 集中參數契約、輸入模型、Source 介面、計算、範本與 generator。 正式 DB adapter 放 repository，實作 report 的 Source 並回傳完整純值輸入；service 承接授權範圍、交易與產品流程。 依賴規則及遷移契約的權威指南為 報表責任分區。

HTML＋CSS 用來理解、溝通與確認報表格式，是 ADR-020 的版面規格； 目前試點由 Java 建立文件並使用框架 renderer 輸出 PDF，承接使用者對目前分工的確認。 本 ADR 不處理 renderer 選型或後續路線；通用 HTML→PDF 引擎依 ADR-020，須另案評估框架設計及現有 flow／fixed 能力。 本決策保留 ADR-017 的參數介面及 US／RPT 責任。

考量的方案​

方案取捨
持續放在 service 子包搬移成本較低，但 RPT 的獨立文件契約與產品流程仍共享目錄邊界
report 分區，DB adapter 留 repository（已採用）對應獨立 RPT，純值文件組成可獨立驗證；需更新 consumers、測試、practices 與證據來源
所有查詢與 Entity 存取都放 report聚集報表程式，但持久化及文件組成的邊界模糊，不能維持純值範本

相容與遷移​

  1. 這是應用端作者化慣例，不增加框架 jar API 或第五個通用 runtime primitive。
  2. feature/report 與 job 的 reference domain 繼續依原有所有權管理；不移動 job／executor／下載服務。
  3. 既有報表依本次授權逐一搬移，不以 fleet publish 自動修改各應用的業務碼。
  4. 包名／入口類名改動需由編譯及 consumer 核對；資料與版面不變時不遞增 RPT revision。
  5. 來源 bytes 改變仍使舊 PDF 帳本 stale；新帳本遵循現行 HTML／PDF 證據契約，不改寫舊接受。
  6. 框架 order 與 nbsos specimen 試點以既有測試、DB 範圍測試與架構檢查提供重構證據； 正式產品整合與尚未完成的 HTML／PDF 重錄另按原有流程承接。

審閱落點​

本次人審 20261004-report-layer 第 2 輪通過，三條意見均已處置，無 open 意見；close 結論落點經使用者確認。

  • R1-01：本 ADR 只決定報表責任分區，不處理 renderer 路線；ADR-020 的通用 HTML→PDF 引擎另案評估維持。
  • R1-02：report 本體、Source adapter 與同名 job 領域的適用範圍，由責任指南及兩種 server 的 30-report-reference.md 承接； job controller／service 沿各自規範，repository Source 可使用持久化 API 完成純值投影。
  • R1-03：report-layer 的設計指南分類、ADR-021 的索引順序及 design README 導覽已修正。

框架與 nbsos 試點的 package 搬移以 81 項測試及 12 份／20 頁合成樣張比對驗證； 第 2 輪只改文件與規則，Java 指紋保持，原有 Git index 與歷史報表證據保留。 這些是重構證據，不是新的 HTML／PDF 接受、正式資料授權或產品流程驗收。

三份 RPT 的舊帳本目前為 stale、HTML 尚未登錄，補建 HTML 與 PDF 重錄記入框架 backlog FU-127； 與 FU-117 的 nbsos 試點及 FU-126 的受控版面包工具限制分別承接，不將原接受改寫成新接受。 order 正式 Source 與產品整合、真實資料及跨資料庫驗證仍依各試點既有範圍另行處理。

本批沒有 renderer／executor／job 的 feature 契約或 API 變更，故不新增 FEATURE_CHANGELOG。 close 解鎖後續提交與 methodology／practices 發布流程，本次未執行 commit、push 或 publish。

變更歷史​

日期內容
2026-10-04提案並完成兩輪 peer review；第 2 輪通過，close 落點確認後採納，HTML／PDF 補證據記為 FU-127