pasteToPrint — technická dokumentácia jazykového asistenta

01 · Výsledok

Čo bolo implementované

Asistent je univerzálna dokumentová vrstva, nie fakturačné jadro. Rozumie požiadavke, vyberie vhodný typ dokumentu, použije iba údaje, ktoré zadal používateľ, a chýbajúce polia ponechá ako vyplniteľné zástupné miesta v striktne validovanom PTDF. Po jednorazovom povolení môže bežné dokumentové zmeny aplikovať priamo do editora.

zámerov asistenta vrátane bezpečného generovania obrázka alebo omaľovánky

povolených PTDF operácií v aplikačnom kontrakte

API kľúčov odoslaných do JavaScriptu alebo vložených do HTML

20/20

lokálnych akceptačných scenárov v poslednom zázname testovania

Povinná bezpečnostná akcia

API kľúč, ktorý bol niekedy vložený do chatu, ticketu, zdrojového súboru alebo klienta, treba zrušiť a nahradiť novým. Dokumentácia kľúč neobsahuje. Nový kľúč sa ukladá iba cez chránenú administráciu a backend ho šifruje v MySQL.

Aktuálny lokálny stav

Lokálny status endpoint pri vytvorení tejto dokumentácie hlásil model gpt-5.5 ako nakonfigurovaný a dostupný. Prípravný preflight prešiel s jediným upozornením: pred produkčným štartom treba nastaviť verejný HTTPS pôvod.

Preflight: ready with warnings produkčné HTTPS čaká

Autoritatívny zdroj stavu

Hodnoty v hornom paneli sa pri otvorení cez lokálny server načítajú z status.php a manifest.php. Otvorenie dokumentácie ako lokálneho súboru používa statický fallback a nevykoná žiadnu požiadavku na model.

02 · Rozsah

Návrhové princípy

Rozhodnutia, ktoré držia asistenta všeobecného, bezpečného a rozšíriteľného aj pri raste počtu jazykov a dokumentových modulov.

01Univerzálnosť. Faktúra je iba jeden modul registra. Jadro pracuje so zámermi, blokmi, operáciami a schémami bez účtovnej doménovej závislosti.
02Šablóna je deterministická opora. Model vyberá typ a dodáva obsah; vizuálne pravidlá, povinné polia a PTDF blueprinty spravuje aplikácia.
03Človek povoľuje priame úpravy. Prvý zápis vyžaduje verziovaný súhlas. Ďalšie validované zmeny sú automatické, vratné a povolenie možno kedykoľvek odvolať.
04Server je hranica dôvery. Kľúč, rate limit, prístupová politika, skenovanie tajomstiev aj validácia odpovede sú serverové.

05Kontrakty pred voľným textom. Responses API vracia strict Structured Output, ktorý prejde provider schémou, registrom šablón, PTDF validátorom a odpoveďovým kontraktom.
06Jazyk konverzácie ≠ jazyk dokumentu. Obe lokality sú samostatné polia, čo podporuje napríklad slovenské pokyny pre nemecký dokument.
07Minimum trvalých dát. História, návrhy a diagnostika sú v pamäti stránky; server ukladá iba neobsahové agregáty a prevádzkový stav.
08Bezpečný default. Neznámy dokument padá na blank, neúplné údaje zostanú vo vyplniteľných poliach bez vypytovania a nedostupný runtime nevytvorí modelovú požiadavku.

03 · Implementačný záznam

Etapy 1 až 13

Každá etapa je samostatne dohľadateľná podľa cieľa, funkcie, súboru alebo akceptačného kritéria.

Hľadať iba v etapách

Oblasť

01Výsuvná vrstva asistentaElegantný vstupný bod v strede spodnej hrany editora＋

Cieľ: pridať asistenta bez narušenia pracovnej plochy.

Plávajúci launcher, dialógová vrstva, mobilný režim a klávesnicové ovládanie.
Stavy zavreté / otvorené / spracovanie / chyba a lokalizované texty.
Vstup ostáva súčasťou existujúceho editora a neotvára samostatnú aplikáciu.

Akceptácia: otvorenie, fokus, Escape a návrat fokusu fungujú; rozloženie je responzívne.

index.html assets/css/ai-assistant.css assets/js/ai-assistant.js

02Univerzálny dokumentový kontraktVerzionované schémy namiesto fakturačného jadra＋

Cieľ: definovať stabilnú hranicu medzi UI, modelom a dokumentovými režimami.

8 akcií: create_document, update_document, format_content, change_template, analyze_document, request_missing_data, answer_question a generate_image.
Kontrakt ptp.assistant/2 prenáša contentMode, zdôvodnenie voľby a diskriminovaný PTDF alebo HTML artifact.
ptp.html-pipeline/1 zjednocuje všeobecný HTML/CSS import, preview, finálne vloženie a konštrukciu dôveryhodného HTML artifactu; výstup obsahuje report odstránených elementov, atribútov a CSS deklarácií.
Etapa 3 prijíma HTML zo siete iba ako nedôveryhodný kandidát, lokálne ho kanonizuje a zobrazí v izolovanom iframe. Použitie vyžaduje samostatné potvrdenie nahradenia a zmeny formátu; PTDF direct-edit súhlas sa na HTML nevzťahuje.
Etapa 4 zapája produkčný provider: server podľa explicitnej voľby, aktuálneho režimu a vizuálnej zložitosti autoritatívne volí PTDF alebo statické HTML/CSS.
Etapa 5 povoľuje iba jednorazový JavaScript generátor pre výpočty, podmienky a programové opakovanie. Beží mimo aplikačného originu v zničiteľnom Web Workeri; do dokumentu vstupuje len sanitizované statické HTML/CSS. Aktívny JavaScript po importe ostáva zakázaný.
Starší ptp.assistant/1 zostáva podporovaný pre PTDF a chybové odpovede.

Akceptácia: platné príklady oboch vetiev prejdú; reálny browser test odstráni spustiteľné HTML a nepovolené CSS, zachová povolený štýl a finálne vloženie emituje strojovo čitateľný sanitizačný report.

contract.php schema/v2/schema.json html-document-pipeline.js Stage 5 generator assistant-generator-runtime.js assistant-contract.js

02.6Real-time orchestrácia dokumentových režimovPravdivý priebeh, viditeľná voľba PTDF/HTML a bezpečné zrušenie＋

Cieľ: sprístupniť reálne fázy jednej požiadavky bez streamovania čiastočných dokumentov.

Nový klient explicitne vyžiada striktne verzovaný ptp.assistant.stream/1 NDJSON prúd; starý JSON transport zostáva nezmenený.
Server oznamuje validáciu požiadavky, autoritatívnu voľbu režimu, generovanie a prijatie úplného kandidáta. Klient dopĺňa skutočné lokálne fázy generátora, sanitizácie, validácie a prípravy preview.
Stop preruší fetch a zničí lokálny generátor pred hranicou návrhu/aplikácie. Neskorý výsledok sa ignoruje; už prijatú upstream požiadavku však klient nevie garantovane zrušiť.
Prúd je iba informačný: nepovoľuje formát, JavaScript ani zmenu dokumentu a nikdy neprenáša čiastočný artifact.

Akceptácia: striktne sa odmietne neznáma alebo neusporiadaná udalosť, JSON fallback ostáva funkčný a reálny browser test potvrdí zrušenie bez aplikácie a sanitizované HTML bez spustenia skriptu.

Stage 6 kontrakt stream schema stream parser message endpoint

02.7Bezpečné priame úpravy HTMLSamostatný súhlas, úzka eligibility a strážené Undo＋

Cieľ: umožniť automatickú aplikáciu bezpečnej úpravy existujúceho HTML bez prenesenia PTDF súhlasu.

HTML má vlastný verzovaný consent scope a oddelený úložný kľúč bez správ alebo obsahu dokumentu.
Automaticky sa použije iba čistý HTML→HTML návrh s dôvodom preserve_current_html, platným fingerprintom, nulovým sanitizačným zásahom a bez generátora.
Nový HTML dokument, zmena formátu, neaktuálny návrh, opravené HTML a JavaScript-generator výstup zostávajú v manuálnom izolovanom review.
Finálne vloženie znovu prejde ptp.html-pipeline/1, vytvorí jeden históriový krok a sprístupní strážené Undo.

