Evidence — เอกสารอ้างอิงเชิงลึก

ภาพรวมโดยย่อ

หน้านี้คือเอกสารอ้างอิงเชิงลึกสำหรับโมดูล NextPDF\Enterprise\Evidence โมดูลนี้ผนึก findings จากการตรวจสอบเข้าเป็น EvidencePackage ที่เปลี่ยนแปลงไม่ได้ ส่งออกเป็น JSON เชิงกำหนดพร้อม digest SHA-256 ที่เสถียร คงข้อมูลผ่านสัญญาที่จัดเก็บแบบเสียบต่อได้ และติดตามการถดถอยระหว่างการรันด้วย ContinuousMonitor โมดูลนี้ใช้ findings ที่สร้างขึ้นจากพื้นผิว Validation และ Compliance มันไม่ได้ทำการตรวจสอบความสอดคล้องด้วยตนเอง สำหรับคำแนะนำเวิร์กโฟลว์ ให้อ่านหน้าความสามารถ Evidenceก่อน

การมีให้ใช้และการอนุญาตสิทธิ์

ความสามารถนี้จัดส่งใน NextPDF Enterprise (nextpdf/enterprise) และเปิดใช้งานด้วย license envelope ระดับ Enterprise การนำไปใช้งานที่ไม่มีสิทธิ์ดังกล่าวจะไม่โหลดคลาสของความสามารถนี้ เปรียบเทียบรุ่นและรับใบอนุญาต

พื้นผิวนี้ได้รับอนุญาตสิทธิ์โดยความสามารถ enterprise.compliance.evidence สิทธิ์ที่ถูกปฏิเสธจะปฏิเสธฟีเจอร์ Core และ Pro สร้าง findings และรายงาน แต่การผนึก findings เข้าเป็นแพ็กเกจที่เปลี่ยนแปลงไม่ได้ เป็นเชิงกำหนด มีไทม์สแตมป์ที่เป็นทางเลือก พร้อมการติดตามการถดถอย ไม่มีรายการเทียบเท่าในระดับ Core หรือ Pro

พื้นผิว Public API

composer require nextpdf/enterprise:^3

