Evidence — szczegółowa referencja

W skrócie

Ta strona to pełna dokumentacja referencyjna modułu NextPDF\Enterprise\Evidence. Moduł pieczętuje ustalenia walidacji w niemutowalnym EvidencePackage, eksportuje je jako deterministyczny JSON ze stabilnym skrótem SHA-256, utrwala przez wtykowy kontrakt magazynu i śledzi regresje między przebiegami za pomocą ContinuousMonitor. Moduł konsumuje ustalenia wytwarzane przez powierzchnie Validation i Compliance; sam nie wykonuje żadnych kontroli zgodności. Wskazówki dotyczące przepływu pracy znajdziesz najpierw na stronie możliwości Evidence.

Dostępność i licencjonowanie

Ta możliwość jest dostarczana w NextPDF Enterprise (nextpdf/enterprise) i uaktywnia się wraz z kopertą licencyjną poziomu Enterprise. Wdrożenie bez tego uprawnienia nie ładuje klas tej możliwości. Porównaj edycje i uzyskaj licencję.

Powierzchnia jest licencjonowana przez możliwość enterprise.compliance.evidence; odmówione uprawnienie odmawia dostępu do funkcji. Core i Pro wytwarzają ustalenia oraz raporty; zapieczętowanie ustaleń w niemutowalny, deterministyczny, opcjonalnie oznaczony znacznikiem czasu pakiet ze śledzeniem regresji nie ma odpowiednika na poziomie Core ani Pro.

Powierzchnia publicznego API

composer require nextpdf/enterprise:^3

