Enterprise edycja

AST audit trail — szczegółowa referencja

W skrócie

Moduł AST w edycji Enterprise rejestruje mutacje dokumentu i przygotowuje dokumenty do potoków wyszukiwania (retrieval).

AstAuditTrailInterface definiuje ścieżkę audytu tylko-do-dopisywania, prowadzoną per dokument, nad MutationLog z AST w Pro.
AstAuditEntry to niemutowalny zapis jednej mutacji: tożsamość węzła, rodzaj mutacji, strona, migawki przed/po oraz znacznik czasu UTC.
InMemoryAstAuditTrail to referencyjna implementacja kontraktu ścieżki, działająca w obrębie procesu.
AstAwareChunker przechodzi AST w głąb i emituje wartości AstChunk z kotwicą cytowania na potrzeby zasilania RAG.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Enterprise (nextpdf/enterprise) i aktywuje się wraz z kopertą licencyjną poziomu Enterprise. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Porównaj edycje i uzyskaj licencję.

Powierzchnia ścieżki audytu AST jest licencjonowana przez możliwość enterprise.compliance.evidence. Odmówione uprawnienie odmawia dostępu do funkcji.

Poziom	Zapewnia
Core	Model dokumentu AST (`AstDocument`, `AstNode`, `NodeId`)
Pro	Przepływ mutacji AST oraz `MutationLog`
Enterprise	Ścieżka audytu per dokument tylko-do-dopisywania; dzielący na fragmenty z kotwicą cytowania

Powierzchnia Enterprise konsumuje dziennik mutacji Pro. Nie zastępuje modelu AST.

composer require nextpdf/enterprise:^3

Powierzchnia publicznego API

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się błędem	Uwagi
`AstAuditTrailInterface::record()`	`string $documentSourceHash`, `MutationLog $log`	Przekształca każdy wpis mutacji z dziennika w `AstAuditEntry` i go dopisuje	`void`	Nic w implementacji referencyjnej	Powtarzane wywołania z tym samym skrótem akumulują wpisy
`AstAuditTrailInterface::findByDocument()`	`string $documentSourceHash`	Zwraca wpisy zarejestrowane dla jednego dokumentu, w kolejności wstawiania	`list<AstAuditEntry>`	Nic w implementacji referencyjnej	Pusta lista, gdy żaden wpis nie pasuje do skrótu
`AstAuditTrailInterface::count()`	brak	Zlicza wpisy audytu	`int<0, max>`	Nic w implementacji referencyjnej	Łącznie dla wszystkich dokumentów, nie per dokument
`InMemoryAstAuditTrail`	brak	Ścieżka oparta na tablicy, ograniczona do bieżącego procesu	implementuje `AstAuditTrailInterface`	Nic	Nietrwała; odpowiednia do cykli życia pojedynczego żądania
`AstAuditEntry`	konstruktor promuje wszystkie pola	Niemutowalny zapis audytu	obiekt wartości	Nic	`final readonly`; zobacz blok sygnatury poniżej
`AstAwareChunker::__construct()`	`int $maxChunkChars = 1500`, `int $overlapChars = 150`	Weryfikuje granice dzielenia na fragmenty przy konstrukcji	instancja	`InvalidArgumentException` przy konfiguracji poza zakresem	Granice: `16 <= maxChunkChars <= 1048576`; `0 <= overlapChars < maxChunkChars`
`AstAwareChunker::chunk()`	`AstDocument $document`	Przejście w głąb; nagłówki rozgraniczają fragmenty; tekst liści akumuluje się	`list<AstChunk>`	Nic	Pusta lista dla dokumentu bez tekstu do akumulacji
`AstChunk`	konstruktor promuje wszystkie pola	Zapis fragmentu z kotwicą cytowania	obiekt wartości	Nic	`final readonly`; zobacz blok sygnatury poniżej

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

Kontrakt zachowania

Ścieżka audytu

Tylko do dopisywania. Implementacje muszą być tylko do dopisywania: zarejestrowanego wpisu nie można zmodyfikować ani usunąć przez to API. Powtarzane wywołania record() z tym samym skrótem akumulują wpisy.
Konwersja. record() przekształca każdy wpis dziennika MutationLog z Pro (przez MutationLog::all()) w AstAuditEntry i go dopisuje. Wszystkie wpisy wyprodukowane przez jedno wywołanie record() współdzielą jeden znacznik czasu UTC occurredAt.
Izolacja na poziomie dokumentu. findByDocument() filtruje po dokładnym skrócie źródła dokumentu i zachowuje kolejność wstawiania. count() to łączna liczba dla wszystkich dokumentów.
Migawki. before i after to mapy atrybutów kluczowane przez text_content. Mutacja updated wypełnia obie strony; inserted pozostawia before puste; deleted pozostawia after puste. mutationType to wartość tekstowa wyliczenia MutationType z Pro: updated, inserted lub deleted.
Wyprowadzanie strony. pageIndex jest wydobywany z kanonicznego identyfikatora węzła (ast:{hash}:{page}:{seq}). Zniekształcony identyfikator węzła daje pageIndex 0; wpis i tak jest rejestrowany.

