Rychlý start

Požadavky

• Docker a Docker Compose (doporučeno pro lokální vývoj)
• nebo Node.js 20+ a PostgreSQL 16+

Spuštění s Docker Compose

Nejjednodušší způsob — spustí celý stack: PostgreSQL, Zitadel, Login UI, Admin panel a API.

# Klonování repozitáře
git clone <repo-url>
cd atrea-user-api

# Spuštění celého stacku
docker compose up -d

# API je dostupné na
# http://localhost:3001
# Swagger UI: http://localhost:3001/api/docs
# Dokumentace: http://localhost:3001/docs/

Spuštění bez Dockeru

# Instalace závislostí
npm install

# Konfigurace databáze (viz config/default.yaml)
# Potřebujete běžící PostgreSQL na localhost:5432

# Inicializace databáze
psql -U app atrea-user-db < sql/init.sql
psql -U app atrea-user-db < sql/data.sql

# Build TypeScriptu a spuštění
npm run build
npm start

# nebo development mód (watch + nodemon)
npm run dev

Ověření funkčnosti

# Health check
curl http://localhost:3001/api/test

# Verze
curl http://localhost:3001/api/version

# Swagger UI — v prohlížeči
open http://localhost:3001/api/docs

# Dokumentace — v prohlížeči
open http://localhost:3001/docs/

První API volání — ověření oprávnění

Endpointy /check nevyžadují JWT token, pouze optional x-internal-api-key. Volání z backend aplikace:

curl -X POST http://localhost:3001/api/check \
  -H "Content-Type: application/json" \
  -d '{
    "email": "uzivatel@firma.cz",
    "app": "moje-app",
    "permission": "documents.read"
  }'

# Odpověď
{ "success": true, "data": { "allowed": false } }

Zavolání chráněného endpointu

Pro endpointy vyžadující JWT token (např. /profile/me) potřebujete Bearer token od jednoho z podporovaných providerů:

curl http://localhost:3001/api/profile/me \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5..."

Skripty

Skript	Popis
npm run dev	Vývojový mód (TypeScript watch + nodemon)
npm run build	Build TypeScriptu do dist/
npm start	Build + spuštění produkčního serveru
npm run lint	ESLint kontrola
npm run lint:fix	ESLint autofix
npm run docs:dev	VitePress dev server pro dokumentaci
npm run docs:build	Build dokumentace do docs/.vitepress/dist/
npm run docs:preview	Preview buildu dokumentace

Struktura projektu

atrea-user-api/
├── src/
│   ├── index.ts              # Inicializace Express aplikace
│   ├── middleware/           # JWT verifikace, autorizace
│   ├── routes/               # API endpointy (14 routerů)
│   ├── services/             # Business logika (18 servisů)
│   ├── entities/             # TypeORM entity (17 tabulek)
│   └── utils/                # Pomocné třídy (ApiResponse, logger, ...)
├── config/
│   ├── default.yaml          # Výchozí konfigurace (dev)
│   ├── production.yaml       # Produkční přepisy
│   └── test.yaml             # Test prostředí
├── sql/
│   ├── init.sql              # DDL — vytvoření tabulek
│   ├── data.sql              # Seed data (brands)
│   └── drop.sql              # Smazání tabulek
├── docs/                     # Tato dokumentace (VitePress)
├── docker-compose.yml        # Lokální vývoj
├── docker-compose.production.yml  # Produkce
└── Dockerfile                # Node 20 Alpine build

Prostředí

Aplikace používá balíček config s YAML soubory v config/. Přepínání pomocí proměnné NODE_ENV:

NODE_ENV=production npm start   # načte config/production.yaml
NODE_ENV=test npm start         # načte config/test.yaml
# default → config/default.yaml

Viz Konfigurace pro kompletní seznam nastavení.