ADR-020：HTML＋CSS 成為 RPT 的正式版面規格

ADR 編號：020 狀態：已接受 (Accepted) 提案日期：2026-10-03 決策日期：2026-10-03 審閱：20261003-html-report-layout，第 3 輪通過；close 結論落點經使用者確認 最後修訂：2026-10-20（P2-6 設計通過，明確對齊 ADR-023 D2 的既有不能提交來源窄例外；原決策維持 Accepted） 修訂審閱：20261004-report-reproducibility，第 2 輪通過；close 結論落點經使用者確認，修訂決策日期為 2026-10-04 還原流程修訂審閱：20261007-report-restoration-confirmation，第 3 輪通過；兩輪共 9 條意見（2 major、7 minor）均已處置，close 結論落點經使用者確認 方向確認：使用者同意將 HTML 納入報表規格；方法論採納依據為第 3 輪 peer review 與 close 落點確認 範圍：RPT 範本、版面確認流程、/report、HTML／PDF 證據工具

問題

只有文字版面條件與實作後 PDF，容易讓人類與 AI 對欄寬、日期位置、雙行紀錄分隔、合計對齊及分頁產生不同理解。 即使業務欄位與計數正確，PDF 仍可能偏離提供的樣張；等實作後才確認，修改成本也較高。

決策

RPT 由 Markdown 業務契約、HTML＋CSS 版面規格及合成資料共同定義，均納入版控與修訂追蹤。 人類提供樣張時，AI 先忠實重建 HTML、明列不能確定的尺寸／字型，再提供對照讓人類確認。 原樣張還原與需求調整後的採用版面分開標示；沒有原樣張時建立 HTML 提案。 PDF 範本依有效已確認的採用版面實作，完成後使用同一組合成資料與規格容差對照 HTML，再由人類接受精確 PDF。

契約分工

產物	責任
RPT Markdown	參數介面、資料語意／來源、計算、容量、錯誤、flow／fixed 規則及版面包路徑
HTML＋CSS 版面包	可檢視的版面、欄位映射、資產、合成案例、差異清單、預覽環境與重現方式
原樣張還原確認附件	原樣張／還原內容及資產的指紋、對照入口、未決差異與真人對理解是否正確的確認
採用 HTML 帳本	整包及必要來源指紋、版次、真人對實際製作版面的確認
PDF 帳本	測試與輸出證據、已確認 HTML 快照、真人對精確 PDF 的接受

Markdown 與 HTML 衝突時須取得決策並同步修訂，不能靜默選擇一方。 條件、容量與欄位語意不由樣張推測；這項決策不改變 ADR-017 的參數介面與 US 責任。

指紋及相容性

HTML 版面包由 Git 列舉 tracked 與未被忽略的 untracked 成員取指紋，包含 CSS、字型、合成資料及環境設定；ignored 殘渣不影響狀態。外部原始需求以脫敏來源摘要承接；實作／測試來源由 PDF 帳本承接，不混入 HTML 語意來源。 HTML 確認採整包接受，部分接受不能標示整包通過；新 PDF record 要求同一 RPT 有效已接受的 HTML。 PDF schema 2 保存當時的 HTML 接受快照，後來 HTML 帳本重新登錄但內容未變，不抹去既有 PDF 依據。 內容／來源改變仍使依據 stale；重新登錄保留歷史且不沿用接受。

既有 schema 1 PDF 帳本保持可核對與原有接受語意，另顯示 htmlStatus: not-recorded。 不因新流程自動撤銷原接受，也不將原 PDF 接受轉成 HTML 確認。下一輪改版或 record 時補上 HTML。 這包含首次只修 bug、版面未改的重錄：仍有補建 HTML 與一次真人確認的成本。已有有效 HTML 而版面／語意來源未變的實作修正，可沿用 HTML 接受後重驗 PDF。

能力邊界

HTML 是版面規格，不表示目前框架能將任意 HTML／CSS 直接轉 PDF。 既有 renderer 可依 HTML 規格以公開 authoring API 實作；無法滿足的部分列為能力缺口，循既有設計／RFC 流程或取得版面調整決策。 預覽需明定瀏覽器／排版工具、字型、實體尺寸與分頁；工具只核對指紋及接受資料，不能證明 CSS 正確、資產完整或真人身分。 HTML／PDF 接受仍不取代真實資料授權、產品流程、實紙套印或掃讀驗收。

