AST 稽核軌跡

速覽

NextPDF Enterprise 會將每一次 AST 變動記錄為僅可附加、以單一文件為範圍的稽核軌跡，並為下游管線產生語意上有界、帶引用錨點的 AST 區塊。該軌跡支援稽核與可追溯性工作流程。它不是法律證明，也不是文件完整性的認證。

可用性與授權

此能力隨 NextPDF Enterprise（nextpdf/enterprise）出貨，並以 Enterprise 層級的授權信封啟用。未持有該權限的部署不會載入此能力的類別。比較各版本並取得授權。

安裝

composer require nextpdf/enterprise:^3

概念總覽

AstAuditTrailInterface 是記錄合約。record($documentSourceHash, $log) 會將 Pro AST MutationLog 中的每一筆項目轉換成一個 AstAuditEntry 並附加之；以同一個文件雜湊重複呼叫，會累積項目。其實作依合約僅可附加：一旦記錄，項目即無法修改或移除。findByDocument($hash) 會依插入順序回傳某一份文件的項目；count() 會回傳所有文件的總數。InMemoryAstAuditTrail 是參考實作。

AstAuditEntry 是一次變動的不可變紀錄：文件來源雜湊、正規化節點 id、變動類型（updated / inserted / deleted）、以 0 為起點的頁面索引、變動前後的屬性快照，以及項目被記錄時的 UTC 時間。擷取以每個文件雜湊為範圍，因此稽核歷史會以每份文件為單位保持隔離。

AstAwareChunker 會深度優先走訪一個 AST，並發出尊重文件結構的 AstChunk 實例：標題會開啟一個新區塊、葉節點文字會累積到一個設定好的大小，而一個重疊窗口會在切分邊界間保留連續性。每一個區塊都帶有其第一個貢獻節點的節點 id、頁面索引、定界框，以及節點類型，因此下游系統可以引用一個精確的來源位置。

此模組主張什麼

此模組會 記錄變動歷史並產生結構化區塊。它不認證完整性，也不提供法律證明。

• 稽核軌跡在所設定儲存區內依合約僅可附加。防竄改證據與不可否認性，是你「在何處、以何種方式持久化並蓋上時間戳記」的屬性（請參閱 Evidence），而非此模組本身單獨提供的保證。
• 記錄一次變動證明的是它發生過。它不驗證或授權該變更。
• 區塊引用指向來源位置；它們是導覽輔助，不是一致性聲明。

稽核軌跡支援稽核工作流程；它不是法律證明，也不是稽核認證。

層級邊界

• NextPDF Core / Pro AST 提供 AST 模型與變動日誌。
• NextPDF Enterprise AST（本頁） 在那些變動之上，新增僅可附加、以單一文件為範圍的稽核軌跡，以及帶引用錨點的分塊器。它消費 Pro 變動日誌；它不取代 AST 模型。

為何如此設計

承載重量的決策是範圍上的克制。此模組記錄一次變動發生過；持久性、防竄改證據與不可否認性則委派給支撐儲存區與 Evidence 模組。這讓承諾保持誠實：一種給稽核人員的記錄輔助，而非此模組單獨無法佐證的認證。擷取以 documentSourceHash 為鍵，因此一份文件的歷史絕不會滲入另一份。分塊器將每一個區塊錨定到其第一個節點，並在前端驗證 maxChunkChars 與 overlapChars，因此引用保持精確。持久化與資料落地留在操作者手中，因此同一個介面既能服務 WORM 支撐的證據儲存區，也能服務較輕量的管線。

設計背景：你可以交給稽核人員的合規。

API 介面

類別 / 介面	職責
AstAuditTrailInterface	僅可附加的記錄與每個文件擷取合約。
AstAuditEntry	帶有變動前後快照、一次變動的不可變紀錄。
InMemoryAstAuditTrail	參考的僅可附加軌跡實作。
AstAwareChunker	尊重結構、帶引用錨點的 AST 分塊器。
AstChunk	帶有節點 id、頁面索引、bbox 與節點類型的單一區塊。

程式碼範例——快速上手

$trail->record($documentSourceHash, $mutationLog);
$entries = $trail->findByDocument($documentSourceHash);

程式碼範例——正式環境

$trail->record($documentSourceHash, $mutationLog);

foreach ($trail->findByDocument($documentSourceHash) as $entry) {
    $logger->info('ast.audit', [
        'node'     => $entry->nodeId,
        'type'     => $entry->mutationType,
        'page'     => $entry->pageIndex,
        'recorded' => $entry->occurredAt->format(DATE_RFC3339),
    ]);
}
// Persist the trail in a WORM-backed store for tamper-evidence (see Evidence).

