From 758ee2cfed8f9349cc338aa69cdd02c6f20c1cb3 Mon Sep 17 00:00:00 2001 From: Do Siki Date: Sun, 13 Sep 2026 12:33:33 +0200 Subject: [PATCH] docs(agent): refresh architecture/CLAUDE.md docs for Payload CMS (MITHOME-95) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Content layer description across the AI-agent steering docs still described the pre-migration JSON system as the live, current mechanism — rule #1 in CLAUDE.md and the Content row in architecture.md explicitly told future work (and future agent sessions) to edit proto/src/content/pages/*.json directly, which the live site hasn't read since MITHOME-91. Rewrote, per the ticket's named targets: - .agent/steering/architecture.md: system overview, the Content layer table row, rule #1, and the Content Management code example now describe Payload Globals/Collections + the payload-content.ts Local API adapter, with /admin as the editing surface. - CLAUDE.md: Stack line now names Payload CMS, rule #1 rewritten the same way, and the project-structure tree gets the (frontend)/(payload) route groups, globals/, collections/, and payload.config.ts that were entirely missing from it. Also fixed directly-adjacent staleness found while doing this pass — same "how is content edited" documentation debt, just not literally named in the ticket: - .agent/AGENTS.md: same project-structure tree gap as CLAUDE.md. - .agent/workflows/new-feature.md: step 3 told contributors to edit the JSON file directly; now points at the Payload config + admin. - .agent/workflows/review.md: the example "flag hardcoded text" review comment suggested moving it into the JSON file. - .agent/steering/development-rules.md: the TRADEOFF code example literally used "JSON content management vs CMS" as a live open decision — that decision is resolved, updated the example to match. - README.md: the entire "Tartalomkezelés" section and a "CMS Publikálás gomb" paragraph described the retired content-editor.js workflow (git-push-based publish, JSON directory tour) as current; also dropped a dead link to docs/felhasznaloi-utmutato.md, deleted in MITHOME-93. Doc-only change, no proto/ source touched — no gate to run beyond a sanity re-read of each edited file. Co-Authored-By: Claude Sonnet 5 --- .agent/AGENTS.md | 11 ++++++++--- .agent/steering/architecture.md | 26 +++++++++++++++++--------- .agent/steering/development-rules.md | 5 +++-- .agent/workflows/new-feature.md | 8 ++++++-- .agent/workflows/review.md | 3 ++- CLAUDE.md | 20 +++++++++++++------- README.md | 25 +++++++++++++------------ 7 files changed, 62 insertions(+), 36 deletions(-) diff --git a/.agent/AGENTS.md b/.agent/AGENTS.md index deaa6c3..8e107af 100644 --- a/.agent/AGENTS.md +++ b/.agent/AGENTS.md @@ -80,10 +80,15 @@ sync: update Plane issues + TODO [leírás] websitedev/ ├── proto/ # Fő Next.js alkalmazás (itt futtatsd a parancsokat!) │ ├── src/ -│ │ ├── app/ # Next.js App Router (pages és API routes) +│ │ ├── app/ +│ │ │ ├── (frontend)/ # Publikus oldalak: [locale]/[slug] catch-all +│ │ │ └── (payload)/ # Payload admin (/admin) + REST/GraphQL API │ │ ├── components/ # React komponensek (Header, Footer, ThemeProvider) -│ │ ├── content/ # JSON tartalom-kezelő rendszer -│ │ ├── lib/ # Utility könyvtárak (MongoDB, Logger, Site Config) +│ │ ├── globals/ # Payload Globals (Home, About, Services, Contact, Common) +│ │ ├── collections/ # Payload Collections (LegalPages, Partners, Media, ContactSubmissions, Users) +│ │ ├── payload.config.ts # Payload CMS konfiguráció +│ │ ├── content/ # RÉGI JSON rendszer — csak migrációs seed + teszt-fixture (MITHOME-91/93/96) +│ │ ├── lib/ # payload-content.ts (Local API adapter), MongoDB health-check, Logger │ │ ├── config/ # Statikus site konfiguráció │ │ └── types/ # TypeScript típusdefiníciók │ └── public/ # Statikus fájlok diff --git a/.agent/steering/architecture.md b/.agent/steering/architecture.md index 7da2385..45b10c9 100644 --- a/.agent/steering/architecture.md +++ b/.agent/steering/architecture.md @@ -8,11 +8,12 @@ Ez a fájl minden interakcióban automatikusan betöltődik az AI számára a pr ## Rendszer áttekintés -A projekt egy **Next.js 15 alapú marketing weboldal** a mozdIT Bt. számára, App Router architektúrával, TypeScript-tel és Tailwind CSS 4-gyel. +A projekt egy **Next.js 15 alapú marketing weboldal** a mozdIT Bt. számára, App Router architektúrával, TypeScript-tel és Tailwind CSS 4-gyel, **Payload CMS**-sel (self-hosted, `/admin`) mint tartalomkezelő réteggel (MITHOME-85 epic). -- **Frontend**: Next.js 15 App Router (SSR/SSG), React 19, Tailwind CSS 4 -- **Backend**: Next.js API Routes (`/api/*`) -- **Adatbázis**: MongoDB (Mongoose ODM) — site config és contact form logok +- **Frontend**: Next.js 15 App Router (dinamikus renderelés — lásd MITHOME-97 WHY: SSG helyett, hogy egy admin publikálás azonnal látszódjon), React 19, Tailwind CSS 4 +- **CMS**: Payload CMS — Globals (Home/About/Services/Contact/Common) + Collections (LegalPages/Partners/Media/ContactSubmissions/Users), hu/en lokalizáció, draft/publish + verziózás +- **Backend**: Next.js API Routes (`/api/*`), Payload REST/GraphQL API + Local API +- **Adatbázis**: MongoDB — Payload-collection-önként (mongooseAdapter), plusz egy vékony natív `mongodb` driveres réteg (`proto/src/lib/mongodb.ts`) csak az `/api/health` connectivity-ellenőrzéséhez - **Logging**: Winston + Loki (strukturált naplózás) - **Infrastructure**: Docker + Docker Compose, natív deploy (`deploy.sh`) @@ -24,13 +25,13 @@ A projekt egy **Next.js 15 alapú marketing weboldal** a mozdIT Bt. számára, A | **Component** | Újrahasználható UI elemek | `proto/src/components/` | | **API Route** | Route handling, validáció | `proto/src/app/api/` | | **Service/Lib** | Üzleti logika, DB kapcsolat | `proto/src/lib/` | -| **Content** | JSON alapú tartalom | `proto/src/content/` | +| **Content** | Payload CMS Globals/Collections (admin: `/admin`), Local API adapter | `proto/src/globals/`, `proto/src/collections/`, `proto/src/lib/payload-content.ts` | | **Config** | Statikus site konfiguráció | `proto/src/config/` | | **Agent / Tools** | AI ügynökök eszközei | `.agent/` | ## Fontos Architektúra Szabályok -1. **Tartalom JSON-ban**: SOHA ne égess be szöveget közvetlenül komponensbe — használd a `src/content/` rendszert. +1. **Tartalom Payload-ban**: SOHA ne égess be szöveget közvetlenül komponensbe — a tartalom Payload Global/Collection mezőkben él, az ügyfél a `/admin` felületen szerkeszti, a frontend a `src/lib/payload-content.ts` adapteren (Payload Local API) keresztül olvassa. (Kivétel: `proto/src/content/*.json` még mindig létezik, de csak a `migrate-content-to-payload.ts` seed-script forrásaként és néhány komponens-teszt fixture-jeként — élő oldal nem olvassa közvetlenül, lásd MITHOME-91/93/96.) 2. **Stateless API**: A backend API teljesen stateless — session-t a kliens kezel. 3. **Observability**: Minden hiba legyen logolva Winstonnal. API válaszok egységes formátumban: `{ success, data, error }`. 4. **Security-by-design**: Input validáció minden API route-on, secrets csak env változókból. @@ -55,14 +56,21 @@ A projekt egy **Next.js 15 alapú marketing weboldal** a mozdIT Bt. számára, A ## Content Management ```typescript -// Helyes: content rendszer használata -import { content, getPageContent } from '@/content' -const pageData = content.pages.about +// Helyes: Payload Local API adapter használata (Server Component-ben) +import { getAboutContent } from '@/lib/payload-content' +const about = await getAboutContent(locale) // locale: 'hu' | 'en' // TILOS: közvetlen szöveg komponensben