Akceptácia: PTDF súhlas neautorizuje HTML, zmena editora zneplatní návrh a browser test potvrdí čistú auto-aplikáciu, návrat presného snapshotu aj review fallback pri odstránenom event handleri.

Stage 7 kontrakt scoped consent assistant controller atomic HTML boundary

02.8Vyjednávanie reálnych schopností prehliadačaRuntime probe, serverový prienik a bezpečný statický fallback＋

Cieľ: povoliť HTML a jednorazový JavaScript generátor iba v prehliadači, ktorý reálne zvládol ich bezpečnostné hranice.

Klient pred prvou správou vykoná neobsahový test ptp.html-pipeline/1, scriptless review iframe a skutočný disposable iframe/Worker generátor.
Na server posiela presne päť polí kontraktu ptp.assistant.client-capabilities/1; žiadny user-agent, hardvér, device ID, obsah dokumentu ani detail chyby.
Server hodnoty iba pretne s vlastnou politikou. Neúspešný JS probe prepne na kompletné statické HTML; nedostupný bezpečný HTML review HTML požiadavku zablokuje; PTDF ostáva dostupné.
activeJavascriptDocument musí byť vždy false. Capability nikdy nepovolí skript v uloženom dokumente ani v aplikačnom origine.

Akceptácia: striktný parser odmietne neznáme a nekonzistentné polia, chýbajúce capability sú fail-closed a reálny Chromium test potvrdí úspešný izolovaný probe, odstránenie jeho iframe aj odoslanie presného kontraktu.

Stage 8 kontrakt client detection server parser capability schema

02.9Ohraničená obnova po zlyhaní generátoraJeden viditeľný retry so statickým HTML a nulovým čiastočným stavom＋

Cieľ: bezpečne dokončiť požiadavku, keď prehliadač prešiel runtime probe, ale konkrétny jednorazový skript zlyhá alebo timeoutne.

Recovery je povolené iba pre platný generator kandidát a explicitné runtime/input/execution chyby; nie pre sieť, sanitizér, kontrakt alebo zrušenie používateľom.
Klient zahodí prvý výstup, zobrazí stav fallbacku a zopakuje nezmenenú správu a snapshot s novým request ID najviac raz.
Druhý capability objekt ponechá overený HTML pipeline/review, ale nastaví javascriptGenerator: false; ďalší generátor je policy mismatch a nespustí sa.
Druhý request opakuje access, rate limit, runtime admission, secret scan, routing aj provider/output validáciu a výsledok zostáva v manuálnom HTML review.

Akceptácia: reálny Chromium test vyvolá chybu Workera, zachytí presne dva requesty, overí downgrade capability, viditeľný priebeh, žiadny čiastočný dokument a označený statický návrh.

Stage 9 kontrakt recovery policy bounded orchestration browser test

02.10Reálny systémový action contractAutoritatívny register, command binding a nulové vymyslené schopnosti＋

Cieľ: vytvoriť pravdivý základ pre budúce ovládanie pasteToPrint asistentom.

ptp.assistant.actions/1 prenáša iba aktuálnu dostupnosť 20 registrovaných systémových workflow; klientsky snapshot nikdy nie je oprávnenie.
Každá akcia je mapovaná na reálny pasteToPrint.editor-commands/1 príkaz, má uzavretú vstupnú schému, účinok, bezpečnostnú úroveň, pravidlo potvrdenia a undo vlastnosť.
Formát a orientácia papiera majú nové verejné aplikačné príkazy. Tlač, exporty, e-mail PDF, podpis, cloud a mobilný prenos sa objavia iba vtedy, keď ich reálny command adapter registruje a povolí.
executionEnabled je v celej etape presne false; model smie schopnosť pravdivo opísať, ale nesmie tvrdiť, že niečo vykonal, odoslal alebo exportoval.

Akceptácia: PHP a JS odmietnu vymyslené ID, neznáme polia a zapnutie executora; Chromium potvrdí reálny binding orientácie a odoslanie snapshotu bez zmeny dokumentu či exportu.

Stage 10 kontrakt action discovery serverový parser autoritatívny register

02.11Lokálny transakčný executorPäť reálnych nízkorizikových príkazov s live recheckom a postcondition＋

Cieľ: umožniť asistentovi bezpečne dokončiť prvé lokálne požiadavky v reálnom rozhraní pasteToPrint.

ptp.assistant/3 a ptp.assistant.provider/4 prenášajú najviac jeden serverom validovaný plán ptp.assistant.action-plan/1.
Allowlist obsahuje iba formát a orientáciu papiera, Undo, Redo a prepnutie témy; všetky majú účinok mutate, nízke riziko a nepotrebujú potvrdenie.
Prehliadač pred dispatchom znovu overí živú dostupnosť a canExecute, vykoná existujúci command binding, počká na front a skontroluje výsledný command state.
Request ID chráni pred replay a lokálne mutácie sa serializujú. Úspešná veta sa zobrazí až po overenom výsledku.
Tlač, export, download, e-mail, podpis, import, cloud a prenos zostávajú vykonávaním vypnuté a patria do ďalších etáp.

Akceptácia: serverové a klientské testy blokujú nepovolené ID, zlé vstupy, replay, zmenu politiky a neúspešnú postcondition; Chromium reálne zmení orientáciu aj tému, nespustí download a nezobrazí úspech stale plánu.

Stage 11 kontrakt lokálny executor serverový plánovač Chromium test

02.12Potvrdené lokálne výstupyTlač a šesť reálnych exportov s výsledkovým handshake＋

Cieľ: umožniť asistentovi dokončiť reálnu tlač a lokálne exporty bez falošných tvrdení.

Allowlist pridáva iba file.print, PDF, TXT, HTML, JSON a PTDF; každý výstup má politiku export / guarded / review.
Klient vyžaduje nové viditeľné potvrdenie pri každom výstupe. Odmietnutie nič nedispatchne a úspešná modelová veta sa zahodí.
Existujúci command dispatcher volá reálne output workflow. Executor čaká na zhodné action ID a request ID v pasteToPrint.output-result/1.
Download je úspešný až po reálnom kliknutí odkazu. Pri tlači možno potvrdiť iba otvorenie dialógu, nikdy dokončenú tlač.
E-mail PDF, cloud, podpis, import, prenos a ľubovoľné UI kliknutia zostávajú blokované.

Akceptácia: unit testy blokujú chýbajúci súhlas, odmietnutie, timeout, replay aj externé ID; Chromium po súhlase reálne stiahne TXT a po odmietnutí nevytvorí druhý download ani falošný úspech.

Stage 12 kontrakt output executor serverový allowlist Chromium test

02.13Explicitné odoslanie PDF e-mailomJedna reálna externá akcia s adresou, súhlasom a potvrdením accepted＋

Cieľ: dovoliť asistentovi bezpečne odoslať aktuálny dokument ako PDF bez tvrdenia o nedokázanom doručení.

Externý allowlist obsahuje iba file.email-pdf s politikou external / high / explicit a povinným validným vstupom email.
Server overí, že adresa je priamo v aktuálnej správe používateľa. Pred dispatchom sa zobrazí v čerstvom explicitnom potvrdení spolu s hranicou výsledku.
Existujúci PDF generátor odošle multipart na reálny email endpoint. Executor čaká na zhodné action ID a request ID v pasteToPrint.external-result/1.
Úspech znamená iba deliveryStatus: accepted; nie doručenie, otvorenie ani prečítanie.
Cloud, mobilný prenos, podpis, import a navigácia zostávajú nevykonateľné.

Akceptácia: unit testy blokujú zlú, chýbajúcu aj v aktuálnej správe neprítomnú adresu, nesprávnu politiku, cloud, transfer, odmietnutie a timeout; Chromium v lokálne zachytenom endpointe overí PDF multipart a potlačí úspech po odmietnutí aj chybe.

Stage 13 kontrakt externý executor PDF email workflow Chromium test