Tylko-do-dopisywania jest kontraktem skonfigurowanego magazynu, a nie właściwością kryptograficzną. Odporność na manipulacje oraz niezaprzeczalność wynikają z tego, jak ścieżka jest utrwalana i oznaczana znacznikiem czasu (moduł Evidence), a nie z samego tego modułu.

Dzielący na fragmenty (chunker)

Przechodzenie. chunk() przechodzi AST w głąb, zaczynając od korzenia dokumentu.
Akumulacja tekstu. Tekst liści typu Paragraph, ListItem, TableCell, Code lub Annotation akumuluje się do bieżącego bufora. Typy kontenerowe (Document, Section, Artifact, FormField, Figure, Table, List, TableRow) są przechodzone bez emitowania tekstu.
Ograniczniki. Węzeł Heading opróżnia bieżący bufor jako fragment i zasiewa następny bufor tekstem nagłówka.
Dzielenie. Gdy zakumulowany tekst przekroczyłby maxChunkChars, dzielący wypełnia pozostałe miejsce, opróżnia fragment i kontynuuje od ostatnich overlapChars znaków wraz z nadmiarem. Rozliczanie długości opiera się na znakach UTF-8.
Kotwica cytowania. Każdy AstChunk niesie nodeId, pageIndex, bbox oraz nodeType swojego pierwszego współtworzącego węzła, a także skrót źródła dokumentu i sekwencyjny, liczony od 0 chunkIndex.
Finalizacja. Końcowy bufor z zawartością niebędącą białym znakiem jest opróżniany jako ostatni fragment; reszty złożone wyłącznie z białych znaków są odrzucane, a tekst fragmentu jest przycinany.

Przypadki brzegowe i tryby awarii

Dwukrotne zarejestrowanie tego samego MutationLog akumuluje zduplikowane wpisy; idempotencja musi być egzekwowana po stronie poprzedzającej.
Świeży, niewspółdzielony InMemoryAstAuditTrail jest zawsze pusty. Kontrakt integracji wymaga jednej współdzielonej instancji AstAuditTrailInterface przekazanej zarówno przepływowi produkującemu mutacje, jak i konsumentowi odczytującemu audyt, z wywołaniem record() po każdym udanym zapisie. Do tego czasu findByDocument() zwraca pustą listę, a count() zwraca 0.
Ścieżka w pamięci działa w obrębie procesu i nie jest trwała; wpisy nie przetrwają żądania, które je utworzyło. Środowisko produkcyjne dostarcza implementację trwałą.
Identyfikator węzła, którego nie da się kanonicznie sparsować, nie przerywa rejestrowania; dotknięty wpis przyjmuje domyślnie pageIndex 0.
AstAwareChunker::__construct() odrzuca zdegenerowaną konfigurację (overlapChars >= maxChunkChars lub maxChunkChars poza [16, 1048576]) z InvalidArgumentException. Zapobiega to nieograniczonemu wzrostowi bufora podczas dzielenia na fragmenty.
AstChunk::$bbox ma wartość null, gdy pierwszy współtworzący węzeł nie niesie ramki ograniczającej.
Dokument bez tekstu do akumulacji daje pustą listę fragmentów.
Ten moduł nie wykonuje żadnych operacji kryptograficznych. Haszowanie, podpisywanie oraz znakowanie czasem na potrzeby odporności na manipulacje obsługują moduły Evidence, Security oraz Signature; tam też mieści się polityka trybu FIPS.

Zgodność

Zachowanie	Odniesienie
Kontekst aktualizacji przyrostowej / integralności podpisu	ISO 32000-2:2020 §12.8

Ścieżka audytu jest pomocą w prowadzeniu rejestrów. Wspiera przepływy dowodowe w stylu audytu; nie jest certyfikacją ani atestacją prawną, a NextPDF nie posiada żadnej certyfikacji.

Uwagi dla programistów

Dostarcz trwałą implementację AstAuditTrailInterface na potrzeby retencji między żądaniami. Utrwalaj ją w magazynie zdolnym do WORM tam, gdzie zgodność wymaga niezmienności; gwarancja tylko-do-dopisywania jest tak silna, jak magazyn stanowiący podstawę.
Migawki mutacji mogą nieść dane osobowe; rezydencja danych zależy od magazynu operatora.
Ścieżka konsumuje dziennik mutacji Pro w postaci, w jakiej został wyprodukowany; nie wyprowadza ponownie mutacji ze stanu dokumentu.
Domyślne wartości dzielącego (maxChunkChars 1500, overlapChars 150) pasują do typowego zasilania RAG; dostrajaj w udokumentowanych granicach dla modeli osadzeń o odmiennych budżetach kontekstu.
Szczegóły wewnętrznego mechanizmu pozostają w wewnętrznej dokumentacji repozytorium źródłowego i są poza zakresem tego podręcznika.

Granica publikacji

Ta strona dokumentuje wyłącznie zewnętrznie obserwowalne zachowanie oraz obsługiwaną powierzchnię publicznego API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.