Enterprise 版本

AST 稽核軌跡 — 深入參考

概覽

Enterprise AST 模組會記錄文件變動，並為檢索管線預備文件。

AstAuditTrailInterface 在 Pro AST MutationLog 之上定義一個僅可附加、逐文件的稽核軌跡。
AstAuditEntry 是單一變動的不可變記錄：節點識別、變動種類、頁面、前/後快照、UTC 時間戳。
InMemoryAstAuditTrail 是該軌跡合約的逐行程參考實作。
AstAwareChunker 會以深度優先方式走訪 AST，並發出引用錨定的 AstChunk 值以供 RAG 攝入。

可用性與授權

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

AST 稽核軌跡介面由 enterprise.compliance.evidence 能力授權。被拒絕的權益會拒絕此功能。

層級	提供
Core	AST 文件模型（`AstDocument`、`AstNode`、`NodeId`）
Pro	AST 變動流程與 `MutationLog`
Enterprise	僅可附加的逐文件稽核軌跡；引用錨定的分塊器

Enterprise 介面消耗 Pro 變動日誌。它不取代 AST 模型。

composer require nextpdf/enterprise:^3

公開 API 介面

符號	參數	預設行為	回傳	拋出或失敗於	註記
`AstAuditTrailInterface::record()`	`string $documentSourceHash`, `MutationLog $log`	將日誌中的每一個變動項目轉換為一個 `AstAuditEntry` 並加以附加	`void`	參考實作中無	以同一個雜湊重複呼叫會累積項目
`AstAuditTrailInterface::findByDocument()`	`string $documentSourceHash`	依插入順序回傳單一文件所記錄的項目	`list<AstAuditEntry>`	參考實作中無	無項目符合該雜湊時為空清單
`AstAuditTrailInterface::count()`	無	計算稽核項目數	`int<0, max>`	參考實作中無	是跨所有文件的總數，非逐文件
`InMemoryAstAuditTrail`	無	以陣列為底、限縮於當前行程的軌跡	實作 `AstAuditTrailInterface`	無	不具耐久性；適合單次請求生命週期
`AstAuditEntry`	建構子提升所有欄位	不可變的稽核記錄	值物件	無	`final readonly`；參見下方簽章圍欄
`AstAwareChunker::__construct()`	`int $maxChunkChars = 1500`, `int $overlapChars = 150`	在建構時驗證分塊界限	實例	組態超出範圍時拋出 `InvalidArgumentException`	界限：`16 <= maxChunkChars <= 1048576`；`0 <= overlapChars < maxChunkChars`
`AstAwareChunker::chunk()`	`AstDocument $document`	深度優先走訪；標題界定區塊；葉節點文字累積	`list<AstChunk>`	無	對無可累積文字的文件回傳空清單
`AstChunk`	建構子提升所有欄位	引用錨定的區塊記錄	值物件	無	`final readonly`；參見下方簽章圍欄

namespace NextPDF\Enterprise\Ast;

use NextPDF\Pro\Ast\Mutation\MutationLog;

interface AstAuditTrailInterface
{
    public function record(string $documentSourceHash, MutationLog $log): void;

    /** @return list<AstAuditEntry> */
    public function findByDocument(string $documentSourceHash): array;

    /** @return int<0, max> */
    public function count(): int;
}

final readonly class AstAuditEntry
{
    public function __construct(
        public readonly string            $documentSourceHash,
        public readonly string            $nodeId,
        public readonly string            $mutationType,
        public readonly int               $pageIndex,
        public readonly array             $before,
        public readonly array             $after,
        public readonly DateTimeImmutable $occurredAt,
    ) {}
}

final class AstAwareChunker
{
    public function __construct(
        private readonly int $maxChunkChars = 1500,
        private readonly int $overlapChars = 150,
    ) {}

    /** @return list<AstChunk> */
    public function chunk(AstDocument $document): array {}
}

final readonly class AstChunk
{
    public function __construct(
        public readonly string $text,
        public readonly string $nodeId,
        public readonly int $pageIndex,
        public readonly ?array $bbox,
        public readonly string $nodeType,
        public readonly string $documentSourceHash,
        public readonly int $chunkIndex,
    ) {}
}

行為合約

稽核軌跡