02.14Dočasný mobilný prenosReálny HTML/TXT odkaz a QR kód s pravdivým stavom ready＋

Cieľ: umožniť asistentovi vytvoriť reálny mobilný prenos bez tvrdenia, že ho zariadenie prevzalo.

Allowlist pridáva iba transfer.send-mobile s politikou external / high / explicit a povinným formátom html alebo txt.
Server overí, že formát je priamo v aktuálnej správe. Potvrdenie zobrazí formát aj informáciu o dočasnom externom odkaze.
Existujúci send-mobile workflow odošle sanitizovaný HTML alebo čistý text na reálny create endpoint a zobrazí modal, prijímací odkaz a lokálny QR kód.
Úspech vyžaduje platný token, status: ready a zhodný pasteToPrint.external-result/1; znamená iba pripravený odkaz a QR.
Cloud, prijímanie z mobilu, podpis, import a navigácia zostávajú nevykonateľné.

Akceptácia: testy blokujú chýbajúci alebo zlý formát, formát mimo aktuálnej správy, cloud, receive-mobile, odmietnutie, chybu aj timeout; Chromium vytvorí jeden lokálne zachytený HTML prenos a overí modal, odkaz a QR kód bez skutočného serverového súboru.

Stage 14 kontrakt send-mobile workflow externý executor Chromium test

02.15Prijímacia relácia z mobiluUpload odkaz a QR kód s pravdivým stavom pending＋

Cieľ: pripraviť reálnu reláciu na prijatie súboru bez tvrdenia, že súbor už prišiel.

Allowlist pridáva transfer.receive-mobile s politikou external / high / explicit a bez vstupných parametrov.
Potvrdenie vysvetlí vytvorenie dočasnej externej upload relácie, odkazu a QR kódu aj to, že súbor ešte nie je prijatý.
Existujúci transfer workflow zavolá reálny create endpoint, overí pending stav a token, zobrazí modal a spustí polling status endpointu.
Asistentov úspech vyžaduje zhodný pasteToPrint.external-result/1 so stavom pending; nesmie tvrdiť upload ani prijatie súboru.
Cloud, podpis, import a navigácia zostávajú nevykonateľné.

Akceptácia: testy blokujú vstupné polia, inú politiku, cloud, podpis, odmietnutie, chybu aj timeout; Chromium vytvorí jednu lokálne zachytenú pending reláciu, overí modal, odkaz, QR a polling bez skutočného tokenu alebo súboru.

Stage 15 kontrakt receive-mobile workflow externý executor Chromium test

02.16Lokálne importné pickeryOffice/PDF, fotografia a PTDF bez prístupu AI k lokálnym súborom＋

Cieľ: umožniť asistentovi vyžiadať reálny systémový výber súboru bez tvrdenia, že import už prebehol.

Allowlist pridáva file.import-office, file.import-photo a file.import-ptdf s politikou navigate / guarded / explicit a bez vstupných parametrov.
Čerstvé potvrdenie pomenuje druh súboru a vysvetlí, že výber, načítanie aj import zostávajú pod kontrolou používateľa.
Core vyvolá presný existujúci file input a vyšle zhodný pasteToPrint.import-result/1 iba so stavom picker_requested.
Úspech nesmie znamenať vybraný, načítaný, validovaný, vložený alebo aplikovaný súbor.
Podpis, cloud a všeobecná navigácia zostávajú nevykonateľné.

Akceptácia: serverové a klientské testy blokujú lokálnu cestu, inú politiku, odmietnutie, chybu aj timeout; Chromium zachytí reálne filechooser udalosti na troch správnych inputoch bez výberu skutočného súboru.

Stage 16 kontrakt picker bridge import executor Chromium test

03Register šablón a typov dokumentov14 univerzálnych typov, povinné polia a PTDF blueprinty＋

Cieľ: oddeliť obsahový zámer od vizuálnej šablóny.

Typy od prázdneho dokumentu a poznámky po faktúru, ponuku, list, reklamáciu, zápisnicu a servisný záznam.
Každý typ deklaruje zámery, kategóriu, povinné/voliteľné polia, prekladové kľúče a blueprint.
Neznámy alebo neurčitý zámer bezpečne používa blank.

Akceptácia: PHP aj browser registry vracajú rovnakých 14 typov a všetky prejdú schémou.

templates/registry.php registry.json templates schema template-registry.js

04Serverový GPT-5.5 providerOpenAI Responses API, strict Structured Outputs, žiadny kľúč v klientovi＋

Cieľ: bezpečne pripojiť model k dokumentovému kontraktu.

POST https://api.openai.com/v1/responses, model gpt-5.5, store: false, reasoning effort low.
Modelový výstup má zúžených 7 PTDF operácií alebo kompletný statický HTML/CSS kandidát; server autoritatívne vynucuje zvolený režim.
Médiá sa z kontextu odstraňujú; binárne dataUrl sa modelu neposielajú.

Akceptácia: provider testy používajú injektovaný mock transport a nevykonajú platené volanie.

provider.php provider schema message.php

05Kontrolovaná vrstva návrhovPreview, história návrhov a ochrana pred zastaraným dokumentom＋

Cieľ: zabrániť neaktuálnej zmene dokumentu.

Maximálne 8 posledných návrhov len v pamäti stránky; obnovenie stránky alebo nový rozhovor ich odstráni.
Návrh možno prezrieť, stiahnuť ako PTDF, odmietnuť a počas relácie obnoviť.
Fingerprint vstupného PTDF odhalí, že editor sa od vytvorenia návrhu zmenil, a aplikáciu zablokuje.

Akceptácia: fingerprint sa kontroluje pred manuálnym aj automatickým použitím; neaktuálny návrh dokument nezmení.

assistant-proposals.js ai-assistant.js

06Kvalita, spätná väzba a observabilityNeobsahová telemetria a offline viacjazyčné evaly＋

Cieľ: merať kvalitu bez ukladania dokumentov a konverzácií.

Explicitné „Pomohlo / Nepomohlo“; server prijíma iba strict feedback kontrakt.
Mesačné agregované počty, retencia 12 mesiacov, limit 60 spätných väzieb / IP / 24 h.
Max. 40 diagnostických udalostí v pamäti stránky; export neobsahuje prompt ani odpoveď.
Viacjazyčné evaly používajú mock transport.

Akceptácia: agregácia neobsahuje message, history, document, reply, request ID ani IP.

feedback.php feedback-contract.php assistant-observability.js run-assistant-evals.php

07Produkčné runtime brzdyFeature flag, rollout, rozpočet, kapacita a circuit breaker＋

Cieľ: kontrolovať dostupnosť a náklady pred každou provider požiadavkou.

Hlavný prepínač, deterministický rollout podľa zdrojovej IP, denný UTC rozpočet a súbežné lease.
Circuit breaker pri opakovaných chybách provideru a verejný, ne-senzitívny status endpoint.
Klient status obnoví pri otvorení asistenta; server ostáva autoritatívny.

Akceptácia: zablokovaný runtime nevytvorí požiadavku na OpenAI a vracia stabilný kód s retryAfter, kde je relevantný.

runtime.php runtime schema status.php assistant-runtime.js

08Ochrana obsahu a tajomstievVstupný aj výstupný scanner a hranice dôvery promptu＋

Cieľ: zabrániť odoslaniu vysokokonfidenčných tajomstiev a prijatiu nebezpečného výstupu.

Pred rate limitom a runtime admission sa skenuje správa, história a normalizovaný text PTDF.
Preskočí sa iba validované obrazové pole dataUrl normalizovaného PTDF; reťazec, ktorý iba vyzerá ako Data URI v správe, histórii alebo textovom bloku, sa naďalej skenuje.
Blokujú sa API kľúče, private-key hlavičky, bearer credentials, JWT a známe access tokeny; IBAN, IČ DPH, adresy a fakturačné údaje ostávajú povolené.
Po validácii sa rovnakou politikou skenuje aj výstup modelu.
Dokument a história sú označené ako nedôveryhodný referenčný obsah; pokyny v nich nemajú prioritu.

