Enterprise phiên bản

AST audit trail — Tài liệu tham chiếu chuyên sâu

Tổng quan nhanh

Module AST Enterprise ghi lại các mutation của tài liệu và chuẩn bị tài liệu cho các retrieval pipeline.

AstAuditTrailInterface định nghĩa một audit trail chỉ-thêm (append-only), theo từng tài liệu, trên MutationLog của AST Pro.
AstAuditEntry là một bản ghi bất biến của một mutation: định danh node, loại mutation, trang, các ảnh chụp trước/sau, dấu thời gian UTC.
InMemoryAstAuditTrail là hiện thực tham chiếu theo từng process của contract trail.
AstAwareChunker duyệt AST theo chiều sâu trước và phát ra các giá trị AstChunk neo-trích-dẫn cho việc nạp RAG.

Tính khả dụng và cấp phép

Năng lực này được phát hành trong NextPDF Enterprise (nextpdf/enterprise) và được kích hoạt bằng một license envelope bậc Enterprise. Một triển khai không có entitlement đó sẽ không tải các class của năng lực này. So sánh các phiên bản và lấy giấy phép.

Bề mặt AST audit-trail được cấp phép bởi năng lực enterprise.compliance.evidence. Một entitlement bị từ chối sẽ từ chối tính năng.

Bậc	Cung cấp
Core	Mô hình tài liệu AST (`AstDocument`, `AstNode`, `NodeId`)
Pro	Luồng mutation AST và `MutationLog`
Enterprise	Audit trail chỉ-thêm theo từng tài liệu; chunker neo-trích-dẫn

Bề mặt Enterprise tiêu thụ nhật ký mutation của Pro. Nó không thay thế mô hình AST.

composer require nextpdf/enterprise:^3

Bề mặt Public API

Symbol	Tham số	Hành vi mặc định	Trả về	Ném ra hoặc thất bại với	Ghi chú
`AstAuditTrailInterface::record()`	`string $documentSourceHash`, `MutationLog $log`	Chuyển mỗi mục mutation trong log thành một `AstAuditEntry` và thêm nó vào	`void`	Không có gì trong hiện thực tham chiếu	Các lời gọi lặp lại với cùng một hash tích lũy các mục
`AstAuditTrailInterface::findByDocument()`	`string $documentSourceHash`	Trả về các mục đã ghi cho một tài liệu, theo thứ tự chèn	`list<AstAuditEntry>`	Không có gì trong hiện thực tham chiếu	Danh sách rỗng khi không có mục nào khớp với hash
`AstAuditTrailInterface::count()`	không có	Đếm các mục audit	`int<0, max>`	Không có gì trong hiện thực tham chiếu	Tổng số trên tất cả các tài liệu, không phải theo từng tài liệu
`InMemoryAstAuditTrail`	không có	Trail dựa trên mảng, giới hạn trong process hiện tại	hiện thực `AstAuditTrailInterface`	Không có gì	Không bền; phù hợp với vòng đời một-request
`AstAuditEntry`	constructor promote tất cả các trường	Bản ghi audit bất biến	value object	Không có gì	`final readonly`; xem khối signature bên dưới
`AstAwareChunker::__construct()`	`int $maxChunkChars = 1500`, `int $overlapChars = 150`	Kiểm tra các giới hạn chunking khi khởi tạo	instance	`InvalidArgumentException` khi cấu hình nằm ngoài phạm vi	Giới hạn: `16 <= maxChunkChars <= 1048576`; `0 <= overlapChars < maxChunkChars`
`AstAwareChunker::chunk()`	`AstDocument $document`	Duyệt theo chiều sâu trước; các heading phân định các chunk; văn bản lá tích lũy	`list<AstChunk>`	Không có gì	Danh sách rỗng cho một tài liệu không có văn bản tích lũy được
`AstChunk`	constructor promote tất cả các trường	Bản ghi chunk neo-trích-dẫn	value object	Không có gì	`final readonly`; xem khối signature bên dưới

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,
    ) {}
}

Hợp đồng hành vi

Nhật ký kiểm toán

Chỉ-thêm (append-only). Các hiện thực phải là chỉ-thêm: một mục đã ghi không thể bị chỉnh sửa hoặc xóa thông qua API này. Các lời gọi record() lặp lại với cùng một hash tích lũy các mục.
Chuyển đổi. record() chuyển mỗi mục của MutationLog Pro (qua MutationLog::all()) thành một AstAuditEntry và thêm nó vào. Tất cả các mục được tạo bởi một lời gọi record() chia sẻ cùng một dấu thời gian occurredAt UTC.
Cô lập theo từng tài liệu. findByDocument() lọc theo document source hash chính xác và bảo toàn thứ tự chèn. count() là tổng số trên tất cả các tài liệu.
Ảnh chụp. before và after là các map thuộc tính được đánh khóa bởi text_content. Một mutation updated điền cả hai phía; inserted để before rỗng; deleted để after rỗng. mutationType là giá trị chuỗi của enum MutationType Pro: updated, inserted, hoặc deleted.
Suy ra trang. pageIndex được trích xuất từ node ID chuẩn tắc (ast:{hash}:{page}:{seq}). Một node ID sai định dạng cho ra pageIndex 0; mục vẫn được ghi lại.

