crm-server/README.md

# CRM Server – Architektúra a flow

Tento dokument popisuje, ako backend funguje: aká je štruktúra kódu, akou cestou prechádza požiadavka, aké služby spolu komunikujú a kde sa riešia bezpečnostné a chybové scenáre. Všetky cesty v kóde sú písané v ES modules.

## Základný stack
- **Express 4** (ESM) + **Drizzle ORM** (PostgreSQL)
- **JWT** pre prístupové/refresh tokeny (httpOnly cookies), **bcrypt** pre heslá
- **Zod** na validačné schémy, **helmet**, **cors**, **express-rate-limit**
- **JMAP** integrácia pre e-maily (Truemail) + AES-256-GCM šifrovanie hesiel k e-mail účtom

## Štruktúra priečinkov (hlavné časti)
- `src/app.js` – skladá middleware pipeline a mountuje routes, pridáva notFound/error handler.
- `src/index.js` – spúšťací bod servera.
- `src/routes/` – deklarácie endpointov (1 súbor = 1 doména). Všetky používajú middlewares + volajú controller.
- `src/controllers/` – spracovanie requestu, volanie service vrstvy, odoslanie odpovedí. Chyby posielajú cez `next(err)`.
- `src/services/` – biznis logika a práca s DB/JMAP (bez Express závislosti).
- `src/middlewares/` – auth (JWT + role), security (rate limiting, Zod validateInput), global (validateBody pattern check, 404, error handler).
- `src/utils/` – `errors.js` (AppError a formátovanie), `jwt.js`, `password.js`, `logger.js`.
- `src/validators/` – Zod schémy pre vstupy.
- `src/db/` – Drizzle schéma a config.

## Životný cyklus požiadavky (pipeline)
1) **Logovanie**: `morgan('dev')` (len stdout).
2) **Bezpečnostné hlavičky**: `helmet` s CSP (self + inline styles) a HSTS (preload, subdomains).
3) **CORS**: povolený pôvod z `CORS_ORIGIN` (default `http://localhost:5173`), credentials povolené.
4) **Body parsers**: `express.json` a `express.urlencoded` (limit 10 MB), `cookieParser` pre JWT v cookies.
5) **Global validateBody**: rýchly regex-detektor podozrivých payloadov (loguje a vráti 400 pri matches).
6) **Rate limiting**: `apiRateLimiter` na `/api/*` (100 req/15 min v production, 1000 v dev). Špecifické limitery na login a citlivé operácie sa aplikujú v routes.
7) **Routes**: `auth`, `admin`, `contacts`, `emails` (CRM), `email-accounts`, `timesheets`, `companies`, `projects`, `todos`, `time-tracking`, `notes`.
8) **404**: `notFound` middleware nastaví 404 a pošle ďalej ako Error.
9) **Global error handler**: `errorHandler` loguje, zvolí status (`err.statusCode` > `res.statusCode` ≥400 > 500) a formátuje pomocou `formatErrorResponse`. Ak už sú hlavičky poslané, púšťa chybu ďalej.

## Validácia a bezpečnosť
- **Zod validácia**: `validateBody/validateQuery/validateParams` (v `middlewares/security/validateInput.js`) na úrovni routes; nahrádzajú `req.body/query/params` validovanými dátami.
- **Auth**: `authenticate` vytiahne JWT z Bearer header alebo cookie, overí cez `verifyAccessToken`, načíta usera (`auth.service.getUserById`) a uloží do `req.user` + `req.userId`.
- **Role**: `requireRole` / `requireAdmin` / `requireOwnerOrAdmin` (role middleware) na autorizáciu.
- **Rate limiting**: `loginRateLimiter` (default 5 pokusov/15 min, počíta len neúspechy), `sensitiveOperationLimiter` (10 prod / 50 dev za 15 min).
- **Šifrovanie**: `password.encryptPassword` používa AES-256-GCM (kľúč zo `JWT_SECRET` + `ENCRYPTION_SALT`). Heslá v DB sú bcrypt hashované.
- **Audit logy**: `audit.service` loguje login pokusy, zmeny hesla, role, tvorbu userov atď. do DB + konzoly.

## Error handling (kde a ako)
- **Typy chýb**: `AppError` + podtriedy (ValidationError, AuthenticationError, ForbiddenError, NotFoundError, ConflictError, RateLimitError).
- **Formát odpovede**: `formatErrorResponse` vracia `{ success:false, error:{ message, statusCode, details?, stack? } }`. Stack iba v NODE_ENV=development.
- **Použitie**: Kontroléry nemajú lokálne try/catch formatovanie; pri chybe volajú `next(err)`. Auth middleware vracia 401 pri Auth chybách, inak púšťa ďalej do globálneho handlera.