Symbol	Parametry	Domyślne zachowanie	Zwraca	Zgłasza lub kończy się błędem	Uwagi
EvidencePortal::__construct	EvidenceStoreInterface $store, EvidenceExporter $exporter	Podłącza magazyn i eksporter	EvidencePortal	Nic nie zadeklarowano	Oba współpracujące obiekty są wstrzykiwalne
EvidencePortal::generateEvidence	string $documentHash, list<EvidenceRecord> $records, ?string $tsaTimestamp = null	Zlicza wyniki pozytywne/negatywne, pieczętuje pakiet ze świeżym identyfikatorem UUID i zegarowym generatedAt, utrwala go	EvidencePackage	Nic nie zadeklarowano	Utrwala przez store(), a nie persistImmutable()
EvidencePortal::getEvidence	string $documentHash	Najnowszy zapisany pakiet dla skrótu	?EvidencePackage	Nic nie zadeklarowano	null, gdy nic nie zapisano
EvidencePortal::getHistory	string $documentHash	Pełna historia, od najnowszych	list<EvidencePackage>	Nic nie zadeklarowano	Kolejność dostarcza magazyn
EvidencePortal::exportAsJson	EvidencePackage $package	Deleguje do eksportera	non-empty-string	JsonException	Te same bajty co EvidenceExporter::toJson
EvidencePackage::__construct	osiem nazwanych parametrów, zob. blok kodu	Niemutowalny obiekt wartości	EvidencePackage	Nic nie zadeklarowano	Liczby nie są walidowane względem $records
EvidencePackage::allPassed	brak	failedCount === 0	bool	Nic nie zadeklarowano	true dla pustego pakietu; bramkuj po totalFindings
EvidencePackage::passRate	brak	passedCount / totalFindings	float	Nic nie zadeklarowano	0.0, gdy totalFindings === 0
EvidenceRecord::__construct	string $policyName, bool $passed, string $details, string $validatorVersion, DateTimeImmutable $timestamp	Niemutowalny wynik pojedynczej kontroli polityki	EvidenceRecord	Nic nie zadeklarowano	Wszystkie właściwości są public readonly
EvidenceExporter::toJson	EvidencePackage $package	JSON o ustalonej kolejności kluczy; nieucieczkowane ukośniki i Unicode	non-empty-string	JsonException	Kolejność kluczy jest nośna
EvidenceExporter::exportHash	EvidencePackage $package	SHA-256 nad bajtami toJson()	non-empty-string (64 hex)	JsonException	Stabilny dla danego pakietu
EvidenceStoreInterface::store	EvidencePackage $package	Dopisuje; dozwolona historia dla każdego skrótu dokumentu	void	Zależne od implementacji	Wymagana semantyka tylko-dopisywania
EvidenceStoreInterface::persistImmutable	EvidencePackage $package	Zapis WORM tam, gdzie backend go wspiera	void	Zależne od implementacji	Backendy bez WORM zachowują się jak store()
EvidenceStoreInterface::findByDocumentHash	string $documentHash	Najnowszy pakiet dla skrótu	?EvidencePackage	Zależne od implementacji
EvidenceStoreInterface::findAllByDocumentHash	string $documentHash	Wszystkie pakiety dla skrótu, od najnowszych	list<EvidencePackage>	Zależne od implementacji
EvidenceStoreInterface::count	brak	Łączna liczba zapisanych pakietów	int<0, max>	Zależne od implementacji
InMemoryEvidenceStore	klasa	Magazyn oparty na tablicy do testów i programowania	n/a	n/a	Nietrwały; brak semantyki WORM
ContinuousMonitor::__construct	EvidenceStoreInterface $store	Podłącza magazyn	ContinuousMonitor	Nic nie zadeklarowano
ContinuousMonitor::check	EvidencePackage $currentEvidence, string $documentHash	Porównuje nazwy polityk zakończonych niepowodzeniem z zapisanym najnowszym pakietem	MonitorResult	Nic nie zadeklarowano	Pierwsza kontrola traktuje każde bieżące niepowodzenie jako nowe
ContinuousMonitor::isDue	string $documentHash, MonitorSchedule $schedule	Wymagalne, gdy brak wcześniejszych dowodów, upłynął interwał lub zapisane dowody mają datę z przyszłości	bool	Nic nie zadeklarowano	Bezpieczne w razie rozjazdu zegara
MonitorResult::__construct	osiem nazwanych parametrów, zob. blok kodu	Niemutowalny wynik porównania	MonitorResult	Nic nie zadeklarowano	Zawiera oba pakiety oraz checkedAt
MonitorSchedule::__construct	MonitorFrequency $frequency, int $retentionDays = 90, bool $alertOnNewIssues = true	Obiekt wartości konfiguracji	MonitorSchedule	Nic nie zadeklarowano	Retencja i alerty są egzekwowane przez host
MonitorFrequency	enum oparty na łańcuchu	Przypadki Daily, Weekly, Monthly	n/a	n/a	Wartości bazowe daily, weekly, monthly
MonitorFrequency::intervalSeconds	brak	Interwał na przypadek: 86400, 604800, 2592000	positive-int	Nic nie zadeklarowano	Monthly to stałe 30 dni

Sygnatury punktów wejścia

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
}

Kontrakt zachowania

EvidencePortal::generateEvidence(string $documentHash, list<EvidenceRecord> $records, ?string $tsaTimestamp = null): EvidencePackage jest punktem wejścia pieczętowania. Reguły obserwowalne z zewnątrz:

