Spec: avax-apz — platforma ekonomicko-právních výpočetních aplikací (KONSOLIDOVANÁ)¶

Status: MASTER / locked model (2026-06-19, Michal). Tahle spec konsoliduje vše o apz do jednoho zdroje pravdy a nahrazuje roztříštěné app-legal/docs/spec/avax-legal-apz*.md. Obsahuje správný model + sekci vyloučených špatných směrů (§11), ať se nechodí v kruhu.

1. Co je apz¶

Platforma pro ekonomicko-právní výpočetní aplikace (mzdová účtárna, a další — každá počítá něco jiného). Každá aplikace = full-stack runner: FastAPI backend za apps-gateway + Next.js web; compute = legal temporal komponenty (apl) syncované z legalu.

2. SPRÁVNÝ MODEL (locked) — každá apz = vlastní vše¶

Každá apz aplikace = vlastní Gitea repo (<slug>-app) + vlastní kontejner (avax-app-<slug>) + vlastní compute. Každá počítá něco jiného (to bylo zadání).
Generuje se z template přes tlačítko „Nová aplikace" (create_app, app_kind=legal/apz) → plnohodnotná runner instance.
apl komponenty (subprogramy z legalu: vzorce, číselníky, proměnné, resource) — aplikace jich obsahuje hodně, jsou temporal (mění se v čase) a syncují se z avaxlegal/apz/. Legal je „plní daty".
Vlastní život: vlastní DB schema, data, uživatelé, běhy. Ale compute je vázané na legal (apl ze sdíleného legal zdroje, který se v čase mění).

3. Tři úložiště (role)¶

Úložiště	Co	Režim
Gitea `<slug>-app`	kód aplikace per app (full-stack runner kostra)	vlastní repo
avaxlegal S3 `avaxlegal/apz/`	legal compute data (`apl` komponenty + programy)	read-only, sdílené, temporal (plní app-legal)
Vlastní app data	write bucket + DB schema per app (běhy, snapshoty, user data)	per app, izolované

4. Co je v každé runner instanci¶

Backend (FastAPI): sync z avaxlegal/apz/ → compute kernel (engine + Variable DAG + temporal) → API (/programs, /schema, /run, /runs) → DB cache.
Web (Next.js): program picker → form (z /schema) → výsledek / dashboard.
CI (.gitea/workflows/backend.yml): push master → build image → deploy kontejner avax-app-<slug> → smoke (/health+DB) → auto-rollback.
Per-app: port (8101–8199), gateway route /apps/<slug>/, DB schema, M2M, storage.

5. Multi-output (program = N nezávislých výsledků)¶

structure_format=2, outputs[]: jeden program = víc nezávislých výsledků (mzdová účtárna = čistá mzda + nemocenské + exekuce) poskládaných z apl komponent. Back-compat structure_format=1 = degenerovaný outputs=[{target}]. Compute engine beze změny; checksum beze změny. (Implementováno + 12/12 testů — apz-app repo.)

6. Compute kernel¶

Engine (Variable DAG, formule, temporal §9A model), resolve z apl bundlů (sync cache), golden == backend /compute (deterministické, bit-exact). Žádný runtime wiring/codegen — kompozice je datová (Variables se slijí podle jména).

7. Sync model (avaxlegal/apz/ → app)¶

index.json → apl komponenty (subprograms/apl-*/) + programy (programs/<key>/) + app manifest (apps/<slug>/) → checksum verify → DB cache. Temporal: verze platné k as_of, gap (ERROR) / drift (WARNING) per output. Read-only (runner do avaxlegal nikdy nezapisuje).

8. Vytvoření aplikace (`create_app`) — jak vzniká nová apz app¶

Tlačítko „Nová aplikace" (launcher) → POST /admin/app-management/create (app_kind=legal|apz). Kompletní vytvoření MUSÍ udělat:

DB row (apps) — slug, name, vendor, schema, port, …
Vlastní Gitea repo <slug>-app + template push (apz runner kostra) + CI secrets (LEGAL_S3_* read, APPDIST_S3_*, AVAX_M2M_*).
Vlastní kontejner — CI na push postaví image + deploy (port collision-safe).
Gateway routing /apps/<slug>/ — auto-enable po prvním /health 200.
Vlastní úložiště — data bucket + DB schema (auto-provision při create).
Lokální adresář — launcher po create naklonuje repo do C:\avaxis\apps\<slug>.
avaxlegal sync — LEGAL_S3_* pro read avaxlegal/apz/.

⚠ GAPS k opravě (zjištěno 2026-06-19 na apz-mzdovauctarna): - Port alokátor je slepý k untracked kontejnerům (_allocate_container_port čte jen apps tabulku; avax-apz z flow B nebyl v tabulce → kolize 8113 → kontejner „Created"/nejede → health nikdy → gateway se nezapne). → zpřísnit (vidět reálně obsazené porty / reserved list) nebo každou instanci registrovat. - gateway se nezapnula (kaskáda z mrtvého kontejneru). - vlastní úložiště se nepřiřadilo (app_data_s3_key_id=NULL) — wizard pole neexponuje / legal nedostane data bucket default. - lokální adresář se nevytvořil (local_path je v DB jen string, launcher neklonuje). - Gitea se VYTVOŘILA (HTTP 200), ale feedback je zahrabaný v next_actions.

9. Plán: postavit správný vzor (`apz-vzor`)¶

Současný stav je rozbitý; pokračovat v něm = chodit v kruhu. Proto:

Vygeneruj apz-vzor přes tlačítko „Nová aplikace" (neutrální, žádná data).
Aplikuj všechny správně promyšlené změny (§8 gaps: collision-safe port, gateway auto-enable, storage + schema, local clone) → neutrální vzorová app.
app-legal předá co má → doplní data do vzoru pro test.
Test → tohle je THE správný vzor + funkční řešení.
Pak koncepční nasazení jakékoli apz aplikace z tohoto vzoru.

10. `avax-apz` prototyp¶

Byl jen test/vzor (deploynutý flow B z apz-app repa, port 8113). Nahradí ho apz-vzor. Drží 8113 → kolize. Retire po postavení vzoru (uvolní port). apz-mzdovauctarna (rozbité) — zahodit a předělat přes vzor.

11. VYLOUČENÉ ŠPATNÉ SMĚRY (ať se nechodí v kruhu)¶

❌ „jeden apz repo, N instancí" (detour 2026-06-19) → každá app má vlastní repo + kontejner + compute (každá počítá něco jiného).
❌ desktop skeleton (customtkinter, starý apz/skeleton) → full-stack runner.
❌ míchat apm fork do apz → apm je separátní (content/modulový runner, spec avax-apm.md), teď PAUSED; apz se řeší samostatně.
❌ avax-apz prototyp jako produkční → je jen vzor, nahradí apz-vzor.
❌ apz-mzdovauctarna (rozbité, port kolize, half-deployed) → zahodit, postavit přes vzor.
❌ per-app data v jednom sdíleném schématu → vlastní schema per app (izolace).

12. Otevřené / next¶

Opravit create_app gaps (§8) — collision-safe port, gateway auto-enable, storage default, launcher clone, jasný Gitea feedback.
Postavit apz-vzor (§9) → doladit → app-legal data → test → reference.
Uklidit: retire avax-apz, zvážit smazání apz-mzdovauctarna + repo.
create_app app_kind=content pro apm (later, až apz vzor stojí).

Zdroj pravdy. Starší avax-legal-apz*.md (app-legal) = superseded. Detaily compute kernelu/temporalu zůstávají v kódu apz-app repa (runtime/, sync/).