سجل تدقيق AST — مرجع متعمّق

في لمحة

تُسجّل وحدة ⁨AST⁩ في ⁨Enterprise⁩ طفرات المستند وتُهيّئ المستندات لخطوط أنابيب الاسترجاع.

• يُعرّف AstAuditTrailInterface سجل تدقيق بنمط الإلحاق فقط لكل مستند فوق MutationLog الخاص بـ ⁨Pro⁩ AST.
• إن 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

سطح واجهة برمجة التطبيقات العامة

الرمز	المعاملات	السلوك الافتراضي	القيمة المُعادة	يرمي أو يفشل بـ	ملاحظات
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,
    ) {}
}

عقد السلوك

سجل التدقيق

• الإلحاق فقط. يجب أن تكون التنفيذات بنمط الإلحاق فقط: لا يمكن تعديل مُدخل مُسجَّل أو إزالته عبر هذه الواجهة. تتراكم المُدخلات عند تكرار استدعاءات record() بالتجزئة ذاتها.
• التحويل. يحوّل record() كل مُدخل في MutationLog الخاص بـ ⁨Pro⁩ (عبر MutationLog::all()) إلى AstAuditEntry ويُلحقه. تتشارك كل المُدخلات الناتجة عن استدعاء record() واحد طابعاً زمنياً واحداً occurredAt بتوقيت ⁨UTC⁩.
• العزل لكل مستند. يُرشّح findByDocument() على تجزئة مصدر المستند بالضبط ويحافظ على ترتيب الإدراج. أما count() فهو الإجمالي عبر كل المستندات.
• اللقطات. إن before وafter خريطتا سمات مُفهرَستان بـ text_content. تملأ الطفرة updated كلا الجانبين؛ وتترك inserted جانب before فارغاً؛ وتترك deleted جانب after فارغاً. إن mutationType هو القيمة النصية لتعداد MutationType الخاص بـ ⁨Pro⁩: updated أو inserted أو deleted.
• اشتقاق الصفحة. يُستخرج pageIndex من معرّف العقدة القانوني (ast:{hash}:{page}:{seq}). يُنتج معرّف العقدة المشوّه قيمة 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 لأول عقدة مُساهِمة فيها، إضافة إلى تجزئة مصدر المستند وchunkIndex تسلسلي يبدأ من 0.
• الإنهاء. يُفرَغ مخزن مؤقت متبقٍّ يحوي محتوى غير خالٍ من المسافات كقطعة نهائية؛ وتُهمَل البقايا المكوّنة من مسافات فقط، ويُقتطع فراغ نص القطعة.

الحالات الحدّية وأنماط الفشل

• تسجيل MutationLog ذاته مرتين يُراكم مُدخلات مكرّرة؛ ويجب فرض الحيادية (idempotency) في الأعلى.
• إن InMemoryAstAuditTrail جديداً وغير مُشترَك يكون فارغاً دوماً. يتطلب عقد التكامل نسخة AstAuditTrailInterface واحدة مُشترَكة تُمرَّر إلى كلٍّ من تدفّق إنتاج الطفرات ومستهلك قراءة التدقيق، مع استدعاء record() بعد كل كتابة ناجحة. وإلى أن يتحقق ذلك، يُعيد findByDocument() قائمة فارغة ويُعيد count() القيمة 0.
• السجل داخل الذاكرة على مستوى العملية وغير دائم؛ لا تبقى المُدخلات بعد الطلب الذي أنشأها. يوفّر الإنتاج تنفيذاً دائماً.
• لا يُجهض معرّف العقدة الذي يفشل في التحليل القانوني عملية التسجيل؛ إذ يرجع المُدخل المتأثّر إلى pageIndex تساوي 0.
• يرفض AstAwareChunker::__construct() الإعداد المتردّي (overlapChars >= maxChunkChars، أو maxChunkChars خارج [16, 1048576]) عبر InvalidArgumentException. يمنع ذلك النمو غير المحدود للمخزن المؤقت أثناء التقطيع.
• تكون AstChunk::$bbox مساوية null عندما لا تحمل أول عقدة مُساهِمة أي مربع إحاطة.
• يُنتج مستند بلا نص قابل للتراكم قائمة قطع فارغة.
• لا تُجري هذه الوحدة أي عمليات تشفيرية. تتولّى وحدات ⁨Evidence⁩ و⁨Security⁩ و⁨Signature⁩ التجزئة والتوقيع والختم الزمني لأجل مقاومة العبث؛ وتقيم سياسة وضع ⁨FIPS⁩ هناك.

المطابقة

السلوك	المرجع
سياق التحديث التزايدي / سلامة التوقيع	ISO 32000-2:2020 §12.8

سجل التدقيق أداة مساعِدة لحفظ السجلات. وهو يدعم مسارات الأدلة بأسلوب التدقيق؛ لكنه ليس شهادة ولا إقراراً قانونياً، ولا تحمل ⁨NextPDF⁩ أي شهادة.

ملاحظات التطوير

• وفّر تنفيذاً دائماً لـ AstAuditTrailInterface لأجل الاحتفاظ عبر الطلبات. احفظه في مخزن قادر على ⁨WORM⁩ حيث يقتضي الامتثال عدم القابلية للتغيير؛ فضمان الإلحاق فقط قوي بقدر قوة المخزن الداعم فقط.
• قد تحمل لقطات الطفرات بيانات شخصية؛ وتتبع إقامة البيانات مخزن المُشغّل.
• يستهلك السجل سجل طفرات ⁨Pro⁩ كما يُنتَج؛ وهو لا يُعيد اشتقاق الطفرات من حالة المستند.
• تناسب إعدادات المُقطِّع الافتراضية (maxChunkChars بقيمة 1500، وoverlapChars بقيمة 150) استيعاب ⁨RAG⁩ النموذجي؛ اضبطها ضمن الحدود المُوثّقة لنماذج التضمين ذات ميزانيات السياق المختلفة.
• تبقى تفاصيل الآليات الداخلية في التوثيق الداخلي لمستودع المصدر وهي خارج نطاق هذا الدليل.

حدود النشر

توثّق هذه الصفحة السلوك القابل للرصد خارجياً وسطح واجهة برمجة التطبيقات العامة المدعوم فقط. أما مسارات فضاء الأسماء الداخلية، والفئات المساعِدة، وجداول الآليات، وأسماء ملفات كتب التشغيل، وبادئات التذاكر فهي خارج النطاق.

اطّلع أيضاً

• سجل تدقيق AST — صفحة القدرة
• Evidence — مرجع متعمّق
• Validation — مرجع متعمّق
• Core AST