‏⁨Evidence⁩ — مرجع متعمّق

لمحة سريعة

هذه الصفحة هي المرجع المتعمّق لوحدة ‏NextPDF\Enterprise\Evidence. تختم الوحدة نتائج التحقّق في ‏EvidencePackage غير قابل للتغيير، وتُصدِّره بصيغة ⁨JSON⁩ حتمية بملخّص ⁨SHA-256⁩ مستقرّ، وتُديمه عبر عقد مخزن قابل للتوصيل، وتتتبّع التراجعات بين التشغيلات باستخدام ‏ContinuousMonitor. تستهلك الوحدة النتائج التي يُنتجها سطحا ⁨Validation⁩ و⁨Compliance⁩؛ وهي لا تُجري أي فحوص مطابقة بنفسها. للحصول على إرشادات سير العمل، اقرأ أولًا صفحة قدرة ⁨Evidence⁩.

التوفّر والترخيص

تُشحَن هذه القدرة في ‏⁨NextPDF Enterprise⁩ (‏nextpdf/enterprise) وتُفعَّل بمغلّف ترخيص من طبقة ⁨Enterprise⁩. والنشر الذي يفتقر إلى ذلك الاستحقاق لا يُحمِّل أصناف القدرة. قارن الإصدارات واحصل على ترخيص.

يُرخَّص هذا السطح بقدرة ‏enterprise.compliance.evidence؛ والاستحقاق المرفوض يرفض الميزة. يُنتج ⁨Core⁩ و⁨Pro⁩ نتائج وتقارير؛ أمّا ختم النتائج في حزمة غير قابلة للتغيير وحتمية وموسومة زمنيًا اختياريًا مع تتبّع التراجعات فلا مكافئ له في طبقة ⁨Core⁩ ولا طبقة ⁨Pro⁩.

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

composer require nextpdf/enterprise:^3