2026-10-07 修訂：先確認還原理解，再確認採用設計

使用者明確要求把原樣張還原與採用設計分為前後兩個真人關卡，並以「正確。請開始調整。」授權本次修訂。此項是本次使用者決策，不冒充先前 peer review 的新增裁決。

• 有樣張時，HTML＋CSS 還原目標是原樣一致，包括版面、完整原始範例資料、字體、字級與顏色；原錯字、錯誤數值及不合理配置原樣保留，觀察另列。不因資料是否含真實個資替換、遮蔽或改為合成值，不套用規格或專案預設。
• 第一關確認 AI 是否正確理解原樣張；無法辨識或重現處明列，由人類處置。以 restoration-confirmation.json（schema: 1）保存原樣張及還原檔案摘要、對照 URL、觀察與真人原話；作者核對實際內容，現行 helper 不新增此階段的命令，自動化另由框架 backlog FU-134 承接。
• 還原包不得置於採用包：可公開素材使用獨立 static/reports/restorations/{RPT-ID}/{restorationId}/，受控素材保存在團隊受控儲存並由獨立受控 Docusaurus 提供，來源／build 不入公開輸出。原字型預覽或受控環境無可執行方式時第一關阻塞，能力缺口沿 FU-126 追蹤，不替換原內容。作者核對原樣張及全部還原檔案的 HTTP bytes／摘要，公開建置清單涵蓋還原及 PDF 展示目錄；操作權威置於指南，不宣稱已有受控預覽工具。
• 第一關完成後，才依原樣張、RPT 及專案樣式提出採用設計、修改理由與基本／空資料／長文／跨頁／容量邊界等合成案例；第二關使用既有 accept-html 確認最終採用包。還原與採用檔案分開標示、保留，採用設計不覆寫已確認還原。
• PDF 實作後仍以 accept 取得精確檔案接受；三個命題與紀錄分開，沒有原樣張時略過第一關。保存及存取方式不改變還原內容；採用與 PDF 驗證仍使用合成案例。
• 方法論修訂不批次改既有 RPT／版面包／帳本，不撤銷既有有效接受或補造過往還原確認；後續新建或重新製作原樣張還原才依新關卡辦理。

原決策已涵蓋還原與採用分工，本次將先後順序、原資料保留及確認命題明確化；工具的採用 HTML／PDF schema、CLI 與既有接受承接條件維持原契約。權威操作與紀錄欄位見 報表規格指南。

本次修訂經 20261007-report-restoration-confirmation 第 3 輪通過，無未處置或不採納意見。結論由本 ADR、report skill 2.6.0、方法論索引、權威指南及 RPT 範本承接；框架 backlog FU-134 保存還原確認工具自動化待辦，FU-130 擴充部署清單至還原與 PDF 展示目錄，既有 FU-126 受控包工具限制保留。下游使用自己的待辦 ID，不將框架編號當成本專案指令。 使用者以「確認上述落點，完成 close（建議）」確認上述結論落點；本次修訂完成 close 檢核，原決策維持 Accepted。 受控 Docusaurus 依指南四項最低條件判定，符合即可執行；本次未實作受控預覽工具、還原確認自動化或部署守衛。既有報表原值及有效接受保留，不補造歷史還原確認；方法論通過不代表報表版面接受、commit、下游 publish 或站台部署。

2026-10-04 修訂：相同 PDF 的接受承接（已採納）

20261004-report-reproducibility 經第二輪審閱通過並完成 close，採納明確的 carry-acceptance 操作，保留「重新登錄不自動沿用接受」。 只有同一 RPT、相同契約與已接受 HTML 版面包、指定的同名案例完整 PDF SHA-256 相同，且已重新完成自動驗證時， 才能在證據維護後承接原 PDF 版面接受。原 schema 2 帳本、接受紀錄及 PDF bytes 必須保留且可核對； 操作保留原接受者、原話與接受時間，另記來源帳本時間、舊 PDF 路徑、承接理由與操作時間。 只承接逐項指定的案例，不將部分接受擴張為整批接受，也不補造新的真人接受。

