NextPDF Connect'te ortam tanılaması çalıştırma

Bir bakışta

Asıl iş yükünü çalıştırmadan önce bir NextPDF Connect sunucusunun sağlıklı olduğunu ve iş akışınızın gerektirdiği yeteneklere sahip olduğunu doğrulayın. Bunu her türlü aracılı (agentic) işlem hattında ilk adım olarak kullanın. Sunucu araç kaydı (registry) üzerinden doğrulanan araçlar şunlardır: diagnostic.doctor, diagnostic.capabilities ve diagnostic.verify. Kayıt bunları noktalı protokol adlarıyla sunar; ayrıca ilişkili bir diagnostic.inspect bulunur. Bunların tümü Core araçlarıdır.

Kurulum

composer require nextpdf/server

Bir taşıma katmanı bağlayın. veraPDF yalnızca isteğe bağlı uyumluluk doğrulaması adımında gereklidir. Yapısal doğrulama için harici araç gerekmez.

Kavramsal genel bakış

diagnostic.doctor temel bir sağlık raporu döndürür: PHP sürümü, yüklü uzantılar, sunucu sürümü, etkin katman ve varsa uyarılar. status alanını eşik (gate) olarak kabul edin. ok durumunda devam edin, warnings bilgisini warning durumunda okuyun ve error durumunda durun.
diagnostic.capabilities kayıtlı yetenekleri, katmanları ve çalışma zamanı durumlarıyla birlikte listeler (available, unavailable, degraded). Yeteneklerin sayısı çalışma zamanına ve katmana bağlıdır, bu nedenle toplam sayıyı sabit kodlamayın. İş akışınızın gerektirdiği her yeteneği denetleyin.
diagnostic.verify yapısal bütünlüğü denetler: PDF başlığı, EOF işaretçisi ve çapraz başvuru tablosu. Bu denetimin hedefi, sayfa ağacı üzerinden erişilen belge yapısıdır (ISO 32000-2 §7.5). compliance_flavour ile ayrıca veraPDF’i çağırır.

Bir tanılama sonucu, her taşıma katmanında normal bir yanıttır (PHP Standard Recommendation 18, PSR-18 §p2).

API yüzeyi

Araç	Rol	Risk katmanı
`diagnostic.doctor`	Ortam sağlık raporu	Güvenli
`diagnostic.capabilities`	Durum bilgisiyle yetenek envanteri	Güvenli
`diagnostic.verify`	Yapısal / uyumluluk doğrulaması	Güvenli
`create_pdf`, `add_text`, `output_pdf`	Bir belge üzerinde duman testi yapma	başka yerde belgelendiği şekilde

Bu adlar kayıttaki protokol adlarıdır. Araç kataloğu temel alınacak katalogdur. Hangi araçların ve yeteneklerin bulunduğunu kurulu katman belirler; bu nedenle asla sabit bir araç veya yetenek sayısı varsaymayın.

Kod örneği — hızlı başlangıç

diagnostic.doctor (bağımsız değişken yok) → status alanını okuyun.
diagnostic.capabilities (bağımsız değişken yok) → gerekli her yeteneğin available olduğunu doğrulayın.
create_pdf ardından add_text → asgari bir duman testi belgesi.
diagnostic.verify, document_id ile → yapısal denetimler.
İsteğe bağlı olarak diagnostic.verify, compliance_flavour: "4" ile → veraPDF.
output_pdf (base64) → duman testi oturumunu sonlandırın.

Kod örneği — üretim

İşlem hattının akışını diagnostic.doctorstatus değerine göre belirleyin. Her iş akışı bağımlılığını belirli bir yetenek kimliğiyle eşleştirin ve bağımlı adımları çalıştırmadan önce available durumunu doğrulayın. degraded durumunu, noktasal denetim gerektiren bir kalite riski olarak kabul edin. Yapısal diagnostic.verify işlemini her zaman çalıştırın. Uyumluluk çeşidini yalnızca uyumluluk önem taşıdığında çalıştırın. veraPDF mevcut değilse, sunucu hatası yerine açık bir bulunamadı sonucu döner.

Uç durumlar ve tuzaklar

veraPDF mevcut değil. Uyumluluk çağrısı açık bir bulunamadı sonucu döndürür. Yapısal denetimler yine de çalışır. Uyumluluk doğrulamasına ihtiyaç duyarsanız, veraPDF’i kurun ve sunucu sürecinin PATH ortam değişkenine ekleyin.
veraPDF zaman aşımı. Büyük belgeler, doğrulama zaman aşımını tetikleyebilir. Belge boyutunu küçültün veya sunucu yapılandırmasında zaman aşımını artırın.
degraded yetenek. Bir bağımlılık yalnızca kısmen kullanılabilir olduğundan, çıktı kalitesi düşebilir. Kullanılan yedek mekanizma için sunucu günlüklerini denetleyin.
Doctor’ın error durumu. Kritik bir gereksinim karşılanmamıştır. Devam etmeyin.

Performans

Yapısal doğrulama hızlıdır. Uyumluluk yolu veraPDF’i başlatır ve doğrulama zaman aşımıyla sınırlıdır. Geniş bütçe bu alt süreci yansıtır.

Güvenlik notları

Tanılama çıktısı ortam ayrıntılarını açığa çıkarır: PHP sürümü, uzantılar ve katman. Bunu yalnızca operatöre özel bilgi olarak değerlendirin ve güvenilmeyen çağıran taraflara göstermeyin.

Uygunluk

Beyan	Belirtim	Madde	reference_id
Tanılama sonucu normal bir taşıma yanıtıdır.	PSR-18	§p2
Yapısal bütünlük, sayfa ağacına bağlı yapıyı hedef alır.	ISO 32000-2	§7.5

Uyumluluk çeşidi veraPDF’i çalıştırır ve sonucunu raporlar. NextPDF uygunluğu kendisi beyan etmez. Kararı doğrulayıcı verir.

Ticari bağlam

Uygulanamaz — tüm tanılama araçları Core’dur.

Taşıma katmanı kullanılabilirliği

Taşıma katmanı	Kullanılabilir	Notlar
MCP (stdio)	Evet	Tanılama sonuçları araç sonuçlarıdır.
REST	Evet	Sağlık uç noktaları bu araçlarla eşleşir.
gRPC	Evet	Tekli (unary); sonuç aynı durum alanlarını taşır.

HITL risk katmanı

Üç tanılama aracının tümü Güvenli’dir: salt okunur, yan etkisiz. Onay kapısını asla tetiklemezler. Duman testindeki output_pdf base64 modundadır (İnceleme, kapı yok).

Onay kapısı JSON zarfı

Tanılamalar asla kapı uygulamaz.

{ "allowed": true }