الرمز	المعاملات	السلوك الافتراضي	القيمة المُرجَعة	يرمي أو يفشل بـ	ملاحظات
EvidencePortal::__construct	EvidenceStoreInterface $store، EvidenceExporter $exporter	يربط المخزن والمُصدِّر	EvidencePortal	لا شيء معلن	كلا المتعاونَين قابل للحقن
EvidencePortal::generateEvidence	string $documentHash، list<EvidenceRecord> $records، ?string $tsaTimestamp = null	يعدّ النجاح/الفشل، ويختم حزمة بمُعرِّف ⁨UUID⁩ جديد وطابع generatedAt من ساعة الحائط، ويُديمها	EvidencePackage	لا شيء معلن	يُديم عبر store()، لا persistImmutable()
EvidencePortal::getEvidence	string $documentHash	أحدث حزمة مُخزَّنة لهذا التجزئة	?EvidencePackage	لا شيء معلن	تكون null عند عدم تخزين أي حزمة
EvidencePortal::getHistory	string $documentHash	التاريخ الكامل، الأحدث أولًا	list<EvidencePackage>	لا شيء معلن	الترتيب يوفّره المخزن
EvidencePortal::exportAsJson	EvidencePackage $package	يفوّض إلى المُصدِّر	non-empty-string	JsonException	البايتات نفسها التي يُنتجها EvidenceExporter::toJson
EvidencePackage::__construct	ثمانية معاملات مُسمّاة، انظر المقطع البرمجي	كائن قيمة غير قابل للتغيير	EvidencePackage	لا شيء معلن	الأعداد لا يُتحقَّق منها مقابل $records
EvidencePackage::allPassed	لا شيء	failedCount === 0	bool	لا شيء معلن	تكون true لحزمة فارغة؛ فبوابة القرار على totalFindings
EvidencePackage::passRate	لا شيء	passedCount / totalFindings	float	لا شيء معلن	تكون 0.0 عندما يكون totalFindings === 0
EvidenceRecord::__construct	string $policyName، bool $passed، string $details، string $validatorVersion، DateTimeImmutable $timestamp	نتيجة فحص سياسة واحدة غير قابلة للتغيير	EvidenceRecord	لا شيء معلن	كل الخصائص public readonly
EvidenceExporter::toJson	EvidencePackage $package	‏⁨JSON⁩ بترتيب مفاتيح ثابت؛ شرطات و⁨Unicode⁩ غير مهروبة	non-empty-string	JsonException	ترتيب المفاتيح جوهري (حَمّال للمعنى)
EvidenceExporter::exportHash	EvidencePackage $package	‏⁨SHA-256⁩ على بايتات toJson()	non-empty-string (⁨64 hex⁩)	JsonException	مستقرّ لكل حزمة
EvidenceStoreInterface::store	EvidencePackage $package	يُلحِق؛ ويُسمح بتاريخ لكل تجزئة مستند	void	مُعرَّف حسب التنفيذ	دلالات الإلحاق فقط مطلوبة
EvidenceStoreInterface::persistImmutable	EvidencePackage $package	كتابة ⁨WORM⁩ حيث تدعمها الخلفية	void	مُعرَّف حسب التنفيذ	الخلفيات غير الداعمة لـ ⁨WORM⁩ تتصرّف مثل store()
EvidenceStoreInterface::findByDocumentHash	string $documentHash	أحدث حزمة لهذا التجزئة	?EvidencePackage	مُعرَّف حسب التنفيذ
EvidenceStoreInterface::findAllByDocumentHash	string $documentHash	كل الحزم لهذا التجزئة، الأحدث أولًا	list<EvidencePackage>	مُعرَّف حسب التنفيذ
EvidenceStoreInterface::count	لا شيء	العدد الكلي للحزم المُخزَّنة	int<0, max>	مُعرَّف حسب التنفيذ
InMemoryEvidenceStore	صنف	مخزن مدعوم بمصفوفة للاختبارات والتطوير	لا ينطبق	لا ينطبق	غير دائم؛ بلا دلالات ⁨WORM⁩
ContinuousMonitor::__construct	EvidenceStoreInterface $store	يربط المخزن	ContinuousMonitor	لا شيء معلن
ContinuousMonitor::check	EvidencePackage $currentEvidence، string $documentHash	يقارن أسماء السياسات الفاشلة بأحدث حزمة مُخزَّنة	MonitorResult	لا شيء معلن	الفحص الأول يعامل كل فشل حالي كأنه جديد
ContinuousMonitor::isDue	string $documentHash، MonitorSchedule $schedule	مُستحَقّ عند غياب أدلّة سابقة، أو انقضاء الفترة، أو كون الأدلّة المُخزَّنة مؤرَّخة في المستقبل	bool	لا شيء معلن	آمن عند الفشل تجاه انحراف الساعة
MonitorResult::__construct	ثمانية معاملات مُسمّاة، انظر المقطع البرمجي	نتيجة فرق غير قابلة للتغيير	MonitorResult	لا شيء معلن	يتضمّن الحزمتين وcheckedAt
MonitorSchedule::__construct	MonitorFrequency $frequency، int $retentionDays = 90، bool $alertOnNewIssues = true	كائن قيمة للإعداد	MonitorSchedule	لا شيء معلن	الاحتفاظ والتنبيه يفرضهما المضيف
MonitorFrequency	تعداد مدعوم بسلسلة	الحالات Daily وWeekly وMonthly	لا ينطبق	لا ينطبق	القيم الداعمة daily وweekly وmonthly
MonitorFrequency::intervalSeconds	لا شيء	الفترة لكل حالة: ⁨86400⁩ و⁨604800⁩ و⁨2592000⁩	positive-int	لا شيء معلن	قيمة Monthly هي ⁨30⁩ يومًا ثابتة

تواقيع نقاط الدخول

final class EvidencePortal
{
    public function __construct(
        private readonly EvidenceStoreInterface $store,
        private readonly EvidenceExporter $exporter,
    )

    public function generateEvidence(string $documentHash, array $records, ?string $tsaTimestamp = null): EvidencePackage

    public function getEvidence(string $documentHash): ?EvidencePackage