Rólunk

``` +Az ügyfél a tartalmat a Payload admin felületen (`/admin`) szerkeszti — +Global (pl. Home, About) vagy Collection (pl. LegalPages, Partners) dokumentum +formájában, "Save Draft"/"Publish changes" munkafolyamattal (MITHOME-92). Új +mező felvételekor a megfelelő `proto/src/globals/*.ts` vagy +`proto/src/collections/*.ts` fájlt bővítsd, majd generáld újra a típusokat +(`payload generate:types`). + ## Dependency szabályok - Új NPM package bevezetéséhez **jóváhagyás szükséges** diff --git a/.agent/steering/development-rules.md b/.agent/steering/development-rules.md index 764dca1..64f88c3 100644 --- a/.agent/steering/development-rules.md +++ b/.agent/steering/development-rules.md @@ -142,8 +142,9 @@ const rateLimitStore = new Map(); // DECISION: fire-and-forget MongoDB write — ne várakozzon a válasz a cache írásra dbClient.logContact(data).catch(() => null); -// TRADEOFF: JSON content management vs CMS — könnyebb deploy, de nem non-tech szerkeszthető -const content = await import('@/content/pages/home.json'); +// TRADEOFF: Payload Local API vs statikus JSON import — élő, adminból +// szerkeszthető tartalom, cserébe minden kérésnél DB-olvasás kell (MITHOME-97) +const content = await getHomeContent(locale); ``` ## Pre-modification kockázatbecslés diff --git a/.agent/workflows/new-feature.md b/.agent/workflows/new-feature.md index 218036c..34362b7 100644 --- a/.agent/workflows/new-feature.md +++ b/.agent/workflows/new-feature.md @@ -55,8 +55,12 @@ git checkout -b feature/[leíró-feature-neve] ``` ### 3. Content frissítés (ha szöveges tartalom kell) -- Módosítsd a megfelelő `proto/src/content/pages/*.json` fájlt -- Frissítsd a `types.ts`-t ha új content struktúra kell +- Új mező esetén bővítsd a megfelelő `proto/src/globals/*.ts` vagy + `proto/src/collections/*.ts` Payload config fájlt, majd generáld újra a + típusokat (`payload generate:types`) +- Meglévő mező szövegét az ügyfél a Payload admin felületen (`/admin`) + szerkeszti — ne írj bele közvetlenül `proto/src/content/*.json`-ba (az már + csak a migrációs seed-script forrása, élő oldal nem olvassa, MITHOME-91/93) ### 4. UI / Komponens implementáció (ha szükséges) - Server Component alapértelmezetten — csak indokolt esetben `"use client"` diff --git a/.agent/workflows/review.md b/.agent/workflows/review.md index 2155578..56f3033 100644 --- a/.agent/workflows/review.md +++ b/.agent/workflows/review.md @@ -74,7 +74,8 @@ description: Kód review checklist — PR előtt és review során ✅ JÓ: [BLOCK] Ez hardcoded szöveget tartalmaz a komponensben. - Át kell tenni: proto/src/content/pages/home.json → content.pages.home.* + Át kell tenni Payload mezőbe (proto/src/globals/*.ts vagy collections/*.ts), + és a payload-content.ts adapteren keresztül kell beolvasni. [SUGGEST] Ezt a logikát érdemes egy helper funkcióba kiszervezni, ha több helyen is szükség lesz rá. diff --git a/CLAUDE.md b/CLAUDE.md index 9733a42..fe326e4 100755 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -10,14 +10,14 @@ - **Projekt**: mozdIT Bt. weboldal (websitedev) - **Plane workspace**: `developments` — `pm.llmdev.mozdit.hu` -- **Stack**: Next.js 15, React 19, TypeScript, Tailwind CSS 4, MongoDB, Winston +- **Stack**: Next.js 15, React 19, TypeScript, Tailwind CSS 4, Payload CMS (self-hosted, `/admin`), MongoDB, Winston - **Fő könyvtár**: `proto/` — **minden parancsot innen futtatunk** --- ## Gyors referencia — Alapszabályok -1. **Szöveg sosem kerülhet közvetlenül komponensbe** → `proto/src/content/pages/*.json` +1. **Szöveg sosem kerülhet közvetlenül komponensbe** → Payload CMS Global/Collection mező (admin: `/admin`), a frontend `proto/src/lib/payload-content.ts`-en át olvassa. (`proto/src/content/pages/*.json` már csak a migrációs seed-script forrása + teszt-fixture, élő oldal nem használja — MITHOME-91/93/96.) 2. **Feladatok**: `TODO.md` (Plane tükörképe), szinkron: `node plane-sync.js` 3. **Tesztek**: minden feature-höz kötelező; commit előtt `npm test` zöld 4. **Commit**: Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`) @@ -47,12 +47,17 @@ node plane-sync.js # Plane szinkronizáció websitedev/ ├── proto/ # Fő Next.js alkalmazás │ └── src/ -│ ├── app/ # App Router: oldalak és API route-ok +│ ├── app/ +│ │ ├── (frontend)/ # Publikus oldalak: [locale]/[slug] catch-all +│ │ └── (payload)/ # Payload admin (/admin) + REST/GraphQL API │ ├── components/ # React komponensek (PascalCase.tsx) -│ ├── content/ # JSON tartalom-kezelő rendszer -│ │ ├── common.json # Közös szövegek -│ │ └── pages/ # Oldal-specifikus JSONok -│ ├── lib/ # MongoDB, Logger, Site Config +│ ├── globals/ # Payload Globals (Home, About, Services, Contact, Common) +│ ├── collections/ # Payload Collections (LegalPages, Partners, Media, ContactSubmissions, Users) +│ ├── payload.config.ts # Payload CMS konfiguráció +│ ├── content/ # RÉGI JSON rendszer — csak migrációs seed + teszt-fixture (MITHOME-91/93/96) +│ │ ├── common.json +│ │ └── pages/ +│ ├── lib/ # payload-content.ts (Local API adapter), MongoDB health-check, Logger │ ├── config/ # Statikus site konfiguráció │ └── types/ # TypeScript típusok ├── docs/ # Projekt dokumentáció (Magyar) @@ -77,6 +82,7 @@ Szükséges változók (`.env` és `proto/.env.local`): - `NEXT_PUBLIC_CONTACT_EMAIL` — Kapcsolati email cím - `PLANE_API_KEY` — Plane szinkronizációhoz (a `.mcp.json`-ban is lehet) - `PAYLOAD_SECRET` — Payload CMS JWT/session aláíráshoz (MITHOME-86); környezetenként egyedi, erős érték +- `ADMIN_EMAIL` / `ADMIN_PASSWORD` — staging/production: `deploy.sh` ezekkel hoz létre egy ismert admin usert egy vadonatúj adatbázison (MITHOME-97 follow-up), csak akkor, ha a `users` collection még üres --- diff --git a/README.md b/README.md index d46dc08..1b2e20a 100755 --- a/README.md +++ b/README.md @@ -39,32 +39,33 @@ scripts/pre-deploy-tests.sh ./deploy.sh production # éles (szerveren, staging ellenőrzése után) ``` -A CMS „Publikálás" gombja szintén commitol + pushol + deployol (csak a beállított környezetre). Részletek: `.agent/workflows/deploy.md`, `docs/helyi-staging-deploy.md`. +A Payload admin (`/admin`) draft/publish + verziózás munkafolyamata (MITHOME-92) nem jár git commit-tal vagy automatikus deployjal — a tartalom közvetlenül a MongoDB-be íródik. Kódváltozás (Globals/Collections séma, frontend) továbbra is a fenti git-alapú deploy folyamaton megy át. Részletek: `.agent/workflows/deploy.md`. ## Tartalomkezelés -A weboldal szövegei és a CMS a `proto/src/content/` JSON-fájljaiból jönnek: +A weboldal szövegei Payload CMS Globals/Collections mezőkben élnek, az ügyfél a `/admin` felületen szerkeszti őket: ``` -proto/src/content/ -├── schema.js # közös séma-validátor (Next + CMS) -├── types.ts # TypeScript típusok -├── index.ts # tartalom-betöltő -├── common.json # közös szövegek (gombok, lábléc, a11y) -└── pages/ # oldalankénti tartalom (home, about, services, …) +proto/src/globals/ # Home, About, Services, Contact, Common +proto/src/collections/ # LegalPages, Partners, Media, ContactSubmissions, Users +proto/src/payload.config.ts ``` -Használat: +Használat Server Component-ből (a Payload Local API-n keresztül): ```typescript -import { content, getPageContent } from '@/content' -const about = content.pages.about +import { getAboutContent } from '@/lib/payload-content' +const about = await getAboutContent(locale) // locale: 'hu' | 'en' ``` +A régi, JSON-alapú content rendszer (`proto/src/content/`) már csak a +`migrate-content-to-payload.ts` seed-script forrásaként és néhány +komponens-teszt fixture-jeként él tovább — élő oldal nem olvassa (MITHOME-91/93). + ## Dokumentáció - **Agent-szabályok**: `.agent/AGENTS.md`, `.agent/steering/`, `.agent/workflows/` -- **CMS felhasználói útmutató**: `docs/felhasznaloi-utmutato.md` (a CMS-ben a ❓ Súgó is ezt rendereli) +- **nginx vhost-ok**: `docs/nginx-vhosts.md` - **Plane szinkron**: `PLANE-SYNC-GUIDE.md` - **Staging deploy**: `docs/helyi-staging-deploy.md` - **Gitea runner**: `docs/gitea-runner-telepites.md`