Enterprise phiên bản

Evidence — Tài liệu tham chiếu chuyên sâu

Tổng quan nhanh

Trang này là tài liệu tham chiếu chuyên sâu cho module NextPDF\Enterprise\Evidence. Module niêm phong các phát hiện kiểm định vào một EvidencePackage bất biến, xuất nó ra dưới dạng JSON xác định với một digest SHA-256 ổn định, lưu trữ bền nó qua một hợp đồng store có thể cắm thay, và theo dõi hồi quy giữa các lần chạy bằng ContinuousMonitor. Module tiêu thụ các phát hiện do các bề mặt Validation và Compliance tạo ra; bản thân nó không thực hiện kiểm tra phù hợp tiêu chuẩn nào. Để có hướng dẫn quy trình, hãy đọc trang khả năng Evidence trước.

Khả dụng & cấp phép

Khả năng này đi kèm trong NextPDF Enterprise (nextpdf/enterprise) và kích hoạt bằng một license envelope bậc Enterprise. Một triển khai không có quyền sử dụng đó sẽ không tải các lớp của khả năng. So sánh các phiên bản và lấy giấy phép.

Bề mặt được cấp phép bởi capability enterprise.compliance.evidence; một quyền sử dụng bị từ chối sẽ từ chối tính năng. Core và Pro tạo ra các phát hiện và báo cáo; việc niêm phong các phát hiện vào một gói bất biến, xác định, có timestamp tùy chọn kèm theo dõi hồi quy không có thành phần tương đương ở bậc Core hay bậc Pro.

Bề mặt Public API

composer require nextpdf/enterprise:^3