    public function getHistory(string $documentHash): array

    public function exportAsJson(EvidencePackage $package): string
}

final readonly class EvidencePackage
{
    public function __construct(
        public string $packageId,
        public string $documentHash,
        public array $records,
        public int $totalFindings,
        public int $passedCount,
        public int $failedCount,
        public DateTimeImmutable $generatedAt,
        public ?string $tsaTimestamp = null,
    )

    public function allPassed(): bool

    public function passRate(): float
}

final readonly class EvidenceRecord
{
    public function __construct(
        public string $policyName,
        public bool $passed,
        public string $details,
        public string $validatorVersion,
        public DateTimeImmutable $timestamp,
    )
}

final readonly class EvidenceExporter
{
    public function toJson(EvidencePackage $package): string

    public function exportHash(EvidencePackage $package): string
}

interface EvidenceStoreInterface
{
    public function store(EvidencePackage $package): void;

    public function persistImmutable(EvidencePackage $package): void;

    public function findByDocumentHash(string $documentHash): ?EvidencePackage;

    public function findAllByDocumentHash(string $documentHash): array;

    public function count(): int;
}

final class ContinuousMonitor
{
    public function __construct(
        private readonly EvidenceStoreInterface $store,
    )

    public function check(EvidencePackage $currentEvidence, string $documentHash): MonitorResult

    public function isDue(string $documentHash, MonitorSchedule $schedule): bool
}

final readonly class MonitorSchedule
{
    public function __construct(
        public MonitorFrequency $frequency,
        public int $retentionDays = 90,
        public bool $alertOnNewIssues = true,
    )
}

enum MonitorFrequency: string
{
    case Daily = 'daily';
    case Weekly = 'weekly';
    case Monthly = 'monthly';

    public function intervalSeconds(): int
}

عقد السلوك

‏EvidencePortal::generateEvidence(string $documentHash, list<EvidenceRecord> $records, ?string $tsaTimestamp = null): EvidencePackage هو نقطة دخول الختم. القواعد القابلة للملاحظة خارجيًا:

