Diagnostyka środowiska w NextPDF Connect

W skrócie

Przed uruchomieniem właściwej pracy potwierdź, że serwer NextPDF Connect działa poprawnie i ma możliwości wymagane przez przepływ pracy. Traktuj tę diagnostykę jako pierwszy krok w każdym potoku agentowym. Narzędzia potwierdzone w rejestrze narzędzi serwera to diagnostic.doctor, diagnostic.capabilities oraz diagnostic.verify. Rejestr udostępnia je pod nazwami protokołu z kropkami, a dostępne jest też powiązane narzędzie diagnostic.inspect. Wszystkie należą do narzędzi Core.

Instalacja

composer require nextpdf/server

Skonfiguruj transport. Narzędzie veraPDF jest potrzebne wyłącznie do opcjonalnego kroku weryfikacji zgodności. Weryfikacja strukturalna nie wymaga zewnętrznego narzędzia.

Przegląd koncepcyjny

diagnostic.doctor zwraca podstawowy raport o kondycji: wersję PHP, załadowane rozszerzenia, wersję serwera, aktywny tier oraz wszystkie ostrzeżenia. Traktuj status jako bramkę. Kontynuuj przy ok, przeczytaj warnings przy warning i zatrzymaj się przy error.
diagnostic.capabilities wymienia zarejestrowane możliwości wraz z ich poziomem (tier) oraz stanem w środowisku uruchomieniowym (available, unavailable, degraded). Liczba możliwości zależy od środowiska uruchomieniowego i poziomu (tier), więc nie wpisuj jej na sztywno. Sprawdź każdą możliwość wymaganą przez przepływ pracy.
diagnostic.verify sprawdza integralność strukturalną: nagłówek PDF, znacznik EOF oraz tablicę odwołań krzyżowych. Dotyczy to struktury dokumentu dostępnej poprzez drzewo stron (ISO 32000-2 §7.5). Wraz z compliance_flavour wywołuje także veraPDF.

Wynik diagnostyki jest zwykłą odpowiedzią w ramach każdego transportu (PHP Standard Recommendation 18, PSR-18 §p2).

Powierzchnia API

Narzędzie	Rola	Poziom ryzyka
`diagnostic.doctor`	Raport o kondycji środowiska	Bezpieczne
`diagnostic.capabilities`	Inwentarz możliwości wraz ze stanem	Bezpieczne
`diagnostic.verify`	Weryfikacja strukturalna / zgodności	Bezpieczne
`create_pdf`, `add_text`, `output_pdf`	Test dymny dokumentu	zgodnie z dokumentacją w innym miejscu

Te nazwy są nazwami protokołu pochodzącymi z rejestru. Katalogiem referencyjnym jest katalog narzędzi. Zainstalowany poziom (tier) decyduje o tym, które narzędzia i możliwości są dostępne, więc nigdy nie zakładaj stałej liczby narzędzi ani możliwości.

Przykład kodu — szybki start

diagnostic.doctor (bez argumentów) → odczytaj status.
diagnostic.capabilities (bez argumentów) → potwierdź, że każda potrzebna możliwość ma stan available.
create_pdf, a następnie add_text → minimalny dokument testowy.
diagnostic.verify z document_id → sprawdzenia strukturalne.
Opcjonalnie diagnostic.verify z compliance_flavour: "4" → veraPDF.
output_pdf (base64) → zniszcz sesję testową.

Przykład kodu — środowisko produkcyjne

Uzależnij potok od wartości diagnostic.doctorstatus. Powiąż każdą zależność przepływu pracy z konkretnym identyfikatorem możliwości i potwierdź stan available, zanim uruchomisz zależne kroki. Traktuj degraded jako zagrożenie dla jakości, które wymaga wyrywkowej kontroli. Zawsze uruchamiaj strukturalne diagnostic.verify. Wariant zgodności uruchamiaj tylko wtedy, gdy zgodność ma znaczenie. Jeśli narzędzie veraPDF jest niedostępne, zwracany jest czytelny wynik „nie znaleziono” zamiast usterki serwera.

Przypadki brzegowe i pułapki

Brak veraPDF. Wywołanie zgodności zwraca jawny wynik „nie znaleziono”. Sprawdzenia strukturalne nadal działają. Jeśli potrzebujesz weryfikacji zgodności, zainstaluj veraPDF i umieść narzędzie w zmiennej PATH procesu serwera.
Przekroczenie limitu czasu veraPDF. Duże dokumenty mogą przekroczyć limit czasu weryfikacji. Zmniejsz rozmiar dokumentu lub zwiększ limit czasu w konfiguracji serwera.
Możliwość w stanie degraded. Zależność jest dostępna tylko częściowo, więc jakość wyniku może się obniżyć. Sprawdź w dziennikach serwera, który mechanizm awaryjny jest używany.
Doctor w stanie error. Krytyczny wymóg nie jest spełniony. Nie kontynuuj.

Wydajność

Weryfikacja strukturalna jest szybka. Ścieżka zgodności uruchamia veraPDF i mieści się w limicie czasu weryfikacji. Szeroki budżet uwzględnia ten podproces.

Uwagi dotyczące bezpieczeństwa

Dane wyjściowe diagnostyki ujawniają szczegóły środowiska: wersję PHP, rozszerzenia oraz poziom (tier). Traktuj je jako informacje przeznaczone wyłącznie dla operatora i nie pokazuj ich niezaufanym wywołującym.

Zgodność

Stwierdzenie	Specyfikacja	Klauzula	reference_id
Wynik diagnostyczny jest zwykłą odpowiedzią transportu.	PSR-18	§p2
Integralność strukturalna dotyczy struktury zakotwiczonej w drzewie stron.	ISO 32000-2	§7.5

Wariant zgodności uruchamia veraPDF i przekazuje jego werdykt. NextPDF sam nie potwierdza zgodności. Decyzję podejmuje walidator.

Kontekst komercyjny

Nie dotyczy — wszystkie narzędzia diagnostyczne należą do Core.

Dostępność transportu

Transport	Dostępny	Uwagi
MCP (stdio)	Tak	Wyniki diagnostyki są wynikami narzędzi.
REST	Tak	Punkty końcowe kondycji odpowiadają tym narzędziom.
gRPC	Tak	Unarne; wynik zawiera te same pola statusu.

Poziom ryzyka HITL

Wszystkie trzy narzędzia diagnostyczne są bezpieczne: tylko do odczytu, bez efektów ubocznych. Nigdy nie uruchamiają bramki potwierdzenia. Testowe output_pdf działa w trybie base64 (Review, bez bramki).

Koperta JSON bramki potwierdzenia

Diagnostyka nigdy nie wymaga bramki.

{ "allowed": true }