Vývojářský návod
Požadavky na hostitele
Jen Docker s Compose v2 a GNU Make. Python, Node.js ani databázi neinstalujte – vše
(včetně testů, lintu, CRAP a mutačních testů) běží ve vývojových kontejnerech.
Pro make deploy je navíc potřeba git a přihlášené GitHub CLI (gh auth login).
Rychlý start
make setup # .env z .env.example, vývojové obrazy, závislosti
make dev # DB, migrace, API, plánovač, frontend, Mailpit
make admin-create # první majitel (heslo se zadává skrytě)
| Služba | Adresa |
|---|---|
| Aplikace (Vite) | http://localhost:5173 |
| API a OpenAPI | http://localhost:8001/api/docs |
| Mailpit (zachycené e-maily) | http://localhost:8025 |
Dokumentace (make docs) | http://localhost:3000 |
Port API na hostiteli lze změnit proměnnou API_PORT v .env.
Struktura
| Adresář | Obsah |
|---|---|
backend/app | FastAPI: auth (přihlášení, MFA), customers, registry (evidence, lhůty), jobs (zakázky, přílohy, protokol), notifications, projects, exchange (import/export), backup, scheduler, cli |
backend/migrations | Alembic (ručně kontrolované revize) |
backend/tests | jednotkové testy; integration/ s dočasnou DB |
frontend/src | React + TypeScript (PWA rozhraní) |
docs/ | ADR (docs/adr) a stav implementace |
docs-site/ | tato dokumentace (Docusaurus) |
scripts/ | skripty Make sdílené s CI |
Kontroly kvality
make lint # ruff, mypy (strict), ESLint, Prettier, tsc – bez změn souborů
make test # pytest (dočasná DB v tmpfs) + Vitest
make crap # CRAP ≤ 30 (backend i frontend)
make test-mutation # mutační testy kritické logiky, skóre ≥ 80 %
make check # povinné před odevzdáním: lint + test
make build # produkční obraz + kouřový test
make security # pip-audit, npm audit, Trivy (po make build)
Migrace
Nová revize: změňte modely a spusťte
docker compose -p lift-dev run --rm migrate alembic revision --autogenerate -m "popis",
revizi zkontrolujte ručně. Migrace navrhujte dopředně kompatibilní (rollback se neřeší –
oprava novou verzí). Test test_migrations_match_models hlídá shodu modelů a migrací.