Akceptácia: detekcia vracia 422 a telemetria uloží iba kategóriu a zdroj, nikdy nájdenú hodnotu.

security.php security test

09Pripravenosť na nasadenie a povereniaŠifrovaný kľúč, pseudonymný safety identifier a preflight＋

Cieľ: pripraviť kontrolovaný handoff bez vystavenia kľúča.

API kľúč sa spravuje cez chránenú administráciu, šifruje Sodium secretboxom a ukladá do jedného riadka MySQL tabuľky.
Šifrovací kľúč a salt pre safety_identifier sa odvodzujú z master secretu oddelenými HKDF kontextmi.
Safety identifikátor je 48-znakový HMAC digest; raw IP ani account ID nejde modelu.
Preflight kontroluje PHP, cURL, schémy, register, poverenia, úložiská, model a produkčné HTTPS.

Akceptácia: report neobsahuje tajomstvá; produkčný režim zlyhá bez HTTPS a externých zapisovateľných adresárov.

credentials.php deployment.php deployment-check.php credential migration ads-manager.html

10Launch acceptance a prístupnosťDeterministický manifest, bezpečný smoke test a voliteľná live sonda＋

Cieľ: získať reprodukovateľný dôkaz o tom, čo sa nasadzuje.

Secret-free manifest obsahuje build ID, verzie komponentov a počty schopností.
Bezpečný launch check kontroluje manifest a runtime bez modelovej požiadavky.
Platená live sonda je nemožná bez súčasného produkčného režimu, --live a --confirm-live.
Dialóg vracia fokus launcheru, používa aria-busy, aria-live a bezpečnostný popis vstupu.

Akceptácia: safe launch check vykáže live_probe: skipped. Súhrnná release gate má prejsť po odstránení aktuálneho false-positive nálezu syntetických credential fixture v dvoch testovacích súboroch.

release.php manifest.php launch.php launch-check.php stage10 gate accessibility test

11Generovanie obrázkov a omaľovánokImage Generation tool, bezpečný WebP a kontrolovaný PTDF import＋

Cieľ: umožniť používateľovi v tom istom rozhovore vytvoriť a vložiť nový vizuál.

Bežná textová požiadavka nástroj image_generation vôbec nedostane. Sprístupní ho iba explicitná rýchla voľba Obrázok alebo Omaľovánka cez pevnú serverovú capability.
Pri autorizovanom obrazovom toku sa modelu neposiela história ani obsah aktuálneho dokumentu; zostane iba neobsahový PTDF shell potrebný na bezpečné pripojenie výsledku.
Neurčitá požiadavka najprv vyvolá otázku na námet a server zachová rovnakú capability iba pre túto nadväzujúcu odpoveď.
Výstup je jeden portrétový WebP; server overí Base64, skutočnú signatúru formátu a limit 1,1 MB ešte pred zostavením PTDF.
Omaľovánka dostáva tlačové pravidlá: biele pozadie, čisté uzavreté obrysy, okraje, bez sivej, tieňov a gradientov.
Pri otvorenom dokumente server zachová existujúci obsah a pridá validovaný image blok; nikdy nevloží binárne dáta vytvorené modelovým JSON plánom.
Verejný kontrakt prenáša jazykovo neutrálny mediaKind, ktorý sa musí zhodovať s autorizovanou capability: bežný obrázok ostáva v PTDF kontrole, ale coloring_page sa po schválení odošle do spoločného importu Omaľovánky.
Spoločný import raster normalizuje, označí a zamkne ako coloring-reference. Referencia sa tak zapojí do kompozitnej mapy hraníc nástroja Výplň a AI obrázok neobíde proces, ktorý drží farbu v uzavretých líniách.
Rýchle voľby Obrázok a Omaľovánka preberajú názvy z existujúceho drawing katalógu vo všetkých 48 lokalitách a iba predvyplnia zadanie, aby používateľ doplnil námet.
Výsledok ostáva návrhom; bežný obrázok čaká na PTDF potvrdenie a Omaľovánka otvorí upraviteľnú drawing reláciu až po schválení návrhu.

Akceptácia: mock testy pokrývajú izoláciu nedôveryhodnej histórie a PTDF obsahu, nový dokument, append do existujúceho PTDF, explicitné rozlíšenie omaľovánky, neautorizovaný, chýbajúci aj neočakávaný tool output; bez plateného API volania.

provider.php provider schema public schema ai-assistant.js drawing.js stage11 gate

12Priame úpravy dokumentuJednorazový súhlas, automatická PTDF aplikácia a Undo＋

Cieľ: odstrániť opakované modálne kroky pri bežných textových úpravách bez oslabenia validácie a ochrany pred súbežnou zmenou.

Prvá vhodná zmena otvorí prístupný dialóg s vysvetlením a odkazom na podmienky.
Verziovaný lokálny súhlas obsahuje iba verziu a čas udelenia; správy ani dokument sa doň neukladajú.
Po súhlase sa nemediálny PTDF výsledok znovu overí fingerprintom, striktne validuje a programovo nahradí aktuálny stav editora.
Každý zápis vytvorí krok histórie, zobrazí tlačidlo Vrátiť AI úpravu a povolenie možno vypnúť priamo v paneli.
Obrázky a omaľovánky ostávajú v explicitnom kontrolnom toku.

Akceptácia: starý alebo neplatný návrh sa neaplikuje; platná zmena po súhlase neotvorí modal pridať/nahradiť a posledný automatický zápis možno vrátiť.

assistant-direct-edit.js ai-assistant.js ptdf.js direct-edit test

13AI asistent vo fullscreen režimeTá istá stavová vrstva nad celoobrazovkovým náhľadom＋

Cieľ: zachovať asistenta dostupného aj v natívnom a náhradnom fullscreen režime bez duplikácie rozhrania alebo stavu.

Pred requestFullscreen() sa existujúci DOM uzol asistenta presunie do fullscreen kontajnera náhľadu.
Otvorený panel, rozpísaný vstup, konverzácia, návrhy aj rozpracovaná odpoveď ostávajú v pôvodnej inštancii.
Pri odchode z fullscreen sa uzol vloží späť do pôvodného rodiča a na pôvodné miesto v DOM.
Rovnaký lifecycle pokrýva natívny fullscreen aj CSS fallback.
Samostatné vrstvenie, limit výšky a mobilné safe-area odsadenie držia panel čitateľný nad náhľadom.

Akceptácia: asistent sa dá vo fullscreen otvoriť a používať, stav sa pri vstupe ani výstupe nestratí a nevznikne druhá inštancia.

core.js ai-assistant.css fullscreen test stage13 gate

04 · Systémový pohľad

Architektúra a tok dát

Prehliadač posiela len kontraktovanú požiadavku aplikačnému endpointu. Všetky dôveryhodné kontroly a provider komunikácia prebiehajú na serveri.

Používateľpokyn + údaje

AI vrstvalocale + stav PTDF

Access + scannerúčet, tajomstvá

Runtime gatelimit, lease, circuit

GPT-5.5Responses API

Validáciaschema + PTDF + scanner

Editorsúhlas → validácia → Undo

API kľúč existuje iba medzi credential úložiskom a serverovým HTTP transportom. Do browser response sa nikdy nevracia.

Klient

UI, lokality, serializácia aktuálneho PTDF, história konverzácie v pamäti, proposal review, feedback a neobsahová diagnostika.

Aplikačný server

Prístupová politika, input validácia, secret scan, rate limit, runtime admission, provider prompt, output validácia, PTDF operácie a response contract.

Externý provider

OpenAI Responses API dostane aplikačné pravidlá a explicitne označené používateľské vstupy. store: false vypína ukladanie response objektu providerom; vstavaný image_generation tool sa pridá iba pri explicitnej obrazovej capability a v tomto toku sa vynechá nedôveryhodná história aj obsah PTDF.

Poradie serverových kontrol