1. التجميع. يعدّ generateEvidence السجلّات الناجحة والفاشلة ويضبط totalFindings على مجموعهما. ويُسنِد مُعرِّف packageId من نوع ⁨UUID⁩ إصدار ⁨4⁩ جديدًا، ويختم generatedAt بساعة الحائط، ويُديم الحزمة عبر EvidenceStoreInterface::store، ويُرجِعها. وتُضمَّن قائمة السجلّات بالترتيب المُعطى، دون تعديل.
2. عدم القابلية للتغيير. ‏EvidencePackage هو final readonly ولا يُغيَّر أبدًا بعد الإنشاء؛ وهو مناسب لتخزين ⁨WORM⁩. ويكون allPassed() مساويًا لـ failedCount === 0. ويكون passRate() مساويًا لـ passedCount / totalFindings، ويساوي 0.0 عندما يكون totalFindings === 0.
3. التصدير الحتمي. يُصدِر EvidenceExporter::toJson المغلّف وكل سجلّ بترتيب مفاتيح ثابت مكتوب يدويًا؛ ويتبع تسلسلُ السجلّات الحزمةَ. والترميز صارم ويرمي عند الفشل، مع ترك الشرطات و⁨Unicode⁩ غير مهروبة (JSON_UNESCAPED_SLASHES). وتُسَلسَل الطوابع الزمنية بصيغة DateTimeInterface::RFC3339_EXTENDED، وهي صيغة ⁨RFC 3339⁩ الممتدّة بأجزاء الثانية. ويُرجِع exportHash ملخّص ⁨SHA-256⁩ بالنظام الست عشري المكوّن من ⁨64⁩ حرفًا على تلك البايتات بالضبط. والحزمة نفسها تُنتج دائمًا الملخّص نفسه، على أي مضيف، وفي أي وقت. وإعادة توليد الأدلّة للمستند نفسه تُنتج packageId وgeneratedAt جديدين، ومن ثمّ ملخّصًا جديدًا: الحتمية لكل حزمة، لا لكل مستند.
4. الطابع الزمني دليل على الوقت، لا حكم. قد تحمل الحزمة رمز ⁨RFC 3161⁩ اختياريًا يوفّره المستدعِي (بترميز ⁨base64⁩). ويربط الرمز مرجع الحزمة بقيمة وقت. وتُضمِّنه الوحدة كسلسلة معتمة؛ وهي لا تجلب الرموز ولا تحلّلها ولا تتحقّق منها، ولا تكفل سلطة الطابع الزمني (⁨TSA⁩). ويعود التحقّق من الرمز إلى وحدتَي ⁨Signature⁩ و⁨Security⁩.
5. تتبّع التراجعات. يحمّل ContinuousMonitor::check أحدث حزمة مُخزَّنة لتجزئة المستند ويقارن أسماء السياسات الفاشلة الفريدة. وتُصنَّف المسائل إلى newIssues (فاشلة الآن، لا سابقًا)، وresolvedIssues (فاشلة سابقًا، لا الآن)، وunchangedIssues (فاشلة في الحالتين). ويكون hasChanges مساويًا لـ true فقط عند وجود مسائل جديدة أو مُحلّة؛ أمّا الإخفاقات غير المتغيّرة وحدها فتُبلِغ عن false. وفي الفحص الأول، يكون كل فشل حالي جديدًا.
6. الجدولة. يُرجِع ContinuousMonitor::isDue القيمة true عندما لا توجد أدلّة للتجزئة، أو عندما يبلغ الوقت المنقضي منذ generatedAt المُخزَّن فترةَ تكرار الجدول، أو عندما تكون الأدلّة المُخزَّنة مؤرَّخة في المستقبل نسبةً إلى المضيف المُستطلِع. وحالة التأريخ المستقبلي آمنة عند الفشل: في أسوأ الأحوال فحص إضافي، لا فحص فائت أبدًا.
7. عقد المخزن. يجب أن تدعم تطبيقات EvidenceStoreInterface دلالات الإلحاق فقط؛ وتشكّل الحزم المتعدّدة لكل تجزئة مستند التاريخَ، الأحدث أولًا. ويستهدف persistImmutable الخلفيات القادرة على ⁨WORM⁩؛ ويجب أن تتصرّف التطبيقات غير الداعمة لـ ⁨WORM⁩ تمامًا مثل store.

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

• الحزمة الفارغة تُبلِغ عن allPassed() بقيمة true وpassRate() بقيمة 0.0. تحقّق ببوابة totalFindings > 0 قبل معاملة الحزمة كنجاح.
• إنشاء EvidencePackage مباشرةً لا يتحقّق من الأعداد مقابل $records. استخدم البوّابة، أو حافظ على اتساق الأعداد بنفسك.
• يُديم generateEvidence قبل الإرجاع. شغّل ContinuousMonitor::check بالحزمة الجديدة قبل إدامتها؛ فالفحص بعد الإدامة يقارن الحزمة بنفسها ويُبلِغ عن عدم وجود تغييرات.
• يغطّي exportHash بايتات toJson بالضبط. وأي ملخّص يُعاد حسابه بأي مُسلسِل آخر أو ترتيب مفاتيح آخر أو سياسة هروب أخرى لن يتطابق.
• ‏MonitorFrequency::Monthly نافذة ثابتة من ⁨30⁩ يومًا، لا شهرًا تقويميًا.
• ‏MonitorSchedule::$retentionDays و$alertOnNewIssues إعداد يُحمَل لمُجدوِلات المضيف. والوحدة لا تحذف الأدلّة أبدًا ولا ترسل تنبيهات أبدًا.
• ‏InMemoryEvidenceStore مخصّص للاختبارات والتطوير. وتُفقَد الحزم عند خروج العملية، وpersistImmutable فيه بلا دلالات ⁨WORM⁩.
• تُصدَّر سلاسل details في السجلّ حرفيًا؛ والمُصدِّر لا يحجب. أبقِ الأسرار والبيانات الشخصية الخاضعة للتنظيم خارج details. والإقامة والاحتفاظ والتحكّم في الوصول تتبع تنفيذ مخزن المُشغِّل.
• تُقبَل الوسيطة tsaTimestamp كسلسلة معتمة. والرمز المُشوَّه يُضمَّن دون تغيير ولا يظهر إلا عند التحقّق اللاحق.

