admin) per aplikace¶

Audience: vendor app developers (per-app „JC" Claude) + platform docs maintainers

Cíl: každá AVAX aplikace produkuje dokumentaci pro 3 publika, která se sama složí do docs portálu (docs.avaxis.cz) — nová appka se objeví ve správných tabech bez ruční editace mkdocs.yml.

0. TL;DR (co musí každá app udělat)¶

<repo>/docs/
  user/     index.md + .pages     → tab „Uživatelská"    (koncový uživatel)
  dev/      index.md + .pages     → tab „Programátorská"  (vendor / integrátor)
  admin/    index.md + .pages     → tab „Admin"           (super_admin provoz)
  *.md      (root)                → interní vendor guides (NEpull, viz §2)

V každé ze tří složek: index.md (landing) + .pages (název sekce + pořadí).
V H2/H3 titulcích používej explicit anchory ## Titulek { #id } (deep linky, §6).
Píšeš pro dané publikum (§7 rozhodovací tabulka).
git push → pull-sync (~15 min) → obsah je na portálu ve třech tabech (§8).

Zbytek dokumentu je „proč a přesně jak".

1. Tři publika = tři taby¶

Portál má 3 top-level taby = publika (navigation.tabs). V každém tabu je levé menu složené z Platforma (cross-cutting obsah AVAXu) + Aplikace/<app> (per-app, dodává appka).

Tab	Kdo to čte	Per-app zdroj	Platform zdroj (cross-cutting)
Uživatelská	koncový uživatel ve firmě	`docs/user/`	`user-guide/*` (launcher, začátečník, FAQ)
Programátorská	vendor / integrátor / app-Claude	`docs/dev/`	`context/`, `dev/`, `spec/`, `implementace.md`
Admin (superadmin)	super_admin / provozovatel platformy	`docs/admin/`	onboarding, gateway, deploy, infra, S3-klíče, RBAC

Kolaps: portál má navigation.expand vypnutý → sekce jsou defaultně sbalené (uživatel rozklikne jen svoji appku). Per-app auto-nav zajišťuje mkdocs-awesome-pages-plugin (§4).

2. Adresářová konvence v app repu¶

<repo>/
  docs/
    user/                    ← PUBLIC, tab „Uživatelská"
      index.md               ← landing (co app dělá pro uživatele)
      .pages                 ← název + pořadí sekce (§4)
      prvni-kroky.md         ← (volitelné) quick-start
      funkce/                ← (volitelné) per-feature deep dive
        <feature>.md
      faq.md                 ← (volitelné) časté dotazy
    dev/                     ← PUBLIC, tab „Programátorská"
      index.md               ← landing (architektura, jak rozšiřovat)
      .pages
      architektura.md        ← (volitelné) datový tok, model
      api.md                 ← (volitelné) endpointy / SDK / konektory
    admin/                   ← PUBLIC, tab „Admin"
      index.md               ← landing (aktivace, provoz)
      .pages
      provoz.md              ← (volitelné) health, monitoring, troubleshooting
      rbac.md                ← (volitelné) role, M2M scopes
  ARCHITECTURE.md            ← INTERNÍ vendor guide (root docs/*.md) — NEPULL
  DEPLOY.md                  ← INTERNÍ — zůstává jen v repu, není public
  ...

Dvě vrstvy dokumentace:

Publikované (docs/{user,dev,admin}/) — pull-sync je vystaví na docs.avaxis.cz. Vše zde je veřejné (žádné secrets — §10).
Interní (docs/*.md v rootu docs/, mimo tři publika) — vendor dev guides, které zůstávají jen v repu / Gitea web UI. Pull-sync je nezachycuje.

Historicky appky psaly dev dokumentaci do docs/*.md v rootu. Nová konvence: to, co má být veřejné pro programátory, patří do docs/dev/ (jde do tabu „Programátorská"). docs/*.md v rootu nech jen pro čistě interní / contractor guides.

3. Mapování repo → portál → URL¶

Pull-sync kopíruje každou složku do své cílové oblasti v platform repu. URL vychází z cesty souboru (use_directory_urls: true), ne z názvu tabu — přeskupení tabů v nav proto NErozbíjí existující odkazy.

App repo	Platform repo (`docs/`)	Publikovaná URL	Tab
`docs/user/`	`user-guide/apps/<slug>/`	`https://docs.avaxis.cz/user-guide/apps/<slug>/`	Uživatelská
`docs/dev/`	`dev/apps/<slug>/`	`https://docs.avaxis.cz/dev/apps/<slug>/`	Programátorská
`docs/admin/`	`admin/apps/<slug>/`	`https://docs.avaxis.cz/admin/apps/<slug>/`	Admin
`docs/*.md` (root)	—	— (nepublikováno)	interní vendor

<slug> = docs_slug aplikace (typicky slug z manifest.json, [a-z0-9-]+).

4. `.pages` soubor — auto-nav bez editace `mkdocs.yml`¶

Portál používá mkdocs-awesome-pages-plugin. Plugin čte soubor .pages v každém adresáři a z něj poskládá levé menu. Díky tomu nová appka nevyžaduje žádnou změnu mkdocs.yml — stačí, že její docs/{user,dev,admin}/ po pull-sync přistanou jako podadresáře a nesou svůj .pages.

4.1 Formát (`title` + pořadí)¶

# .pages — mkdocs-awesome-pages-plugin
# Řídí NÁZEV této app-sekce v levém menu + POŘADÍ jejích stránek.
title: Moje Aplikace        # přepíše auto-title složky (jinak = název adresáře)
nav:                        # explicitní pořadí; '...' = všechno ostatní (auto)
  - index.md                # landing první
  - prvni-kroky.md
  - funkce                  # podadresář (má vlastní .pages)
  - faq.md
  - ...                     # cokoli nového přibude sem automaticky

4.2 Varianta bez explicitního `nav` (jen řazení)¶

Když nechceš vyjmenovávat soubory, nech plugin řadit:

title: Moje Aplikace
order: asc            # asc | desc
order_by: filename    # filename | title

4.3 Užitečné klíče¶

Klíč	Účel
`title:`	Název sekce v nav (per-app = lidský název aplikace).
`nav:`	Explicitní pořadí položek. `...` (tři tečky) = „zbytek, auto".
`order:` / `order_by:`	Řazení, když není `nav:`.
`collapse: true`	Sbalí složku s jediným dítětem do jednoho odkazu.
`hide: true`	Skryje složku z nav (zůstane dostupná přes URL).

4.4 Pravidla (jinak build spadne)¶

Každá položka v nav: musí existovat — plugin je striktní. Nevyjmenovávej soubor/podadresář, který zatím nemáš (přidej ho, až vznikne, nebo ho nech chytit ...).
index.md dej první — s navigation.indexes se stane klikatelnou landing stránkou celé app-sekce.
README.md do nav nedávej — je to vendor-meta (viz docs/user/README.md v šabloně) a platform build ho vylučuje (exclude_docs).

5. `index.md` — landing per publikum¶

Každá ze tří složek musí mít index.md. Je to:

kotva URL app-sekce (/…/apps/<slug>/),
landing v levém menu (díky navigation.indexes),
první dojem pro dané publikum — 2–5 vět „co tady najdeš" + rozcestník.

Minimální kostra (viz EDITME stuby v šablonách):

# <Název aplikace> — <publikum>

Krátký odstavec: co tato appka dělá z pohledu tohoto publika.

## Obsah { #obsah }

- [První kroky](prvni-kroky.md)
- [FAQ](faq.md)

6. Anchory a deep linky `{ #id }`¶

Kontextová ⓘ ikona v UI (launcher i vendor app přes SDK) otevírá přesnou sekci v docs. Aby URL fragment nebyl fragile, MUSÍŠ dávat explicit anchor do každého H2/H3, na který chceš linkovat:

## Přidání záznamu { #add-record }

Klik na „+ Nový"…

### Validace polí { #add-record-validation }

Bez explicit anchoru se auto-anchor odvodí z textu titulku → přejmenuješ titulek → URL se rozbije → ⓘ link 404. Explicit { #id } je stabilní.

Tvar deep-linku podle publika (doc_path pro SDK/registry helper):

Publikum	`doc_path`	Výsledná URL
user	`user-guide/apps/<slug>/<file>#<id>`	`…/user-guide/apps/<slug>/<file>/#<id>`
dev	`dev/apps/<slug>/<file>#<id>`	`…/dev/apps/<slug>/<file>/#<id>`
admin	`admin/apps/<slug>/<file>#<id>`	`…/admin/apps/<slug>/<file>/#<id>`

# vendor app přes SDK
from avaxis_sdk import help_icon
help_icon(row, doc_path="apps/<slug>/funkce/zaznamy#add-record",
          inline_hint="Jak přidat nový záznam")

Detailně: help-deep-links.md.

7. Co kam patří (rozhodovací tabulka)¶

Obsah	user	dev	admin
Co app dělá / k čemu je (uživatelsky)	✅	—	—
První kroky, screenshoty, běžné úlohy	✅	—	—
FAQ koncového uživatele, řešení problémů	✅	—	—
Architektura, datový tok, datový model	—	✅	—
REST endpointy, SDK, konektory, schémata	—	✅	—
Jak appku rozšířit / lokálně buildit / testovat	—	✅	—
Registr ⓘ deep-linků / anchor mapa	—	✅	—
Aktivace / gateway route / enable app	—	—	✅
RBAC role (`required_roles`), M2M scopes	—	—	✅
Health, monitoring, provoz, rollback, zálohy	—	—	✅
Secrets, tokeny, hesla, klíče	❌	❌	❌

Pravidlo palce: user = „umím to používat", dev = „umím to rozšířit / integrovat", admin = „umím to nasadit a provozovat na platformě".

8. Sync mechanismus (pull_vendor_docs)¶

Central skript tools/pull_vendor_docs.py na avaxdev (systemd timer ~15 min) pulluje docs z vendor rep a kopíruje všechny tři flavory do cílových oblastí:

GET /admin/app-management/list        → seznam apps (+ gitea_repo_url, docs_slug)
per app (git clone --depth 1, idempotent přes commit-hash cache):
  docs/user/  → docs/user-guide/apps/<slug>/
  docs/dev/   → docs/dev/apps/<slug>/
  docs/admin/ → docs/admin/apps/<slug>/
auto-commit + push → MkDocs build → live

Vlastnosti:

Idempotent — clone jen když vendor pushl nový commit (.cache/vendor-docs-sync-state.json).
Flavor volitelný — chybí-li docs/dev/ nebo docs/admin/, ta oblast se pro danou app přeskočí (ne chyba).
Anti-dataloss — chybí-li docs/ v repu úplně, cíl se nemaže.
Backward-compat — appka jen s docs/user/ funguje dál (dev/admin prostě nevznikne). Legacy „markdown přímo v docs/" → legacy mode + warning.

Stav skriptu: dnes pull_vendor_docs.py kopíruje jen docs/user/. Rozšíření na dev/+admin/ (stejná smyčka, 3 páry zdroj→cíl) je součástí zavedení této konvence — viz §9. Do té doby appky klidně docs/dev/ a docs/admin/ produkují; propíšou se, jakmile je skript umí.

Podrobně: vendor-docs-sync.md.

9. Platform enablement (zapnout jednou) — stav¶

Tato konvence popisuje cílový stav. Na platform straně (avax-platform repo) je k plnému zapnutí potřeba:

mkdocs-awesome-pages-plugin do build prostředí (.gitea/workflows/docs.yml pip install + lokální venv) a do plugins: v mkdocs.yml.
mkdocs.yml: navigation.expand vypnout (kolaps); taby přejmenovat/ přeskupit na Uživatelská / Programátorská / Admin; per-app větve (user-guide/apps/, dev/apps/, admin/apps/) přenechat awesome-pages (.pages) místo ručního nav:.
docs/dev/apps/ a docs/admin/apps/ složky (cíle pull-syncu) + jejich .pages (title „Aplikace", řazení).
exclude_docs v mkdocs.yml zobecnit z user-guide/apps/*/README.md na */apps/*/README.md (aby vendor-meta README nekolidovalo v žádném flavoru).
tools/pull_vendor_docs.py: smyčka přes 3 páry zdroj→cíl (§8).

Mapování stávajícího obsahu do nových tabů (re-tab přes nav, ne přesun souborů — URL zůstávají):

Dnes	Nový tab
tab „Uživatel" (`user-guide/*`)	Uživatelská
tab „Vývoj" (`context/`, `dev/`, `spec/`, `implementace.md`)	Programátorská
onboarding, apps-gateway, deploy, infrastructure, S3-klíče, RBAC	Admin

Do doby zapnutí pluginu nepřidávej .pages do docs/ platform repu — build v CI běží mkdocs build --strict a bez pluginu by .pages byl jen mrtvý statický soubor. .pages v šablonách (tools/avax-*-template/) jsou mimo docs_dir, takže platform build se jich netýká.

10. Bezpečnost — co NEpublikovat¶

Všechny tři flavory (user/, dev/, admin/) jsou po pull-syncu veřejné na docs.avaxis.cz. Proto nikdy:

API tokeny, M2M client secrets, hesla, S3 access/secret klíče,
connection stringy, interní IP + credentials,
contractor-only / NDA obsah (ten patří do interního docs/*.md v rootu, nebo do privátního repo).

I „admin" flavor je jen návod jak provozovat, ne úložiště secretů.

11. Checklist nové aplikace¶

docs/user/index.md + .pages — nahraď EDITME reálným obsahem.
docs/dev/index.md + .pages — architektura / jak rozšířit.
docs/admin/index.md + .pages — aktivace / provoz.
.pages každé složky: title: = lidský název aplikace, nav: s index.md první + ....
Explicit anchory { #id } u všech H2/H3, na které míří ⓘ deep linky.
Žádné secrets (§10).
git push → do ~15 min na portálu ve třech tabech.

12. Související¶

vendor-docs-sync.md — pull-sync skript, systemd timer, troubleshooting.
help-deep-links.md — ⓘ ikony, help_registry.json, anchor konvence.
../spec/platform-docs.md — docs portál + RAG corpus (source_type).
Šablony: tools/avax-app-template/, tools/avax-legal-app-template/, tools/avax-apm-app-template/ — každá nese docs/{user,dev,admin}/ s EDITME stuby + .pages.