Ký hiệu	Tham số	Hành vi mặc định	Trả về	Ném ra hoặc thất bại với	Ghi chú
`EvidencePortal::__construct`	`EvidenceStoreInterface $store`, `EvidenceExporter $exporter`	Nối store và exporter	`EvidencePortal`	Không khai báo gì	Cả hai collaborator đều có thể tiêm
`EvidencePortal::generateEvidence`	`string $documentHash`, `list<EvidenceRecord> $records`, `?string $tsaTimestamp = null`	Đếm số đạt/không đạt, niêm phong một gói với id UUID mới và `generatedAt` theo đồng hồ hệ thống, lưu trữ bền nó	`EvidencePackage`	Không khai báo gì	Lưu trữ bền qua `store()`, không phải `persistImmutable()`
`EvidencePortal::getEvidence`	`string $documentHash`	Gói đã lưu mới nhất cho hash	`?EvidencePackage`	Không khai báo gì	`null` khi chưa lưu gói nào
`EvidencePortal::getHistory`	`string $documentHash`	Toàn bộ lịch sử, mới nhất trước	`list<EvidencePackage>`	Không khai báo gì	Thứ tự do store cung cấp
`EvidencePortal::exportAsJson`	`EvidencePackage $package`	Ủy thác cho exporter	`non-empty-string`	`JsonException`	Cùng byte với `EvidenceExporter::toJson`
`EvidencePackage::__construct`	tám tham số được đặt tên, xem khối mã	Value object bất biến	`EvidencePackage`	Không khai báo gì	Các số đếm không được kiểm tra đối chiếu với `$records`
`EvidencePackage::allPassed`	không có	`failedCount === 0`	`bool`	Không khai báo gì	`true` với một gói rỗng; hãy chốt cổng theo `totalFindings`
`EvidencePackage::passRate`	không có	`passedCount / totalFindings`	`float`	Không khai báo gì	`0.0` khi `totalFindings === 0`
`EvidenceRecord::__construct`	`string $policyName`, `bool $passed`, `string $details`, `string $validatorVersion`, `DateTimeImmutable $timestamp`	Kết quả kiểm tra policy đơn lẻ, bất biến	`EvidenceRecord`	Không khai báo gì	Mọi thuộc tính đều là `public readonly`
`EvidenceExporter::toJson`	`EvidencePackage $package`	JSON với thứ tự khóa cố định; slash và Unicode không được escape	`non-empty-string`	`JsonException`	Thứ tự khóa mang tính then chốt
`EvidenceExporter::exportHash`	`EvidencePackage $package`	SHA-256 trên các byte của `toJson()`	`non-empty-string` (64 hex)	`JsonException`	Ổn định theo từng gói
`EvidenceStoreInterface::store`	`EvidencePackage $package`	Ghi thêm; cho phép lịch sử theo từng hash tài liệu	`void`	Do hiện thực định nghĩa	Bắt buộc ngữ nghĩa chỉ-ghi-thêm
`EvidenceStoreInterface::persistImmutable`	`EvidencePackage $package`	Ghi WORM ở nơi backend hỗ trợ	`void`	Do hiện thực định nghĩa	Backend không phải WORM hành xử như `store()`
`EvidenceStoreInterface::findByDocumentHash`	`string $documentHash`	Gói gần đây nhất cho hash	`?EvidencePackage`	Do hiện thực định nghĩa
`EvidenceStoreInterface::findAllByDocumentHash`	`string $documentHash`	Tất cả gói cho hash, mới nhất trước	`list<EvidencePackage>`	Do hiện thực định nghĩa
`EvidenceStoreInterface::count`	không có	Tổng số gói đã lưu	`int<0, max>`	Do hiện thực định nghĩa
`InMemoryEvidenceStore`	lớp	Store nền mảng cho kiểm thử và phát triển	n/a	n/a	Không bền; không có ngữ nghĩa WORM
`ContinuousMonitor::__construct`	`EvidenceStoreInterface $store`	Nối store	`ContinuousMonitor`	Không khai báo gì
`ContinuousMonitor::check`	`EvidencePackage $currentEvidence`, `string $documentHash`	So sánh khác biệt các tên policy không đạt với gói mới nhất đã lưu	`MonitorResult`	Không khai báo gì	Lần kiểm tra đầu coi mọi thất bại hiện tại là mới
`ContinuousMonitor::isDue`	`string $documentHash`, `MonitorSchedule $schedule`	Đến hạn khi chưa có chứng cứ trước đó, khoảng thời gian đã trôi qua, hoặc chứng cứ đã lưu mang mốc thời gian tương lai	`bool`	Không khai báo gì	An toàn khi lỗi trước lệch đồng hồ
`MonitorResult::__construct`	tám tham số được đặt tên, xem khối mã	Kết quả so sánh bất biến	`MonitorResult`	Không khai báo gì	Bao gồm cả hai gói và `checkedAt`
`MonitorSchedule::__construct`	`MonitorFrequency $frequency`, `int $retentionDays = 90`, `bool $alertOnNewIssues = true`	Value object cấu hình	`MonitorSchedule`	Không khai báo gì	Lưu giữ và cảnh báo do host thực thi
`MonitorFrequency`	enum nền chuỗi	Các case `Daily`, `Weekly`, `Monthly`	n/a	n/a	Giá trị nền `daily`, `weekly`, `monthly`
`MonitorFrequency::intervalSeconds`	không có	Khoảng thời gian theo từng case: 86400, 604800, 2592000	`positive-int`	Không khai báo gì	`Monthly` cố định 30 ngày

Chữ ký điểm vào

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
}

Hợp đồng hành vi

EvidencePortal::generateEvidence(string $documentHash, list<EvidenceRecord> $records, ?string $tsaTimestamp = null): EvidencePackage là điểm vào niêm phong. Các quy tắc quan sát được từ bên ngoài:

Lắp ráp. generateEvidence đếm các bản ghi đạt và không đạt rồi đặt totalFindings bằng tổng của chúng. Nó gán một packageId UUID phiên bản 4 mới, đóng dấu generatedAt bằng đồng hồ hệ thống, lưu trữ bền gói qua EvidenceStoreInterface::store, và trả về nó. Danh sách bản ghi được nhúng theo thứ tự đã cho, không bị sửa đổi.
Tính bất biến. EvidencePackage là final readonly và không bao giờ bị biến đổi sau khi khởi tạo; nó phù hợp cho lưu trữ WORM. allPassed() là failedCount === 0. passRate() là passedCount / totalFindings, và bằng 0.0 khi totalFindings === 0.
Xuất xác định. EvidenceExporter::toJson phát ra phần envelope và từng bản ghi với thứ tự khóa cố định, viết tay; trình tự bản ghi theo sát gói. Việc mã hóa là nghiêm ngặt và ném ra khi thất bại, với slash và Unicode được để nguyên không escape (JSON_UNESCAPED_SLASHES). Timestamp được tuần tự hóa bằng DateTimeInterface::RFC3339_EXTENDED, dạng mở rộng của RFC 3339 với phần giây thập phân. exportHash trả về digest SHA-256 dạng hex dài 64 ký tự trên đúng các byte đó. Cùng một gói luôn cho ra cùng một digest, trên bất kỳ host nào, vào bất kỳ lúc nào. Việc tạo lại chứng cứ cho cùng một tài liệu cho ra một packageId và generatedAt mới, do đó một digest mới: tính xác định là theo từng gói, không phải theo từng tài liệu.
Timestamp là chứng cứ về thời gian, không phải một phán quyết. Một gói có thể mang theo một token RFC 3161 tùy chọn do bên gọi cung cấp (mã hóa base64). Token ràng buộc dữ liệu của gói với một giá trị thời gian. Module nhúng nó như một chuỗi mờ; nó không lấy, không phân tích, và không xác minh token, và nó không bảo chứng cho TSA. Việc xác minh token thuộc về các module Signature và Security.
Theo dõi hồi quy. ContinuousMonitor::check tải gói mới nhất đã lưu cho hash tài liệu và so sánh khác biệt các tên policy không đạt duy nhất. Các vấn đề được phân loại thành newIssues (không đạt bây giờ, trước đó thì không), resolvedIssues (không đạt trước đó, bây giờ thì không), và unchangedIssues (không đạt ở cả hai). hasChanges chỉ là true khi tồn tại vấn đề mới hoặc đã giải quyết; riêng các thất bại không đổi báo false. Ở lần kiểm tra đầu tiên, mọi thất bại hiện tại đều là mới.
Lập lịch. ContinuousMonitor::isDue trả về true khi không có chứng cứ nào cho hash, khi thời gian trôi qua kể từ generatedAt đã lưu đạt tới khoảng tần suất của lịch, hoặc khi chứng cứ đã lưu mang mốc thời gian tương lai so với host thăm dò. Trường hợp mốc thời gian tương lai là an-toàn-khi-lỗi: tệ nhất là một lần kiểm tra lại thừa, không bao giờ bỏ lỡ một lần.
Hợp đồng store. Các hiện thực EvidenceStoreInterface phải hỗ trợ ngữ nghĩa chỉ-ghi-thêm; nhiều gói cho mỗi hash tài liệu tạo thành lịch sử, mới nhất trước. persistImmutable nhắm tới các backend có khả năng WORM; các hiện thực không phải WORM phải hành xử đúng như store.

Trường hợp biên & chế độ lỗi

Một gói rỗng báo allPassed() true và passRate() 0.0. Hãy chốt cổng theo totalFindings > 0 trước khi coi một gói là đạt.
Việc khởi tạo EvidencePackage trực tiếp không kiểm tra các số đếm đối chiếu với $records. Hãy dùng portal, hoặc tự giữ các số đếm nhất quán.
generateEvidence lưu trữ bền trước khi trả về. Hãy chạy ContinuousMonitor::check với gói mới trước khi lưu trữ bền nó; một lần kiểm tra sau khi lưu trữ sẽ so sánh gói với chính nó và báo không có thay đổi.
exportHash bao trùm đúng các byte của toJson. Một digest được tính lại bởi bất kỳ bộ tuần tự hóa, thứ tự khóa, hoặc chính sách escape nào khác sẽ không khớp.
MonitorFrequency::Monthly là một cửa sổ cố định 30 ngày, không phải một tháng theo lịch.
MonitorSchedule::$retentionDays và $alertOnNewIssues là cấu hình được mang theo cho các bộ lập lịch của host. Module không bao giờ xóa chứng cứ và không bao giờ gửi cảnh báo.
InMemoryEvidenceStore dành cho kiểm thử và phát triển. Các gói bị mất khi tiến trình thoát, và persistImmutable của nó không có ngữ nghĩa WORM.
Các chuỗi details của bản ghi được xuất nguyên văn; exporter không biên tập che giấu. Hãy để bí mật và dữ liệu cá nhân chịu quản lý ra ngoài details. Nơi lưu trú, lưu giữ, và kiểm soát truy cập tuân theo hiện thực store của người vận hành.
Tham số tsaTimestamp được chấp nhận như một chuỗi mờ. Một token sai định dạng được nhúng nguyên vẹn và chỉ lộ ra ở khâu xác minh phía sau.

