CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Projekt

BistroUsky e-shop — webová aplikace pro prodej zákusků a cukrovinek. Produkčně použitelný e-shop s administrací, katalogem, košíkem, objednávkami a platbami.

Hlavní pravidla

Neměň architekturu bez vysvětlení.
Před větší změnou navrhni postup a počkej na souhlas.
Po změně uveď, co bylo změněno a jak to otestovat.
Nepřepisuj existující funkčnost, pokud to není nutné.

Tech stack

Vrstva	Technologie
Framework	Next.js 16 (App Router)
Jazyk	TypeScript
Styling	Tailwind CSS v4 + shadcn/ui
Databáze	PostgreSQL + Prisma ORM
Autentizace	NextAuth.js v5 (beta) + @auth/prisma-adapter
Platby	Stripe
E-mail	Resend + React Email
Validace	Zod v4
Testy	Vitest + @testing-library/react (unit), Playwright (E2E)

Příkazy

npm install           # instalace závislostí
npm run dev           # vývojový server → http://localhost:3000
npm run build         # produkční build
npm run lint          # ESLint
npm test              # Vitest (watch mode)
npx vitest run src/path/to/test.spec.ts   # jeden test
npm run test:e2e      # Playwright E2E testy
npm run db:migrate    # aplikace nových DB migrací
npm run db:generate   # regenerace Prisma klienta
npm run db:studio     # Prisma Studio GUI

Architektura

src/
  app/
    (shop)/           # veřejná část e-shopu — layout a pages pro zákazníka
    (admin)/          # admin sekce — chráněna rolí ADMIN
    api/
      auth/[...nextauth]/   # NextAuth handler
      webhooks/             # Stripe webhook
  components/
    ui/               # shadcn/ui primitive komponenty (button, input, ...)
    shop/             # doménové komponenty (ProductCard, CartItem, ...)
    admin/            # admin komponenty (ProductForm, OrderTable, ...)
  lib/
    db.ts             # Prisma client singleton — vždy importuj odtud
    auth.ts           # NextAuth konfigurace (handlers, auth, signIn, signOut)
    stripe.ts         # Stripe client
    resend.ts         # Resend client
  emails/             # React Email šablony (OrderConfirmation, ...)
  types/              # sdílené TypeScript typy a Zod schémata
prisma/
  schema.prisma       # datový model
  migrations/         # DB migrace (generované, neupravuj ručně)

Klíčové konvence

Server Actions pro mutace (formuláře, košík, objednávky) — ne API routes.
API routes jen pro webhooky (Stripe) a veřejné REST endpointy.
Zod schémata definovat v src/types/ a sdílet mezi Server Actions a klientem.
Prisma client importovat výhradně ze src/lib/db.ts (singleton, zabraňuje memory leaks v dev).
Ceny ukládat vždy v haléřích (integer), zobrazovat konverzí /100 s formátováním.
Route groups (shop) a (admin) oddělují layout a middleware ochranu — v middleware.ts chránit /admin/* rolí ADMIN.

Doménový model (Prisma)

Klíčové vztahy:

Product → Category (N:1), ProductVariant[] (1:N)
Cart → CartItem[] → ProductVariant (guest přes sessionId, přihlášený přes userId)
Order → OrderItem[] → snapshot ceny (unitPrice) v době objednávky
User má role: CUSTOMER | ADMIN

Prostředí (.env)

DATABASE_URL          # PostgreSQL connection string
AUTH_SECRET           # NextAuth secret (generuj: npx auth secret)
STRIPE_SECRET_KEY
STRIPE_PUBLISHABLE_KEY
STRIPE_WEBHOOK_SECRET
RESEND_API_KEY
NEXT_PUBLIC_APP_URL   # http://localhost:3000 ve vývoji

3.6 KiB Raw Blame History