API kontrakt

• Konzistence nad pohodlím: chyby i payloady musí být predikovatelné.
• Doménové chyby jsou first-class: doménové validační chyby se surfacují odlišně od neočekávaných selhání.
• Žádný tenant leakage: každý request se interpretuje v aktivním org kontextu (pro app routy) a vynucuje vlastnictví.

Použití:

• endpointy pro spuštění výpočtu (pokud klient potřebuje přímé compute volání)
• webhook endpointy (billing provider apod.)

Použití:

• vytvořit projekt
• aktualizovat vstupy (edit mode)
• spustit výpočet
• exportovat

Poznámka pro exporty:

• sync export může vracet soubor přímo
• async export má preferovat vytvoření export jobu a vracet stav queued nebo processing
• export route ani server action nesmí obcházet tenant-scoped audit zápis exportu

#### Kontrakt server action: vytvořit projekt

• Požadované oprávnění: create_project
• Vstupní pole (FormData klíče):
• projectName
• building.widthMeters, building.heightMeters, building.levels
• scaffoldSystem.name, scaffoldSystem.frameWidthMeters, scaffoldSystem.bayLengthMeters, scaffoldSystem.levelHeightMeters
• Vedlejší efekty:
• vložení nového řádku Projektu do DB (v kontextu aktivní organizace)
• revalidace cache/tagů pro projektové seznamy/detail
• redirect na /app/projects/:id/edit

• Používat explicitní DTO pro všechny externí rozhraní.
• Převádět DTO → doménový vstup pomocí validace a normalizace.
• Nikdy neposílat raw request body přímo do doménových funkcí.

Pro JSON endpointy:

• Success:
• { "success": true, "data": <payload> }
• Error (očekávané):
• { "success": false, "error": { "code": "<string>", "message": "<string>", "details": <optional> } }
• Error (neočekávané):
• stejný tvar, s code = "INTERNAL_ERROR" a bezpečnou zprávou

• VALIDATION_ERROR (doména/vstup)
• UNAUTHORIZED (bez session)
• FORBIDDEN (RBAC)
• SUBSCRIPTION_REQUIRED / UPGRADE_REQUIRED (plan gating)
• NOT_FOUND (zdroj chybí nebo není vlastněn)
• CONFLICT (současné editace, version mismatch)
• INTERNAL_ERROR (neočekávané)

• Preferovat idempotentní zápisy, kde to dává smysl (zejména u exportů).
• Vyhnout se vedlejším efektům u “calculate-only” operací, pokud si je use-case explicitně nevyžádá.
• Exporty mají zapisovat auditovatelný job i tehdy, když je výsledný soubor vrácen synchronně.

• Každý request by měl být traceovatelný (request id / correlation id).
• Logovat strukturované eventy pro:
• běhy výpočtu
• exporty
• billing eventy
• permission denials (rate-limited)