Přeskočit obsah

platform-docs — uživatelská dokumentace + RAG corpus

Status: draft Verze spec: 0.1 Aktualizováno: 2026-05-15 Souvisí: ai-rag.md, ai-chat.md, apps-autosync

1. Cíl

Postavit uživatelskou dokumentaci AVAX Platform v MkDocs (Material theme) co:

  1. Slouží jako single source of truth pro koncové uživatele — registrace firmy, instalace launcher2, návody k aplikacím (legal, mzdy, …), FAQ.
  2. Roste s katalogem — nové aplikace dostávají automaticky vlastní sekci (per-app sub-navigace).
  3. Napájí RAG corpus — markdown soubory se chunkují, embeddují a perzistují do ai_documents s source_type='platform_docs' / 'app_docs'. AI asistent (platform-helper, per-app asistenti) má retrieval fallback nad dokumentací → odpovídá s [Source] referencemi.
  4. Sjednocuje stávající dva světy: interní dev specs (docs/spec/*, docs/context/*, …) a user-facing guides (nový obsah). Material theme navigation tabs rozdělí site na dvě top-level sekce.

Co spec NEPOPISUJE: - Pre-existing auto-sync docs/apps/ z admin API (tools/sync_app_docs.py) — funguje, zůstává. - Per-app technický spec (avax-legal pilot) — to je docs/spec/avax-legal.md. - RAG implementace V1+V2 — docs/spec/ai-rag.md shipped. Toto spec přidá source_type rozšíření.

2. Architektura

┌────────────────────────────────────────────────────────────────────┐
│  Autor (Avaxis tým / AI / vendor)                                  │
│  Edituje `docs/user-guide/**/*.md` v repu                          │
└─────────────────────────────────┬──────────────────────────────────┘
                                  │ git push
                                  ▼
┌────────────────────────────────────────────────────────────────────┐
│  Gitea repo `avax-platform/master`                                 │
│  Gitea Actions: workflow `docs.yml` (paths: docs/**, mkdocs.yml)   │
└─────────────────────────────────┬──────────────────────────────────┘
                                  │ act_runner
                                  ▼
┌────────────────────────────────────────────────────────────────────┐
│  Build steps:                                                       │
│  1. `pip install mkdocs-material` + plugins                        │
│  2. `mkdocs build` → `site/` static HTML                           │
│  3. Sync na avaxdev nginx (rsync nebo S3 → mountpoint)             │
│  4. `python tools/sync_docs_corpus.py` → invokuje Celery task      │
│     `ai.sync_docs_corpus`                                          │
└─────────────────────────────────┬──────────────────────────────────┘
                                  │
            ┌─────────────────────┴─────────────────────┐
            ▼                                            ▼
┌──────────────────────────┐              ┌─────────────────────────────┐
│  Hosting                 │              │  RAG corpus (ai_documents)  │
│  Dev: avaxdev nginx      │              │  source_type:               │
│  Prod: docs.avaxis.cz    │              │   - 'platform_docs'         │
│  Static HTML serve       │              │     (top-level user-guide/) │
│  Hybrid auth (nginx      │              │   - 'app_docs' + app_id     │
│  auth_request gate pro   │              │     (apps/<slug>/)          │
│  /advanced/**)           │              │  Globally readable          │
└──────────────────────────┘              └─────────────────────────────┘

3. Struktura docs/

docs/
├── index.md                       Hlavní landing (Co je AVAX)
│
├── user-guide/                    NOVÝ — User-facing dokumentace
│   ├── index.md                   Úvod, struktura návodu
│   ├── zacatecnik/
│   │   ├── index.md
│   │   ├── registrace-firmy.md    [public]
│   │   ├── instalace-launcheru.md [public]
│   │   ├── prvni-prihlaseni.md    [public]
│   │   └── pridani-uzivatelu.md   [auth]
│   ├── launcher/
│   │   ├── index.md
│   │   ├── prehled-rozhrani.md    [public]
│   │   ├── katalog-aplikaci.md    [public]
│   │   ├── chat.md                [auth]
│   │   ├── ai-asistent.md         [auth]
│   │   ├── synchronizace.md       [auth]
│   │   ├── nastaveni.md           [auth]
│   │   └── zalohovani.md          [auth]
│   ├── apps/                      Per-app uživatelské návody
│   │   ├── index.md               Generated (link na všechny apps)
│   │   ├── avax-legal/
│   │   │   ├── index.md
│   │   │   ├── prvni-kroky.md
│   │   │   ├── vyhledavani-zakonu.md
│   │   │   ├── casova-osa.md
│   │   │   ├── ai-vyklad.md
│   │   │   └── faq.md
│   │   └── ...                    (budoucí apps stejnou strukturou)
│   ├── faq.md                     [public] Globální FAQ
│   └── reseni-problemu.md         [public] Troubleshooting
│
├── apps/                          AUTO-SYNC (existing, z admin API)
│   ├── index.md                   Tabulka apps z DB
│   ├── avax-legal-client.md       Per-app metadata (slug, kategorie, ...)
│   └── ...
│
└── (existing dev sections: context/, workflow/, infrastructure/,
   dev/, spec/, implementace.md zustavaji)

3.1 Frontmatter pro auth

Soubory s gated obsahem mají v YAML frontmatter:

---
title: AI asistent v launcheru
auth: required       # public | required
audience: user       # user | admin | vendor
---

auth: required → nginx auth_request redirect na login pokud chybí JWT cookie.

3.2 Per-app sub-section (auto-discovery)

docs/user-guide/apps/<slug>/ — vendor / Avaxis tým napíše ručně. Index page se vygeneruje automaticky:

  • tools/sync_app_docs.py extend — pro každou app v admin API zkontroluje existenci docs/user-guide/apps/<slug>/index.md. Pokud neexistuje, vytvoří stub s placeholder hint-em.
  • mkdocs.yml nav neudržujeme ručně — používáme mkdocs-awesome-nav plugin (auto-generate z directory struktury + .nav.yml override per directory).

4. MkDocs config update

Stávající mkdocs.yml rozšíříme o:

theme:
  features:
    - navigation.tabs           # Top-level tabs (existuje)
    - navigation.tabs.sticky    # Sticky při scroll
    - navigation.path           # Breadcrumb path
    - search.suggest            # Existuje
    - search.highlight          # Existuje

plugins:
  - search:
      lang: [cs, en]            # Existuje
  - awesome-nav                 # NOVÝ — auto-nav z dir struktury

nav:
  - Úvod: index.md

  # Top-level tab "Uživatel"
  - Uživatelská příručka:
      - Začátečník: user-guide/zacatecnik/
      - Práce s launcherem: user-guide/launcher/
      - Aplikace: user-guide/apps/
      - FAQ: user-guide/faq.md
      - Řešení problémů: user-guide/reseni-problemu.md

  # Top-level tab "Vývoj" (existing content)
  - Vývoj:
      - Kontext: context/
      - Workflow: workflow/
      - Infrastruktura: infrastructure/
      - Dev reference: dev/
      - Implementace: implementace.md
      - Specifikace: spec/

  # Top-level tab "Aplikace" (existing auto-sync metadata)
  - Aplikace (metadata): apps/

5. Hosting plan

Fáze 1 (dev) — avaxdev nginx

Static HTML serve z /srv/avax-docs/ (nginx alias). Build na avaxdev lokálně:

cd ~/avax-platform
./.venv/bin/pip install mkdocs-material mkdocs-awesome-nav
./.venv/bin/mkdocs build --site-dir /srv/avax-docs

Nginx config (/etc/nginx/sites-available/avax-docs):

server {
    listen 80;
    server_name docs.avaxdev.local;  # zatim lokalni — pak docs.avaxis.cz

    root /srv/avax-docs;
    index index.html;

    location / {
        try_files $uri $uri/ $uri.html =404;
    }

    location ~ ^/advanced/ {
        auth_request /auth/check;
        error_page 401 = @login_redirect;
        try_files $uri $uri/ $uri.html =404;
    }

    location = /auth/check {
        internal;
        proxy_pass http://127.0.0.1:8000/auth/me;
        proxy_pass_request_body off;
        proxy_set_header Content-Length "";
        proxy_set_header Authorization "Bearer $cookie_avax_token";
    }

    location @login_redirect {
        return 302 https://api.avaxis.cz/login?redirect=$request_uri;
    }
}

Systemd timer pro rebuild při push do master (poll-based):

# /etc/systemd/system/avax-docs-build.timer
[Timer]
OnUnitActiveSec=5min  # check master každých 5 min
Persistent=true

# avax-docs-build.service
ExecStart=/usr/local/bin/avax-docs-rebuild.sh

avax-docs-rebuild.sh: 

cd ~/avax-platform
git pull --ff-only
if [[ $(git rev-parse HEAD) != $(cat /var/lib/avax-docs/last-build) ]]; then
    ./.venv/bin/mkdocs build --site-dir /srv/avax-docs
    git rev-parse HEAD > /var/lib/avax-docs/last-build
    # Trigger RAG sync
    curl -s -X POST http://127.0.0.1:8000/admin/docs/resync \
         -H "Authorization: Bearer $AVAX_SERVICE_TOKEN" || true
fi

Fáze 2 (production) — docs.avaxis.cz

DNS A-record na vm-gateway → nginx vhost → static serve z /srv/avax-docs/. Let's Encrypt SSL certbot.

CI/CD: Gitea Actions workflow .gitea/workflows/docs.yml (paths: docs/**, mkdocs.yml): 1. mkdocs build 2. SSH rsync site/ → vm-gateway /srv/avax-docs/ 3. Trigger RAG resync přes /admin/docs/resync

6. RAG corpus integrace

6.1 Schema rozšíření (migrace 024)

# Migrace 024_ai_docs_corpus.py
op.add_column("ai_documents", sa.Column("source_type", sa.String(50),
                                          nullable=False,
                                          server_default="user_upload"))
op.add_column("ai_documents", sa.Column("source_path", sa.Text(),
                                          nullable=True))
op.add_column("ai_documents", sa.Column("app_id", sa.UUID(as_uuid=True),
                                          sa.ForeignKey("apps.id", ondelete="SET NULL"),
                                          nullable=True))

op.create_check_constraint(
    "ck_ai_documents_source_type", "ai_documents",
    "source_type IN ('user_upload', 'platform_docs', 'app_docs')",
)

op.create_index("ix_ai_documents_source_type", "ai_documents",
                ["source_type"],
                postgresql_where=sa.text("source_type != 'user_upload'"))
op.create_index("ix_ai_documents_app_corpus", "ai_documents",
                ["app_id", "source_type"],
                postgresql_where=sa.text("source_type = 'app_docs'"))
  • source_type — 'user_upload' (V1.5), 'platform_docs' (top-level user-guide), 'app_docs' (per-app guides).
  • source_path — relativní cesta v docs/ (např. user-guide/launcher/ai-asistent.md) — pro deduplikaci při resync.
  • app_id — pro 'app_docs', vazba na konkrétní aplikaci.

6.2 Celery task ai.sync_docs_corpus

@celery_app.task(name="ai.sync_docs_corpus", bind=True)
def sync_docs_corpus_task(self) -> dict:
    """Pulluje markdown z docs/, embed-uje a perzistuje do ai_documents.

    Idempotent — pro každý markdown najde existující doc by source_path,
    porovná hash content, re-index pokud změna. Mazaná docs (source_path
    už není v repu) jsou označená status='archived'.
    """
    ...

Workflow: 1. Iteruj docs/user-guide/**/*.md + docs/apps/**/*.md (NE dev specs) 2. Per soubor: - source_path = relativní cesta - source_type = 'platform_docs' pokud user-guide/launcher/ nebo user-guide/zacatecnik/; 'app_docs' pokud user-guide/apps/<slug>/; ignore apps/ (auto-sync metadata) - app_id = resolve podle slug z directory (apps/avax-legal/) - content_hash = sha256 markdown content - Pokud existující ai_documents row s tímto source_path má stejný hash → skip - Jinak: smaž staré chunks, INSERT/UPDATE row, status='uploaded', send_task ai.index_document 3. Archived: soubory v DB ale ne v repu → status='archived', is_active=false

Frontmatter auth: required → flag metadata={"auth": "required"} — retrieval respektuje (jen pro authed users).

6.3 retrieve_context extension

Stávající scope chain attached → global user. Extend:

1. ai_conversation_documents (per-conv attached docs) — KDYŽ JE
2. Owner per-user uploaded docs (user_upload) — KDYŽ JE
3. App docs (source_type='app_docs', app_id=conversation.app_id) — KDYŽ
   konverzace má app_id (per-app asistent volání z avax-legal apod.)
4. Platform docs (source_type='platform_docs') — vždy fallback

V SQL retrieval query přidat OR filter na source_type + per-conversation app_id resolution:

async def _resolve_doc_ids(conv, user_id, db) -> list[str]:
    """Resolve doc IDs in priority order — vrátí první non-empty list."""
    # 1. attached
    attached = await _attached_docs(conv.id, db)
    if attached:
        return attached, "attached"

    # 2. user uploaded
    uploaded = await _user_docs(user_id, db)
    if uploaded:
        return uploaded, "user_upload"

    # 3. app docs (jen pokud conv má app_id)
    if conv.app_id:
        app_docs = await _app_docs(conv.app_id, db)
        if app_docs:
            return app_docs, "app_docs"

    # 4. platform docs fallback
    platform = await _platform_docs(db)
    return platform, "platform_docs"

6.4 Citation rendering

Sources z platform_docs mají kratší URL preview — UI klient render-uje s odkazem na MkDocs site:

{
  "document_id": "uuid",
  "chunk_index": 3,
  "score": 0.87,
  "source_type": "platform_docs",
  "source_path": "user-guide/launcher/ai-asistent.md",
  "site_url": "https://docs.avaxis.cz/user-guide/launcher/ai-asistent/",
  "preview": "Tlačítko 📎 v AI panelu otevře file picker..."
}

Klik na citation → otevře MkDocs site v browseru.

7. Backend endpoint update

Endpoint Účel
POST /admin/docs/resync Super_admin / service token. Trigger ai.sync_docs_corpus task. Vrátí task_id.
GET /admin/docs/status Last sync time, počty docs per source_type, případně errors.
GET /ai/documents?source_type=platform_docs Filtrované list — public přístup (read-only). User vidí seznam docs co AI může znát.

8. Auth a security

  • Public docs (frontmatter auth: public) — bez restrikce, MkDocs static HTML, nginx serve.
  • Gated docs (auth: required) — nginx auth_request proxy na /auth/me core-api. Vyžaduje JWT cookie avax_token z login flow.
  • Per-firma docs (audience: company_admin) — V2, dnes všichni authed.
  • RAG indexace — všechny docs jsou indexované bez auth gate (corpus globální). Při retrieval respektujeme metadata: pokud metadata.auth == "required" a user nemá session token, chunk skipnout.

9. Acceptance criteria

Phase 1 — site struktura (target 2026-05-22)

  • mkdocs-awesome-nav plugin nainstalovaný v venv + v requirements.txt
  • mkdocs.yml rozšířen o 2-tab navigation (Uživatel / Vývoj)
  • docs/user-guide/index.md — landing page se 4 quick-link kartami
  • docs/user-guide/zacatecnik/ — 4 markdown soubory (registrace, instalace, login, uživatelé)
  • docs/user-guide/launcher/ — 6 markdown souborů s screenshoty
  • docs/user-guide/apps/avax-legal/ — 5 markdown souborů
  • mkdocs serve běží lokálně, navigace funkční

Phase 2 — hosting dev (target 2026-05-25)

  • /srv/avax-docs/ na avaxdev s static build
  • nginx vhost docs.avaxdev.local (lokálně /etc/hosts pro test)
  • systemd timer avax-docs-build.timer poll master každých 5 min
  • tools/avax-docs-rebuild.sh script

Phase 3 — RAG corpus (target 2026-05-28)

  • Migrace 024: ai_documents.source_type + source_path + app_id
  • Celery task ai.sync_docs_corpus — iterace + hash compare + reindex queue
  • POST /admin/docs/resync endpoint
  • retrieve_context priority chain rozšířená o app_docs + platform_docs
  • launcher2 citations: odkaz na docs.avaxis.cz/... u source_type='platform_docs'

Phase 4 — production (target 2026-06-05)

  • DNS docs.avaxis.cz → vm-gateway
  • Let's Encrypt SSL
  • Gitea Actions workflow .gitea/workflows/docs.yml — build + rsync deploy
  • nginx auth_request pro gated docs

10. Otevřené otázky

  • Search v MkDocs vs RAG — Material search je full-text, RAG je semantic. Spolu nebo separátně v UI? Default search → AI button "zeptat se AI" otevře launcher2 chat s pre-fillem dotazu?
  • Per-vendor docs ownership — pokud 3rd-party vendor (qwen-style) má vlastní apps, kdo edituje docs/user-guide/apps/<slug>/? Vendor přes PR do avax-platform repa? Nebo separátní per-app docs repo se sync-em?
  • Versioned docs — pokud launcher2 v0.4 změní UI, staré screenshoty/instrukce zastarají. Mike (mkdocs versioning) nebo jen banner „aktualizováno YYYY-MM-DD"?
  • CMS pro non-dev autora — Avaxis tým co píše návody. MkDocs vyžaduje git push. Alternativa: Decap CMS web-based editor v gated section.
  • Screenshots — kde uložit — docs/user-guide/launcher/images/ nebo S3 app-docs/? S3 šetří git repo size, ale ztratí offline preview v IDE.
  • Multi-jazyk — CZ je primární, EN pro vendory? i18n mkdocs plugin.
  • Embedded video tutoriály — youtube embed v markdown? Vlastní hosting na S3?

11. Timeline

Fáze Status Cíl
Spec draft ✓ done 2026-05-15
Phase 1 — site struktura ⏳ open 2026-05-22
Phase 2 — dev hosting ⏳ open 2026-05-25
Phase 3 — RAG corpus ⏳ open 2026-05-28
Phase 4 — production docs.avaxis.cz ⏳ open 2026-06-05

12. Související