#	Kontrola	Dôvod poradia	Výsledok pri chybe
1	HTTP metóda a veľkosť tela	Najlacnejšie odmietnutie neplatného vstupu.	405 / 413
2	JSON, povolené polia, verzia a locale	Nedovolí neznámy kontrakt do ďalších vrstiev.	400 / 422
3	História a PTDF normalizácia	Model nikdy nedostane neplatnú dokumentovú štruktúru.	422
4	Prístup účtu	Guest / Free / Premium politika je serverovo vynútená.	403
5	Vstupný secret scanner	Tajomstvo sa odmietne ešte pred rate limitom a providerom.	422
6	IP rate limit	Chráni verejný endpoint pred zneužitím.	429
7	Runtime admission + lease	Kontroluje rollout, denný budget, circuit a kapacitu.	429 / 503
8	Provider + strict output	Jediná vrstva, ktorá môže vytvoriť platenú požiadavku.	429 / 502 / 503
9	Schema, registry, PTDF a výstupný scan	Do browsera sa vráti iba bezpečný a konzistentný návrh.	502
10	Uvoľnenie lease	Prebehne po úspechu aj chybe; expirované lease majú TTL 240 s, teda viac než 180 s provider timeout.	interné zotavenie

05 · Dátové rozhrania

Kontrakty, request a PTDF

Verejný aplikačný kontrakt má verziu ptp.assistant/3 a rozlišuje PTDF, HTML artifact a jeden ohraničený lokálny systémový plán. Produkčný provider vie pripraviť PTDF, statický HTML/CSS kandidát, autorizovaný jednorazový generátor statického HTML alebo jednu povolenú akciu Etapy 11. Aktívny JavaScript v dokumente ostáva vypnutý. Verzie ptp.assistant/2 a ptp.assistant/1 zostávajú kompatibilné pre pôvodné dokumentové odpovede, nie pre vykonávanie akcií. Provider používa užšiu internú verziu ptp.assistant.provider/4; používateľský klient ju priamo nevidí.

Príklad požiadavky browser → pasteToPrint

JSON · bez poverení

{
  "contractVersion": "ptp.assistant/3",
  "requestId": "req-demo-0001",
  "message": "Vytvor cenovú ponuku v nemčine pre troch používateľov.",
  "conversationLocale": "sk",
  "documentLocale": "de",
  "state": {
    "history": [],
    "lastDocumentType": null,
    "missingFields": [],
    "currentDocument": null
  }
}

Serverový payload pre Responses API — zjednodušený tvar

Pole tools v ukážke sa pridáva iba pri explicitnej obrazovej capability; v bežnej požiadavke úplne chýba.

JSON · Authorization hlavička zámerne nie je zobrazená

{
  "model": "gpt-5.5",
  "instructions": "Aplikačné pravidlá a hranice dôvery…",
  "input": [
    { "role": "user", "content": [{ "type": "input_text", "text": "Používateľská požiadavka…" }] }
  ],
  "store": false,
  "reasoning": { "effort": "low" },
  "max_output_tokens": 12000,
  "tools": [{
    "type": "image_generation",
    "action": "generate",
    "size": "1024x1536",
    "quality": "medium",
    "background": "opaque",
    "output_format": "webp",
    "output_compression": 72
  }],
  "text": {
    "format": {
      "type": "json_schema",
      "name": "pastetoprint_document_plan",
      "strict": true,
      "schema": "obsah provider/v4/schema.json"
    }
  },
  "safety_identifier": "pseudonymný 48-znakový HMAC digest"
}

Statusy odpovede

needs_input — iba výber jedného podporovaného režimu alebo chýbajúci námet pri explicitne spustenej tvorbe obrázka.
preview_ready — kompletný validovaný artifact je pripravený; neznáme dokumentové údaje obsahuje ako prázdne polia.
action_ready — server pripravil jeden povolený lokálny plán; úspešná odpoveď sa zobrazí až po overenom vykonaní.
informational — odpoveď bez režimu a artifactu.
unsupported — zámer mimo rozsahu.
error — aplikačná chyba s kódom a retryable flagom.

Pravidlá chýbajúcich údajov

requiredFields určujú štruktúru dokumentu, nie otázky pre používateľa. Provider môže použiť údaje, ktoré používateľ sám zadal v správe alebo dokumente. Chýbajúce údaje nesmie vypytovať ani vymýšľať; zobrazí ich ako lokalizované názvy s prázdnym miestom alebo neutrálnym zástupným poľom. Toto pravidlo platí pre všetky typy, jazyky, režimy, vytvorenia, úpravy aj analýzy.

Povolené aplikačné operácie PTDF

Operácia	Účel	Typická ochrana
`set_title`	Nastavenie názvu dokumentu.	Dĺžka a normalizácia textu.
`set_metadata`	Kontrolovaná zmena metadát PTDF.	Povolené kľúče a typy.
`set_template`	Zmena vizuálnej šablóny.	ID musí existovať v registry.
`append_block`	Pridanie bloku na koniec.	Validný typ bloku, max. počet.
`insert_block`	Vloženie na index.	Index v povolenom rozsahu.
`update_block`	Úprava existujúceho bloku.	Existujúci index a validný blok.
`delete_block`	Odstránenie bloku.	Existujúci index.
`move_block`	Presun medzi indexmi.	Zdroj aj cieľ v rozsahu.
`replace_document`	Celý nový dokument.	Zakázané pri existujúcom dokumente s médiami.
`format_runs`	Formátovanie behov v texte.	Rozsahy a podporované štýly.

Ochrana médií

Existujúce Base64 médiá sa do modelového kontextu neposielajú. Pri generovaní modelový JSON plán obsahuje iba druh, názov, alt text a voliteľný popis; binárny výsledok prichádza oddeleným tool outputom a server pred PTDF kontroluje Base64, signatúru WebP/PNG/JPEG aj veľkosť. Úplná AI náhrada existujúceho PTDF s médiami je naďalej odmietnutá.

06 · Internacionalizácia

48 lokalít a 14 dokumentových typov

Asistent nededukuje jazyk iba z prehliadača. Konverzačný a dokumentový jazyk putujú kontraktom oddelene a server ich zachová v odpovedi.

Konverzačná lokalita

Určuje jazyk otázok, vysvetlení, chybových hlášok a priebehu rozhovoru.

Dokumentová lokalita

Určuje jazyk výsledného dokumentu; môže byť odlišná od jazyka používateľského pokynu.

RTL

Arabčina a ďalšie pravostranné scenáre majú testovaný smer rozhrania aj dokumentu bez zmeny kontraktu.

Typy dokumentov v univerzálnom registry

ID	Kategória	Príklady	Povinné dáta — príklady
`blank`	general	voľný dokument, text	body
`note`	internal	poznámka, memo, záznam	body
`invoice`	finance	faktúra, vyúčtovanie	supplier, customer, dates, currency, VAT, items
`price_offer`	finance	cenová ponuka, odhad	supplier, customer, subject, items, currency
`order`	business	objednávka, nákup	customer, supplier, items, deadline
`business_letter`	business	obchodný list, korešpondencia	sender, recipient, subject, body
`complaint`	official	reklamácia, sťažnosť	parties, problem, requested resolution
`handover`	service	odovzdávací protokol	parties, subject, items, date
`meeting`	internal	zápisnica, agenda	date, participants, topic
`request`	official	žiadosť, podanie	applicant, recipient, subject, body
`declaration`	official	vyhlásenie, čestné vyhlásenie	declarant, body, date
`work_report`	service	výkaz práce, timesheet	worker, date, entries
`delivery_note`	business	dodací list	supplier, customer, items, date
`service`	service	servisný alebo opravárenský záznam	customer, location, request description

Všetky položky deklarujú supportedLocales: ["*"]; počet 48 v release manifeste predstavuje podporované aplikačné lokality, nie 48 kópií registry.

07 · HTTP rozhranie

Endpointy, limity a chyby