**僅可附加。**實作必須為僅可附加：透過此 API 無法修改或移除一個已記錄的項目。以同一個雜湊重複呼叫 record() 會累積項目。
轉換。record() 會將 Pro MutationLog 的每一個項目（透過 MutationLog::all()）轉換為一個 AstAuditEntry 並加以附加。單次 record() 呼叫所產生的所有項目共用同一個 UTC occurredAt 時間戳。
逐文件隔離。findByDocument() 會以精確的文件來源雜湊過濾並保留插入順序。count() 是跨所有文件的總數。
快照。before 與 after 是以 text_content 為鍵的屬性映射。updated 變動會填入兩側；inserted 使 before 為空；deleted 使 after 為空。mutationType 是 Pro MutationType 列舉的字串值：updated、inserted 或 deleted。
頁面推導。pageIndex 從標準節點 ID（ast:{hash}:{page}:{seq}）擷取而得。格式錯誤的節點 ID 會產生 pageIndex 0；該項目仍會被記錄。

僅可附加是所設定儲存體的一項合約，而非密碼學屬性。竄改證據與不可否認性來自於該軌跡如何被持久化與蓋章（Evidence 模組），而非單靠本模組。

分塊器

走訪。chunk() 會從文件根節點以深度優先方式走訪 AST。
**文字累積。**Paragraph、ListItem、TableCell、Code 或 Annotation 類型的葉節點文字會累積到當前緩衝區。容器類型（Document、Section、Artifact、FormField、Figure、Table、List、TableRow）會被走訪但不發出文字。
**界定符。**Heading 節點會將當前緩衝區作為一個區塊沖出，並以標題文字作為下一個緩衝區的起始種子。
**切分。**當累積的文字會超過 maxChunkChars 時，分塊器會填滿剩餘空間、沖出該區塊，並以最後 overlapChars 個字元加上溢位部分繼續。長度計算以 UTF-8 字元為基準。
**引用錨點。**每個 AstChunk 都承載其第一個貢獻節點的 nodeId、pageIndex、bbox 與 nodeType，加上文件來源雜湊，以及一個從 0 起算、循序遞增的 chunkIndex。
**收尾。**具有非空白內容的尾端緩衝區會作為最終區塊沖出；僅含空白的殘餘會被捨棄，且區塊文字會被修剪。

邊界案例與失敗模式

將同一個 MutationLog 記錄兩次會累積重複的項目；冪等性必須在上游強制執行。
一個全新、未共享的 InMemoryAstAuditTrail 恆為空。整合合約要求將單一共享的 AstAuditTrailInterface 實例同時交給產生變動的流程與讀取稽核的消費端，並在每次成功寫入後呼叫 record()。在此之前，findByDocument() 會回傳空清單，而 count() 會回傳 0。
記憶體內軌跡是逐行程且不具耐久性；項目不會存續於建立它的請求之外。正式環境會提供一個持久化實作。
無法通過標準解析的節點 ID 不會中止記錄；受影響的項目會回退為 pageIndex 0。
AstAwareChunker::__construct() 會以 InvalidArgumentException 拒絕退化的組態（overlapChars >= maxChunkChars，或 maxChunkChars 落在 [16, 1048576] 之外）。這可防止分塊過程中緩衝區無界成長。
當第一個貢獻節點不帶邊界框時，AstChunk::$bbox 為 null。
無可累積文字的文件會產生空的區塊清單。
本模組不進行任何密碼學運算。用於竄改證據的雜湊、簽署與蓋章由 Evidence、Security 與 Signature 模組處理；FIPS 模式原則存在於那些模組中。

一致性

行為	參考
增量更新/簽章完整性情境	ISO 32000-2:2020 §12.8

稽核軌跡是一項紀錄留存輔助。它支援稽核式的證據工作流程；它不是認證，也不是法律背書，且 NextPDF 未持有任何認證。

開發註記

為跨請求保留，請提供一個耐久的 AstAuditTrailInterface 實作。在合規要求不可變性之處，將其持久化於具 WORM 能力的儲存體中；僅可附加的保證只會與其後端儲存體同等強固。
變動快照可能承載個人資料；資料落地遵循運維人員的儲存體。
該軌跡會消耗 Pro 變動日誌的原樣輸出；它不會從文件狀態重新推導變動。
分塊器的預設值（maxChunkChars 1500、overlapChars 150）適合典型的 RAG 攝入；針對具有不同語境預算的嵌入模型，請在所記載的界限內調校。
內部機制細節保留於原始碼儲存庫的內部文件中，不在本手冊範圍內。

發佈邊界

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