app/CLAUDE.md

CLAUDE.md

Projektová paměť

Před začátkem práce si načti relevantní soubory z memory/:

• MEMORY.md - tech stack, architektura, klíčové poznámky
• structure.md - adresářová struktura, routes, API endpointy
• patterns.md - coding konvence (frontend i backend), CSS architektura
• modules.md - detaily modulů (attendance, offers, orders, invoices, projects, atd.)
• design-system.md - CSS třídy, komponenty, theme tokens
• security.md - bezpečnostní audit, auth, rate limiting

Čti podle typu úkolu - nemusíš vše, ale vždy alespoň MEMORY.md.

---

Prostředí

• Projekt: D:\Claude\BOHA Website\app
• Frontend: Vite dev server (npm run dev) - port 3000
• Backend: PHP built-in server (php -S localhost:8000) - port 8000
• Databáze: MySQL 8.4 na localhost, DB název: app
• Vite proxy: /api -> http://localhost:8000
• npm: při instalaci balíčků vždy --legacy-peer-deps
• Git remote: https://git.boha-automation.cz/boha_admin/app.git
• Git credentials: uloženy v ~/.git-credentials (credential.helper=store), push funguje bez zadávání hesla
• Gitea API token: 8539cea57be2e251b15c0fa973dac8e231e15259 (pro issues, releases atd.)
• Gitea API: https://git.boha-automation.cz/api/v1/repos/boha_admin/app/
• Gitea API a UTF-8: curl na Windows nepřenáší českou diakritiku správně - pro API volání s českým textem použij node -e s https modulem a Content-Type: application/json; charset=utf-8

---

Spuštění dev serveru

# Terminal 1 - Frontend
npm run dev

# Terminal 2 - PHP API
php -S localhost:8000

Aplikace běží na http://localhost:3000

---

Build a Git workflow

• dist/ JE v gitu (neni v .gitignore) - slouzi pro deploy na produkci
• Produkce se aktualizuje pres git pull z tohoto repa
• VZDY spust npm run build pred pushnutim
• NIKDY necommituj bez uspesneho buildu
• Kazdy commit MUSI obsahovat aktualni dist/

Postup pred kazdym pushem:

# 1. Lint kontroly
npx eslint src/
vendor/bin/phpcs

# 2. Build
npm run build

# 3. Commit vse vcetne dist/
git add .
git commit -m "typ: popis zmeny"
git push

---

Autonomní režim

Když běžíš s --auto, dodržuj tento postup:

Před jakoukoli prací:

1. Načti memory/MEMORY.md a relevantní memory soubory
2. Spusť diagnostiku:
   • npx eslint src/ - zkontroluj chyby
   • vendor/bin/phpcs - zkontroluj PSR-12
   • npm run build - ověř že build projde

Během práce:

• Po každé větší změně spusť npm run build - ověř že nic nerozbíjíš
• Opravuj průběžně ESLint a PHPCS chyby
• Pokud si nejsi jistý architektonickým rozhodnutím, zapiš do reportu a pokračuj dál

Po dokončení práce:

1. Spusť finální kontroly:
   • npx eslint src/ - 0 errors
   • vendor/bin/phpcs - 0 errors
   • npm run build - musí projít
2. Commitni a pushni (VCETNE dist/):
   • git add .
   • git commit -m "typ: stručný popis změn"
   • git push
3. Napiš report do reports/YYYY-MM-DD.md

Commit message konvence:

• feat: - nová funkce
• fix: - oprava bugu
• refactor: - refaktoring bez změny funkčnosti
• style: - formátování, lint opravy
• docs: - dokumentace
• perf: - optimalizace výkonu

Report formát:

# Report YYYY-MM-DD

## Zadání
- Co bylo požadováno

## Provedené změny
- Seznam změn s krátkým popisem

## Nalezené problémy
- Problémy co vyžadují rozhodnutí uživatele (pokud nějaké)

## Stav
- ESLint: PASS/FAIL
- PHPCS: PASS/FAIL
- Build: PASS/FAIL
- Git: commitnuto a pushnuto / jen commitnuto / nepushnuto

---

Coding Standards

PHP

• PSR-12, strict_types=1 vždy
• Typované parametry a návratové typy povinné
• Repository pattern pro DB - žádné raw SQL v controllerech
• Prepared statements s ? placeholdery, žádná string interpolace v SQL
• PHPStan level 6 musí projít
• vendor/bin/phpcs (PSR-12) musí projít bez chyb
• Docblock PŘED declare(strict_types=1), ne za ním

React

• Funkcionální komponenty, žádné class components (výjimka: ErrorBoundary.jsx)
• Props typované přes interface, ne inline type
• Žádné any typy
• Custom hooks pro business logiku - ne inline useEffect spaghetti
• Žádné vnořené ternáry - použít early return, if/else, helper funkci nebo lookup objekt
• Striktní porovnání (===/!==), nikdy ==/!=
• API volání vždy přes apiFetch() z ../utils/api (výjimka: AuthContext.jsx)

Data konvence

• Všechny response klíče snake_case (DB sloupce, PHP proměnné, JSON klíče)
• $authData['user_id'] (ne userId)
• camelCase jen tam, kde to vyžaduje React/JS ekosystém (handlery, hooky, props, state)
• Stabilní React keys: _key property, nikdy array index

Error handling

• API success: { "success": true, "data": {...} }
• API error: { "success": false, "error": "message" }
• PHP: jsonResponse(), errorResponse(), successResponse() helpery
• Frontend: alert.success() / alert.error() přes useAlert()
• Formulářová validace vždy frontend inline

Inline validace formulářů

• has-error class na .admin-form-group + .admin-form-error pod inputem
• Error message vždy za inputem (ne před ním)
• const [errors, setErrors] = useState({}) - validace v handleSubmit/handleSave, clear na onChange
• Povinná pole: required class na labelu (červená hvězdička)
• Detaily viz design-system.md

---

Komentáře v kódu

• Piš jako programátor, stručně a k věci
• Nekomentuj zřejmé věci
• Nepoužívej em dash, používej normální pomlčku (-)
• Čeština i angličtina OK, preferuj češtinu u nových komentářů
• Komentář jen když přidává info, které nejde vyčíst z kódu
• Docblocky jen u složitějších funkcí/API endpointů
• Žádné komentáře typu // Set headers, // Get input

---

Migrace (SQL změny)

• Každá SQL změna (INSERT, ALTER TABLE, CREATE TABLE) MUSÍ mít migrační soubor v migrations/
• Formát názvu: NNN_popis.sql (číslování navazuje na poslední existující)
• Migrace commitovat přes git add -f migrations/ (složka je v .gitignore)
• Migraci vytvořit VŽDY - i když se SQL spustí ručně přes PHP nebo phpMyAdmin

---

Zakázané operace

• NIKDY nečti .env soubory
• NIKDY nepoužívej SSH, SCP, rsync na jakýkoli vzdálený server
• NIKDY neměň databázi na vzdáleném serveru
• NIKDY nespouštěj Chrome bez výslovné žádosti uživatele
• NIKDY necommituj bez úspěšného npm run build
• Žádné TODO/FIXME v kódu
• Žádné console.log v kódu (console.error jen s import.meta.env.DEV guardem)
• Funkce max 50 řádků - u React komponent se počítá logika, ne JSX template
• Žádné any typy v TypeScript/React
• Žádná string interpolace v SQL dotazech