Package io.leandev.appfuse.pdf
package io.leandev.appfuse.pdf
中立 PDF 產物與保存契約（PdfArtifact、StoredPdf、StoredPdfs）遵循一般公開 API 相容政策。
FixedDocument、FixedPdfRenderer、FixedTextMeasurer、FixedLayoutException 為實驗性固定版面 API。
固定幾何使用 mm，字級使用 pt；不暴露 PDFBox 型別。
-
ClassDescription固定版面文件；幾何為 mm（左上原點，x 向右、y 向下），文字、字距、線寬與虛線長度為 pt。 頁面、明細容量及續頁由模板明確建立，不自動流動或分頁；元素依清單順序繪製。黑白向量條碼。moduleMm 不縮放；一維碼 heightMm 為條高，QR 高度由模組數決定。 quietModules 為每側靜區，QR 至少 4、一維碼至少 10。payload 的業務檢查碼由應用提供。 不自動加入人眼可讀文字，需另建 Text。橢圓外接框，可用於蓋章區；填色可省略。固定文字框／圖像框；座標為外框左上角。PNG／JPEG 於框中等比置中，不拉伸；位元組防禦複製。STATIC 為框線／底圖等預印內容；VARIABLE 為每份資料。套印只輸出 VARIABLE。建立者判定的幾何問題，例如區塊重疊；不可用此接點表示權限、資料或版本錯誤。 自訂 code 應使用應用自己的穩定命名空間。嚴格政策拒絕，警示政策完整繪製。任意方向線段，可用於撕線、點線或虛線分隔。 dashPatternPt 為交替的線段與空白長度（pt，與線寬同單位）；空清單為實線，奇數個元素由 PDF 重複兩次形成週期。 dashPhasePt 為週期起點偏移，實線必須為 0。整條線以單一路徑繪製，不需拆段。固定頁；同頁 ID 不得重複。嚴格政策要求框線筆畫也位於紙張內。PDF 頁面外觀底稿，固定為 STATIC 層。頁碼從 1 起，不匯入註解、AcroForm 或動作。 來源頁面須無旋轉、CropBox 原點為 0、UserUnit 為 1，尺寸與目標頁相同；不自動縮放。fillRgb 為 null 表示不填色；線寬必須大於 0。CRLF／CR 正規化為 LF，Tab 展開成四個空格（非 tab stop）；其他控制字元拒絕。 lineHeightPt 為基線間距；使用整個文字框所用字型的最大 ascent／descent 檢查上下界，不以裁切掩蓋超框。 letterSpacingPt 為同一行相鄰 code point 之間額外加的距離（非負，預設 0）；行尾不加， 對齊、換行與超框檢查都以含字距的寬度計算。不做字距微調（kerning）。超框依 LayoutPolicy 回報警示或拒絕；不靜默縮字或截斷。固定版面無法依契約輸出；建構期 location 為元件 ID，render 期為頁碼／元件。 code／location 供持有例外的呼叫端診斷，不包含業務資料值。 ReportStatus.Failed 對外只保留通用 report.invalid，不傳送內部定位資訊。固定版面 PDF 公開入口，與流式 ReportDocument／ReportArtifact 無關。 共用已驗證的字型登錄與 PDFBox runtime；renderer 可跨執行緒重用。只處理幾何排版異常；字型、資產、容量與生成錯誤仍拒絕。 預設 OUTPUT_WITH_WARNINGS；只有明確選用 STRICT 才拒絕幾何異常。平移校準以 mm，作用於全部輸出元素；不更改紙張尺寸。overlayOnly 略過 STATIC 層。以與
FixedPdfRenderer相同的字型登錄、fallback 鏈與字距規則量測單行文字， 供應用在建立FixedDocument前自行計算座標（例如逐字定位、置中或拉伸標籤）。 同一份ReportFonts下，量得的寬度等於 renderer 對齊與超框檢查使用的寬度。與 authoring model 無關的完成 PDF；呼叫端擁有並負責 close。 關閉後不可再開串流；已開串流可讀完，最後一個串流關閉時刪除暫存檔。 close 可重複呼叫，清理失敗只記 WARN，不取代產生或保存結果。固定 PDF 的幾何排版診斷；頁碼為原始 PDF 的實體頁碼（從 1 起）。 識別與訊息由建立者提供，對外傳送前應用須確認不含私密資料。已保存的 PDF 中性描述；保存期限以 storedAt 起算。把
PdfArtifact保存到FileStorageStoredPdf stored = StoredPdfs.save(fileStorage, partition, renderer.render(document, options, "form.pdf"));partition 必須是經應用驗證的可信分區識別，不可直接接受外部輸入或路徑片段（如
..）。 partition 由應用決定：tenant 模組傳目前 tenant ID，tenantless 模組傳應用常數或依資料範圍設計的值。 保存期限由應用以StoredPdf.storedAt()計算並自行刪除；框架不排程刪除。