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, vypýta si chýbajúce údaje a vráti striktne validovaný PTDF. Po jednorazovom povolení môže bežné dokumentové zmeny aplikovať priamo do editora.

8

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

10

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

0

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 vedú k otázke 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 PTDF.

8 akcií: create_document, update_document, format_content, change_template, analyze_document, request_missing_data, answer_question a generate_image.
10 aplikačných operácií vrátane metadát, blokov, výmeny dokumentu a formátovacích behov.
Presné verzie, exact-object validácia a jednotný error objekt.

Akceptácia: platné príklady prejdú; cudzie polia, neplatná verzia alebo nekonzistentný status sú odmietnuté.

contract.php schema/v1/schema.json assistant-contract.js

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 operácií; server ich aplikuje na PTDF a následne vracia širší aplikačný kontrakt.
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/1. Provider používa užšiu internú verziu ptp.assistant.provider/1; používateľský klient ju priamo nevidí.

Príklad požiadavky browser → pasteToPrint

JSON · bez poverení

{
  "contractVersion": "ptp.assistant/1",
  "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/v1/schema.json"
    }
  },
  "safety_identifier": "pseudonymný 48-znakový HMAC digest"
}

Statusy odpovede

needs_input — chýbajú povinné fakty.
preview_ready — návrh PTDF je pripravený.
informational — odpoveď bez dokumentu.
unsupported — zámer mimo rozsahu.
error — aplikačná chyba s kódom a retryable flagom.

Pravidlá chýbajúcich údajov

Pred formálnym dokumentom provider porovná známe údaje s requiredFields vybraného typu. Ak niečo chýba, nesmie vytvoriť draft ani operácie; vráti všetky chýbajúce polia a stručné otázky.

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

12

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

50

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.
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/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/v1/schema.json`	Verejný assistant response JSON Schema.
schema	`api/assistant/provider/v1/schema.json`	Strict Structured Output pre 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/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á faktúra s chýbajúcimi údajmi → needs_input,
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