## Doménové moduly – kto koho volá

### Autentifikácia (`routes/auth.routes.js`, `auth.controller.js`, `auth.service.js`)
- **/login**: `loginRateLimiter` → `validateBody(loginSchema)` → controller zavolá `authService.loginWithTempPassword` (porovná temp/permanent heslo, nastaví lastLogin, vygeneruje tokeny) → audit `logLoginAttempt` (success/fail) → nastaví httpOnly cookies + response.
- **/set-password**: `authenticate` → `sensitiveOperationLimiter` → `validateBody(setPasswordSchema)` → `authService.setNewPassword` (bcrypt, zmaže tempPassword) → audit `logPasswordChange`.
- **/logout**, **/session**: vyžadujú `authenticate`; logout vyčistí cookies, session vráti `req.user`.
- **Tokeny**: generované v `utils/jwt.js` (access + refresh); overenie hádže `AuthenticationError` pri expirácii/neplatnosti.

### Admin (`routes/admin.routes.js`, `admin.controller.js`)
- `router.use(authenticate)` + `router.use(requireAdmin)` pre všetky admin-only akcie.
- CRUD nad používateľmi: create (generuje temp heslo + voliteľné linknutie email účtu), get/list, change role, delete. Používa `email-account.service` pri zakladaní účtu, loguje audit udalosti.

### Email účty (`routes/email-account.routes.js`, `email-account.controller.js`, `email-account.service.js`)
- Každá akcia vyžaduje `authenticate`.
- **Create**: `sensitiveOperationLimiter` + Zod schéma → service overí JMAP credentials (`validateJmapCredentials` z `email.service.js`), šifruje heslo (AES-256-GCM), vytvorí účet a many-to-many link do `userEmailAccounts`. Ak účet existuje, vie ho len „nasdieliť“ po overení hesla.
- **Set primary**: pre konkrétneho používateľa; transakčne zruší ostatné `isPrimary` a aktivuje účet.
- **Delete**: odstráni link, a ak nikto iný účet nepoužíva, zmaže aj samotný účet.
- **Get**: vracia účty používateľa; špeciálna funkcia `getEmailAccountWithCredentials` dešifruje heslo na JMAP operácie.

### CRM Emaily (`routes/crm-email.routes.js`, `crm-email.controller.js`, `crm-email.service.js`, `jmap.service.js`)
- Všetky endpointy za `authenticate`.
- **Listing/search**: DB filter + fulltext (subject/body/from), alebo JMAP full-text (`/search-jmap`). Filtrovanie podľa účtu, kontaktu, stavu prečítania.
- **Threads**: `/thread/:threadId` načíta konverzáciu; `/thread/:threadId/read` označí všetky maily v threade.
- **Sync**: `/sync` spustí fetch z JMAP pre daného používateľa/účet.
- **Mark contact read**: `/contact/:contactId/read` označí všetky maily od kontaktu ako prečítané.
- **Reply**: `/reply` cez JMAP; používa dešifrované heslo z email-account service.
- **Unread count**: `/unread-count` agreguje per účet.

### Kontakty (`routes/contact.routes.js`, `contact.controller.js`, `contact.service.js`)
- Všetko za `authenticate`.
- **Get/Discover**: zoznam kontaktov (voliteľný filter `accountId`), discover číta unikátnych odosielateľov z JMAP.
- **Create**: validácia + uloženie, následne auto-sync všetkých emailov od tohto odosielateľa.
- **Update/Delete**: meno/poznámky, prípadne zmazanie; pri delete ostávajú emaily, len sa odpojí contact_id.
- **Link/Unlink company** a **create company from contact** využívajú company service.

### Companies (`routes/company.routes.js`, `company.controller.js`, `company.service.js`, `company-email.service.js`, `company-reminder.service.js`)
- `authenticate` povinné.
- **CRUD firmy**, plus **email threads** pre firmu (agregácia emailov naprieč účtami používateľa).
- **Unread counts** per firma (agreguje emaily podľa kontaktov a účtov).
- **Notes** (vnořené /:companyId/notes) používajú `note.service`.
- **Reminders**: CRUD + summary/endpoints na prehľad (upcoming, counts, summary). Všetko cez `company-reminder.service`.