Chỉ-thêm là một contract của store được cấu hình, không phải một thuộc tính mật mã. Tính bằng chứng-chống-giả-mạo và tính không thể chối bỏ đến từ cách trail được lưu bền và được gắn dấu thời gian (module Evidence), không phải từ riêng module này.

Chunker

Duyệt. chunk() duyệt AST theo chiều sâu trước từ gốc tài liệu.
Tích lũy văn bản. Văn bản lá thuộc loại Paragraph, ListItem, TableCell, Code, hoặc Annotation tích lũy vào buffer hiện tại. Các loại container (Document, Section, Artifact, FormField, Figure, Table, List, TableRow) được duyệt qua mà không phát ra văn bản.
Dấu phân định. Một node Heading xả buffer hiện tại thành một chunk và khởi tạo buffer tiếp theo với văn bản heading.
Chia tách. Khi văn bản tích lũy vượt quá maxChunkChars, chunker điền vào không gian còn lại, xả chunk, và tiếp tục với overlapChars ký tự cuối cùng cộng với phần tràn. Việc tính độ dài dựa trên ký tự UTF-8.
Neo trích dẫn. Mỗi AstChunk mang theo nodeId, pageIndex, bbox, và nodeType của node đóng góp đầu tiên của nó, cộng với document source hash và một chunkIndex tuần tự bắt đầu từ 0.
Hoàn tất. Một buffer cuối cùng có nội dung không phải khoảng trắng được xả thành chunk cuối; các phần dư chỉ có khoảng trắng bị loại bỏ, và văn bản chunk được cắt gọn.

Trường hợp biên và các chế độ thất bại

Ghi cùng một MutationLog hai lần tích lũy các mục trùng lặp; tính lũy đẳng phải được thực thi ở upstream.
Một InMemoryAstAuditTrail mới, không được chia sẻ luôn rỗng. Contract tích hợp yêu cầu một instance AstAuditTrailInterface được chia sẻ, trao cho cả luồng tạo-mutation lẫn consumer đọc-audit, với record() được gọi sau mỗi lần ghi thành công. Cho đến lúc đó, findByDocument() trả về một danh sách rỗng và count() trả về 0.
Trail trong bộ nhớ là theo từng process và không bền; các mục không tồn tại sau request đã tạo ra chúng. Production cung cấp một hiện thực lưu bền.
Một node ID không phân tích được theo chuẩn tắc không làm hủy việc ghi; mục bị ảnh hưởng quay về pageIndex 0.
AstAwareChunker::__construct() từ chối cấu hình suy biến (overlapChars >= maxChunkChars, hoặc maxChunkChars nằm ngoài [16, 1048576]) với InvalidArgumentException. Điều này ngăn sự tăng trưởng buffer không giới hạn trong quá trình chunking.
AstChunk::$bbox là null khi node đóng góp đầu tiên không mang theo bounding box.
Một tài liệu không có văn bản tích lũy được cho ra một danh sách chunk rỗng.
Module này không thực hiện thao tác mật mã nào. Việc băm, ký và gắn dấu thời gian cho tính bằng chứng-chống-giả-mạo được xử lý bởi các module Evidence, Security và Signature; chính sách FIPS-mode nằm ở đó.

Phù hợp tiêu chuẩn

Hành vi	Tham chiếu
Ngữ cảnh cập nhật gia tăng / tính toàn vẹn chữ ký	ISO 32000-2:2020 §12.8

Audit trail là một công cụ hỗ trợ lưu hồ sơ. Nó hỗ trợ các luồng bằng chứng kiểu audit; nó không phải là một chứng nhận và không phải là một chứng thực pháp lý, và NextPDF không nắm giữ chứng nhận nào.

Ghi chú phát triển

Cung cấp một hiện thực AstAuditTrailInterface bền để lưu giữ xuyên request. Lưu nó trong một store có khả năng WORM ở nơi tuân thủ yêu cầu tính bất biến; đảm bảo chỉ-thêm chỉ mạnh bằng store nền tảng.
Các ảnh chụp mutation có thể mang theo dữ liệu cá nhân; tính cư trú dữ liệu tuân theo store của người vận hành.
Trail tiêu thụ nhật ký mutation Pro như được tạo ra; nó không tái suy ra các mutation từ trạng thái tài liệu.
Các giá trị mặc định của chunker (maxChunkChars 1500, overlapChars 150) phù hợp với việc nạp RAG điển hình; hãy tinh chỉnh trong các giới hạn đã tài liệu hóa cho các embedding model có ngân sách ngữ cảnh khác nhau.
Chi tiết cơ chế nội bộ nằm trong tài liệu nội bộ của source repository và nằm ngoài phạm vi của sổ tay này.

Ranh giới xuất bản

Trang này chỉ tài liệu hóa hành vi quan sát được từ bên ngoài và bề mặt public API được hỗ trợ. Các đường dẫn namespace nội bộ, các helper class, các bảng cơ chế, các tên tệp runbook, và các tiền tố ticket nằm ngoài phạm vi.