576 lines
22 KiB
Markdown
576 lines
22 KiB
Markdown
# Refaktoring AI Data Analyst — Finální plán
|
|
|
|
## Kontext
|
|
|
|
Platforma vznikla iterativně pro interní Keboola a nyní se má stát produktem pro zákazníky (Groupon aj.). Klíčové problémy z transcriptu ZS+Padák: křehký filesystem stav (JSON soubory, permission konflikty), žádné API (vše SSH+skripty), bezpečnost přes Linux skupiny, složitá instalace (10+ kroků). Systém je navržen pro AI agenty — člověk diskutuje s AI, AI řeší vše (user, admin, dev operace).
|
|
|
|
**UX zůstává stejné.** Tooling: `uv` všude místo pip. Docker + Kamal pro server. CLI (`da`) jako primární rozhraní pro AI agenty.
|
|
|
|
---
|
|
|
|
## Architektura — cílový stav
|
|
|
|
```
|
|
SERVER (Docker + Kamal):
|
|
├── webapp Flask UI (katalog, login, corporate memory)
|
|
├── api FastAPI (CLI backend, sync manifest, data download)
|
|
├── scheduler APScheduler (nahrazuje 7 systemd timerů)
|
|
├── telegram-bot Telegram notifikace
|
|
├── ws-gateway WebSocket pro desktop app
|
|
└── script-runner Sandboxovaný runner pro user skripty
|
|
|
|
LOKÁLNĚ (analytik):
|
|
├── da CLI Python balíček (uv tool install)
|
|
├── DuckDB Embedded (analytics.duckdb → views na parquety)
|
|
└── Parquety Stažené ze serveru přes da sync
|
|
|
|
DVA DuckDB NA SERVERU:
|
|
├── /data/state/system.duckdb Systémový stav (users, sync_state, knowledge...)
|
|
└── /data/analytics/server.duckdb Views → /data/parquet/** (profiler, remote query, skripty)
|
|
|
|
JEDEN DuckDB LOKÁLNĚ:
|
|
└── user/duckdb/analytics.duckdb Views → server/parquet/** + user tabulky
|
|
```
|
|
|
|
---
|
|
|
|
## Fáze 0: Základ — DuckDB state + repository vrstva
|
|
|
|
**Cíl:** Nahradit 10+ JSON souborů DuckDB databází. Eliminovat #1 zdroj outages (file permission konflikty).
|
|
|
|
**Proč DuckDB:** Už v stacku, agent může joinovat stav s analytickými daty, lepší než SQLite pro analytické dotazy nad stavem.
|
|
|
|
### Task 0A: DuckDB schema + repository vrstva [INDEPENDENT]
|
|
|
|
Nové soubory:
|
|
- `src/db.py` — DuckDB connection management, schema creation, migration system
|
|
- `src/repositories/__init__.py`
|
|
- `src/repositories/sync_state.py` — CRUD pro sync stav
|
|
- `src/repositories/users.py` — CRUD pro uživatele + role
|
|
- `src/repositories/knowledge.py` — CRUD pro corporate memory
|
|
- `src/repositories/table_registry.py` — CRUD pro registr tabulek
|
|
- `src/repositories/audit.py` — audit log
|
|
- `src/repositories/notifications.py` — telegram links, pending codes, script registry
|
|
|
|
Schema tabulky (mapování z JSON):
|
|
|
|
| Současný JSON | DuckDB tabulka | Zdroj soubor |
|
|
|---|---|---|
|
|
| `sync_state.json` | `sync_state` | `src/data_sync.py:37-138` |
|
|
| `sync_settings.json` | `user_sync_settings` | `webapp/sync_settings_service.py:20` |
|
|
| `knowledge.json` | `knowledge_items` | `webapp/corporate_memory_service.py` |
|
|
| `votes.json` | `knowledge_votes` | `webapp/corporate_memory_service.py` |
|
|
| `audit.jsonl` | `audit_log` | `webapp/corporate_memory_service.py` |
|
|
| `telegram_users.json` | `telegram_links` | `services/telegram_bot/storage.py` |
|
|
| `pending_codes.json` | `pending_codes` | `services/telegram_bot/storage.py` |
|
|
| `password_users.json` | `users` | `webapp/password_auth.py` |
|
|
| `table_registry.json` | `table_registry` | `src/table_registry.py` |
|
|
| `profiles.json` | `table_profiles` | `src/profiler.py` |
|
|
|
|
Přidat navíc: `sync_history` (posledních 10 syncí per tabulka, ne jen last), `script_registry` (deployed skripty).
|
|
|
|
### Task 0B: Migrace existujících service souborů na repository [DEPENDS ON 0A]
|
|
|
|
Soubory k úpravě (nahradit `_read_json`/`_write_json` za repository volání):
|
|
- `webapp/sync_settings_service.py` řádky 40-62
|
|
- `webapp/corporate_memory_service.py` — 31 JSON operací
|
|
- `webapp/telegram_service.py` řádky 22-45
|
|
- `src/data_sync.py` — třída `SyncState` řádky 37-138
|
|
- `src/table_registry.py` — `_load`, `_atomic_write_json`
|
|
- `src/profiler.py` — uložení profilů
|
|
- `services/corporate_memory/collector.py` — čtení/zápis knowledge
|
|
- `services/telegram_bot/storage.py` — 15 JSON operací
|
|
|
|
Pattern: dual-write (JSON + DuckDB) po přechodnou dobu → ověřit → smazat JSON zápisy.
|
|
|
|
### Task 0C: Migrační skript [DEPENDS ON 0A]
|
|
|
|
- `scripts/migrate_json_to_duckdb.py` — načte všechny JSON, vloží do DuckDB
|
|
- Idempotentní (safe to run multiple times)
|
|
- Validace po migraci (count porovnání)
|
|
|
|
### Co se NEMĚNÍ v Fázi 0
|
|
- Flask routes v `webapp/app.py`
|
|
- HTML šablony
|
|
- Konektory (`connectors/keboola/`, `connectors/bigquery/`, `connectors/jira/`)
|
|
- `src/config.py` (čte `data_description.md` — konfigurace, ne stav)
|
|
- `config/loader.py` (čte `instance.yaml`)
|
|
- `src/parquet_manager.py`
|
|
|
|
---
|
|
|
|
## Fáze 1: API vrstva (FastAPI)
|
|
|
|
**Cíl:** REST API pro CLI. Všechny operace co dnes vyžadují SSH.
|
|
|
|
### Task 1A: FastAPI základ + auth [INDEPENDENT od 0B, DEPENDS ON 0A]
|
|
|
|
Nové soubory:
|
|
```
|
|
api/
|
|
__init__.py
|
|
app.py # FastAPI app, middleware, CORS
|
|
auth.py # JWT vydávání + validace
|
|
dependencies.py # DI pro DuckDB session, current_user
|
|
```
|
|
|
|
Auth flow:
|
|
1. `POST /api/auth/login` — přijme OAuth token z webappu, vydá JWT
|
|
2. `POST /api/auth/token` — přijme API key, vydá JWT
|
|
3. JWT obsahuje: user_id, email, role, expiry
|
|
4. Middleware validuje JWT na všech /api/* endpoints
|
|
|
|
### Task 1B: Sync + Data endpointy [DEPENDS ON 1A, 0A]
|
|
|
|
```
|
|
api/routers/
|
|
sync.py # GET /api/sync/manifest, POST /api/sync/trigger
|
|
data.py # GET /api/data/{table}/download (parquet stream)
|
|
```
|
|
|
|
- `/api/sync/manifest` — vrátí hashe všech parquetů, docs, rules, profilů (filtrované per-user dle subscription)
|
|
- `/api/data/{table}/download` — streaming parquet souboru s ETag/If-None-Match
|
|
- `/api/sync/trigger` — spustí DataSyncManager (reuse `src/data_sync.py`)
|
|
|
|
### Task 1C: Query + Scripts endpointy [DEPENDS ON 1A, 0A]
|
|
|
|
```
|
|
api/routers/
|
|
query.py # POST /api/query (remote query)
|
|
scripts.py # POST /api/scripts/run, /deploy, /list
|
|
```
|
|
|
|
- `/api/query` — reuse `src/remote_query.py`, výsledek jako JSON/parquet
|
|
- `/api/scripts/run` — spustí Python skript v sandboxu na serveru
|
|
- `/api/scripts/deploy` — nahraje skript + registruje v scheduleru
|
|
- `/api/scripts/list` — deployed skripty s jejich schedules
|
|
|
|
### Task 1D: User management + Corporate memory endpointy [DEPENDS ON 1A, 0A]
|
|
|
|
```
|
|
api/routers/
|
|
users.py # CRUD uživatelů, role, permissions
|
|
settings.py # GET/PUT sync settings per user
|
|
memory.py # Corporate memory CRUD, voting, governance
|
|
health.py # GET /api/health (strukturovaná diagnostika)
|
|
upload.py # POST sessions, artifacts, CLAUDE.local.md
|
|
```
|
|
|
|
### Task 1E: Odstranění SSH/sudo závislostí [DEPENDS ON 1B, 1D]
|
|
|
|
Smazat/přepsat:
|
|
- `webapp/sync_settings_service.py` řádky 128-240 (sudo/rsync-filter kód)
|
|
- `webapp/user_service.py` — Linux user management (`pwd.getpwnam`, `sudo add-analyst`)
|
|
- SSH key validace workflow
|
|
- `server/sudoers-webapp`, `server/sudoers-deploy`
|
|
- `server/bin/add-analyst`
|
|
|
|
---
|
|
|
|
## Fáze 2: CLI nástroj (`da`)
|
|
|
|
**Cíl:** Jediné rozhraní pro AI agenty. Nahrazuje SSH+skripty. `uv tool install`.
|
|
|
|
### Task 2A: CLI základ + auth [INDEPENDENT od 1B-1E, DEPENDS ON 1A]
|
|
|
|
```
|
|
cli/
|
|
__init__.py
|
|
main.py # Typer app, global options (--server, --json)
|
|
config.py # ~/.config/da/ management
|
|
client.py # HTTP client wrapper (auth, retry, streaming)
|
|
commands/
|
|
auth.py # da login, da logout, da whoami
|
|
```
|
|
|
|
- `da login` → otevře browser pro OAuth → server vydá JWT → uloží do `~/.config/da/token.json`
|
|
- `da --json` flag na všech příkazech pro strukturovaný output
|
|
- `da --server URL` override (default z config.yaml)
|
|
|
|
### Task 2B: Sync příkazy [DEPENDS ON 2A, 1B]
|
|
|
|
```
|
|
cli/commands/
|
|
sync.py # da sync, da sync --table X, da sync --upload-only
|
|
```
|
|
|
|
Flow:
|
|
1. `GET /api/sync/manifest` → porovnej s `~/.config/da/sync_state.json`
|
|
2. Download změněné parquety (HTTP streaming s progress barem)
|
|
3. Download docs, rules, profily
|
|
4. Upload sessions, artifacts, CLAUDE.local.md
|
|
5. Rebuild DuckDB views (DROP views, CREATE VIEW per tabulka, zachovej user tabulky)
|
|
6. Update lokální manifest
|
|
|
|
Přepíše funkci `scripts/sync_data.sh` (475 řádků).
|
|
|
|
### Task 2C: Query + Scripts příkazy [DEPENDS ON 2A, 1C]
|
|
|
|
```
|
|
cli/commands/
|
|
query.py # da query "SQL" [--remote] [--json]
|
|
scripts.py # da scripts list/run/deploy/undeploy
|
|
explore.py # da explore {table} — profil tabulky
|
|
```
|
|
|
|
- `da query` — lokální DuckDB default, `--remote` přes server API
|
|
- `da scripts run X` — lokálně default, `--remote` přes server
|
|
- `da scripts deploy X --schedule "cron"` — upload + registrace na serveru
|
|
- `da explore orders` — profil z lokálních dat (nebo `--remote` ze serveru)
|
|
|
|
### Task 2D: Admin + Server příkazy [DEPENDS ON 2A, 1D]
|
|
|
|
```
|
|
cli/commands/
|
|
admin.py # da admin add-user/remove-user/list-users
|
|
status.py # da status [--local] — zdraví systému
|
|
server.py # da server deploy/rollback/logs/status
|
|
diagnose.py # da diagnose — AI-friendly diagnostika
|
|
```
|
|
|
|
- `da status` — strukturovaný health report (tabulky, sync stav, služby)
|
|
- `da status --local` — offline: kdy jsem synkoval, kolik dat mám
|
|
- `da diagnose` — projde logy, sync stav, konektivitu → root cause
|
|
- `da server deploy` — wrapper kolem `kamal deploy`
|
|
- `da server logs webapp` — wrapper kolem `kamal app logs`
|
|
|
|
### Task 2E: PyPI distribuce [DEPENDS ON 2A]
|
|
|
|
- `pyproject.toml` pro CLI balíček
|
|
- `uv tool install data-analyst` nebo `uv pip install data-analyst`
|
|
- Entry point: `[project.scripts] da = "cli.main:app"`
|
|
- Minimální dependencies: typer, httpx, duckdb, rich (progress bars)
|
|
|
|
---
|
|
|
|
## Fáze 3: Docker + Kamal
|
|
|
|
**Cíl:** `docker compose up` pro dev, `kamal deploy` pro produkci. Nahrazuje 10+ manuálních kroků.
|
|
|
|
### Task 3A: Dockerfile + docker-compose.yml [INDEPENDENT]
|
|
|
|
```
|
|
Dockerfile # python:3.13-slim, uv install, jeden image
|
|
docker-compose.yml # webapp, api, scheduler, telegram-bot, ws-gateway
|
|
docker-compose.test.yml # api + test-runner pro integrační testy
|
|
```
|
|
|
|
- Jeden image, různý CMD per služba
|
|
- Volume `/data` sdílený mezi kontejnery
|
|
- `profiles: ["full"]` pro volitelné služby (telegram, ws-gateway)
|
|
- `uv sync` místo `pip install` v Dockerfile
|
|
|
|
### Task 3B: Scheduler služba [DEPENDS ON 0A]
|
|
|
|
Nový soubor: `services/scheduler/__main__.py`
|
|
- APScheduler (nebo jednoduchý custom) nahrazuje 7 systemd timerů:
|
|
|
|
| Timer | Schedule | Funkce |
|
|
|---|---|---|
|
|
| data-refresh | 15 min | `DataSyncManager.sync_scheduled()` |
|
|
| catalog-refresh | 15 min | Catalog refresh |
|
|
| corporate-memory | 30 min | Knowledge collector |
|
|
| session-collector | 6h | Session collection (z uploaded dat) |
|
|
| user-scripts | per-script cron | Script runner |
|
|
| profiler | po data-refresh | Auto-profile nových dat |
|
|
|
|
### Task 3C: Kamal konfigurace [DEPENDS ON 3A]
|
|
|
|
```
|
|
config/
|
|
deploy.yml # produkční Kamal config
|
|
deploy.staging.yml # staging override
|
|
```
|
|
|
|
- Kamal Proxy pro auto-SSL (Let's Encrypt)
|
|
- Healthcheck na `/api/health`
|
|
- Zero-downtime deploy
|
|
- Accessories: scheduler, telegram-bot, ws-gateway, script-runner
|
|
- Environment secrets přes Kamal env management
|
|
|
|
### Task 3D: GitHub Actions CI/CD [DEPENDS ON 3A, 3C]
|
|
|
|
```
|
|
.github/workflows/
|
|
ci.yml # test + build na každém push
|
|
deploy.yml # staging na PR, production na merge do main
|
|
```
|
|
|
|
Flow: push → pytest → integrační testy (docker compose) → build image → push GHCR → kamal deploy staging (PR) / production (merge)
|
|
|
|
### Task 3E: Smazání starého server infra [DEPENDS ON 3A-3D, ověřeno že nové funguje]
|
|
|
|
Smazat:
|
|
- `server/setup.sh` (103 řádků)
|
|
- `server/webapp-setup.sh` (171 řádků)
|
|
- `server/deploy.sh` (395 řádků)
|
|
- `server/migrate-to-v2.sh` (146 řádků)
|
|
- Všechny systemd unit soubory (`services/*/systemd/`)
|
|
- `server/sudoers-*`
|
|
- `server/bin/add-analyst` a related skripty
|
|
- `scripts/sync_data.sh` (475 řádků)
|
|
- `server/webapp.service`, `server/webapp-nginx.conf`
|
|
|
|
---
|
|
|
|
## Fáze 4: RBAC + bezpečnost
|
|
|
|
**Cíl:** Aplikační RBAC místo Linux skupin. Audit trail. Script sandboxing.
|
|
|
|
### Task 4A: Role + permissions v DuckDB [DEPENDS ON 0A]
|
|
|
|
Nový soubor: `src/rbac.py`
|
|
|
|
```python
|
|
class Role(Enum):
|
|
VIEWER = "viewer" # Katalog, čtení dat
|
|
ANALYST = "analyst" # Sync, queries, voting, skripty
|
|
ADMIN = "admin" # Správa uživatelů, schvalování knowledge
|
|
KM_ADMIN = "km_admin" # Corporate memory governance
|
|
```
|
|
|
|
- Dataset-level permissions (kdo má přístup ke kterým datům)
|
|
- Přepsat `webapp/auth.py` řádky 37-65 (admin_required/km_admin_required)
|
|
- Přepsat `webapp/user_service.py` celý — DB místo `pwd.getpwnam()` + `sudo`
|
|
|
|
### Task 4B: Audit trail [DEPENDS ON 0A]
|
|
|
|
- Každý API call logován do `audit_log` tabulky
|
|
- Struktura: timestamp, user_id, action, resource, params, result, duration
|
|
- Agent může: `da query "SELECT * FROM system.audit_log WHERE action='sync_trigger' ORDER BY timestamp DESC LIMIT 10"`
|
|
|
|
### Task 4C: Script sandboxing [DEPENDS ON 3A]
|
|
|
|
- Script-runner jako izolovaný Docker kontejner
|
|
- Read-only přístup k DuckDB
|
|
- Omezená paměť (512MB), čas (5min), žádný network (kromě notification dispatch)
|
|
- Explicitní whitelist Python balíčků (pandas, duckdb, matplotlib)
|
|
|
|
### Task 4D: Corporate memory push model [DEPENDS ON 1D]
|
|
|
|
- Uživatelé pushují CLAUDE.local.md přes `da sync --upload-only`
|
|
- Server nikdy nečte `/home/*/` jako root
|
|
- Corporate memory collector zpracovává uploaded data z DB
|
|
|
|
---
|
|
|
|
## Dependency graf pro multi-agenty
|
|
|
|
```
|
|
Fáze 0:
|
|
0A (DuckDB schema) ─────────────────────┐
|
|
0C (migrační skript) ← závisí na 0A │
|
|
0B (migrace services) ← závisí na 0A │
|
|
│
|
|
Fáze 1: │
|
|
1A (FastAPI základ) ← závisí na 0A ─────┤
|
|
1B (sync/data EP) ← závisí na 1A, 0A │
|
|
1C (query/scripts EP) ← závisí na 1A │
|
|
1D (users/memory EP) ← závisí na 1A │
|
|
1E (remove SSH) ← závisí na 1B, 1D │
|
|
│
|
|
Fáze 2: │
|
|
2A (CLI základ) ← závisí na 1A │
|
|
2B (sync cmd) ← závisí na 2A, 1B │
|
|
2C (query/scripts cmd) ← závisí na 2A │
|
|
2D (admin/server cmd) ← závisí na 2A │
|
|
2E (PyPI) ← závisí na 2A │
|
|
│
|
|
Fáze 3: │
|
|
3A (Dockerfile) ← INDEPENDENT ──────────┘
|
|
3B (scheduler) ← závisí na 0A
|
|
3C (Kamal) ← závisí na 3A
|
|
3D (CI/CD) ← závisí na 3A, 3C
|
|
3E (cleanup) ← závisí na 3A-3D verified
|
|
|
|
Fáze 4:
|
|
4A (RBAC) ← závisí na 0A
|
|
4B (audit) ← závisí na 0A
|
|
4C (sandbox) ← závisí na 3A
|
|
4D (push model) ← závisí na 1D
|
|
```
|
|
|
|
### Paralelní agenty — optimální rozložení
|
|
|
|
```
|
|
AGENT 1: DuckDB + Repositories AGENT 2: FastAPI AGENT 3: Docker + Kamal
|
|
───────────────────────────── ───────────────── ──────────────────────
|
|
0A: DuckDB schema (čeká na 0A) 3A: Dockerfile + compose
|
|
0C: migrační skript 1A: FastAPI základ 3B: scheduler služba
|
|
0B: migrace services 1B: sync/data EP 3C: Kamal konfigurace
|
|
4A: RBAC 1C: query/scripts EP 3D: CI/CD workflow
|
|
4B: audit trail 1D: users/memory EP 4C: script sandbox
|
|
1E: remove SSH deps
|
|
|
|
AGENT 4: CLI + Skills AGENT 5: Integrace + Cleanup
|
|
───────────────────── ───────────────────────────
|
|
(čeká na 1A) (čeká na agents 1-4)
|
|
2A: CLI základ + auth End-to-end testování
|
|
2B: sync příkazy 3E: smazání starého infra
|
|
2C: query/scripts příkazy 4D: corporate memory push
|
|
2D: admin/server příkazy 5A: CLAUDE.md template update
|
|
2E: PyPI distribuce Dokumentace update
|
|
5B: CLI skills (help/docs)
|
|
5C: da setup (interactive)
|
|
5D: da diagnose
|
|
5E: da infra (multi-customer)
|
|
```
|
|
|
|
---
|
|
|
|
## Znovupoužité vs. přepsané soubory
|
|
|
|
### Beze změny (business logika zachována)
|
|
- `src/config.py` — TableConfig, Config parsing (625 řádků)
|
|
- `src/parquet_manager.py` — Parquet conversion engine
|
|
- `connectors/keboola/adapter.py` + `client.py`
|
|
- `connectors/bigquery/adapter.py` + `client.py`
|
|
- `connectors/jira/` — celý connector
|
|
- `connectors/llm/` — LLM abstrakce
|
|
- `connectors/openmetadata/` — katalog enrichment
|
|
- `webapp/config.py`, `config/loader.py`
|
|
- `webapp/templates/` — všechny HTML šablony
|
|
- `src/remote_query.py` — query logika (zabalená API)
|
|
- `src/profiler.py` — profiling logika (output do DuckDB)
|
|
|
|
### Přepojené na DuckDB (logika zachována, I/O vrstva vyměněna)
|
|
- `webapp/corporate_memory_service.py`
|
|
- `webapp/sync_settings_service.py`
|
|
- `webapp/telegram_service.py`
|
|
- `src/data_sync.py` (SyncState třída)
|
|
- `src/table_registry.py`
|
|
- `services/corporate_memory/collector.py`
|
|
- `services/telegram_bot/storage.py`
|
|
|
|
### Přepsané
|
|
- `webapp/user_service.py` — DB místo Linux users
|
|
- `webapp/auth.py` řádky 37-65 — RBAC místo Linux skupin
|
|
|
|
### Nové
|
|
- `src/db.py`, `src/repositories/`, `src/rbac.py`
|
|
- `api/` — celý FastAPI server
|
|
- `cli/` — celý CLI nástroj
|
|
- `Dockerfile`, `docker-compose*.yml`, `config/deploy*.yml`
|
|
- `services/scheduler/__main__.py`
|
|
- `.github/workflows/ci.yml`, `.github/workflows/deploy.yml`
|
|
|
|
### Smazané
|
|
- `server/setup.sh`, `server/webapp-setup.sh`, `server/deploy.sh`
|
|
- `server/migrate-to-v2.sh`
|
|
- `server/sudoers-*`, `server/bin/add-analyst`
|
|
- `scripts/sync_data.sh`
|
|
- Všechny `services/*/systemd/` soubory
|
|
- `server/webapp.service`, `server/webapp-nginx.conf`
|
|
|
|
---
|
|
|
|
## Fáze 5: Agent Skills (CLAUDE.md + CLI skills)
|
|
|
|
**Cíl:** AI agent má vestavěné znalosti pro nasazení, administraci, diagnostiku a vývoj. Nemusí nic googlit — vše je v skills.
|
|
|
|
### Task 5A: CLAUDE.md template pro analytiky [INDEPENDENT]
|
|
|
|
Aktualizovat `docs/setup/claude_md_template.md`:
|
|
- Instrukce pro `da` CLI místo SSH/rsync
|
|
- `da sync` jako povinný start session
|
|
- Jak pracovat s lokálním DuckDB
|
|
- Jak vytvářet a deployovat skripty
|
|
- Jak používat corporate memory
|
|
- Notifikační vzory (lokální vs serverové)
|
|
|
|
### Task 5B: Admin/Deploy skills v CLI [DEPENDS ON 2D]
|
|
|
|
`da` CLI bude obsahovat vestavěné skills — dlouhé help texty s domain knowledge, které AI agent přečte přes `da <command> --help` nebo `da skills <topic>`:
|
|
|
|
```bash
|
|
da skills list # seznam všech dostupných skills
|
|
da skills setup # kompletní průvodce setup nové instance
|
|
da skills troubleshoot # diagnostické postupy
|
|
da skills connectors # jak přidat nový data source
|
|
da skills notifications # jak fungují notifikace
|
|
da skills corporate-memory # governance, approval flow
|
|
da skills security # RBAC, permissions, audit
|
|
da skills backup-restore # disaster recovery
|
|
da skills upgrade # jak upgradovat verzi
|
|
```
|
|
|
|
Každý skill = markdown soubor v `cli/skills/` který se zobrazí přes `da skills <name>`.
|
|
|
|
### Task 5C: Interaktivní setup skill [DEPENDS ON 2D, 1A]
|
|
|
|
```bash
|
|
da setup # AI agent spustí interaktivní setup
|
|
```
|
|
|
|
Flow (agent řídí):
|
|
1. `da setup init` → vygeneruje `instance.yaml` z konverzace s uživatelem
|
|
2. `da setup test-connection` → ověří credentials (Keboola/BigQuery)
|
|
3. `da setup deploy` → `docker compose up` nebo `kamal deploy`
|
|
4. `da setup first-sync` → triggeruje první data sync
|
|
5. `da setup verify` → healthcheck, počet tabulek, sample query
|
|
6. `da setup add-user` → přidá prvního analytika
|
|
|
|
Každý krok vrací strukturovaný JSON → agent ví co dělat dál.
|
|
|
|
### Task 5D: Diagnose skill [DEPENDS ON 2D, 1D]
|
|
|
|
```bash
|
|
da diagnose # kompletní diagnostika
|
|
da diagnose --symptom "data not updating" # cílená diagnostika
|
|
da diagnose --component scheduler # diagnostika jedné služby
|
|
```
|
|
|
|
Output (strukturovaný pro agenta):
|
|
```json
|
|
{
|
|
"overall": "degraded",
|
|
"checks": [
|
|
{"name": "api", "status": "ok", "latency_ms": 12},
|
|
{"name": "scheduler", "status": "ok", "last_run": "2026-03-27T08:00"},
|
|
{"name": "data_freshness", "status": "warning",
|
|
"detail": "table 'orders' last synced 26h ago, expected 15min",
|
|
"suggested_action": "da server logs scheduler | grep orders"},
|
|
{"name": "disk", "status": "ok", "usage": "45%"},
|
|
{"name": "duckdb", "status": "ok", "tables": 47, "total_rows": "12.3M"}
|
|
],
|
|
"suggested_actions": [
|
|
"Check scheduler logs for 'orders' sync failures",
|
|
"Run: da server logs scheduler --since 24h | grep -i error"
|
|
]
|
|
}
|
|
```
|
|
|
|
### Task 5E: Operační skills pro multi-customer [DEPENDS ON 3C]
|
|
|
|
```bash
|
|
da infra list # seznam zákaznických instancí
|
|
da infra provision --customer acme --cloud gcp --region europe-west1
|
|
da infra status acme # zdraví zákaznické instance
|
|
da infra deploy acme # deploy na zákaznický server
|
|
da infra backup acme # snapshot dat
|
|
```
|
|
|
|
Budoucí rozšíření — Terraform pod kapotou pro provision, Kamal pro deploy.
|
|
|
|
---
|
|
|
|
## Verifikace
|
|
|
|
### Per-fáze
|
|
1. **Fáze 0:** `pytest tests/` zelený, webapp funguje identicky s DuckDB backendem
|
|
2. **Fáze 1:** `curl /api/health` → ok, `curl /api/sync/manifest` → manifest, parquet download funguje
|
|
3. **Fáze 2:** `da login && da sync` vytvoří identickou strukturu jako `sync_data.sh`, `da query` funguje offline
|
|
4. **Fáze 3:** `docker compose up` → všechny služby běží, `kamal deploy -d staging` → staging funguje
|
|
5. **Fáze 4:** viewer nemůže triggerovat sync, admin může spravovat uživatele, skripty běží v sandboxu
|
|
|
|
### End-to-end test (celý flow)
|
|
1. `docker compose up -d` (nebo `kamal deploy`)
|
|
2. Přes webapp: přihlásit se, vybrat datasety
|
|
3. `da login && da sync` → parquety lokálně
|
|
4. `da query "SELECT count(*) FROM orders"` → výsledek offline
|
|
5. `da scripts run sales_alert` → lokální exekuce
|
|
6. `da scripts deploy sales_alert --schedule "0 8 * * MON"` → serverová exekuce
|
|
7. `da sync --upload-only` → sessions/artifacts na serveru
|
|
8. Corporate memory: knowledge items viditelné ve webappu
|
|
9. Telegram notifikace doručeny
|
|
10. `da diagnose` → strukturovaný health report
|