契約、HTML、PDF bytes 任一改變、原接受缺失／已知誤判、或需要真人重驗時，仍須新的接受。 schema 1 保持原 status／accept 相容性，但不能作為承接來源；不排除 /ID、不以相同圖像代替完整 bytes。 這項例外不承接自動測試或產品流程驗收；證據維護與真人重驗的界線沿用 ADR-019。 工具只核對帳本一致性，原真人接受仍須有原始對話或受控紀錄佐證。

同批 flow renderer 修正 /ID 可重現性，但首次升級會改變既有 PDF bytes，故不能直接承接升級前的接受。 本修訂已採納並提交，操作由 report skill 2.2.0 提供；流式 renderer 修正於 2026-10-04 隨 appfuse-server 4.0.0-alpha.24 發布。 方法論下行依 /methodology publish 的納入範圍與實際结果核對，不因框架 artifact 發布而宣稱所有下游已同步；操作細節見 報表規格指南。 結論由本 ADR、report skill／rules、權威指南及 framework CHANGELOG 承接；兩項 minor 已處置，不新增 follow-up 或 FEATURE_CHANGELOG。

考量的方案

方案	判斷
只增加一張預覽截圖	缺乏可檢查與修訂的排版結構，無法承接長文／分頁案例
HTML 僅作暫時示意	後續實作與驗收失去共同依據，採用變更也難以追蹤
HTML＋CSS 作為正式 RPT 版面規格	已採用；先確認理解，再實作與對照 PDF
同時更換為通用 HTML→PDF 引擎	超出本輪方法論範圍；須另評估框架設計及現有 flow／fixed 能力

2026-10-20 補充：原件保存與 ADR-023 D2 對齊

P2-6 設計通過第 2 輪審閱（受審 revision r2-87cfce29bd2c9c8c，審閱者 ada@leandev.io）；保存決策與完整結論見證據保留 §6、§11。

• Git 為一般文件及可提交來源的預設共享儲存；已有來源契約明示不能提交的原件／證據包，繼續保存在原定 controlledRoot／evidence-location。Git 保存來源版次、路徑基準、相對檔案清單、完整 SHA-256、取回說明及確認附件，不保存憑證。這是對 ADR-023 D2 的窄例外，不自動建立外部服務、LFS、下載或搬移既有原件。
• 同一內部專案文檔站仍提供本輪完整固定副本、原樣張與還原對照；維持原樣張理解、採用 HTML、精確 PDF 三個不同確認命題。沿用 2026-10-10 的本站入口與部署分工，不恢復讀者／存取控制／部署批准關卡或另一個審閱網站。
• ignored 展示副本不是唯一原件；來源不可取得或摘要不符時揭露 unavailable／不可重建，不宣稱可安全清理。既有有效接受、歷史原文及完整 bytes 不改寫。
• UAT 快照及 report 帳本／runs 維持原位，以完整歷史引用保留。retention 為提交參考，blocked 時本次原生有效成果依原契約及授權精確保存／交付，不新增交付閘門，不豁免原有 verifier／人工接受。此設計不授權自動刪除或 stage。
• 設計結案時 report-source 分類及原生 retention／exporter、協作鎖與提交出口驗收仍待 P2-6 實作及另輪審閱（實作對照見證據保留 §12）；本補充不宣稱已支援外部／ignored 採用 HTML 包登錄，也不完成 FU-126／FU-134。

2026-10-10 修訂：完整本站瀏覽與部署分工

使用者再次明確定位應用文檔站為開發團隊內部、供 AI 與人類溝通的網站，所需素材可供團隊存取，部署由人類決定；並要求「要讓人類可以透過瀏覽介面存取需要存取的文件」。本修訂依本次對話決策，不冒充既有 peer review 的新增通過結論。

• 本輪需要人類閱讀或確認的完整文件及附件，包含原始樣張、還原對照、採用 HTML 與全部 PDF 案例，直接由同一專案文檔站提供瀏覽／下載入口。
• 刪除現行流程中的讀者／存取控制重新核對、未核對部署視為公開輸出及改用獨立受控 Docusaurus 分支；這些部署前提不能阻擋開發期間展示。
• AI 核對入口可用、本輪內容、必要資產、版本與完整檔案摘要，維持進行中的審閱 URL。部署方式、環境及交付範圍由人類決定，另依既有部署流程處理。
• 原件、gitignored 展示副本、採用包及證據帳本仍分開保存；字型實際網頁使用授權、三次真人確認及 helper 指紋／schema 契約保留，不補造或撤銷既有報表接受。