สัญลักษณ์	พารามิเตอร์	พฤติกรรมเริ่มต้น	คืนค่า	โยนหรือล้มเหลวด้วย	หมายเหตุ
EvidencePortal::__construct	EvidenceStoreInterface $store, EvidenceExporter $exporter	เชื่อม store และ exporter	EvidencePortal	ไม่มีการประกาศ	ทั้งสองตัวร่วมงานสามารถ inject ได้
EvidencePortal::generateEvidence	string $documentHash, list<EvidenceRecord> $records, ?string $tsaTimestamp = null	นับผ่าน/ไม่ผ่าน ผนึกแพ็กเกจด้วย UUID id ใหม่และ generatedAt ตามเวลานาฬิกา แล้วคงข้อมูล	EvidencePackage	ไม่มีการประกาศ	คงข้อมูลผ่าน store() ไม่ใช่ persistImmutable()
EvidencePortal::getEvidence	string $documentHash	แพ็กเกจที่จัดเก็บล่าสุดสำหรับ hash นั้น	?EvidencePackage	ไม่มีการประกาศ	null เมื่อไม่มีการจัดเก็บ
EvidencePortal::getHistory	string $documentHash	ประวัติทั้งหมด ใหม่สุดก่อน	list<EvidencePackage>	ไม่มีการประกาศ	ลำดับกำหนดโดย store
EvidencePortal::exportAsJson	EvidencePackage $package	มอบหมายให้ exporter	non-empty-string	JsonException	ไบต์เดียวกับ EvidenceExporter::toJson
EvidencePackage::__construct	พารามิเตอร์แบบระบุชื่อแปดตัว ดูในบล็อกโค้ด	value object ที่เปลี่ยนแปลงไม่ได้	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 ที่ลำดับคีย์ตายตัว ไม่ escape เครื่องหมายทับและ Unicode	non-empty-string	JsonException	ลำดับคีย์มีความสำคัญเชิงโครงสร้าง
EvidenceExporter::exportHash	EvidencePackage $package	SHA-256 เหนือไบต์ของ toJson()	non-empty-string (hex 64 ตัว)	JsonException	เสถียรต่อแพ็กเกจ
EvidenceStoreInterface::store	EvidencePackage $package	ต่อท้าย อนุญาตให้มีประวัติต่อ hash เอกสาร	void	กำหนดโดยการนำไปใช้	ต้องมีความหมายแบบต่อท้ายเท่านั้น
EvidenceStoreInterface::persistImmutable	EvidencePackage $package	การเขียนแบบ WORM เมื่อ backend รองรับ	void	กำหนดโดยการนำไปใช้	backend ที่ไม่ใช่ WORM ทำงานเหมือน store()
EvidenceStoreInterface::findByDocumentHash	string $documentHash	แพ็กเกจล่าสุดสำหรับ hash นั้น	?EvidencePackage	กำหนดโดยการนำไปใช้
EvidenceStoreInterface::findAllByDocumentHash	string $documentHash	แพ็กเกจทั้งหมดสำหรับ hash นั้น ใหม่สุดก่อน	list<EvidencePackage>	กำหนดโดยการนำไปใช้
EvidenceStoreInterface::count	ไม่มี	จำนวนแพ็กเกจที่จัดเก็บทั้งหมด	int<0, max>	กำหนดโดยการนำไปใช้
InMemoryEvidenceStore	คลาส	store ที่ใช้ array สำหรับการทดสอบและการพัฒนา	n/a	n/a	ไม่คงทน ไม่มีความหมาย WORM
ContinuousMonitor::__construct	EvidenceStoreInterface $store	เชื่อม 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	value object สำหรับการกำหนดค่า	MonitorSchedule	ไม่มีการประกาศ	การเก็บรักษาและการแจ้งเตือนบังคับใช้โดยโฮสต์
MonitorFrequency	enum ที่มี string รองรับ	เคส Daily, Weekly, Monthly	n/a	n/a	ค่ารองรับ 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 นับ records ที่ผ่านและไม่ผ่าน แล้วตั้ง totalFindings เป็นผลรวมของทั้งสอง มันกำหนด packageId เป็น UUID เวอร์ชัน 4 ใหม่ ประทับ generatedAt ด้วยเวลานาฬิกา คงข้อมูลแพ็กเกจผ่าน EvidenceStoreInterface::store แล้วคืนค่ากลับ รายการ record ถูกฝังตามลำดับที่ให้มาโดยไม่แก้ไข
2. ความเปลี่ยนแปลงไม่ได้ EvidencePackage เป็น final readonly และไม่มีวันถูกแก้ไขหลังการสร้าง เหมาะกับการจัดเก็บแบบ WORM allPassed() คือ failedCount === 0 ส่วน passRate() คือ passedCount / totalFindings และเป็น 0.0 เมื่อ totalFindings === 0
3. การส่งออกเชิงกำหนด EvidenceExporter::toJson ปล่อย envelope และแต่ละ record ด้วยลำดับคีย์ที่ตายตัวและเขียนด้วยมือ ลำดับของ record เป็นไปตามแพ็กเกจ การเข้ารหัสเข้มงวดและโยนข้อผิดพลาดเมื่อล้มเหลว โดยปล่อยเครื่องหมายทับและ Unicode ไว้โดยไม่ escape (JSON_UNESCAPED_SLASHES) ไทม์สแตมป์ถูก serialize ด้วย DateTimeInterface::RFC3339_EXTENDED ซึ่งเป็นรูปแบบขยายของ RFC 3339 พร้อมเศษวินาที exportHash คืนค่า digest SHA-256 แบบ hex ความยาว 64 ตัวอักษรเหนือไบต์เหล่านั้นพอดี แพ็กเกจเดียวกันให้ digest เดียวกันเสมอ บนโฮสต์ใดก็ตาม ณ เวลาใดก็ตาม การสร้างหลักฐานใหม่สำหรับเอกสารเดียวกันให้ packageId และ generatedAt ใหม่ จึงได้ digest ใหม่ ความเป็นเชิงกำหนดเป็นแบบต่อแพ็กเกจ ไม่ใช่ต่อเอกสาร
4. ไทม์สแตมป์คือหลักฐานของเวลา ไม่ใช่คำตัดสิน แพ็กเกจอาจถือโทเค็น RFC 3161 ที่เป็นทางเลือกซึ่งผู้เรียกจัดหา (เข้ารหัส base64) โทเค็นนี้ผูก datum ของแพ็กเกจเข้ากับค่าเวลา โมดูลฝังมันเป็นสตริงทึบ มันไม่ดึง ไม่แจง และไม่ตรวจสอบโทเค็น และไม่รับรอง TSA การตรวจสอบโทเค็นเป็นหน้าที่ของโมดูล Signature และ Security
5. การติดตามการถดถอย ContinuousMonitor::check โหลดแพ็กเกจล่าสุดที่จัดเก็บไว้สำหรับ hash เอกสาร แล้วเปรียบเทียบชื่อนโยบายที่ไม่ผ่านแบบไม่ซ้ำ ประเด็นถูกจัดประเภทเป็น newIssues (ไม่ผ่านตอนนี้ ไม่ใช่ก่อนหน้า) resolvedIssues (ไม่ผ่านก่อนหน้า ไม่ใช่ตอนนี้) และ unchangedIssues (ไม่ผ่านทั้งสอง) hasChanges เป็น true เฉพาะเมื่อมีประเด็นใหม่หรือประเด็นที่แก้ไขแล้ว ความล้มเหลวที่ไม่เปลี่ยนแปลงเพียงอย่างเดียวรายงาน false ในการตรวจครั้งแรก ความล้มเหลวปัจจุบันทุกรายการเป็นรายการใหม่
6. การจัดตาราง ContinuousMonitor::isDue คืนค่า true เมื่อไม่มีหลักฐานสำหรับ hash นั้น เมื่อเวลาที่ผ่านไปนับจาก generatedAt ที่จัดเก็บถึงช่วงความถี่ของตาราง หรือเมื่อหลักฐานที่จัดเก็บมีวันที่ในอนาคตเทียบกับโฮสต์ที่ทำการ polling กรณีวันที่ในอนาคตเป็นแบบปลอดภัย อย่างแย่ที่สุดคือการตรวจซ้ำเพิ่มขึ้น ไม่มีวันพลาดการตรวจ
7. สัญญาของ store การนำ EvidenceStoreInterface ไปใช้ต้องรองรับความหมายแบบต่อท้ายเท่านั้น หลายแพ็กเกจต่อ hash เอกสารก่อเป็นประวัติ ใหม่สุดก่อน persistImmutable มุ่งไปที่ backend ที่รองรับ WORM ส่วนการนำไปใช้ที่ไม่ใช่ WORM ต้องทำงานเหมือน store ทุกประการ

