Enterprise sürüm

AST denetim izi — Derinlemesine başvuru

Bir bakışta

Enterprise AST modülü, belge mutasyonlarını kaydeder ve belgeleri getirme hatlarına hazırlar.

AstAuditTrailInterface, Pro AST MutationLog üzerinde yalnızca-ekle, belge başına bir denetim izi tanımlar.
AstAuditEntry, bir mutasyonun değişmez kaydıdır: düğüm kimliği, mutasyon türü, sayfa, öncesi/sonrası anlık görüntüleri, UTC zaman damgası.
InMemoryAstAuditTrail, iz sözleşmesinin süreç başına referans uygulamasıdır.
AstAwareChunker, AST’yi derinlik öncelikli gezer ve RAG alımı için alıntı-çıpalı AstChunk değerleri üretir.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Enterprise (nextpdf/enterprise) içinde sunulur ve Enterprise katmanı bir lisans zarfıyla etkinleşir. Bu hakka sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve bir lisans alın.

AST denetim-izi yüzeyi, enterprise.compliance.evidence yeteneğiyle lisanslanır. Reddedilen bir hak, özelliği reddeder.

Katman	Sağlar
Core	AST belge modeli (`AstDocument`, `AstNode`, `NodeId`)
Pro	AST mutasyon akışı ve `MutationLog`
Enterprise	Belge başına yalnızca-ekle denetim izi; alıntı-çıpalı parçalayıcı

Enterprise yüzeyi Pro mutasyon günlüğünü tüketir. AST modelinin yerini almaz.

composer require nextpdf/enterprise:^3

Genel API yüzeyi

Simge	Parametreler	Varsayılan davranış	Döndürür	Şununla fırlatır veya başarısız olur	Notlar
`AstAuditTrailInterface::record()`	`string $documentSourceHash`, `MutationLog $log`	Günlükteki her mutasyon girişini bir `AstAuditEntry`’ye dönüştürür ve ekler	`void`	Referans uygulamada hiçbir şey	Aynı karmayla yinelenen çağrılar girişleri biriktirir
`AstAuditTrailInterface::findByDocument()`	`string $documentSourceHash`	Bir belge için kaydedilen girişleri ekleme sırasında döndürür	`list<AstAuditEntry>`	Referans uygulamada hiçbir şey	Karmayla eşleşen giriş yoksa boş liste
`AstAuditTrailInterface::count()`	yok	Denetim girişlerini sayar	`int<0, max>`	Referans uygulamada hiçbir şey	Belge başına değil, tüm belgeler genelindeki toplam
`InMemoryAstAuditTrail`	yok	Geçerli sürece kapsanmış, dizi destekli iz	`AstAuditTrailInterface`’i uygular	Hiçbir şey	Dayanıklı değil; tek istekli yaşam döngülerine uygun
`AstAuditEntry`	yapıcı tüm alanları yükseltir	Değişmez denetim kaydı	değer nesnesi	Hiçbir şey	`final readonly`; aşağıdaki imza bloğuna bakın
`AstAwareChunker::__construct()`	`int $maxChunkChars = 1500`, `int $overlapChars = 150`	Yapımda parçalama sınırlarını doğrular	örnek	Aralık dışı yapılandırmada `InvalidArgumentException`	Sınırlar: `16 <= maxChunkChars <= 1048576`; `0 <= overlapChars < maxChunkChars`
`AstAwareChunker::chunk()`	`AstDocument $document`	Derinlik öncelikli gezinme; başlıklar parçaları sınırlar; yaprak metni birikir	`list<AstChunk>`	Hiçbir şey	Biriktirilebilir metni olmayan bir belge için boş liste
`AstChunk`	yapıcı tüm alanları yükseltir	Alıntı-çıpalı parça kaydı	değer nesnesi	Hiçbir şey	`final readonly`; aşağıdaki imza bloğuna bakın

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

Davranış sözleşmesi

Denetim izi

Yalnızca-ekle. Uygulamalar yalnızca-ekle olmalıdır: kaydedilmiş bir giriş bu API üzerinden değiştirilemez veya kaldırılamaz. Aynı karmayla yinelenen record() çağrıları girişleri biriktirir.
Dönüştürme. record(), Pro MutationLog’un her girişini (MutationLog::all() aracılığıyla) bir AstAuditEntry’ye dönüştürür ve ekler. Tek bir record() çağrısının ürettiği tüm girişler tek bir UTC occurredAt zaman damgasını paylaşır.
Belge başına yalıtım. findByDocument(), tam belge kaynak karması üzerinde filtreler ve ekleme sırasını korur. count(), tüm belgeler genelindeki toplamdır.
Anlık görüntüler. before ve after, text_content ile anahtarlanan öznitelik haritalarıdır. Bir updated mutasyonu her iki tarafı da doldurur; inserted, before’ı boş bırakır; deleted, after’ı boş bırakır. mutationType, Pro MutationType numaralandırmasının dize değeridir: updated, inserted veya deleted.
Sayfa türetme. pageIndex, kanonik düğüm kimliğinden (ast:{hash}:{page}:{seq}) çıkarılır. Hatalı biçimli bir düğüm kimliği pageIndex 0 verir; giriş yine de kaydedilir.