本修訂由共通執行 rule、report skill 2.8.0、專案文檔協作指南、報表指南與 RPT 範本承接。以下 2026-10-07 的分流及部署前置紀錄保留為歷史，現行要求以上述修訂及權威指南為準。框架公開指南站維持自己的用途；本次不修改 host 建置、renderer、既有報表或 backlog 的完成狀態。

2026-10-07 補充：內部專案文檔站作為過程成果入口

使用者明確定位應用文檔站為開發團隊內部、人類與 AI 共用的專案文檔網站，不對外開放；並要求樣張還原、樣板設計等報表製作過程也能在此瀏覽。此項補充依本次使用者決策，不冒充前述 peer review 的裁決。

本補充及同批共通文檔協作變更經 20261007-project-documentation 第 3 輪 peer review 通過（2026-10-07）；前兩輪 12 條意見均已處置，第 3 輪 R3-01 的版本及待審文字修正亦已落地。使用者已於 2026-10-07 確認 close 結論落點：本 ADR、既有 rules／skills／指南及 FU-135，不另建立 Feature Changelog。此紀錄獨立於本 ADR 的歷史通過批次。

• 原樣張與還原對照、設計樣板及各資料情境預覽、最終 PDF，均以同一內部專案文檔站為預設瀏覽入口，分別取得還原理解、採用樣板與 PDF 接受。
• 存取分流依實際讀者範圍，不以「可否對外公開」決定是否能進內部站台。本站符合素材可閱範圍及網頁使用條件時沿用；只有素材範圍比本站更窄，或來源／build 另供公開輸出共用時，才另用受控實例。
• 原件、展示副本、採用包及接受帳本仍依各自保存契約管理；不能提交的原件不因本站內部使用而進版控。helper 對外部／ignored 採用包的限制、既有有效接受及歷史證據保留。

本補充修正前述歷史修訂中以公開站台為前提的存取分流；現行操作依 報表規格指南 與 report skill 2.7.2。本站是瀏覽入口，不因本次定位說明而宣稱已實作部署存取控制或受控包工具。