กรณีขอบและโหมดความล้มเหลว

• แพ็กเกจที่ว่างเปล่ารายงาน allPassed() เป็น true และ passRate() เป็น 0.0 ให้ตรวจ totalFindings > 0 ก่อนถือว่าแพ็กเกจนั้นผ่าน
• การสร้าง EvidencePackage โดยตรงไม่ตรวจสอบจำนวนนับเทียบกับ $records ให้ใช้ portal หรือรักษาให้จำนวนนับสอดคล้องกันด้วยตนเอง
• generateEvidence คงข้อมูลก่อนคืนค่า ให้รัน ContinuousMonitor::check ด้วยแพ็กเกจใหม่ก่อนคงข้อมูล การตรวจหลังการคงข้อมูลจะเปรียบเทียบแพ็กเกจกับตัวเองและรายงานว่าไม่มีการเปลี่ยนแปลง
• exportHash ครอบคลุมไบต์ toJson ที่แน่นอน digest ที่คำนวณใหม่ด้วย serializer ลำดับคีย์ หรือนโยบายการ escape อื่นใดจะไม่ตรงกัน
• MonitorFrequency::Monthly คือช่วง 30 วันตายตัว ไม่ใช่เดือนตามปฏิทิน
• MonitorSchedule::$retentionDays และ $alertOnNewIssues เป็นการกำหนดค่าที่พกพาไว้สำหรับตัวจัดตารางของโฮสต์ โมดูลไม่มีวันลบหลักฐานและไม่มีวันส่งการแจ้งเตือน
• InMemoryEvidenceStore มีไว้สำหรับการทดสอบและการพัฒนา แพ็กเกจจะสูญหายเมื่อกระบวนการสิ้นสุด และ persistImmutable ของมันไม่มีความหมาย WORM
• สตริง details ของ record ถูกส่งออกตามคำต่อคำ ตัว exporter ไม่ทำการปิดบัง อย่าใส่ความลับและข้อมูลส่วนบุคคลที่อยู่ภายใต้กฎระเบียบไว้ใน details ถิ่นที่อยู่ การเก็บรักษา และการควบคุมการเข้าถึงเป็นไปตามการนำ store ไปใช้ของผู้ปฏิบัติการ
• อาร์กิวเมนต์ tsaTimestamp ถูกรับเป็นสตริงทึบ โทเค็นที่มีรูปแบบผิดจะถูกฝังโดยไม่เปลี่ยนแปลงและปรากฏเฉพาะที่การตรวจสอบปลายทาง