邊界案例與陷阱

• 將同一個 MutationLog 記錄兩次會累積項目；若你需要冪等性，請在上游去除重複。
• 記憶體內的軌跡不具持久性；正式環境部署應提供一個持久化的 AstAuditTrailInterface。
• 僅可附加是儲存區的合約，而非密碼學屬性；請搭配 Evidence 封裝以取得防竄改證據。

效能

記錄的成本與變動項目數量呈線性。分塊是一次深度優先的 AST 走訪；成本隨節點數量與設定的區塊大小增加。

安全注意事項

變動前後快照可能含有文件文字。請將軌跡在靜態時視為敏感。僅可附加合約可防止透過此 API 進行原地編輯，但持久性與防竄改證據取決於支撐儲存區。

資料落地與 PII 緩解措施

變動快照可能承載從文件擷取出的個人資料。持久化委派給你的軌跡實作，因此落地隨你的儲存區而定。請對已記錄的快照套用保留與最小化控制措施。

安全遙測與日誌清洗

節點 id、變動類型、頁面索引與時間戳記可以安全記錄。變動前後快照可能含有文件內容；在轉送到共用接收端之前，請先將其遮蔽。

一致性

行為	參考	狀態
增量更新 / 完整性情境	ISO 32000-2:2020 §12.8	已參考（防竄改證據的情境）

此表記錄此模組運作所在的規格情境。稽核軌跡是一種記錄輔助，不是認證，也不是法律證明。

FIPS 模式行為

此模組不執行任何密碼學運算。用於防竄改證據的雜湊、簽署與蓋時間戳記由 Evidence、Security 與 Signature 模組處理。

威脅模型

輸入是一份變動日誌。緩解措施：僅可附加的記錄合約、以每個文件為範圍以隔離歷史，以及將持久性與防竄改證據委派給具 WORM 能力的儲存區與 Evidence 模組。

行為合約

• 稽核軌跡在所設定儲存區內依合約僅可附加：一旦記錄，項目即無法透過此 API 修改或移除。
• 每一筆項目都是一次變動的不可變紀錄（文件來源雜湊、正規化節點 id、變動類型、頁面索引、變動前後快照、記錄的 UTC 時間）；擷取以每個文件雜湊為範圍。
• 將同一份變動日誌記錄兩次會累積項目——若需要冪等性，請在上游去除重複。
• 分塊器會深度優先走訪 AST，並發出尊重結構的區塊，承載節點 id、頁面索引、定界框與節點類型，以供精確的來源引用。
• 記錄一次變動證明的是它發生過；它不驗證或授權該變更，而區塊引用是導覽輔助，不是一致性聲明。

發佈邊界

本頁僅記載外部可觀察的行為與所支援的公開 API 介面。內部命名空間路徑、輔助類別、機制表格、runbook 檔名，以及工單前綴皆不在範圍內。

Core 回退

NextPDF Core / Pro AST 提供 AST 模型與變動日誌。僅可附加、以單一文件為範圍的稽核軌跡與帶引用錨點的分塊器沒有 Core 層級的對應；Enterprise 介面消費變動日誌，它不取代 AST 模型。

Pro 回退

NextPDF Pro AST 提供 AST 模型與變動日誌，但沒有僅可附加、以單一文件為範圍的稽核軌跡，也沒有帶引用錨點的分塊器。那些僅隨 nextpdf/enterprise 套件提供；Enterprise 介面消費 Pro 變動日誌。

Enterprise 邊界註記

記錄合約、每個文件擷取，以及分塊器以行為層級描述。參考的記憶體內軌跡有記載；持久化由主機提供，而任何內部儲存區內部實作皆不在公開介面範圍內。

部署邊界

僅可附加是儲存區的合約，而非密碼學屬性。操作者提供一個持久化的軌跡實作，並負責將其持久化於一個 WORM 支撐的儲存區以取得防竄改證據；持久性與不可否認性取決於該儲存區與 Evidence 模組，而非單靠此模組。變動快照可能承載個人資料；落地隨操作者的儲存區而定。

法律合規邊界

AST 稽核軌跡介面不適用任何出口管制限制。稽核軌跡支援稽核工作流程；它不是法律證明，也不是稽核認證。本文件不是法律意見；請諮詢你自己的合規與法律顧問。

另請參閱

• Evidence — 封緘並為軌跡蓋上時間戳記。
• Validation — 結構性原則檢查。
• Core AST — AST 模型。
• AST 稽核軌跡——深入參考 — 持久化儲存區內部實作與完整的公開 API 介面。