### Projekty (`routes/project.routes.js`, `project.controller.js`, `project.service.js`)
- `authenticate` povinné.
- CRUD projektov, správa členov projektu (assign/update role/remove), projektové poznámky (vrátane `reminderAt`).

### Todos (`routes/todo.routes.js`, `todo.controller.js`, `todo.service.js`)
- `authenticate`; CRUD + toggle completed.

### Poznámky (`routes/note.routes.js`, `note.controller.js`, `note.service.js`)
- `authenticate`; všeobecné poznámky s filtrom na company/project/todo/contact; CRUD operácie.

### Time Tracking (`routes/time-tracking.routes.js`, `time-tracking.controller.js`, `time-tracking.service.js`)
- `authenticate`; Zod validácia na start/stop/update.
- **Start/Stop**: vytvára/uzatvára bežiaci záznam (oprávnenie viazané na `req.userId`).
- **Bežiace položky**: `/running` (aktuálne pre usera), `/running-all` (všetkých userov – dashboard).
- **Listing/Filters**: všeobecný listing, mesačné výpisy a štatistiky, detail/relations.
- **Generate timesheet**: vytvorí XLSX výstup za mesiac (využíva `exceljs`).

### Timesheets upload (`routes/timesheet.routes.js`, `timesheet.controller.js`, `timesheet.service.js`)
- `authenticate`; Multer s **memory storage** a limit 5 MB, whitelist MIME (PDF, XLSX, XLS). Admin môže nahrávať za iných, inak len za seba. Ukladá súbory do `uploads/timesheets`.

### Admin (už popísané vyššie)

### Audit (`audit.service.js`)
- Jednotné logovanie udalostí do DB + konzoly (tag `[AUDIT]`). Použité v auth flow a user managemente; možno rozšíriť na ďalšie služby.

## Pomocné utility
- `utils/errors.js` – definícia AppError podtried + `formatErrorResponse`.
- `utils/jwt.js` – generovanie/verifikácia access/refresh tokenov.
- `utils/password.js` – bcrypt hash/compare, generovanie temp hesla, AES-256-GCM encrypt/decrypt pre email heslá.
- `utils/logger.js` – farebný stdout logger (info/success/warn/error/debug/audit).

## Request → DB/JMAP tok (v skratke)
`Route` → `Zod middleware` (+ auth/role/rate-limit) → `Controller` → `Service` → `DB (Drizzle)` alebo `JMAP` → späť do controller → JSON response. Chyby: buď AppError (očakávané, neseká stack v prod), alebo neočakávané → global `errorHandler`.

## Dôležité závislosti medzi modulmi
- **authMiddleware** závisí na `utils/jwt` a `auth.service` (pre user fetch). Bez prístupu k DB nie je možné overiť token.
- **crm-email.service** používa `jmap.service` + `email-account.service` (pre dešifrované heslo) + DB schémy.
- **contact.service** pri vytvorení kontaktu volá `crm-email.service` na sync emailov od odosielateľa.
- **company.controller** používa `company-email.service` (agregácia email threadov) a `note.service` / `company-reminder.service`.
- **time-tracking.service** používa Drizzle schémy `timeEntries`, `projects`, `todos`, `companies`, `users` na joiny a agregácie.
- **timesheet.controller**/routes využívajú Multer; uloženie súboru/metadata robí `timesheet.service`.

## Ako rozširovať
- Nový endpoint: pridaj Zod schému do `validators`, zapoj `validateBody/Params/Query`, použi `authenticate`/`requireAdmin` podľa potreby, v controllery volaj service a pri chybe `next(err)`.
- Nová logika: implementuj v `services` (bez Express závislosti), AppError pri očakávaných stavoch.
- Error/response shape je centrálne daný `errorHandler` + `formatErrorResponse` – nechaj ho pracovať.

## Environment a spustenie (stručne)
- Env vars: `PORT`, `CORS_ORIGIN`, `JWT_SECRET`, `JWT_REFRESH_SECRET`, `ENCRYPTION_SALT`, `RATE_LIMIT_*`, DB credentials atď. (pozri `.env.example` ak existuje / README bezpečnostný checklist).
- Skripty: `npm run dev` (nodemon), `npm start`, `npm test` (Jest), drizzle migrácie `db:generate/push/studio`.

Tento README má slúžiť ako rýchla mapa: čo kde je, čo koho volá a kde hľadať validačné/bezpečnostné háky alebo biznis logiku.