# CLAUDE.md — Urbino specifikáció, Claude Code instrukció **Dokumentum-típus:** Claude Code kísérő-instrukció (feature-független) **Hatókör:** az `urbino-docs` repó minden specifikációs dokumentuma **Verzió:** v1.3 **Dátum:** 2026.05.20 > **Mire való ez a fájl.** Ez az állandó instrukció a Claude Code-nak, amikor > az Urbino-specifikációból kódot generál. **Minden feature-spec implementálása > előtt ezt kell elsőként elolvasni.** Nem feature-függő — a dokumentum-réteg > használatát, a hivatkozás-feloldást és a hallucináció-megelőzést szabályozza. > Ahogy új feature-spec születik, ez a fájl változatlan marad; a feature-specifikus > tudás a feature-spec-ekben él. --- ## 1. A dokumentum-réteg — mit honnan veszel Az Urbino-specifikáció **réteges**. Egy feature-spec sosem önálló — hivatkozik a többi dokumentumra. A teljes kontextust ismerni kell: | Dokumentum | Mit tartalmaz | Mikor olvasd | |---|---|---| | `00_terminologia.md` | Magyar/angol fogalomjegyzék, a névsíkok | Ha egy fogalom kódbeli neve kérdéses | | `00_domain_model.md` | A teljes domain-modell: 17 entitás, mezők, típusok, méretek, enumok, kapcsolatok | **Mindig** — ez az entitás-igazság | | `01_kozos_mintak.md` | Platform-minták: multi-tenancy, tenant-resolution, auth, API-konvenciók, hibakód-keret, i18n-elvek | **Mindig** — ez a platform-igazság | | `02_globalis_allapotgep.md` | A `Ticket` állapotgépe: öt állapot, átmenetek, előfeltételek, a "miből mibe" mátrix | Ha `Ticket`-státuszt érintő kódot írsz | | `99_donesnaplo.md` | A specifikációs döntések (SD-xxx) és a felmérő-kör döntései (Ü-xxx) teljes szöveggel | Ha egy SD-xxx hivatkozás indokát keresed | | `kanonikus_donek.md` | A funkcionális/stratégiai projekt kanonikus döntései (K-xxx) | Ha egy K-xxx hivatkozást kell feloldani | | `NN_modul/NN_feature.md` | A konkrét feature-spec — ezt implementálod | A feladat kiindulópontja | **A két kódrepó `CLAUDE.md`-je** (`project_backend`, `project_backend_client_angular`) adja a **kód-mintákat** (`BaseController`, `TableStateConfig`, FluentValidation auto-regisztráció, AutoMapper, `[validationForm]`, `LookupLoaderService`, stb.). A specifikáció ezekre **hivatkozik**, nem másolja — a tényleges mintát a kódrepó `CLAUDE.md`-jéből és a meglévő kódból kell venni. **Olvasási sorrend egy feature implementálásakor:** (1) ez a fájl; (2) a feature-spec; (3) a feature-spec által hivatkozott alapdokumentumok az érintett szakaszokon; (4) a releváns kódrepó `CLAUDE.md`-je és a meglévő minta-kód. --- ## 2. A legfontosabb szabály — ahol megállsz, nem találsz ki A specifikáció **tudatosan** hagy nyitva pontokat — ezek más feature-spec vagy a funkcionális projekt hatáskörébe tartoznak. Ahol a spec az alábbi jelöléseket használja, ott **NE generálj kitalált megoldást** — állj meg, és jelezd a fejlesztőnek: - **"NY-xxx" / "nyitott kérdés"** — a kérdés szándékosan eldöntetlen. Ne hozz döntést helyette. Pl. az `NY-2` (a `Ticket.reporterId` célentitása) — ne hozz létre kitalált `Reporter` entitást; a polgári adatigény-spec dönti el. - **"külön feature" / "külön feature-spec"** — az a rész egy másik specifikációban lesz. Ne építsd meg előre. Pl. a "Hasonló bejelentések" doboz tartalmi szerződése a duplikáció-feature dolga — a bejelentés-adatlap csak a doboz *helyét* foglalja. - **"megtartott hiány"** — funkcionálisan nincs megtervezve. Ne pótold. Pl. a "Sablon-válasz polgárnak" gomb és a "Te is segíthetsz" blokk. - **"TBD" / "fejlesztői döntés"** — itt van mozgástered, de a kódrepó meglévő mintáját kövesd, és ha a döntésnek érdemi következménye van, jelezd a fejlesztőnek. - **"visszacsorgó jelzés" / "VF-xxx"** — ezek a funkcionális projektnek szóló jelzések, NEM kódolási feladat. Hagyd figyelmen kívül a kódgeneráláskor. **Az alapelv:** ha egy entitást, mezőt, végpontot vagy szabályt a specifikáció nem ad meg, és nem a kódrepó standard mintájából következik — **ne találd ki**. Kérdezz. Egy kitalált entitás később drága hiba. --- ## 3. "Eltérés a mintától" — hogyan olvasd A specifikáció a `BaseController` és a `TableStateConfig` minták fölött a **"csak az eltérést specifikáld"** elvet követi (`01_kozos_mintak.md` 6.4): - Ha egy entitás/végpont leírásánál **nincs** "Eltérés a mintától:" jelölés, a **standard `BaseController` / `TableStateConfig` minta érvényes** — azt generáld, ahogy a kódrepó `CLAUDE.md`-je és a meglévő kód mutatja. - Ahol **"Eltérés a mintától:"** jelölés áll, **csak azt a részt** kódold a leírt módon — a többi a standard minta. - Ha egy szakasz azt írja, *"Standard CRUD a `BaseController` szerint"*, ne írj egyedi kontrollert — a standard mintát alkalmazd. Példa: a `TicketNote` "Standard CRUD a `BaseController` szerint" — nincs egyedi logika. A `Ticket` akció-végpontjai viszont "Eltérés a mintától" — önálló action-method-ök, workflow-logikával. **Két különleges eltérés-mintázat, amelyeket a Beállítások-feature vezetett be:** - **"Egyedi-fájl-mező" minta (SD-60, SD-68).** Amikor egy entitásnak van egy szakosított képmezeje (pl. `Tenant.logoFileRef`, `News.coverImageRef`, `Event.coverImageRef`), ami **nem** `Attachment` (mert az `Attachment` `ticketId`-hez kötött), és nem általános fájl-rendszer: dedikált `POST`/`DELETE` multipart-végpont az entitás-erőforrás alá (pl. `POST /v1/tenant-settings/logo`, `POST /v1/news/{id}/cover-image`), a binárist S3-objektum-kulcsra fordítja és csak a hivatkozást írja az entitás-mezőbe. Az `Attachment.fileRef`-mintával konzisztens (SD-15) a tárolásban, de **nem** `Attachment`-entitás. A standard `PUT`-on a fájl-mező szerkesztése tiltott (`400 field_not_editable`). A `60_tartalom`-spec az SD-68-tal a `News.coverImageRef` és `Event.coverImageRef` mezőkre is alkalmazta ezt a mintát — ezzel a `30_beallitasok.md` VF-K1 visszacsorgó jelzése lezárult. Cserekor a régi S3-objektum törlése az `AfterSaveAsync`-ben; meghiúsulás esetén árva-objektum (NY-K3 takarítás iterációs). - **"Core-mezőkre korlátozott tenant-szintű írás" minta (SD-61).** A `tenant_manager` szerepkör általában **nem ír** Core DB-be — de néhány Core-entitás-mező (pl. `Tenant.name`, `contactAddress`, `contactPhone`, `contactEmail`) szűk halmazára kivételt teszünk. Az ilyen végpont **dedikált controllerrel** dolgozik (pl. `TenantSettingsController`), amely a Core `DbContext`-et használja, de a `Tenant` headerből kiolvasott `code`-ra **explicit szűr** (analóg minta: `UserManagementController`, SD-36). A szerkeszthető mezők listája szűkített; a tiltott mezők szerepeltetése `400 field_not_editable`-lel zár. Ez **célzott kivétel**, nem általános felhatalmazás — a `Tenant` regisztrum-mezőit (`code`, `dbConnectionRef`, `status`, `timeZone`, `displayPrefix`) továbbra is csak `urbino_admin` írja. --- ## 4. Hibakezelés és i18n — kötelező konvenciók - **Hibakód-keret** (`01_kozos_mintak.md` 6.3): `400` validáció (`fieldErrors`), `401` auth, `403` jogosultság / rossz tenant, `404` nem létező vagy idegen tenant erőforrás, `409` állapot-konfliktus, `422` üzleti szabály. - **A szerver kulcsot/kódot ad, nem kész szöveget** (`01_kozos_mintak.md` 5.5). A `409`/`422` hibatest `reason`/kód mezőt hordoz; a magyar üzenetet az admin felület i18n-rétege fogalmazza. Soha ne hardkódolj magyar hibaszöveget a szerverbe. - **UI-szöveg sosem hardkódolt** (`01_kozos_mintak.md` 5.3). Minden felhasználói szöveg a `hu.json`-ba, kulcs-alapon. A feature-spec 4.6 (i18n) szakasza adja a kulcsokat. - **A felület tegez** (`01_kozos_mintak.md` 5.4) — minden `hu.json`-szöveg tegező formában. - **A `fieldErrors`** a `400`-as validációnál a meglévő `[validationForm]` + `` minta szerint jelenik meg automatikusan — ne írj rá egyedi hibamegjelenítő kódot. --- ## 5. Multi-tenancy — nem megkerülhető - A tenant-resolution **middleware-ben** történik (`01_kozos_mintak.md` 2.1); a kontroller a tenant-aware `DbContext`-et kapja, **transzparensen** — ne írj tenant-logikát a kontrollerbe. - A `Tenant` HTTP request header azonosít; idegen tenant erőforrás-ID-ja `404`. - A `Ticket` és a kísérői a **Tenant DB**-ben élnek; a Core-entitások (`User`, `Tenant`, `UserTenantRole`, `UserInvitation`, `DefaultCategoryCatalog`) a **Core DB**-ben. A működési útvonalon **nincs cross-DB join** — a tenant-oldali entitások a `TenantUser`-projekcióra mutatnak (SD-2). - **A `tenant_manager` szűk kivétellel Core DB-be is írhat** — a `TenantSettingsController` mintája (SD-61, lásd 3. szakasz). Ez nem általános felhatalmazás; csak a feature-spec által engedélyezett, korlátozott mezőkészletre szól, dedikált controllerrel, explicit `Tenant`-header-szűréssel. - **A `from-default`-jellegű ritka konfigurációs végpontok** (pl. `GET /v1/categories/available-default-roots`, SD-62) **cross-DB olvasást igényelhetnek** — ez nem sérti az SD-2 elvet, mert az SD-2 a *működési* útvonalra (lista, adatlap, Dashboard) szól, nem a ritka konfig-műveletekre. Az ilyen végpontot a feature-spec **lokálisan dokumentálja**, és a műveletet két szekvenciális lekérdezésre bontja, join nélkül. --- ## 6. Jogosultság - A jogosultság **route-alapú**, az `authorization.json`-ban (`01_kozos_mintak.md` 3.3). A feature-spec jogosultság-szakasza adja a bejegyzéseket prefix-formában (`tenant_dispatcher` stb.); a middleware fűzi hozzá a tenant `code`-ot. - **A route-szabály nem mindent fejez ki.** A "csak saját ügye" típusú, **sor-szintű** szűrést (pl. a `field_worker` csak a hozzá rendelt bejelentéseket látja) a feature-spec szövege írja le — ezt a kontroller/service logikájában kell érvényesíteni, nem az `authorization.json`-ban. - A kliens-oldali elrejtés **UX, nem biztonsági határ** — a szerver-végpontnak is el kell utasítania a jogosulatlan kérést. - **A teljes route→szerepkör kép egy helyen.** A `30_szerver/05_jogosultsag_es_authorization.md` a `05_jogosultsagok_v2.md` akció-mátrixának konszolidált leképezése — a traceability-mátrixa (3.2) a teljes route→szerepkör nézet. Ha egy jogosultsági kérdésnél egy feature-specben nem találod a route-ot, ezt a referenciát nézd. **A route kanonikus definíciója azonban a feature-specben él** (`10` 3.8, `20_dup` 3.5, `20_felhasznalokezeles` 3.8, `40_riport` 3.1, `30_beallitasok` 3.5) — a referencia összegez és hivatkozik, nem helyettesít. - **A `vezető ⊇ diszpécser ÉS ⊇ tartalomkezelő` reláció felsorolással képződik le**, nem öröklődéssel: minden diszpécser- és tartalomkezelő-route `roles`-listájában a `tenant_manager` is szerepel. A meglévő `authorization.json`-minta öröklődést nem ismer — ne keress szerepkör-hierarchiát. - **Az MH-J1 megtartott hiány teljesen lezárva.** A `60_tartalom.md` v1.0 lezárásával **már nincs hézagos modul** — a `40_riport.md`, `30_beallitasok.md`, `60_tartalom.md` mind kanonikus route-stringeket adott (Szabály-R1, R2, R3 érvényesítve). Az `05_jogosultsag_es_authorization.md` 3.2 traceability- mátrixának minden sora konkrét route-tal van feltöltve; a "route-string TBD" jelölés sehol nem maradt. Bármely új feature-spec route-leképezésének a meglévő mintát kell követnie (`tenant__`-prefix, OR-szemantika, felsorolásos `vezető`-reláció). --- ## 7. Acceptance criteria — a teszt-kapaszkodó Minden feature-spec 6. szakasza Given/When/Then formájú, gépiesen ellenőrizhető acceptance criteria-t tartalmaz. Ezek a **teszt-specifikáció** — minden kritériumhoz írható (és írandó) automata teszt. Ha egy AC nem teljesül a generált kóddal, a kód hibás, nem az AC. --- ## 8. Ha bizonytalan vagy A sorrend, amikor egy feature implementálása közben hézaghoz érsz: 1. Nézd meg, hogy a feature-spec hivatkozott alapdokumentuma (domain-modell, állapotgép, közös minták) megadja-e. 2. Nézd meg, hogy a kódrepó `CLAUDE.md`-je vagy a meglévő minta-kód megadja-e (standard `BaseController`/`TableStateConfig` viselkedés). 3. Ha egyik sem — és a 2. szakasz "ne találd ki" jelöléseinek egyike áll a közelben — **állj meg és kérdezz**. Ne generálj kitalált entitást, mezőt, végpontot vagy üzleti szabályt. Egy jó kérdés a fejlesztőnek olcsóbb, mint egy kitalált megoldás visszabontása. --- ## Verziónapló - **v1.0 (2026.05.18)** — Első kiadás. A dokumentum-réteg térképe, a hallucináció-megelőző "ne találd ki" szabályok, az "Eltérés a mintától" olvasási szabály, a hibakezelési/i18n/multi-tenancy/jogosultság-konvenciók összefoglalója. Feature-független — a bejelentés-lista és -adatlap feature-spec (v1.1) tapasztalataiból általánosítva. - **v1.1 (2026.05.19)** — A 6. szakasz (Jogosultság) három felsorolás-ponttal bővült a jogosultság-konszolidációs kör nyomán: a `30_szerver/05_jogosultsag_es_authorization.md` referencia mint a teljes route→szerepkör kép egy helyen (a route kanonikus definíciója továbbra is a feature-specben); a `vezető`-reláció felsorolásos (nem öröklődéses) leképezése; a még el nem készült modulok route-jai mint megtartott hiányok (MH-J1). A 2. szakasz nem módosult — a "megtartott hiány" és a "VF-xxx" jelölést már kezeli. - **v1.2 (2026.05.20)** — A Beállítások feature-spec (`20_admin_felulet/30_beallitasok.md` v1.0) két új mintázatot vezetett be, amelyek a `CLAUDE.md`-be illesztendők. **A 3. szakasz "Eltérés a mintától" két különleges eltérés-mintázattal bővült:** (a) az "egyedi-fájl-mező" minta (SD-60) — dedikált multipart-feltöltés egy entitás-mezőhöz, S3-hivatkozás- mezővel, nem `Attachment`-rekord; (b) a "Core-mezőkre korlátozott tenant- szintű írás" minta (SD-61) — a `tenant_manager` szűk kivétellel ír Core DB-be, dedikált controllerrel, explicit `Tenant`-header-szűréssel. **Az 5. szakasz (Multi-tenancy) két új ponttal bővült:** az SD-61-minta mint a "nincs cross- DB" elv szűk kivétele; az SD-62-jellegű ritka konfig-végpontok mint a cross-DB olvasás lokálisan engedélyezett esetei. **A 6. szakasz frissült:** az MH-J1 megtartott hiány a `40_riport` és a `30_beallitasok` feature-spec v1.0 lezárásával **két modulra szűkült** — már csak a `60_tartalom` route-stringei nyitottak. Új entitás-számolás: 14 helyett **17 entitás** (`WeeklyReport`, `UserInvitation`, `WeeklyReportRecipient` hozzáadása óta). - **v1.3 (2026.05.20)** — A `60_tartalom` feature-spec (`20_admin_felulet/60_tartalom.md` v1.0) átvezetése. **A 3. szakasz "egyedi-fájl-mező" minta-magyarázata frissült:** az SD-68 nyomán a `News.coverImageRef` és `Event.coverImageRef` is ezt a mintát követi (a korábbi "ha más entitásnál is felmerül, a `60_tartalom`-spec dönt" függő-zárszó helyére az eldöntött állapot került); a `30_beallitasok.md` VF-K1 visszacsorgó jelzése ezzel **lezárult**. **A 6. szakasz utolsó pontja átíródott:** az MH-J1 megtartott hiány **teljesen lezárva** — a `60_tartalom` modul az utolsó hézagos modul volt; minden modul kanonikus route-stringeket adott (Szabály-R1/R2/R3 mindenhol érvényesítve). A 17 entitás változatlan (a `60_tartalom` nem hozott új entitást — a `News`, `Event`, `CityInfo` már a `00_domain_model.md` 4. blokkjában létezett v1.7 óta).