本批結論由共通執行／網址／人審 rules、對應 skills、內部專案文檔協作指南、本報表補充及應用文檔站說明承接。既有下游 docs-host 的 reviews/**／reports/restorations/** 排除補強記於框架 backlog FU-135；部署清單與讀者範圍預檢仍由 FU-130 承接。未新增產品功能或修改報表 renderer，因此不另建立 Feature Changelog；本次通過不表示已 commit、已發布至下游、已補齊下游守衛或已完成真人報表驗收。

影響與遷移範圍

• 權威指南與 RPT 範本、report skill 2.0.0、方法論／開發護欄／skill 執行位置及索引同步更新。新 record 必填 --html-manifest 是不相容變更，故遞增 MAJOR；舊 schema 1 的 status／accept 仍相容。
• 版面包放在 docs 模組 static/reports/layouts/{RPT-ID}/，JSON／HTML 說明與 pathname 預覽連結，不放在 docs/ 內容樹。原始敏感樣張不進公開 static；內部站台展示依上述讀者範圍提供固定副本，接受帳本不進 static。
• evidence helper 新增 HTML 帳本操作、新 PDF record 的 HTML 前置條件及 schema 2；保留 schema 1 讀取／接受。
• Codex adapter 由 canonical 重新生成，不手改 wrapper；不發布到下游 fleet。
• 既有報表範本、PDF 與驗收帳本本輪不改寫；個別報表下一輪依此流程補規格，不宣稱已完成遷移。
• 本輪不建立產品 UI、HTML importer、renderer 或正式資料整合。

操作與保存契約見 報表規格指南。本決策及本批方法論變更已經第 3 輪 peer review 通過；採納不等同已提交、已發布至下游或真實報表版面已驗收。

通過後的狀態與提交

審閱方明示通過且完成 close 的結論落點檢核後，將本 ADR 改為 Accepted，記錄實際決策日期與審閱輪次，移除指南及 llms.txt 的待審標示。這些採納 metadata 更新須核對並重跑文檔建置，不在尚未通過時提前採納。 close 本身不代做 commit／publish。使用者另行授權提交時，精確列出本批 paths，以限定檔案的提交隔離工作區其他 staged 批次；不使用 git add -A、不清空或還原他人的 index，也不以一般無 pathspec 的 commit 混入 FU-111／FU-117。提交前後核對本批 diff 與原有 staged entries；下游發布另走 methodology 流程。 本次 close 新增的 FU-126 與其他 staged 變更共用同一 backlog 檔案；該檔須按本批變更區塊切分，不能以整檔 commit --only 混入既有批次。

審閱結論落點

第 3 輪裁決通過，R1 的 7 條意見及 R2 的字型授權意見已處置；結論由本 ADR、方法論 rules／report skill 與權威指南承接。索引排序與用字已修正，不另外建立 renderer 的 Feature Changelog。

static 字型須具網頁散佈授權，可入版控或桌面使用不等同該授權。授權不允許時，改用可公開散佈的替代字型，或在授權允許的範圍內受控保存及預覽，不能隨站台發布。 第 3 輪 R3-01 指出受控包的工具缺口：現行 helper 僅接受 workspace 內、Git 可列出的成員，外部或 ignored 的包無法 record-html。此項以框架 backlog FU-126 保留，後續定義登錄／資產摘要與取回契約，並於 FU-117 nbsos 試點驗證；本次不宣稱已支援受控包登錄。

既有 PDF 接受保持原語意，未補造 HTML 確認；個別報表的 HTML 遷移、真人版面確認與 PDF 對照仍由後續報表工作承接。既有 renderer 保留，通用 HTML→PDF 引擎不在本次範圍。

變更歷史

日期	內容
2026-10-20	P2-6 設計通過，保存既有不能提交原件／證據包的受控來源窄例外並對齊 ADR-023 D2；同站完整副本、三關確認與部署分工不變。retention 為提交參考，blocked 不新增交付閘門；工具及分類仍待實作、未清理或搬移原件，Accepted 維持。
2026-10-10	依使用者決策將本站完整文件／附件瀏覽確立為既定前提；report 2.8.0、共通 rule、指南與範本對齊，移除讀者／存取控制核對及獨立受控網站分支，部署由人類另行決定；歷史紀錄與報表接受保留
2026-10-03	初版提案；使用者確認方向，方法論變更等待 peer review
2026-10-03	第 1 輪意見處置：排除 ignored 檔並補 clone 測試、版本改 2.0.0、明列 bug fix 重錄成本、static 版面包與站台連結契約；第 2 輪待審
2026-10-03	第 3 輪通過並完成 close 落點確認，改為 Accepted；字型網頁散佈授權已明訂，受控包登錄缺口另記 FU-126，renderer 與既有報表驗收範圍保留
2026-10-04	新增相同完整 PDF 的明確接受承接修訂提案；等待 20261004-report-reproducibility 審閱，不改寫原接受決策
2026-10-04	20261004-report-reproducibility 第 2 輪通過並完成 close，接受承接修訂已採納；跨 JVM 自動回歸已補齊，既有報表接受與框架發布／升級後的新接受界線保留，不新增 follow-up
2026-10-07	依使用者明確確認拆分原樣張還原理解與採用設計兩個關卡，原資料／外觀完整保留；report 2.6.0、指南、RPT 範本與索引同步，既有工具及已接受報表不批次遷移
2026-10-07	20261007-report-restoration-confirmation 第 3 輪通過並經使用者確認 close 結論落點，兩輪 9 條意見均已處置；還原與採用包分離、受控預覽最低條件、路徑基準及下游引用明確化；新增 FU-134、擴充 FU-130，工具實作仍待後續工作
2026-10-07	依使用者明確定位內部專案文檔站，補明報表還原／設計／PDF 過程瀏覽，修正公開站台前提的存取分流；report 2.7.2、指南與範本對齊，保存及證據工具契約維持；20261007-project-documentation 第 3 輪通過，R3-01 的版本與待審文字已修正，使用者確認 close 結論落點；補明未核對部署視為公開、還原副本 gitignore 及目標 host 的實際排除核對，不推定既有下游已有守衛