Endpoint	Metóda	Úloha	Úspech	Autorizácia / cache
`/api/assistant/message.php`	POST	Hlavná dokumentová požiadavka.	200 JSON kontrakt	Prístup podľa účtu, no-store
`/api/assistant/status.php`	GET	Verejný runtime stav bez tajomstiev.	200 status	Verejný, no-store
`/api/assistant/manifest.php`	GET	Build ID, verzie a schopnosti.	200 manifest	Verejný, secret-free
`/api/assistant/templates/index.php`	GET	Univerzálny template registry.	200 registry	Verejný, cache 300 s
`/api/assistant/feedback.php`	POST	Explicitná agregovaná spätná väzba.	202 accepted	60 / IP / 24 h
`/api/ads-manager/index.php?action=save-assistant-key`	POST	Šifrované uloženie alebo výmena kľúča.	200 public status	Chránená admin session
`/api/ads-manager/index.php?action=delete-assistant-key`	POST	Odstránenie credential riadka.	200 configured=false	Chránená admin session

Validované limity

3 000

znakov v jednej správe alebo položke histórie

správ histórie v otvorenej stránke

750 kB

maximum celého request body

3 MB

maximum provider response body vrátane jedného obrázka

500 k

serializovaných znakov aktuálneho PTDF snapshotu

provider operácií na jednu odpoveď

100

blokov v generovanom drafte

1 / 1,1 MB

obrázok na request / maximálna binárna veľkosť

30/10m

verejný limit správ na zdrojovú IP

Stabilné chybové skupiny

HTTP	Príklady kódov	Klientské správanie
400	`invalid_json`	Neopakovať automaticky; opraviť request.
403	`assistant_disabled`	Zobraziť nedostupnosť pre typ účtu.
405	`method_not_allowed`	Použiť dokumentovanú metódu.
413	`request_too_large`	Zmenšiť históriu alebo PTDF kontext.
422	`unsupported_contract`, `invalid_state`, `assistant_sensitive_data_detected`	Vyžiadať opravu; neodosielať znova bez zmeny.
429	`assistant_rate_limited`, `assistant_daily_limit_reached`	Rešpektovať `Retry-After`.
502	`assistant_invalid_response`, `assistant_image_generation_failed`, `assistant_invalid_image`, `assistant_image_too_large`	Návrh nepoužiť; ponúknuť bezpečné opakovanie.
503	`assistant_not_configured`, `assistant_circuit_open`, `assistant_capacity_reached`, `assistant_provider_unavailable`	Zobraziť stav; opakovať iba ak `retryable`.

08 · Threat model

Bezpečnosť a súkromie

Ochrana je viacvrstvová: credential storage, prístup účtu, vstupná kontrola, dôveryhodnostné značky promptu, strict output, výstupný scan a minimalizovaná telemetria.

Poverenia

Admin formulár posiela kľúč iba na server v chránenom same-origin requeste.
Sodium secretbox používa náhodný nonce; ciphertext, nonce a verzia sú v ptp_assistant_credentials.
Šifrovací kľúč sa odvodí HKDF-SHA256 z master secretu s osobitným kontextom.
Public status vracia len configured a čas zmeny, nikdy kľúč ani jeho časť.

Prístup

Master switch v admin konfigurácii.
Oddelené prepínače pre guest, free a premium.
Environment kill switch má najvyššiu prioritu.
Serverová kontrola je v status aj message ceste; úprava DOM ju neobíde.

Obsah a prompt injection

User message, history a dokument sú nedôveryhodné vstupy.
Inštrukcie nájdené v dokumente sa interpretujú iba ako obsah dokumentu.
Vysokokonfidenčné tokeny sa blokujú pred providerom aj po ňom.
Business identifikátory sa neblokujú plošne, aby ostala použiteľnosť dokumentov.

Minimalizácia dát

Konverzácia, proposal history a diagnostika sú len v pamäti stránky.
Lokálny súhlas s priamymi úpravami obsahuje iba verziu, boolean a čas udelenia; neobsahuje správu ani dokument.
Feedback a security telemetria sú mesačné počty s retenciou max. 12 mesiacov.
store: false je súčasťou každej Responses API požiadavky.
Existujúce mediálne data URL sú z modelového kontextu odstránené; novo vygenerovaný obraz sa drží iba v PTDF návrhu v pamäti stránky.

Klasifikácia uložených dát

Dáta	Miesto	Retencia	Obsah používateľa?
História konverzácie	RAM aktuálnej browser stránky	do reloadu / nového rozhovoru	áno
Návrhy PTDF	RAM stránky, max. 8	do reloadu / nového rozhovoru	áno
Diagnostika	RAM stránky, max. 40 eventov	do reloadu	nie; iba metadáta
Súhlas s priamymi úpravami	localStorage aktuálneho browsera	do odvolania alebo zmeny verzie	nie; iba verzia, stav a čas
Feedback	serverové mesačné agregáty	max. 12 mesiacov	nie
Security detections	serverové mesačné agregáty podľa kategórie/zdroja	max. 12 mesiacov	nie; matched value sa neukladá
Runtime state	zamknutý JSON mimo web rootu v produkcii	priebežný stav UTC dňa	nie
API kľúč	MySQL ciphertext + nonce	do výmeny alebo odstránenia	tajomstvo, šifrované

09 · Prevádzkové riadenie

Runtime konfigurácia

Nasledujúce premenné nemenia kontrakt. Umožňujú bezpečný rollout, nákladový limit a núdzové vypnutie bez úpravy klienta.

Premenná	Default	Rozsah / účel	Produkčné odporúčanie
`PTP_ASSISTANT_ENABLED`	true	Environment kill switch.	Mať pripravenú hodnotu false pre rollback.
`PTP_ASSISTANT_ROLLOUT_PERCENT`	100	0–100; deterministická IP kohorta.	Začať 5–10 %, potom zvyšovať.
`PTP_ASSISTANT_DAILY_REQUEST_LIMIT`	500	1–100000 provider requestov za UTC deň.	Nastaviť podľa rozpočtu a meranej spotreby.
`PTP_ASSISTANT_MAX_CONCURRENT`	4	1–50 aktívnych lease.	Zladiť s PHP worker poolom.
`PTP_ASSISTANT_CIRCUIT_FAILURES`	5	1–20 chýb na otvorenie circuitu.	Ponechať konzervatívne pri štarte.
`PTP_ASSISTANT_CIRCUIT_WINDOW_SECONDS`	300	30–3600 s rolling window.	Monitorovať provider incidenty.
`PTP_ASSISTANT_CIRCUIT_COOLDOWN_SECONDS`	120	30–3600 s pauza.	Vyhnúť sa agresívnemu retry.
`PTP_ASSISTANT_RUNTIME_DIR`	server temp	State, budget a lease.	Perzistentný zapisovateľný adresár mimo web rootu.
`PTP_ASSISTANT_SECURITY_DIR`	server temp	Agregované security počty.	Zapisovateľný adresár mimo web rootu.
`PTP_ASSISTANT_ACCESS_FILE`	`storage/private/assistant-access.json`	Master a account-type prepínače.	Explicitná súkromná cesta mimo web rootu.
`PTP_ASSISTANT_PUBLIC_URL`	prázdne	Verejný pôvod pre preflight.	Presná HTTPS origin URL bez path.

Environment už nie je miesto pre API kľúč

Aktuálna implementácia číta OpenAI credential zo šifrovanej MySQL tabuľky. Do prostredia patria iba prevádzkové prepínače a privátne cesty. Master secret pochádza z existujúcej privátnej konfigurácie aplikácie.

10 · Zdrojový inventár

Technické súbory

Druhé vyhľadávacie pole filtruje iba implementačný inventár podľa cesty, vrstvy alebo zodpovednosti.

Hľadať súbor alebo zodpovednosť

Vrstva