พฤติกรรมในโหมด FIPS

โมดูลนี้คำนวณ digest SHA-256 และฝังโทเค็น RFC 3161 ที่ผู้เรียกจัดหา มันไม่ทำการลงลายเซ็นและไม่ทำการเก็บรักษาคีย์ พฤติกรรมในโหมด FIPS ถูกกำกับโดยโมดูล Security และ Signature

ความสอดคล้อง

ข้อกล่าวอ้าง	มาตรฐาน	ข้อ
โทเค็นไทม์สแตมป์บ่งชี้ว่า datum มีอยู่ ณ จุดเวลาหนึ่ง	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 ไม่กล่าวอ้างการรับรองใด ๆ การเก็บหลักฐานสนับสนุนเวิร์กโฟลว์การตรวจสอบ มันไม่ใช่การยืนยันทางกฎหมายและไม่ใช่การรับรองการตรวจสอบ โทเค็นไทม์สแตมป์เป็นหลักฐานของเวลาเท่านั้น และโมดูลนี้ไม่ยืนยันว่าเนื้อหาใดสอดคล้องตามข้อกำหนด ความสมเหตุสมผลและความสอดคล้องยังคงเป็นคุณสมบัติของไฟล์สุดท้ายบวกกับ validator เอกสารอ้างอิงนี้ไม่ใช่ความเห็นทางกฎหมาย ปรึกษาที่ปรึกษาด้านการปฏิบัติตามข้อกำหนดและกฎหมายของคุณเอง

บันทึกการพัฒนา

• ซอร์สของโมดูลมี @since 2.2.0 เอกสารอ้างอิงนี้บันทึกพื้นผิวตามที่จัดส่งใน nextpdf/enterprise 3.1.0
• ทุกอย่างทำงานในกระบวนการบนโฮสต์ของคุณ โมดูลไม่ทำ network I/O ใด ๆ และไม่มีวันติดต่อ TSA ด้วยตนเอง
• ลำดับคีย์ของ array-literal ในตัว exporter มีความสำคัญเชิงโครงสร้างโดยการออกแบบ การจัดลำดับใหม่จะเปลี่ยน exportHash และทำให้ digest ที่จัดเก็บไว้ก่อนหน้าใช้ไม่ได้ ซอร์สห้ามทำเช่นนั้น
• packageId เป็น UUID เวอร์ชัน 4 ที่ประกอบจากผลลัพธ์ของ \random_bytes(16) ตัวระบุไม่ซ้ำแต่ทำซ้ำไม่ได้
• การคงข้อมูลแบบคงทนโฮสต์เป็นผู้จัดหา การบังคับใช้ WORM และการควบคุมการเข้าถึงเป็นความรับผิดชอบของผู้ปฏิบัติการ store แบบ in-memory เป็นการนำไปใช้เดียวที่รวมมาให้
• MonitorResult เป็น value object แบบ final readonly คุณสมบัติแปดตัวของมันเป็น public รวมถึง checkedAt ซึ่งเป็นเวลานาฬิกาของการตรวจ

ขอบเขตการเผยแพร่

หน้านี้บันทึกเฉพาะพฤติกรรมที่สังเกตได้จากภายนอกและพื้นผิว public API ที่รองรับเท่านั้น เส้นทาง namespace ภายใน คลาสตัวช่วย ตารางกลไก ชื่อไฟล์ runbook และคำนำหน้า ticket อยู่นอกขอบเขต

ดูเพิ่มเติม

• Evidence — หน้าความสามารถพร้อมคำแนะนำเวิร์กโฟลว์
• Validation — เอกสารอ้างอิงเชิงลึก
• Compliance — เอกสารอ้างอิงเชิงลึก
• AST audit trail — เอกสารอ้างอิงเชิงลึก
• ข้อกำหนด: PAdES