Hành vi ở chế độ FIPS

Module này tính các digest SHA-256 và nhúng một token RFC 3161 do bên gọi cung cấp. Nó không thực hiện ký và không lưu giữ khóa. Hành vi ở chế độ FIPS do các module Security và Signature quản lý.

Phù hợp tiêu chuẩn

Tuyên bố	Tiêu chuẩn	Điều khoản
Một token timestamp cho biết rằng một dữ liệu đã tồn tại tại một thời điểm cụ thể.	IETF RFC 3161	§2
Các timestamp được xuất dùng hồ sơ ngày/giờ Internet của ISO 8601, với phần giây thập phân.	IETF RFC 3339	§5.6
Vật liệu xác thực được nhúng bên trong một PDF thuộc về Document Security Store; bề mặt đó là của module Signature, không phải module này.	ISO 32000-2:2020	§12.8.4

Mọi điều khoản đều được diễn giải lại; NextPDF không tái hiện văn bản quy phạm. NextPDF không đưa ra tuyên bố chứng nhận nào. Việc thu thập chứng cứ hỗ trợ các quy trình kiểm toán; nó không phải là một chứng thực pháp lý và không phải một chứng nhận kiểm toán. Một token timestamp chỉ là chứng cứ về thời gian, và module này không khẳng định rằng bất kỳ nội dung nào là tuân thủ. Hiệu lực và sự phù hợp vẫn là thuộc tính của tệp cuối cùng cộng với một validator. Tài liệu tham chiếu này không phải là một ý kiến pháp lý; hãy tham khảo các cố vấn tuân thủ và pháp lý của riêng bạn.

Ghi chú phát triển

Mã nguồn module mang @since 2.2.0; tài liệu tham chiếu này ghi lại bề mặt như được phát hành trong nextpdf/enterprise 3.1.0.
Mọi thứ chạy trong tiến trình trên host của bạn. Module không thực hiện I/O mạng nào và không bao giờ tự liên hệ một TSA.
Thứ tự khóa trong array-literal của exporter mang tính then chốt theo thiết kế. Việc sắp xếp lại nó sẽ làm thay đổi exportHash và vô hiệu hóa các digest đã lưu trước đó; mã nguồn cấm điều đó.
packageId là một UUID phiên bản 4 được lắp ráp từ đầu ra của \random_bytes(16); các định danh là duy nhất nhưng không tái lập được.
Lưu trữ bền do host cung cấp. Việc thực thi WORM và kiểm soát truy cập là trách nhiệm của người vận hành; store trong bộ nhớ là hiện thực duy nhất đi kèm.
MonitorResult là một value object final readonly; tám thuộc tính của nó là public, bao gồm checkedAt, thời gian đồng hồ hệ thống của lần kiểm tra.

Ranh giới xuất bản

Trang này chỉ ghi lại hành vi quan sát được từ bên ngoài và bề mặt public API được hỗ trợ. Các đường dẫn namespace nội bộ, lớp trợ giúp, bảng cơ chế, tên tệp runbook, và tiền tố ticket nằm ngoài phạm vi.

Xem thêm

Evidence — trang khả năng kèm hướng dẫn quy trình.
Validation — tài liệu tham chiếu chuyên sâu
Compliance — Tài liệu tham chiếu chuyên sâu
AST audit trail — tài liệu tham chiếu chuyên sâu
Specifications: PAdES