Vrstva	Súbor	Zodpovednosť
klient	`assets/js/ai-assistant.js`	Orchestrácia UI, message request, lokality, spracovanie odpovede a prístupnosť.
klient	`assets/css/ai-assistant.css`	Výsuvná vrstva, bottom-center launcher a responzívne stavy.
klient	`assets/js/assistant-contract.js`	Browser reprezentácia verziovaného kontraktu a PTDF operácií.
klient	`assets/js/assistant-template-registry.js`	Klientská registry dokumentových typov.
klient	`assets/js/assistant-proposals.js`	Memory-only návrhy, fingerprint, stale guard a PTDF export.
klient	`assets/js/assistant-direct-edit.js`	Verziovaný jednorazový súhlas a pravidlá vhodnosti automatickej aplikácie.
klient	`assets/js/assistant-runtime.js`	Čítanie verejného runtime statusu a klientské availability stavy.
klient	`assets/js/assistant-observability.js`	Feedback UX, pamäťová diagnostika a privacy-safe export.
klient	`assets/js/html-document-pipeline.js`	Kanonická dvojpriechodová HTML/CSS sanitizácia, limity, report a konštrukcia budúceho assistant HTML artifactu.
klient	`assets/js/assistant-client-capabilities.js`	Jednorazový reálny browser preflight HTML pipeline, review iframe a izolovaného generátora.
klient	`assets/js/assistant-generator-recovery.js`	Striktný zoznam obnoviteľných chýb, limit jedného retry a nemenný downgrade capability na statické HTML.
klient	`assets/js/assistant-action-registry.js`	Fail-closed discovery reálnych command bindingov bez vykonania systémovej akcie.
server	`api/assistant/message.php`	Hlavný POST endpoint a kompletné poradie kontrol.
server	`api/assistant/provider.php`	GPT-5.5 prompt, Responses API a Image Generation tool, binárna kontrola, output parsing a PTDF aplikácia.
server	`api/assistant/contract.php`	Aplikačný response kontrakt, normalizácia a error response.
server	`api/assistant/client-capabilities.php`	Striktná normalizácia capability objektu a fail-closed predvolený stav.
server	`api/assistant/generator-recovery.php`	Release identita a maximálny počet statických recovery requestov.
server	`api/assistant/actions.php`	Autoritatívna validácia action snapshotu a bezpečný prienik pre provider.
server	`api/assistant/templates/registry.php`	Autoritatívny register 14 dokumentových typov.
server	`api/assistant/runtime.php`	Rollout, budget, lease, circuit breaker a public state.
server	`api/assistant/security.php`	Detekcia tajomstiev a privacy-preserving mesačné počty.
server	`api/assistant/credentials.php`	Sodium šifrovanie, MySQL čítanie a HKDF derivácia.
server	`api/assistant/access.php`	Guest / Free / Premium rozhodnutie a master access config.
server	`api/assistant/deployment.php`	Preflight a safety_identifier.
server	`api/assistant/release.php`	Deterministický build ID a capability manifest.
server	`api/assistant/launch.php`	HTTP launch acceptance a guarded live probe.
schema	`api/assistant/schema/v2/schema.json`	Aktuálny dvojformátový assistant response JSON Schema.
schema	`api/assistant/schema/v1/schema.json`	Legacy PTDF assistant response Schema pre kompatibilitu.
schema	`api/assistant/client-capabilities/v1/schema.json`	Presný klientsky capability kontrakt bez možnosti aktívneho JavaScript dokumentu.
schema	`api/assistant/actions/v1/schema.json`	Uzavretá schéma systémových capability stavov s trvalo vypnutým executorom Etapy 10.
schema	`api/assistant/provider/v2/schema.json`	Strict Structured Output pre PTDF alebo HTML/CSS modelový plán.
schema	`api/assistant/templates/v1/schema.json`	Schema registra typov a blueprintov.
admin	`ads-manager.html`	Chránené UI pre kľúč a account access.
admin	`api/ads-manager/index.php`	Admin actions pre credential a access config.
test	`scripts/test-assistant-stage10-release.ps1`	Súhrnná release gate etáp 1–10.
test	`scripts/test-assistant-stage11-media.ps1`	Mockovaná gate obrázkov, omaľovánok, PTDF médií, 48 lokalít a manifestu.
test	`scripts/test-assistant-stage13-fullscreen.ps1`	Fullscreen gate pre presun jednej stavovej vrstvy, návrat do pôvodného DOM, prístupnosť a mobilné rozloženie.
test	`scripts/test-assistant-document-modes-stage1-release.ps1`	Kontraktová gate PTDF/HTML artifactov, runtime gatingu a spätnej kompatibility v1.
test	`scripts/test-assistant-document-modes-stage2-release.ps1`	Offline gate spoločného HTML/CSS pipeline, reportu, browser sanitizácie a nezapnutého HTML/JavaScript runtime.
test	`scripts/test-assistant-document-modes-stage9-release.ps1`	Súhrnná dual-format gate etáp 0–9 vrátane reálneho browser capability probe a jedného statického generator recovery retry.
test	`scripts/test-assistant-document-modes-stage10-release.ps1`	Súhrnná gate etáp 0–10 vrátane action parsera, command bindingov a ne-exekučného Chromium discovery testu.
test	`scripts/assistant-deployment-check.php`	Prípravný a produkčný deployment preflight.
test	`scripts/assistant-launch-check.php`	Safe smoke test a explicitná live sonda.
test	`scripts/run-assistant-evals.php`	Offline multilingual eval cases s mock transportom.

11 · Verifikácia

Akceptačná matica — 20 prípadov

Záznam posledného 20-prípadového lokálneho overenia. Provider testy boli mockované; akceptačný beh nevykonal platenú OpenAI požiadavku. Runtime konfigurácia sa odvtedy môže meniť, preto horný panel zobrazuje aktuálny live status.

#	Vrstva	Scenár	Očakávanie	Záznam
1	UI	Načítanie editora a launcheru	Prvok je prítomný na spodnom strede.	PASS
2	UI	Otvorenie asistenta	Vrstva sa otvorí a fokus prejde do vstupu.	PASS
3	A11y	Escape a návrat fokusu	Vrstva sa zavrie, fokus sa vráti launcheru.	PASS
4	i18n	Slovenská lokalizácia	Texty a locale kontrakt sú slovenské.	PASS
5	i18n	Arabčina / RTL	Rozhranie rešpektuje pravostranný smer.	PASS
6	HTTP	Status GET	200 a validný runtime JSON.	PASS
7	HTTP	Status POST	405, `Allow: GET`.	PASS
8	Release	Manifest GET	200, validný build ID a verzie.	PASS
9	Release	Manifest POST	405.	PASS
10	Registry	Zoznam šablón	Presne 14 typov a default `blank`.	PASS
11	Registry	Výber faktúry	Typ `invoice` s povinnými poliami.	PASS
12	Registry	Neznámy typ	Bezpečný fallback `blank`.	PASS
13	Registry	Nejednoznačný query parameter	400 namiesto tichého uhádnutia.	PASS
14	Message	GET na POST endpoint	405.	PASS
15	Message	Neplatný JSON	400 `invalid_json`.	PASS
16	Contract	Nepodporovaná verzia	422 `unsupported_contract`.	PASS
17	Contract	Neplatná história	422 `invalid_state`.	PASS
18	Security	Syntetický secret vo vstupe	422, nič nejde provideru.	PASS
19	Runtime	Bezpečný request pri nenakonfigurovanom stave	503 bez provider call (stav test fixture).	PASS
20	Feedback	Platná spätná väzba	202 accepted, iba agregát.	PASS

Doplňujúce evaly a release gates

4 offline jazykové prípady

slovenská faktúra → preview,
anglický prázdny vzor faktúry → preview s vyplniteľnými poľami bez otázok,
arabská zápisnica → RTL dokumentový tok,
slovenská bezpečná aktualizácia existujúceho PTDF.

4 / 4 PASS

Stage 11 media gate

test-assistant-stage11-media.ps1 skladá provider media mocky, strict schémy, 48 lokalít, verejný kontrakt, observability a manifest. Lokálny browser navyše overil lokalizované nemecké quick actions.

etapa 11 PASS bez plateného volania

Stage 13 fullscreen gate

test-assistant-stage13-fullscreen.ps1 kontroluje presun asistenta pred natívnym fullscreen, CSS fallback, návrat na pôvodné miesto, zachovanie jednej inštancie, prístupnosť a mobilné safe-area pravidlá.

etapa 13 PASS bez volania modelu

Otvorený nález z 26. 8. 2026

Aktuálny rerun prešiel kontraktmi, 14 šablónami, 48 lokalitami, provider mockom, proposal, observability, runtime a 4/4 offline evalmi. Následne ho zastavil globálny scanner, pretože dva credential testy obsahujú syntetický projektový prefix skladaný priamo v testovacom zdroji. Nejde o reálny kľúč, ale gate zostáva červená, kým sa fixture alebo pravidlo scanneru neupraví.