Yalnızca-ekle, yapılandırılmış deponun bir sözleşmesidir, kriptografik bir özellik değil. Kurcalama-kanıtı ve inkâr edilemezlik, yalnızca bu modülden değil, izin nasıl kalıcılaştırıldığından ve zaman damgalandığından (Evidence modülü) gelir.

Parçalayıcı

Gezinme. chunk(), AST’yi belge kökünden derinlik öncelikli gezer.
Metin birikimi. Paragraph, ListItem, TableCell, Code veya Annotation türündeki yaprak metni geçerli arabelleğe birikir. Kapsayıcı türler (Document, Section, Artifact, FormField, Figure, Table, List, TableRow) metin üretmeden gezilir.
Sınırlayıcılar. Bir Heading düğümü, geçerli arabelleği bir parça olarak boşaltır ve sonraki arabelleği başlık metniyle tohumlar.
Bölme. Biriken metin maxChunkChars’ı aşacağı zaman, parçalayıcı kalan alanı doldurur, parçayı boşaltır ve son overlapChars karakter artı taşmayla devam eder. Uzunluk hesabı UTF-8 karakter tabanlıdır.
Alıntı çıpası. Her AstChunk, ilk katkıda bulunan düğümünün nodeId, pageIndex, bbox ve nodeType değerini, ayrıca belge kaynak karmasını ve 0 tabanlı sıralı bir chunkIndex taşır.
Sonlandırma. Boşluk olmayan içeriğe sahip bir sondaki arabellek, son parça olarak boşaltılır; yalnızca boşluktan oluşan kalıntılar atılır ve parça metni kırpılır.

Uç durumlar ve hata modları

Aynı MutationLog’u iki kez kaydetmek yinelenen girişleri biriktirir; idempotentlik yukarı akışta zorunlu kılınmalıdır.
Yeni, paylaşılmamış bir InMemoryAstAuditTrail her zaman boştur. Entegrasyon sözleşmesi, hem mutasyon üreten akışa hem de denetim okuyan tüketiciye verilen tek bir paylaşılan AstAuditTrailInterface örneğini ve her başarılı yazımdan sonra çağrılan record()’u gerektirir. O zamana kadar findByDocument() boş bir liste döndürür ve count() 0 döndürür.
Bellek içi iz süreç başınadır ve dayanıklı değildir; girişler onları oluşturan isteği aşamaz. Üretim, kalıcı bir uygulama sağlar.
Kanonik ayrıştırmada başarısız olan bir düğüm kimliği kaydetmeyi iptal etmez; etkilenen giriş pageIndex 0’a geri döner.
AstAwareChunker::__construct(), bozuk yapılandırmayı (overlapChars >= maxChunkChars veya [16, 1048576] dışındaki maxChunkChars) InvalidArgumentException ile reddeder. Bu, parçalama sırasında sınırsız arabellek büyümesini önler.
İlk katkıda bulunan düğüm bir sınırlayıcı kutu taşımadığında AstChunk::$bbox null’dur.
Biriktirilebilir metni olmayan bir belge boş bir parça listesi verir.
Bu modül hiçbir kriptografik işlem yapmaz. Kurcalama-kanıtı için karma alma, imzalama ve zaman damgalama, Evidence, Security ve Signature modülleri tarafından işlenir; FIPS-modu politikası oralarda yer alır.

Uygunluk

Davranış	Referans
Artımlı-güncelleme / imza-bütünlüğü bağlamı	ISO 32000-2:2020 §12.8

Denetim izi, bir kayıt-tutma yardımıdır. Denetim tarzı kanıt iş akışlarını destekler; bir sertifikasyon ve hukuki tasdik değildir ve NextPDF hiçbir sertifikasyona sahip değildir.

Geliştirme notları

İstekler arası saklama için dayanıklı bir AstAuditTrailInterface uygulaması sağlayın. Uyumluluk değişmezlik gerektirdiğinde onu WORM yetenekli bir depoda kalıcılaştırın; yalnızca-ekle garantisi yalnızca destekleyen depo kadar güçlüdür.
Mutasyon anlık görüntüleri kişisel veri taşıyabilir; veri yerleşimi operatörün deposunu izler.
İz, Pro mutasyon günlüğünü üretildiği gibi tüketir; mutasyonları belge durumundan yeniden türetmez.
Parçalayıcı varsayılanları (maxChunkChars 1500, overlapChars 150) tipik RAG alımına uygundur; farklı bağlam bütçelerine sahip gömme modelleri için belgelenen sınırlar içinde ayarlayın.
Dahilî mekanizma ayrıntısı, kaynak deposunun dahilî belgelerinde kalır ve bu kılavuzun kapsamı dışındadır.

Yayın sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilir davranışı ve desteklenen genel API yüzeyini belgeler. Dahilî ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, runbook dosya adları ve bilet önekleri kapsam dışıdır.