1. Składanie. generateEvidence zlicza rekordy pozytywne i negatywne oraz ustawia totalFindings na ich sumę. Nadaje świeży packageId w postaci UUID wersji 4, stempluje generatedAt zegarem ściennym, utrwala pakiet przez EvidenceStoreInterface::store i zwraca go. Lista rekordów jest osadzona w podanej kolejności, bez modyfikacji.
2. Niemutowalność. EvidencePackage jest final readonly i nigdy nie jest modyfikowany po konstrukcji; nadaje się do przechowywania WORM. allPassed() to failedCount === 0. passRate() to passedCount / totalFindings, a 0.0, gdy totalFindings === 0.
3. Deterministyczny eksport. EvidenceExporter::toJson emituje kopertę i każdy rekord z ustaloną, ręcznie zapisaną kolejnością kluczy; sekwencja rekordów podąża za pakietem. Kodowanie jest ścisłe i zgłasza błąd przy niepowodzeniu, pozostawiając ukośniki i Unicode nieucieczkowane (JSON_UNESCAPED_SLASHES). Znaczniki czasu są serializowane z użyciem DateTimeInterface::RFC3339_EXTENDED, rozszerzonej postaci RFC 3339 z ułamkami sekund. exportHash zwraca 64-znakowy szesnastkowy skrót SHA-256 dokładnie nad tymi bajtami. Ten sam pakiet zawsze daje ten sam skrót, na dowolnym hoście, w dowolnym czasie. Ponowne wygenerowanie dowodów dla tego samego dokumentu daje nowy packageId i generatedAt, więc nowy skrót: determinizm dotyczy pakietu, a nie dokumentu.
4. Znacznik czasu jest dowodem czasu, a nie werdyktem. Pakiet może nieść opcjonalny, dostarczony przez wywołującego token RFC 3161 (zakodowany w base64). Token wiąże dane pakietu z wartością czasu. Moduł osadza go jako nieprzezroczysty łańcuch; nie pobiera, nie parsuje ani nie weryfikuje tokenów i nie poręcza za TSA. Weryfikacja tokenów należy do modułów Signature i Security.
5. Śledzenie regresji. ContinuousMonitor::check wczytuje zapisany najnowszy pakiet dla skrótu dokumentu i porównuje unikalne nazwy polityk zakończonych niepowodzeniem. Problemy są klasyfikowane jako newIssues (niepowodzenie teraz, nie wcześniej), resolvedIssues (niepowodzenie wcześniej, nie teraz) oraz unchangedIssues (niepowodzenie w obu). hasChanges jest true tylko wtedy, gdy istnieją nowe lub rozwiązane problemy; same niezmienione niepowodzenia dają false. Przy pierwszej kontroli każde bieżące niepowodzenie jest nowe.
6. Harmonogramowanie. ContinuousMonitor::isDue zwraca true, gdy dla skrótu nie ma żadnych dowodów, gdy czas, który upłynął od zapisanego generatedAt, osiąga interwał częstotliwości z harmonogramu, lub gdy zapisane dowody mają datę z przyszłości względem hosta odpytującego. Przypadek daty z przyszłości jest bezpieczny w razie awarii: w najgorszym razie dodatkowa ponowna kontrola, nigdy pominięta.
7. Kontrakt magazynu. Implementacje EvidenceStoreInterface muszą wspierać semantykę tylko-dopisywania; wiele pakietów na skrót dokumentu tworzy historię, od najnowszych. persistImmutable jest przeznaczony dla backendów obsługujących WORM; implementacje bez WORM muszą zachowywać się dokładnie jak store.

Przypadki brzegowe i tryby awarii

• Pusty pakiet raportuje allPassed() true i passRate() 0.0. Bramkuj po totalFindings > 0, zanim potraktujesz pakiet jako wynik pozytywny.
• Bezpośrednia konstrukcja EvidencePackage nie waliduje liczb względem $records. Użyj portalu lub samodzielnie utrzymuj spójność liczb.
• generateEvidence utrwala przed zwróceniem. Uruchom ContinuousMonitor::check z nowym pakietem, zanim go utrwalisz; kontrola po utrwaleniu porównuje pakiet z samym sobą i nie raportuje żadnych zmian.
• exportHash obejmuje dokładne bajty toJson. Skrót przeliczony przez dowolny inny serializator, kolejność kluczy lub politykę ucieczki nie będzie się zgadzać.
• MonitorFrequency::Monthly to stałe okno 30 dni, a nie miesiąc kalendarzowy.
• MonitorSchedule::$retentionDays i $alertOnNewIssues to konfiguracja przenoszona dla harmonogramów hosta. Moduł nigdy nie usuwa dowodów i nigdy nie wysyła alertów.
• InMemoryEvidenceStore jest przeznaczony do testów i programowania. Pakiety są tracone przy zakończeniu procesu, a jego persistImmutable nie ma semantyki WORM.
• Łańcuchy details rekordu są eksportowane dosłownie; eksporter niczego nie redaguje. Trzymaj sekrety i regulowane dane osobowe poza details. Rezydencja, retencja i kontrola dostępu zależą od implementacji magazynu operatora.
• Argument tsaTimestamp jest przyjmowany jako nieprzezroczysty łańcuch. Zniekształcony token jest osadzany bez zmian i ujawnia się dopiero przy weryfikacji na dalszym etapie.