Príkazy na opakovanie bezpečných testov

PowerShell · bez plateného modelového volania

& 'C:\laragon\bin\php\php-8.3.30-Win32-vs16-x64\php.exe' scripts/test-assistant-provider.php
& 'C:\laragon\bin\php\php-8.3.30-Win32-vs16-x64\php.exe' scripts/test-assistant-security.php
& 'C:\laragon\bin\php\php-8.3.30-Win32-vs16-x64\php.exe' scripts/run-assistant-evals.php
& scripts/test-assistant-stage10-release.ps1
& scripts/test-assistant-stage11-media.ps1
& scripts/test-assistant-stage13-fullscreen.ps1

12 · Runbook

Nasadenie a rollback

Poradie je navrhnuté tak, aby prvé platené volanie nastalo až po úspešnom produkčnom preflighte a výslovnom potvrdení.

Rotovať exponovaný credential

Zrušiť každý kľúč, ktorý sa objavil mimo zabezpečenej administrácie. Vytvoriť nový projektový kľúč a nevkladať ho do HTML, JavaScriptu, URL, logu ani dokumentácie.

Aplikovať credential migráciu

Raz na databázu vytvoriť tabuľku ptp_assistant_credentials.

PowerShell

& 'C:\laragon\bin\php\php-8.3.30-Win32-vs16-x64\php.exe' scripts/migrate-assistant-credentials.php --confirm=MIGRATE-ASSISTANT-CREDENTIALS

Nastaviť privátne úložiská a HTTPS origin

Runtime, security a access cesty musia byť zapisovateľné a mimo web rootu. PTP_ASSISTANT_PUBLIC_URL musí byť produkčná HTTPS origin URL.

Uložiť nový kľúč cez administráciu

Prihlásiť sa do ads-manager.html, otvoriť kartu Asistent a uložiť nový kľúč. Browser po úspechu dostane iba configured: true.

Uzavrieť release gate a spustiť produkčný preflight

Najprv odstrániť false-positive syntetických credential fixture a vyžadovať zelený test-assistant-stage10-release.ps1. Potom spustiť produkčný preflight:

PowerShell

& 'C:\laragon\bin\php\php-8.3.30-Win32-vs16-x64\php.exe' scripts/assistant-deployment-check.php --production

Pokračovať iba pri stave READY alebo vedome akceptovanom READY WITH WARNINGS bez povinného failu.

Spustiť bezpečný HTTP launch check

PowerShell · žiadna modelová požiadavka

& 'C:\laragon\bin\php\php-8.3.30-Win32-vs16-x64\php.exe' scripts/assistant-launch-check.php --base-url=https://www.pastetoprint.com --production

Voliteľne vykonať jednu live sondu

Iba po safe checku a so súhlasom na platenú požiadavku.

PowerShell · vykoná jedno provider volanie

& 'C:\laragon\bin\php\php-8.3.30-Win32-vs16-x64\php.exe' scripts/assistant-launch-check.php --base-url=https://www.pastetoprint.com --production --live --confirm-live

Postupný rollout a monitoring

Začať malou kohortou, sledovať agregovaný feedback, latency bands, HTTP 429/5xx a circuit stav. Zvyšovať percento až po stabilnom období.

Okamžitý rollback

Nastaviť PTP_ASSISTANT_ENABLED=false. Ak problém súvisí iba s účtami, vypnúť master alebo konkrétny account type v administrácii. Pri podozrení na credential incident kľúč zároveň odstrániť v administrácii a zrušiť u provideru.

13 · Diagnostika

Riešenie problémov

Prejav	Pravdepodobná príčina	Overenie	Náprava
`not_configured`	Chýba credential riadok alebo sa nedá dešifrovať.	Admin credential status + deployment check.	Migrácia, master secret, znovu uložiť nový kľúč.
`assistant_disabled`	Environment, master alebo account switch.	Status endpoint a admin Asistent.	Povoliť správnu vrstvu; neobchádzať server.
`rollout_unavailable`	Zdrojová IP nie je v kohorte.	Skontrolovať rolloutPercent.	Zvýšiť rollout alebo testovať povolenú kohortu.
`daily_limit`	Vyčerpaný UTC denný budget.	Status + runtime state.	Počkať do ďalšieho UTC dňa alebo vedome zvýšiť limit.
`circuit_open`	Viac provider chýb v rolling window.	Status `retryAfter`, serverové 5xx metriky.	Nechať cooldown; overiť provider a credential.
`capacity`	Dosiahnutý počet aktívnych lease.	Status a PHP worker využitie.	Počkať 5 s; až potom ladiť concurrency.
422 sensitive data	Vo vstupe je vysokokonfidenčný token alebo private key.	UI bezpečnostné hlásenie; raw hodnota sa neloguje.	Odstrániť secret a okamžite ho rotovať.
502 invalid response	Modelový výstup neprešiel strict validáciou.	Request ID a neobsahová diagnostika.	Skontrolovať schema/model konzistenciu; návrh nepoužiť.
Produkčný preflight: HTTPS fail	Chýba alebo je neplatná public origin.	`--production` report.	Nastaviť presnú HTTPS origin URL.
Manifest build sa líši	Rozdiel nasadených súborov alebo OPcache.	HTTP manifest vs CLI po redeployi.	Dokončiť atomický deploy a bezpečne obnoviť PHP cache.
Release gate hlási API key-like value v credential testoch	Syntetický testovací prefix zodpovedá globálnemu scanneru.	Výstup stage 7/10 gate a dva credential testy.	Poskladať fixture bez doslovného citlivého prefixu alebo zúžiť scanner tak, aby neoslabil kontrolu produkčných súborov.

14 · Životný cyklus

Údržba a zmeny

Pridanie typu dokumentu

Rozšíriť autoritatívny registry a jeho JSON.
Doplniť prekladové kľúče vo všetkých podporovaných lokalitách.
Ak treba, pridať modul a vizuálnu template ID.
Rozšíriť provider enum a eval case.
Spustiť registry, locale, provider a release testy.

Zmena modelu alebo API

Najprv overiť aktuálnu oficiálnu dokumentáciu OpenAI vrátane Image Generation tool parametrov.
Upraviť provider a runtime model konzistentne.
Ak sa mení výstup, vytvoriť novú verziu schémy; existujúcu v1 neprepisovať nekompatibilne.
Spustiť všetky mock evaly, stage 10 gate aj test-assistant-stage11-media.ps1.
Nový build overiť safe launch checkom; platený obrazový test vykonať iba po výslovnom potvrdení.

Monitoring po štarte

Dostupnosť status endpointu a podiel runtime states.
Latencia podľa pásiem, nie obsah promptov.
429, 502 a 503 podľa stabilného error code.
Helpful / not helpful trend po lokalite a type flow, ak ostáva neidentifikujúci.
Rozpočet a frekvencia circuit open.

Pravidlá kompatibility

Klient posiela explicitnú verziu kontraktu.
Server odmieta neznáme polia a verzie.
Build ID sa mení pri zmene kľúčových serverových, schémových alebo browser orchestrátorových vstupov.
Template registry je autoritatívny; model nesmie vymyslieť nové ID.

15 · Zdroje

Referencie a stav overenia

Technické tvrdenia o OpenAI rozhraní boli overené 26. 8. 2026 proti oficiálnej dokumentácii. Pri budúcej zmene modelu alebo payloadu treba referencie overiť znova.

Oficiálne OpenAI zdroje

Interné zdroje pasteToPrint

AI-ASSISTANT.md — prevádzkové poznámky.
Release manifest — aktuálny build a verzie.
Runtime status — aktuálna dostupnosť.
Template registry API — aktuálne typy.

Tento HTML súbor je dokumentácia a nemení release build ID asistenta. Build ID sa odvodzuje z kontraktov, provideru, credential vrstvy, orchestrácie, bezpečnosti, deployment/release/launch vrstiev a hlavného browser kontroléra.

Univerzálny jazykový asistent pre dokumenty