سلوك وضع ⁨FIPS⁩

تحسب هذه الوحدة ملخّصات ⁨SHA-256⁩ وتُضمِّن رمز ⁨RFC 3161⁩ يوفّره المستدعِي. وهي لا تؤدّي أي توقيع ولا حفظ مفاتيح. ويحكم سلوكَ وضع ⁨FIPS⁩ وحدتا ‏⁨Security⁩ و‏⁨Signature⁩.

المطابقة

الادّعاء	المعيار	البند
رمز الطابع الزمني يشير إلى أنّ بيانةً كانت موجودة في نقطة زمنية معيّنة.	IETF RFC 3161	§2
الطوابع الزمنية المُصدَّرة تستخدم صيغة الإنترنت للتاريخ/الوقت من ⁨ISO 8601⁩، بأجزاء الثانية.	IETF RFC 3339	§5.6
مادة التحقّق المُضمَّنة داخل ملف ⁨PDF⁩ تنتمي إلى مخزن أمان المستند (Document Security Store)؛ وذلك السطح مِلك وحدة ⁨Signature⁩، لا هذه الوحدة.	ISO 32000-2:2020	§12.8.4

كل البنود مُعاد صياغتها؛ ولا يستنسخ ⁨NextPDF⁩ النص المعياري. ‏⁨NextPDF⁩ لا يقدّم أي ادّعاء اعتماد. والتقاط الأدلّة يدعم سير عمل التدقيق؛ وهو ليس تأكيدًا قانونيًا ولا اعتماد تدقيق. ورمز الطابع الزمني دليل على الوقت فقط، وهذه الوحدة لا تؤكّد أنّ أي محتوى مطابق. وتبقى الصلاحية والمطابقة خصائص للملف النهائي مضافًا إليه مُتحقِّق. وهذا المرجع ليس رأيًا قانونيًا؛ استشر مستشاري الامتثال والقانون لديك.

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

• يحمل مصدر الوحدة @since 2.2.0؛ ويوثّق هذا المرجع السطح كما شُحِن في nextpdf/enterprise ⁨3.1.0⁩.
• كل شيء يعمل داخل العملية على مضيفك. والوحدة لا تُجري أي إدخال/إخراج شبكي ولا تتّصل بسلطة طابع زمني (⁨TSA⁩) بنفسها أبدًا.
• ترتيب مفاتيح المصفوفة الحرفية في المُصدِّر جوهري بحكم التصميم. وإعادة ترتيبه ستغيّر exportHash وتُبطِل الملخّصات المُخزَّنة سابقًا؛ والمصدر يمنع ذلك.
• ‏packageId هو ⁨UUID⁩ إصدار ⁨4⁩ مُجمَّع من مخرَج \random_bytes(16)؛ والمُعرِّفات فريدة لكنها غير قابلة للاستنساخ.
• الإدامة الدائمة يوفّرها المضيف. وإنفاذ ⁨WORM⁩ والتحكّم في الوصول مسؤولية المُشغِّل؛ والمخزن في الذاكرة هو التطبيق المُرفَق الوحيد.
• ‏MonitorResult كائن قيمة final readonly؛ وخصائصه الثماني public، بما فيها checkedAt، وهو وقت الفحص بساعة الحائط.

حدود النشر

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

انظر أيضًا

• ‏⁨Evidence⁩ — صفحة القدرة مع إرشادات سير العمل.
• ‏⁨Validation⁩ — مرجع متعمّق
• ‏⁨Compliance⁩ — مرجع متعمّق
• مسار تدقيق ⁨AST⁩ — مرجع متعمّق
• المواصفات: ⁨PAdES⁩