Zachowanie w trybie FIPS

Ten moduł oblicza skróty SHA-256 i osadza dostarczony przez wywołującego token RFC 3161. Nie wykonuje żadnego podpisywania ani powiernictwa kluczy. Zachowanie w trybie FIPS jest zarządzane przez moduły Security i Signature.

Zgodność

Twierdzenie	Standard	Klauzula
Token znacznika czasu wskazuje, że dana istniała w określonym momencie.	IETF RFC 3161	§2
Eksportowane znaczniki czasu używają internetowego profilu daty/czasu ISO 8601, z ułamkami sekund.	IETF RFC 3339	§5.6
Materiał walidacyjny osadzony wewnątrz PDF należy do Document Security Store; ta powierzchnia należy do modułu Signature, a nie tego.	ISO 32000-2:2020	§12.8.4

Wszystkie klauzule są parafrazowane; NextPDF nie odtwarza tekstu normatywnego. NextPDF nie formułuje żadnego twierdzenia o certyfikacji. Rejestrowanie dowodów wspiera procesy audytu; nie jest atestacją prawną ani certyfikacją audytową. Token znacznika czasu jest wyłącznie dowodem czasu, a ten moduł nie stwierdza, że jakakolwiek treść jest zgodna. Ważność i zgodność pozostają właściwościami ostatecznego pliku w połączeniu z walidatorem. Niniejsza dokumentacja referencyjna nie stanowi opinii prawnej; skonsultuj się z własnymi doradcami ds. zgodności i prawnymi.

Uwagi programistyczne

• Źródło modułu zawiera @since 2.2.0; niniejsza dokumentacja opisuje powierzchnię w postaci dostarczonej w nextpdf/enterprise 3.1.0.
• Wszystko działa w obrębie procesu na twoim hoście. Moduł nie wykonuje żadnego wejścia/wyjścia sieciowego i sam nigdy nie kontaktuje się z TSA.
• Kolejność kluczy w literale tablicy eksportera jest z założenia nośna. Jej zmiana zmieniłaby exportHash i unieważniła wcześniej zapisane skróty; źródło tego zabrania.
• packageId to UUID wersji 4 złożony z wyjścia \random_bytes(16); identyfikatory są unikalne, ale nieodtwarzalne.
• Trwałe przechowywanie zapewnia host. Egzekwowanie WORM i kontrola dostępu są obowiązkiem operatora; magazyn w pamięci to jedyna dołączona implementacja.
• MonitorResult to obiekt wartości final readonly; jego osiem właściwości jest public, w tym checkedAt — zegarowy czas kontroli.

Granica publikacji

Ta strona dokumentuje wyłącznie zachowanie obserwowalne z zewnątrz oraz wspieraną powierzchnię publicznego API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków i prefiksy zgłoszeń pozostają poza zakresem.

Zobacz także

• Evidence — strona możliwości ze wskazówkami dotyczącymi przepływu pracy.
• Validation — pełna dokumentacja referencyjna
• Compliance — szczegółowa referencja
• AST audit trail — pełna dokumentacja referencyjna
• Specyfikacje: PAdES