URL a SEO architektura univerzálního e-commerce jádra (Herbatica první konfigurace)

[BleedingDev]

URL a SEO architektura univerzálního e-commerce jádra (Herbatica první konfigurace)

Standalone zadání. Tento issue obsahuje vše potřebné k implementaci bez další konverzace. Agent ani člověk nepotřebuje žádný externí kontext.

• Tento popis = krátká implementační specifikace. Stačí k naimplementování celého rozsahu.
• Komentáře 1–5 = plná normativní specifikace (~32 tis. slov) s důkazy, citacemi primárních zdrojů a evidenční přílohou. Číst při sporu nebo když krátká verze nestačí.

Datum rozhodnutí: 2026-08-05. Cílový release: 2026-08-20. Status: binding.

---

0. Kontext pro agenta (přečti první)

Položka	Hodnota
Repo	TechsioCZ/new-engine, Nx + pnpm monorepo, Node 24, pnpm 11.15.1
Dotčená aplikace	apps/herbatika (Next.js 16.3.0-preview.5, App Router)
Backend	apps/medusa-be (MedusaJS)
Sdílené knihovny	libs/storefront-data, libs/storefront-i18n, libs/ui, libs/std
Nx wrapper	./node_modules/.bin/nubx --node nx ...
Lint/format	pnpm exec oxfmt --check ., pnpm exec oxlint . --type-aware, pnpm exec ultracite check <cesty>
Typecheck	pnpm typecheck:tsc, pnpm typecheck:tsgo
Pravidla kódu	CLAUDE.md v kořeni + nejbližší AGENTS.md/CLAUDE.md v podstromu

Kritická hranice odpovědností:

• MedusaJS neřeší URL ani routing. Poskytuje katalogová a obchodní data.
• Next.js vlastní routing, generování a parsování URL, canonicalizaci, metadata, sitemap, robots a všechny redirecty vzniklé na novém webu.
• Nikdy nepřidávej do Medusy paralelní URL nebo taxonomický systém.

Business kontext: greenfield URL. Klient si sám řeší migraci ze starého Shoptetu a hosting historických redirectů. Staré URL nezachováváme, redirect mapa je mimo rozsah.

Trhy — pevné mapování, jedna doména = jeden trh = jeden sales channel:

Doména	Market	Locale
herbatica.sk	sk	sk-SK
herbatica.cz	cz	cs-CZ
herbatica.hu	hu	hu-HU
herbatica.ro	ro	ro-RO

Žádný locale prefix typu /cs/ v cestě. Produkty, kategorie, zařazení, názvy, slugy i dostupnost se mezi trhy liší.

---

1. Vítězná architektura — rozhodnutí

• Typový prefix ANO, lokalizovaný, v plurálu. Ne root slugy.
• Produkt bez kategorie v URL: /produkty/{slug}. Produkt ve více kategoriích má jednu URL — žádné duplicity, žádné redirect chains.
• Kategorie plochá: /kategorie/{slug}, ne vnořené cesty. Přesun nebo přejmenování kategorie v Medusa stromu URL nemění. Hierarchie žije jen v breadcrumbech, navigaci a structured data.
• Varianta nemá vlastní URL, jen ?varianta={sku}, canonical na produkt.
• Kolize slugů napříč typy jsou nemožné, protože každý typ má vlastní prefix. Uvnitř typu je hlídá unique index v URL registru.
• Trh se určuje výhradně z hostu. Neznámý host → 421. Žádný Accept-Language fallback, žádný default na SK.
• Slug je po publikaci stabilní. Změna názvu entity URL nemění. Ruční změna slugu vytvoří immutable alias.

Zamítnuto a proč:

Varianta	Důvod zamítnutí
Root slugy bez prefixu (/{slug})	nevyhnutelné kolize mezi produkty, kategoriemi, značkami, články a systémovými routami; křehký resolver
Kategorie v produktové URL	produkt ve více kategoriích = duplicitní URL nebo nestabilní canonical
Vnořené kategoriální cesty (/kategorie/a/b/c)	každý přesun v taxonomii vynutí hromadný redirect a rozbije zavedené URL
Locale prefix /cs/ na doméně jednoho trhu	redundantní, doména už trh jednoznačně určuje
Slug generovaný za běhu z názvu	URL se mění při každé editaci obsahu, ztráta SEO stability
Auto-suffixy -2 při kolizi	tichá degradace URL kvality, nekontrolovatelné duplikáty
Neanglické URL logiky v Medusa metadatech	paralelní systém, který nikdo neudrží

---

2. Kompletní URL matice

Zápis {products} = klíč z registru lokalizovaných segmentů (sekce 3).

Typ	Tvar	SK	CZ	HU	RO	Index	Canonical	Sitemap
Home	/	/	/	/	/	✅	self	✅
Produkt	/{products}/{slug}	/produkty/zeleny-caj	/produkty/zeleny-caj	/termekek/zold-tea	/produse/ceai-verde	✅	self	✅
Varianta	?varianta={sku}	/produkty/zeleny-caj?varianta=ZC-100G	totéž	totéž	totéž	❌	produkt bez query	❌
Kategorie	/{categories}/{slug}	/kategorie/bylinne-caje	/kategorie/bylinne-caje	/kategoriak/gyogynovenyteak	/categorii/ceaiuri-din-plante	✅	self bez filtrů	✅
Rozcestník kategorií	/{categories}	/kategorie	/kategorie	/kategoriak	/categorii	✅	self	✅
Značka	/{brands}/{slug}	/znacky/pukka	/znacky/pukka	/markak/pukka	/marci/pukka	✅	self	✅
Rozcestník značek	/{brands}	/znacky	/znacky	/markak	/marci	✅	self	✅
Kolekce	/{collections}/{slug}	/kolekcie/darceky	/kolekce/darky	/gyujtemenyek/ajandekok	/colectii/cadouri	✅	self	✅
Kampaň	/{campaigns}/{slug}	/akcie/leto	/akce/leto	/akciok/nyar	/promotii/vara	✅	self	✅
SEO landing page	/{campaigns}/{slug}	stejný namespace jako kampaň				✅	self	✅
Blog / poradna	/{advice}/{slug}	/poradna/{slug}	/poradna/{slug}	/tanacsok/{slug}	/sfaturi/{slug}	✅	self	✅
Rozcestník poradny	/{advice}	/poradna	/poradna	/tanacsok	/sfaturi	✅	self	✅
Statická stránka	/{information}/{slug}	/informacie/doprava	/informace/doprava	/informaciok/szallitas	/informatii/livrare	✅	self	✅
Právní stránka	/{information}/{terms}	/informacie/obchodne-podmienky	/informace/obchodni-podminky	/informaciok/altalanos-szerzodesi-feltetelek	/informatii/termeni-si-conditii	✅	self	✅
Hledání	/{search}?q=	/vyhladavanie	/vyhledavani	/kereses	/cautare	❌ noindex	–	❌
Košík	/{cart}	/kosik	/kosik	/kosar	/cos	❌	–	❌
Checkout krok	/{checkout}/{krok}	/pokladna/platba	/pokladna/platba	/penztar/fizetes	/finalizare-comanda/plata	❌	–	❌
Návrat z platby	/{checkout}/{paymentReturn}	/pokladna/navrat-z-platby	/pokladna/navrat-z-platby	/penztar/fizetesi-visszateres	/finalizare-comanda/retur-plata	❌	–	❌
Potvrzení objednávky	/{checkout}/{confirmation}	/pokladna/potvrdenie-objednavky	/pokladna/potvrzeni-objednavky	/penztar/rendeles-visszaigazolas	/finalizare-comanda/confirmare-comanda	❌	–	❌
Účet	/{account}/...	/ucet/objednavky	/ucet/objednavky	/fiok/rendelesek	/cont/comenzi	❌	–	❌
Detail objednávky	/{account}/{orders}/{id}	/ucet/objednavky/{id}	/ucet/objednavky/{id}	/fiok/rendelesek/{id}	/cont/comenzi/{id}	❌	–	❌
Přihlášení	/{account}/{login}	/ucet/prihlasenie	/ucet/prihlaseni	/fiok/bejelentkezes	/cont/autentificare	❌	–	❌
Recenze přes token	/{reviews}/{produkt}/{token}	/recenzie/produkt/{token}	/recenze/produkt/{token}	/velemenyek/termek/{token}	/recenzii/produs/{token}	❌	–	❌
API	/api/...	nelokalizované				❌	–	❌

Chování při chybějící nebo změněné entitě:

Stav	Odpověď
Entita neexistuje	404
Publikovaná entita smazána (tombstone)	410
Starý alias slugu	308 na aktuální canonical
Entita mimo sales channel daného trhu	404
Backend nedostupný	503 — nikdy 404
Neznámý query parametr	400
Neznámý host	421

---

3. Registr lokalizovaných segmentů

Jediný zdroj pravdy, jeden TS soubor. URL hodnoty jsou ASCII transliterace nativních názvů.

Klíč	SK	CZ	HU	RO
products	produkty	produkty	termekek	produse
categories	kategorie	kategorie	kategoriak	categorii
brands	znacky	znacky	markak	marci
collections	kolekcie	kolekce	gyujtemenyek	colectii
campaigns	akcie	akce	akciok	promotii
advice	poradna	poradna	tanacsok	sfaturi
information	informacie	informace	informaciok	informatii
search	vyhladavanie	vyhledavani	kereses	cautare
cart	kosik	kosik	kosar	cos
checkout	pokladna	pokladna	penztar	finalizare-comanda
account	ucet	ucet	fiok	cont
reviews	recenzie	recenze	velemenyek	recenzii
checkout.contact	kontakt	kontakt	kapcsolat	contact
checkout.shipping	doprava	doprava	szallitas	livrare
checkout.payment	platba	platba	fizetes	plata
checkout.review	kontrola	kontrola	ellenorzes	verificare
checkout.paymentReturn	navrat-z-platby	navrat-z-platby	fizetesi-visszateres	retur-plata
checkout.confirmation	potvrdenie-objednavky	potvrzeni-objednavky	rendeles-visszaigazolas	confirmare-comanda
account.orders	objednavky	objednavky	rendelesek	comenzi
account.lists	zoznamy	seznamy	listak	liste
account.settings	nastavenia	nastaveni	beallitasok	setari
account.login	prihlasenie	prihlaseni	bejelentkezes	autentificare
account.register	registracia	registrace	regisztracio	inregistrare
account.forgotPassword	zabudnute-heslo	zapomenute-heslo	elfelejtett-jelszo	parola-uitata
account.resetPassword	obnova-hesla	obnova-hesla	jelszo-visszaallitas	resetare-parola
reviews.product	produkt	produkt	termek	produs
about	o-nas	o-nas	rolunk	despre-noi
contact	kontakt	kontakt	kapcsolat	contact
faq	casto-kladene-otazky	caste-dotazy	gyakori-kerdesek	intrebari-frecvente
shipping	doprava	doprava	szallitas	livrare
returns	vratenie-tovaru	vraceni-zbozi	visszakuldes	retururi
terms	obchodne-podmienky	obchodni-podminky	altalanos-szerzodesi-feltetelek	termeni-si-conditii
privacy	ochrana-osobnych-udajov	ochrana-osobnich-udaju	adatvedelmi-tajekoztato	politica-de-confidentialitate
cookies	cookies	cookies	cookie-tajekoztato	politica-cookies

⚠️ Hodnoty jsou návrh z výzkumu, ne překlad ověřený rodilým mluvčím. Před produkčním spuštěním musí projít nativním editorial sign-offem, právní stránky navíc právním. Schválení mění jen tuto tabulku, ne kód. Viditelný label v UI používá plnou diakritiku (Termékek, Gyűjtemények, Coș, Vyhľadávanie); ASCII je jen v URL.

---

4. Slug pravidla

Normalizační pipeline:

nativní název → NFC → lowercase → ASCII transliterace → nealfanumerické na "-"
             → sloučit opakované "-" → trim "-" → validace

• Transliterace: š→s, č→c, ř→r, ž→z, ý→y, ě→e, ů→u, ő→o, ű→u, á→a, é→e, í→i, ó→o, ú→u, ș→s, ț→t, ă→a, â→a, î→i, ľ→l, ĺ→l, ŕ→r, ô→o, ä→a.
• Rumunština: normalizuj legacy cedilla ş/ţ (U+015F/U+0163) na comma-below ș/ț (U+0219/U+021B) před transliterací.
• Povolené znaky výsledku: pouze [a-z0-9-]. Max 80 znaků.
• Prázdný výsledek transliterace = chyba publikace. Nikdy nefallbackuj na ID nebo náhodný řetězec.
• Kolize uvnitř typu a trhu = chyba publikace, řeší člověk. Žádné auto-suffixy -2.
• Rezervovaná slova (nesmí být slug): api, _next, sitemap, sitemap-index, robots, favicon, assets, static, health, __nextjs.
• Slug se po publikaci negeneruje znovu. Editace názvu entity URL nemění.
• Ruční změna slugu = jedna transakce: zapiš nový current, starý překlop na alias s aliasOf na nový current záznam.
• Aliasy se nikdy neřetězí. Při změně slugu přepiš aliasOf u všech existujících aliasů dané entity na nový current. Alias platí jen pro GET/HEAD.

---

5. URL registr — vlastní Next.js, ne Medusa

Vlastní Postgres schema, vlastní migrace generované vlastníkem frameworku. Nikdy needituj existující migrace, přidávej nové.

export type Market = 'sk' | 'cz' | 'hu' | 'ro'

export type UrlKind =
  | 'product' | 'category' | 'brand' | 'collection'
  | 'campaign' | 'article' | 'page'

export type UrlStatus = 'current' | 'alias' | 'tombstone'

export type UrlRecord = {
  id: string
  market: Market
  kind: UrlKind
  slug: string
  entityId: string          // ID v Meduse nebo CMS
  equivalenceKey: string    // stejný napříč trhy pro tutéž entitu → hreflang
  indexable: boolean
  status: UrlStatus
  aliasOf: string | null    // vždy na current záznam, nikdy na alias
  updatedAt: Date
}

Indexy:

• UNIQUE (market, kind, slug) — vynucuje absenci kolizí
• INDEX (market, kind, entityId) — reverzní lookup pro URL builder
• INDEX (equivalence_key) — hreflang alternates

Seed: jednorázový import z Medusa handle a CMS slugů. Po seedu je registr jediným zdrojem pravdy pro URL; Medusa handle se už pro routing nečte.

---

6. Datový kontrakt s Medusou

Bereme jen tato pole. Nic víc, žádné URL, žádnou taxonomii navíc.

Pole	Vlastník	Zdroj	Existuje dnes?	Fallback
product.id	Medusa	core	✅	–
product.handle	Medusa	core	✅	jen pro seed registru
product.title (lokalizovaný)	Medusa Translation	translation module	částečně	chybějící překlad blokuje publikaci entity na daném trhu
product.categories[]	Medusa	core	✅	–
product.metadata.primary_category_id	Medusa	custom merchandising extension	❌ nutno doplnit	nejhlubší leaf kategorie → nižší rank → nejnižší ID
product.variants[].sku	Medusa	core	✅	–
category.id, handle, name	Medusa	core	✅	–
category.parent_category_id, rank	Medusa	core	✅	–
sales-channel dostupnost	Medusa	core	✅ na backendu, ❌ ve storefront kontextu	–
ceny, sklad	Medusa	core (region + country)	✅	–
editorial obsah	CMS	market + locale scoped	❌ dnes natvrdo sk	žádný — chybějící obsah = 404

Jediná potřebná custom položka je metadata.primary_category_id na produktu — a i bez ní systém funguje díky deterministickému fallbacku. Primary category ovlivňuje jen breadcrumb, structured data a merchandising, nikdy URL.

---

7. Next.js routing

Ověřený stav repozitáře: Next.js 16.3.0-preview.5, App Router, cacheComponents: true (apps/herbatika/next.config.ts:65), typedRoutes: true (:118), output: "standalone" (:83).

Klíčový princip: filesystem router nezná lokalizované segmenty. Řeší je proxy rewrite, takže nevznikají čtyři router forky.

apps/herbatika/src/
  proxy.ts                                   # NOVÝ (dnes chybí)
  app/
    (sf)/[market]/page.tsx                   # home
    (sf)/[market]/[kind]/page.tsx            # rozcestníky typů
    (sf)/[market]/[kind]/[slug]/page.tsx     # detaily entit
    (sf)/[market]/flow/[...seg]/page.tsx     # cart, checkout, account, auth, reviews
    sitemap.ts                               # NOVÝ (dnes chybí)
    robots.ts                                # NOVÝ (dnes chybí)
    api/...                                  # beze změny

Ruší se: app/p, app/c, app/znacka, app/blog, app/o-nas, app/faq, app/reset-password a kořenový app/[slug] (kolidoval by s každou novou statickou routou).

proxy.ts dělá pouze statickou práci — žádné DB ani Medusa dotazy:

1. host → market podle allowlistu; neznámý host → 421
2. první segment cesty → kind podle statické segment mapy
3. rewrite na /{market}/{kind}/{slug}
4. scrub klientských interních hlaviček, vložení trusted market kontextu

Route resolution v page (max 2 dotazy do registru):

1. validace syntaxe cesty a query proti per-kind allowlistu → jinak 400
2. jeden indexovaný lookup do URL registru
3. klasifikace current → render, alias → 308, tombstone → 410, missing → 404
4. volitelně jeden bounded equivalence lookup pro hreflang

Nutná změna configu: skipTrailingSlashRedirect: true, aby se host, protokol, case, trailing slash, alias i query normalizace složily do jediného 308. Dnes chybí.

Jediné URL API — zákaz ad hoc skládání stringů:

buildUrl({ market, kind, slug }): string              // '/produkty/zeleny-caj'
buildAbsoluteUrl({ market, kind, slug }): string      // 'https://herbatica.sk/produkty/...'
buildCanonical(request): string                       // bez query kromě povolených
buildAlternates(equivalenceKey): Array<{ hrefLang, href }>

Dnes se URL skládají ručně na mnoha místech (/p/${product.handle} v product cards, objednávkách, košíku, autocomplete). Všechny musí zmizet, jinak se canonical a sitemap rozejdou se skutečnými URL.

Deployment: jedna multi-host standalone instance za reverse proxy. Multi-instance škálování je blokované, dokud není prokázaná cross-instance cache tag propagace — default cache handler je process-local. Kód ale musí podporovat i čtyři samostatná nasazení téhož buildu s runtime ALLOWED_MARKETS subsetem.

Market a canonical origin musí pocházet ze serverového runtime configu, ne z NEXT_PUBLIC_* — ty jsou build-time inline a jeden build by pak neuměl obsloužit čtyři trhy.

---

8. SEO pravidla

Situace	Chování
Canonical	vždy https, non-www, lowercase, bez koncového /, absolutní URL
Filtr na PLP	indexovatelné jen ?znacka= a ?kategorie=; ostatní noindex, follow
Kombinace 2+ filtrů	noindex, canonical na čistou kategorii
Řazení ?razeni=	noindex, canonical na čistou kategorii
Stránkování ?strana=2	indexovatelné, canonical self, žádné rel=prev/next
Tracking parametry (utm_*, gclid, fbclid)	ignorovat v canonical, žádný redirect
Neznámý query parametr	400
Interní odkazy	jen na canonical tvary, nikdy na alias nebo filtrovanou variantu
hreflang	self + skutečné ekvivalenty přes equivalenceKey; chybějící trh se vynechá
x-default	nepoužívat — všechny čtyři trhy jsou rovnocenné, žádná globální varianta
Produkt jen na některých trzích	hreflang jen pro trhy, kde je skutečně dostupný
Přepínač země	odkazuje na ekvivalent, jinak na home daného trhu — nikdy na 404
Sitemap	sitemap index + per-typ soubory, jen indexovatelné URL, lastModified z registru
robots.txt	per-host, Disallow: /{cart}, /{checkout}, /{account}, /{search}, odkaz na sitemap index
301 vs 308	vždy 308 (zachovává metodu i tělo)
404 vs 410	404 = neexistuje, 410 = publikovaná entita smazána
Soft-404	zakázán — chybějící entita musí vrátit skutečný 404, ne stránku s chybovou hláškou a statusem 200
Backend nedostupný	503, nikdy 404

---

9. Implementační backlog

Must-have pro release

#	Úkol	Závisí na	Acceptance criteria
M01	Segment mapa 4 trhů v jednom TS souboru + collision validator v CI	–	CI selže při duplicitním segmentu nebo kolizi s rezervovaným slovem
M02	URL registr: schema, migrace, indexy	–	UNIQUE (market, kind, slug) vynucen v DB, ne jen v kódu
M03	Seed registru z Medusa handle a CMS slugů	M02	všechny publikované entity mají current záznam ve všech trzích, kde jsou dostupné
M04	Admin CRUD pro ruční změnu slugu s atomickým zápisem aliasu	M02	změna slugu vytvoří alias; opakovaná změna nevytvoří řetěz, přepíše aliasOf
M05	Slugifikační modul se 4jazyčnou transliterací	M01	prázdný výsledek i kolize vyhodí typovanou chybu, ne fallback
M06	src/proxy.ts — host→market, segment→kind, rewrite, 421	M01	neznámý host vrátí 421 na drátě; žádná SK response pro cizí host
M07	Přestavba app/ na (sf)/[market]/[kind]/..., zrušení /p, /c, /znacka, /blog, root /[slug]	M06	žádná dvojznačná dynamická routa; collision validator zelený
M08	URL API + odstranění všech ručně skládaných odkazů	M02, M07	grep nenajde žádné /p/${, /c/${ ani obdobné skládání mimo URL API
M09	Status vrstva: 308, 404, 410, 503, 400 + notFound() na produktu	M07	wire testy potvrdí skutečné HTTP statusy před flushem response
M10	generateMetadata — canonical + alternates	M08	každá indexovatelná stránka má absolutní self canonical a reciproční hreflang
M11	app/sitemap.ts + sitemap index	M02, M08	sitemap obsahuje jen indexovatelné URL, validní XML, per-host
M12	app/robots.ts per-host	M01	každá doména vrací vlastní robots s vlastním sitemap odkazem
M13	skipTrailingSlashRedirect: true v next.config.ts	M09	normalizace host + case + trailing slash + alias proběhne jedním 308
M14	Odstranit natvrdo zadané CMS_LOCALE = "sk" (apps/herbatika/src/lib/storefront/cms-client.ts:9)	–	každý trh dostane obsah ve své locale; chybějící obsah = 404, ne slovenský fallback
M15	Přidat salesChannelId do market kontextu (market-context.ts)	–	katalogové dotazy filtrují podle sales channelu; entita mimo channel vrací 404
M16	Zrušit Accept-Language fallback a default sk v resolveru trhu	M06	neznámý host nikdy nevrátí obsah, jen 421
M17	metadata.primary_category_id extension v Meduse + fallback logika	–	breadcrumb je deterministický i bez vyplněné hodnoty
M18	Nativní editorial + právní sign-off segment mapy	M01	každá hodnota má schvalovatele a datum; právní stránky schváleny právně

Should-have

• Kampaně a SEO landing pages jako plnohodnotný typ s vlastním editorem.
• Alias historie viditelná v adminu.
• Redirect a canonical audit jako CI job nad build outputem.
• Structured data (Product, BreadcrumbList, ItemList) navázané na URL API.

Later

• Multi-instance horizontal scaling — blokované process-local cache handlerem.
• x-default, pokud vznikne skutečná globální varianta webu.

---

10. Testovací plán

Unit:

• slugifikace všech 4 jazyků včetně rumunské cedilla normalizace a maďarských dlouhých samohlásek
• prázdný a kolizní výsledek vyhodí chybu
• alias nikdy neřetězí (aliasOf vždy míří na current)
• segment mapa bez kolizí a bez rezervovaných slov
• canonical builder: protokol, host, case, trailing slash, povolené query

Integration:

Případ	Očekávaný status
každý typ × 4 trhy, existující entita	200
alias slugu	308 na canonical
tombstone	410
neexistující slug	404
produkt mimo sales channel trhu	404
neznámý host	421
neznámý query parametr	400
Medusa nedostupná	503
POST na alias	žádný redirect

Browser / E2E:

• přepínač země vede na ekvivalent, jinak na home — nikdy na 404
• canonical a hreflang přítomné v HTML, hreflang reciproční mezi doménami
• stránkování ?strana=2 je indexovatelné, filtry noindex
• sitemap index i dílčí sitemapy jsou validní XML a obsahují jen indexovatelné URL
• trailing slash, velká písmena a www se normalizují jedním hopem
• viditelné labely mají plnou diakritiku, URL jsou ASCII

---

11. Stav repozitáře — co je dnes rozbité

Ověřeno v pracovním stromu 2026-08-05.

Zjištění	Soubor
Žádný middleware ani proxy	apps/herbatika/src/proxy.ts neexistuje
Žádná sitemap ani robots	app/sitemap.ts, app/robots.ts neexistují
Žádné canonical ani hreflang nikde v aplikaci	0 výskytů alternates
Produkt nevolá notFound() → soft-404 se statusem 200	app/p/[handle]/page.tsx
CMS natvrdo slovensky pro všechny čtyři trhy	src/lib/storefront/cms-client.ts:9
Sales channel chybí v market kontextu, jede se jen na region + country	src/lib/storefront/market-context.ts
Kořenový /[slug] koliduje s libovolnou novou statickou routou	app/[slug]/page.tsx
Chybí skipTrailingSlashRedirect	next.config.ts
Trh fallbackuje přes Accept-Language na SK	libs/storefront-i18n/src/core/markets.ts
Aktuální routy k odstranění	app/p, app/c, app/znacka, app/blog, app/o-nas, app/faq, app/reset-password

---

12. Definition of done

• Všechny úkoly M01–M18 hotové a zelené v CI
• pnpm exec oxfmt --check . a pnpm exec oxlint . --type-aware zelené
• pnpm typecheck:tsc a pnpm typecheck:tsgo zelené
• pnpm exec ultracite check <změněné cesty> zelené
• Wire test suite potvrdí všechny statusy z tabulky v sekci 10
• Žádná dvojznačná dynamická routa, collision validator zelený
• Segment mapa má nativní sign-off, právní stránky právní sign-off
• Žádné ručně skládané URL mimo URL API
• Všechny čtyři domény vrací vlastní robots, sitemap, canonical a hreflang

---

13. Metodologická poznámka

Specifikace vznikla vícefázovým multi-agentním výzkumem: průzkum repozitáře, primární webový research (Google Search Central, Next.js dokumentace a source instalované verze, RFC/WHATWG), tři nezávislé návrhy architektury, adversarial verifikace tvrzení a route kolizí, syntéza a completeness kritika. Plná evidenční příloha s citacemi, datem přístupu a mírou jistoty je v komentářích níže.

Kde primární zdroj nedával jednoznačnou odpověď, je rozhodnutí označeno jako architecture choice [AC] a nevydává se za doložené SEO pravidlo. Klíčová slova v URL nejsou v této specifikaci považována za významný ranking faktor; lokalizace slugů je UX a IA rozhodnutí.

Recenzní vlastnictví: @RedEyeCZ — proxy, deployment, Docker, CI, migrace. @KaiUweCZE — Next.js routing, frontend chování, libs/ui, přístupnost.

[BleedingDev]

Plná normativní specifikace — část 01/5. Krátká implementační verze je v popisu issue; tato část je závazný zdroj při sporu.

---

ZÁVAZNÝ ROZHODOVACÍ ZÁZNAM

URL/SEO architektura reusable Next.js e-commerce core — Herbatica first

Sekce 01 — Executive decision a normativní obecný standard

Položka	Hodnota
Datum rozhodnutí	2026-08-05
Cílový release	2026-08-20
Status	Binding
První konfigurace	Herbatica
Frameworková autorita	Next.js v16.3.0-preview.5, tagovaný source v instalovaném node_modules
Router	App Router
Deployment default	Jedna multi-host standalone single-instance aplikace za reverse proxy
Trhy	sk, cz, hu, ro
Domény	herbatica.sk, herbatica.cz, herbatica.hu, herbatica.ro
Locale	sk-SK, cs-CZ, hu-HU, ro-RO
Základní invariant	Jedna doména = jeden market = jeden sales channel = jeden publishable key
Vlastník veřejných URL	Next.js
Vlastník katalogových a obchodních dat	Medusa
Gate G1 — native editorial/legal sign-off segmentů	2026-08-07
Gate G2 — inventarizace publikovaných root CMS URL	2026-08-08
Gate G3 — wire důkaz 410 dispatch mechanismu	2026-08-14
Gate G4 — production-wire hard-status suite pro cacheComponents	2026-08-17

Normativní výrazy MUST, MUST NOT, SHOULD, SHOULD NOT a MAY jsou závazné ve významu RFC 2119/RFC 8174. Značka [AC] označuje explicitní architecture choice projektu, nikoli tvrzení externí autority; kde primární zdroj dokládá i jinou validní variantu, je to uvedeno. Klíčová slova URL nejsou nikde v tomto dokumentu považována za významný ranking faktor; lokalizace slugů je UX/IA rozhodnutí.

Struktura dokumentu

Dokument se skládá ze čtyř částí. Číslování kapitol je platné vždy v rámci své části; odkazy typu „sekce 4.18“ míří do části A, „sekce 6.13“ do části C.

Požadovaný výstup	Umístění
1. Executive decision	Část A, kap. 1–3
2. Obecný normativní URL standard	Část A, kap. 4
3. Kompletní URL matice	Část B
4. Konfigurace Herbatica (SK/CZ/HU/RO)	Část B, registr segmentů a příklady
5. Next.js routing specifikace	Část C, kap. 5
6. Datový kontrakt s Medusou	Část C, kap. 6
7. SEO rozhodovací tabulky	Část D, kap. 7
8. Zamítnuté varianty	Část A, kap. 6
9. Implementační backlog	Část D, kap. 9
10. Testovací plán	Část D, kap. 10
11. Evidenční příloha	Část D, kap. 11 (+ Část A, kap. 7)
Release gates a blockery	Část A, kap. 5; Část D, kap. 12

---

ČÁST A — Executive decision a normativní standard

1. Executive decision

Veřejná URL architektura bude tvořena jediným reusable Next.js storefront core s host-based market resolution, lokalizovanými plurálními type prefixy a Next-owned URL registry (dále URLR). Medusa zůstává výhradním vlastníkem katalogových a obchodních dat; nebude obsahovat paralelní router, SEO taxonomii ani historii veřejných URL.

Každá veřejná commerce nebo content entita bude mít v jednom marketu nejvýše jednu current canonical URL. Publikovaný slug bude stabilní. Manuální změna slugu atomicky vytvoří immutable alias vedoucí přímo na nový canonical target. Alias chains, automatické suffixy typu -2 a runtime slugifikace jsou zakázány.

Produktová URL nebude obsahovat kategorii. Kategorie budou mít plochou canonical URL nezávislou na umístění ve stromu. Multi-category produkt bude mít jedinou produktovou URL; primary category bude ovlivňovat pouze breadcrumb a merchandising.

Veřejné routes budou lokalizované podle hostu, bez locale prefixu v path. Filesystem nebude obsahovat čtyři market router forks. proxy.ts bude pouze statická trust-boundary a rewrite vrstva; databázová URL resolution proběhne až v interní server route před zahájením streamingu.

Canonical URL, hreflang, sitemap, Open Graph URL, structured-data URL a interní odkazy budou generovány jediným typed URL API. Ad hoc skládání URL bude release-blocking porušení.

Canonicalizace hostu, case, trailing slash, aliasu a query se složí do jednoho permanentního 308 redirectu, prováděného výhradně pro GET/HEAD. HTTPS může být vynuceno ingress vrstvou jako jediný dodatečný hop. Neexistující veřejná entita vrátí skutečný HTTP 404; explicitní public tombstone vrátí 410 — mechanismus doručení 410 je vázán na wire důkaz (gate G3) se závazným fallbackem 404 (sekce 4.18); backend failure vrátí 503. Soft-404 je nepřípustný.

Cross-domain alternates budou publikovány pouze pro explicitně mapované a skutečně dostupné ekvivalenty přes URLR equivalence_key. Každý market bude self-referential. Chybějící ekvivalent se vynechá. x-default se v release nepoužije [AC].

Release běží jako jedna standalone instance na environment (Docker za reverse proxy). Multi-instance škálování a Netlify adapter pro storefront jsou mimo release scope, dokud nebude prokázán shared cache handler a cross-instance tag propagation (sekce 2.2).

---

2. Architektura

Klient / crawler
      |
      v
Ingress / reverse proxy
  - TLS + HTTPS redirect (jediný povolený dodatečný hop)
  - raw request-target a authority validace, 414 limit
  - přepis trusted forwarded headers
      |
      v
Next.js proxy.ts (statická vrstva, žádné DB/Medusa/CMS/URLR čtení)
  - canonical host allowlist, host -> market
  - blokace /~sf ve všech case/percent variantách vč. %257E
  - scrub klientských interních headers, vložení trusted market contextu
  - statický localized-prefix -> kind rewrite na /~sf/{market}/{kind}/...
  - host-scoped robots/sitemap/manifest rewrite
      |
      v
Interní semantic route /~sf/{market}/{kind}/...
      |
      v
URL resolver (před prvním flush)
  - syntax + query schema validace (per-kind allowlist)
  - 1 indexed URLR lookup + max 1 bounded equivalence lookup
  - klasifikace current | alias | tombstone | missing
  - composed 308 / 400 / 404 / 410 / 503
      |
      +---------------------------+
      |                           |
      v                           v
Next-owned URLR             Medusa / CMS
  - current slug              - product/category/brand/collection data
  - immutable aliases         - prices/stock/availability
  - tombstones                - sales-channel assignments
  - equivalence keys          - localized catalog content (Translation)
  - index policy              - editorial/legal content (CMS, market locale)
  - timestamps                
      |                           |
      +------------+--------------+
                   v
             Server render
                   |
                   v
canonical / hreflang / metadata / JSON-LD / internal links / response

2.1 Vlastnické hranice

Oblast	Vlastník
Produkty, varianty, ceny, stock	Medusa
Kategorie, strom, rank, assignments	Medusa
Brands, collections, regions, sales channels	Medusa
Market availability (per entity kind, sekce 2.5)	Medusa
Katalogové názvy a popisy	Medusa Translation; chybějící překlad MUST blokovat publish entity v daném marketu
Primary category (merchandising extension)	Medusa
Editorial a právní obsah	CMS, market- a locale-scoped
UI/system texty a statické route segmenty	Next locale resources
Veřejná route taxonomie, parser, builder, canonicalization	Next.js
Current slug, alias, tombstone, equivalence key, index policy, timestamps	Next-owned URLR (samostatné Postgres schema, vlastní migrace)
Metadata, canonical, hreflang, sitemap, robots	Next.js
Redirecty vzniklé na novém webu	Next.js
Historické Shoptet redirecty	Mimo rozsah
Market runtime contract (sekce 2.3)	Next server runtime config

2.2 Deployment a cardinality

1. Release MUST běžet jako jedna multi-host standalone single-instance aplikace na environment (Docker za reverse proxy), protože default cache handler a tag invalidation jsou process-local a shared multi-instance cache handler není v repu doložen ani otestován.
2. Core MUST podporovat i čtyři samostatná nasazení téhož buildu s runtime ALLOWED_MARKETS subsetem; každé nasazení je v release rovněž single-instance.
3. Multi-instance horizontal scaling a Netlify adapter pro storefront MUST NOT být použity v release. Jejich zavedení je samostatná post-release změna podmíněná: zvoleným custom cache handlerem s veřejným kontraktem, prokázanou cross-instance tag propagation, shared Server Functions encryption key a rolling deploymentId; do splnění platí single-instance omezení.
4. Market a canonical origin MUST pocházet ze serverového runtime configu. MUST NOT být odvozeny pouze z NEXT_PUBLIC_*, protože tyto hodnoty jsou build-time inline (release blocker RB-10).
5. Unknown host MUST NOT fallbackovat podle Accept-Language ani na slovenský market; MUST být odmítnut jako 421 Misdirected Request (release blocker RB-1).
6. x-forwarded-host/x-forwarded-proto jsou důvěryhodné jen za proxy, která je přepisuje; trust boundary MUST být doložena a wire-testována per environment.

2.3 Market runtime contract

Server MUST držet validovaný typed kontrakt:

market -> {
  canonicalOrigin,      // https://herbatica.sk
  hostAliases[],        // www.*, vlastněné herbatika.* varianty
  locale,               // sk-SK | cs-CZ | hu-HU | ro-RO
  countryCode,          // SK | CZ | HU | RO
  regionId,             // Medusa region
  salesChannelId,       // právě jeden channel
  publishableKey,       // právě jeden key
  allowedDeployment     // membership v ALLOWED_MARKETS
}

1. Kontrakt MUST být validován při bootu (schema validace, fail-fast).
2. Server MUST vybírat market-specific SDK klient, cache scope a CMS locale výhradně podle tohoto kontraktu.
3. Klient MUST dostat pouze publishable key aktuálního marketu, předaný ze serveru; build MUST NOT obsahovat klíče ostatních marketů.
4. Globální SDK singleton apps/herbatika/src/lib/storefront/sdk.ts a build-time NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY v Docker/Netlify konfiguraci jsou release blockery (RB-10).
5. Klient MUST NOT odvozovat business market z window.location.

2.4 Medusa startup validace

Boot každého storefront deploymentu MUST pro každý market v ALLOWED_MARKETS prokázat proti Medusa Admin API:

1. publishable key existuje a je aktivní;
2. key je linknut právě na očekávaný salesChannelId a na žádný jiný channel (Medusa připouští multi-channel klíč, proto se scope ověřuje testem, ne předpokladem);
3. tento channel není přiřazen žádnému jinému marketu;
4. regionId existuje a obsahuje countryCode marketu.

Neshoda MUST být fail-fast boot error; multi-channel klíč blokuje release. Současný apps/medusa-be/src/utils/publishable-key.ts pouze vytváří jeden klíč podle title a link na sales channel nevytváří ani neověřuje — rozšíření je release blocker (RB-11). Stejná validace MUST existovat jako integration test pro všechny čtyři markety.

2.5 Market availability model per entity kind

1. Product: built-in Medusa product↔sales-channel link; Store API čtení MUST být filtrováno publishable key + channel scope.
2. Category, brand, collection: závazně se zavádějí explicitní Medusa module links category↔sales_channel, brand↔sales_channel, collection↔sales_channel (navržené rozšíření, nikoli standardní Medusa field). Derivační model (availability odvozená z produktové membership) je zamítnut jako nedeterministický.
3. Pro každý kind MUST existovat: publish workflow, který link nastavuje; Store API čtení filtrované podle channelu marketu; a 404 pravidlo — entita bez linku na channel marketu je definitive-missing. /store/brands dnes vrací globální seznam a sales_channel_id filtruje pouze /store/brands/:id/products — market-scoped čtení je release blocker (RB-14).
4. Změna availability linku MUST event-driven invalidovat cache, hreflang a sitemap (sekce 4.22).

2.6 Diskriminovaný read contract

Všechna čtení URLR, Medusy a CMS MUST vracet diskriminovaný výsledek, nikoli null:

found(data) | definitive-missing | unavailable(cause) | invalid-response(cause)

1. found → render; definitive-missing → 404 (resp. 410 u tombstone); unavailable (timeout, network, 5xx) → 503; invalid-response (schema mismatch, neparsovatelné tělo) → 503 + alert.
2. Backendové HTTP 404 smí být mapováno na definitive-missing pouze u endpointů, jejichž kontrakt miss sémanticky garantuje; jinak invalid-response.
3. Každé čtení MUST mít bounded timeout, cancellation a bounded retry.
4. Současný apps/herbatika/src/lib/storefront/cms-client.ts převádí network error i non-2xx na null, což porušuje pravidlo „backend failure → 503“ — release blocker (RB-15).

---

3. Rozhodovací trade-offs

Rozhodnutí	Přínos	Přijatá cena
Plurální lokalizované type prefixy	Jasné namespaces, přirozený index i detail	Delší URL než /p/ a /c/
Plochá category URL	Stabilita při přesunu ve stromu	Hierarchie není zakódována v path
Produkt bez kategorie v URL	Jedna canonical URL pro multi-category produkt	Breadcrumb se musí skládat z dat
Next-owned URLR	Stabilní slug lifecycle a alias history mimo Medusa	Samostatné schema, migrace a invalidace
ASCII slugy [AC]	Predikovatelné zápisy, interoperabilita, jednodušší kolize	Transliterace může sloučit odlišné výrazy
Semantic interní namespace ~sf	Jeden router bez market forks	Vyžaduje důsledné blokování přímého přístupu
URLR lookup mimo Proxy	Čistá trust boundary a snadnější provozní chování	Resolver musí běžet před renderingem
Flat canonical + hluboká taxonomy	Stabilní URL a flexibilní merchandising	URL sama nevyjadřuje rodičovskou cestu
Hreflang pouze pro explicitní ekvivalenty	Žádné syntetické nebo neplatné alternates	Neúplné entity mají menší alternate set
Facety jako noindex bez canonical [AC]	Deterministická kontrola indexového prostoru	SEO landing pages se musí vytvářet explicitně
Pagination page>=2 indexovatelná	Crawlable hlubší katalog	Větší počet indexovatelných listing pages
Jeden URL builder	Eliminace driftu mezi SEO povrchy	Přísná závislost všech consumerů na shared API
Hard HTTP status před streamingem	Bez soft-404 a meta redirectů	Existence check nesmí být odložen za první flush
Single-instance release deployment	Prokazatelná cache konzistence bez shared handleru	Horizontální škálování až post-release
Explicitní availability links pro category/brand/collection	Deterministické 404 per market	Složitější publish workflow v Meduse
410 podmíněné wire důkazem, fallback 404	Žádný neprokázaný dispatch mechanismus v release	Do důkazu slabší removal signál (404 místo 410)

---

4. Normativní obecný URL standard

4.1 Market a origin

1. Jedna veřejná canonical doména MUST odpovídat právě jednomu marketu, locale, country, regionu, publishable key a sales channelu (kontrakt 2.3, validace 2.4).
2. Jeden market MUST NOT být současně publikován pod více canonical hosty.
3. Canonical origins jsou:
   • https://herbatica.sk → sk, sk-SK;
   • https://herbatica.cz → cz, cs-CZ;
   • https://herbatica.hu → hu, hu-HU;
   • https://herbatica.ro → ro, ro-RO.
4. Veřejné URL MUST NOT obsahovat locale prefix typu /sk/, /cs/, /hu/ nebo /ro/.
5. www a vlastněné varianty herbatika.* MAY existovat pouze jako host aliases a MUST permanentně přesměrovat (308) na příslušný canonical origin. Host alias smí být slíben pouze pro doménu s ověřeným vlastnictvím evidovaným v hostAliases kontraktu 2.3.
6. Klientský Host, X-Forwarded-Host, X-Forwarded-Proto nebo market header MUST NOT být použit bez validované ingress trust boundary.
7. Proxy MUST klientské interní market headers odstranit a nastavit vlastní trusted hodnoty.
8. Neznámý nebo nepovolený host MUST vrátit 421; nesmí být přesměrován na homepage jiného marketu ani obsloužen SK obsahem.

4.2 Lokalizované namespaces — navržené, pending native editorial/legal sign-off (gate G1: 2026-08-07)

Statické segmenty MUST pocházet z jediného typed Next locale registry. Parser, builder, navigace, metadata, redirects a testy MUST používat tutéž registraci. Všechny segmenty v tabulkách 4.2.1–4.2.3 mají status navržené; do dokončení native editorial/legal sign-off MUST NOT být označovány jako verified nebo frozen. Oprava před první publikací alias nevytváří; oprava po publikaci alias vytváří (4.8.3). Po sign-off je registry frozen.

4.2.1 Type prefixy a flow roots

Kind	SK	CZ	HU	RO
Products	produkty	produkty	termekek	produse
Categories	kategorie	kategorie	kategoriak	categorii
Brands	znacky	znacky	markak	marci
Collections	kolekcie	kolekce	gyujtemenyek	colectii
Campaigns	akcie	akce	akciok	promotii
Advice/editorial	poradna	poradna	tanacsok	sfaturi
Information	informacie	informace	informaciok	informatii
Search	vyhladavanie	vyhledavani	kereses	cautare
Cart	kosik	kosik	kosar	cos
Checkout	pokladna	pokladna	penztar	finalizare-comanda
Account	ucet	ucet	fiok	cont
Reviews	recenzie	recenze	velemenyek	recenzii

4.2.2 Static public pages (všech osm kinds)

Kind	SK	CZ	HU	RO
About	o-nas	o-nas	rolunk	despre-noi
Contact	kontakt	kontakt	kapcsolat	contact
FAQ	caste-otazky	caste-dotazy	gyik	intrebari-frecvente
Shipping and payment	doprava-a-platba	doprava-a-platba	szallitas-es-fizetes	livrare-si-plata
Returns	vratenie-tovaru	vraceni-zbozi	visszakuldes	retururi
Terms and conditions	obchodne-podmienky	obchodni-podminky	aszf	termeni-si-conditii
Privacy	ochrana-osobnych-udajov	ochrana-osobnich-udaju	adatvedelem	protectia-datelor
Cookies	zasady-cookies	zasady-cookies	sutik	politica-cookie

4.2.3 Flow children (account, auth, checkout, reviews)

Kind	SK	CZ	HU	RO
Login	prihlasenie	prihlaseni	bejelentkezes	autentificare
Registration	registracia	registrace	regisztracio	inregistrare
Forgot password	zabudnute-heslo	zapomenute-heslo	elfelejtett-jelszo	parola-uitata
Reset password	obnova-hesla	obnoveni-hesla	uj-jelszo	resetare-parola
Orders	objednavky	objednavky	rendelesek	comenzi
Wishlist/lists	oblubene	oblibene	kivansaglista	favorite
Settings	nastavenia	nastaveni	beallitasok	setari
Checkout step: contact	udaje	udaje	adatok	date
Checkout step: shipping	doprava	doprava	szallitas	livrare
Checkout step: payment	platba	platba	fizetes	plata
Checkout step: summary	suhrn	souhrn	osszegzes	sumar
Payment return	navrat-z-platby	navrat-z-platby	fizetesi-visszateres	intoarcere-plata
Order confirmation	potvrdenie	potvrzeni	visszaigazolas	confirmare

4.2.4 Pravidla

1. Prefixy MUST být plurální.
2. Lokalizovaný prefix MUST být statický config, nikoli katalogová hodnota z Medusy; MUST NOT být odvozován z Medusa storefront texts.
3. Kořenový dynamický route /{slug} MUST NOT existovat (root inventarizace 4.24).
4. Stejný entity slug MAY existovat v různých type namespaces.
5. V jednom marketu a jednom kind MUST být current slug i alias globálně unikátní.
6. Namespace kolize MUST zastavit build, config deployment nebo publish transakci.

4.3 Route classes

Typ	Veřejný tvar	Výchozí indexace	Sitemap
Homepage	/	index	ano
Product index	/{products}	index	ano
Product detail	/{products}/{slug}	index	ano
Category index	/{categories}	index	ano
Category detail	/{categories}/{slug}	index	ano
Brand index	/{brands}	index	ano
Brand detail	/{brands}/{slug}	index	ano
Collection index	/{collections}	index	ano
Collection detail	/{collections}/{slug}	index	ano
Campaign index	/{campaigns}	index	ano
Campaign detail	/{campaigns}/{slug}	index dle URLR policy	pokud index
Advice index	/{advice}	index	ano
Advice article	/{advice}/{slug}	index	ano
Information detail	/{information}/{slug}	index dle obsahu	pokud index
Information root	/{information}	404	ne
Static public page	/{localized-static-segment}	index	ano
Search	/{search}?q=...	noindex	ne
Cart	/{cart}	noindex	ne
Checkout step	/{checkout}/{step}	noindex	ne
Payment return	`/{checkout}/{payment-return}?...signed schema	noindex	ne
Order confirmation	/{checkout}/{confirmation}/{publicOrderId}	noindex	ne
Account overview	/{account}	noindex	ne
Login	/{account}/{login}	noindex	ne
Registration	/{account}/{registration}	noindex	ne
Forgot password	/{account}/{forgot-password}	noindex	ne
Reset password (token)	/{account}/{reset-password}/{token}	noindex	ne
Orders	/{account}/{orders}	noindex	ne
Order detail	/{account}/{orders}/{publicOrderId}	noindex	ne
Wishlist/lists	/{account}/{lists}	noindex	ne
Settings	/{account}/{settings}	noindex	ne
Review token flow	/{reviews}/{token}	noindex	ne
Robots	/robots.txt	systémová route	ne
Sitemap index	/sitemap.xml	systémová route	ne
Sitemap shard	/sitemaps/{kind}-{n}.xml	systémová route	ne
Manifest	/manifest.webmanifest	systémová route	ne
Product feed	/feeds/products.xml	systémová route	ne
API	/api/...	neveřejný SEO povrch	ne
Internal router	/~sf/...	nepřístupný	ne

4.3.1 Prefix roots

products, categories, brands, collections, campaigns a advice roots MUST být skutečné indexové stránky s vlastním obsahem, self-canonical URL a sitemap membership. information root MUST v release vrátit 404; generic content detail MUST být dostupný pouze jako /{information}/{slug}.

4.3.2 Static public pages

Osm page kinds z 4.2.2 MUST mít lokalizovaný statický segment v route registry. Statické segmenty MUST NOT být odvozovány z Medusa storefront texts. Jejich změna po první publikaci MUST vytvořit alias stejně jako změna entity slugu.

4.3.3 Flow routes

1. Typed registry MUST explicitně obsahovat všechny tvary z tabulky 4.3 (login, registration, forgot/reset password, account overview/orders/order detail/lists/settings, checkout kroky, payment return, order confirmation, review token) pro všechny čtyři markety; zástupné /{account}/... bez registrace konkrétního child MUST NOT existovat.
2. Legacy /reset-password je závazně new-site alias: 308 na /{account}/{reset-password} daného marketu se zachováním token parametru; jako current route se ruší.
3. {token} a {publicOrderId} jsou case-preserving (4.9.9).

4.4 Produkty

1. Canonical produktová URL MUST mít tvar /{products}/{productSlug}.
2. Produktová URL MUST NOT obsahovat category slug, brand slug ani jiný taxonomický parent.
3. Jeden produkt smí mít v jednom marketu právě jednu current canonical URL.
4. Multi-category produkt MUST NOT vytvářet duplicitní produktové URL.
5. Primary category smí ovlivňovat breadcrumb, navigaci a BreadcrumbList, nikoli canonical path.
6. Primary category MUST být Medusa merchandising data (validovaná metadata.primary_category_id — navržené rozšíření, nikoli standardní field). URLR ji MUST NOT vlastnit.
7. Není-li primary category explicitně nastavena, fallback MUST být deterministický [AC]:
   1. nejhlubší dostupná leaf category;
   2. nižší category rank;
   3. lexikograficky nejnižší stabilní ID.
8. Produkt mimo market nebo sales channel MUST vrátit 404, i když jeho URLR current slug existuje; URLR current route sama availability nedokazuje.
9. Vyprodaný, ale stále publikovaný produkt MUST vrátit 200, zůstat indexovatelný, zůstat v sitemapě [AC] a uvést správnou availability v UI i structured data.
10. Produkt odstraněný bez náhrady MUST po vytvoření public tombstone vrátit 410 v cílovém stavu; doručení 410 podléhá gate G3 s fallbackem 404 (4.18.5).
11. Produkt nahrazený skutečným nástupcem MUST vrátit 308 přímo na canonical URL nástupce.
12. Variant selection MAY používat ?variant=...; canonical MUST zůstat na base product URL a přímé otevření MUST vykreslit správný variant state.

4.5 Kategorie

1. Canonical category URL MUST mít tvar /{categories}/{categorySlug}.
2. Category URL MUST být plochá bez parent segmentů.
3. Přesun kategorie ve stromu MUST NOT změnit její URL.
4. Přesun MUST invalidovat breadcrumb, navigaci a structured data přes taxonomyModifiedAt (4.23); sitemap lastModified mění pouze podle pravidel 4.23.
5. Medusa taxonomy depth MAY být libovolná, pokud jsou čtení bounded a paginated.
6. Ve storefront navigaci MUST být zobrazeno nejvýše pět úrovní [AC].
7. Category slug MUST být unikátní v rámci (market, category kind).
8. Změna category slugu MUST vytvořit immutable alias.
9. Chybějící nebo market-unavailable kategorie (bez availability linku 2.5) MUST vrátit 404.
10. Listing category smí zahrnout descendants podle Medusa taxonomy, ale query MUST mít explicitní bounds.

4.6 Brands, collections, campaigns a content

1. Brand URL MUST mít tvar /{brands}/{slug}.
2. Brand slug MUST být uložen v URLR; MUST NOT být za runtime odvozován z title (release blocker RB-9).
3. Brand kolize MUST blokovat publikaci; strategie „first wins“ je zakázána.
4. Collection URL MUST mít tvar /{collections}/{slug}.
5. Campaign URL MUST mít tvar /{campaigns}/{slug}.
6. Campaign indexability MUST být explicitní URLR policy; expirovaná kampaň MUST NOT automaticky přesměrovat na homepage.
7. Advice article MUST mít tvar /{advice}/{slug}.
8. Generic informational content MUST mít tvar /{information}/{slug}.
9. CMS content MUST být market- a locale-scoped; CMS request MUST nést locale marketu z kontraktu 2.3 (release blocker RB-3).
10. Slovenský obsah MUST NOT sloužit jako tichý fallback pro CZ, HU nebo RO.
11. Právní a informační obsah MUST mít explicitní publish state pro každý market (CMS locales vč. hu, ro — release blocker RB-4).
12. Brand/collection/campaign availability per market se řídí modelem 2.5.

4.7 Cart, checkout, account, auth a token routes

1. Cart, checkout, account, auth a token routes MUST být lokalizované pomocí route registry (4.2.3).
2. Tyto routes MUST emitovat noindex a MUST NOT být v sitemapě.
3. Token routes MUST NOT emitovat canonical, hreflang, Open Graph URL ani public structured-data URL.
4. Token MUST NOT vstoupit do metadata, logovaného page title ani veřejné telemetry bez redakce.
5. Invalidní, použitý nebo expirovaný token MUST vrátit jednotné 404; token status MUST NOT vytvářet informační oracle.
6. Checkout step keys MUST být typed config-owned hodnoty (4.2.3); neplatný checkout step MUST vrátit dočasný 307 na default step. Validace stepu MUST proběhnout před connection() a před zahájením streamingu.
7. Payment/provider callback routes MUST mít přesné route-specific query schema; signed provider parametry MUST NOT procházet generickým query sort/strip redirectem.
8. Account order detail MUST ověřit vlastnictví objednávky; cizí nebo neexistující order ID musí vrátit stejný 404.
9. Public order IDs, tokeny a provider values MUST zachovat case a MUST NOT být lowercase-normalizovány.

4.8 Slug standard

4.8.1 Formát

Entity slug MUST odpovídat:

[a-z0-9]+(?:-[a-z0-9]+)*

Maximální délka je 80 znaků [AC]. Lowercase ASCII je provozní volba [AC] — Google podporuje i UTF-8 URL; ASCII nepřináší ranking výhodu.

1. Uložené slugy MUST být lowercase ASCII.
2. Slug MUST být generován pouze při publish/edit transakci.
3. Slug MUST NOT být generován za runtime z názvu, handle nebo title.
4. Publikovaný slug MUST zůstat stabilní, dokud editor explicitně neschválí SEO slug change.
5. Medusa handle MAY být použit pouze jako import candidate při prvním seedu URLR.
6. Runtime entity lookup MUST používat stabilní entity ID uložené v URLR, nikoli Medusa handle.
7. libs/std/src/string.ts MUST NOT být použit pro slugifikaci (odstraňuje diakritiku destruktivně: čaj → aj).

4.8.2 Normalizační pipeline

Publish-time pipeline MUST provést v tomto pořadí:

1. trim;
2. Unicode NFKC;
3. normalizaci rumunských legacy cedilla znaků na comma-below;
4. locale-aware lowercase;
5. zmrazenou a versioned transliterační tabulku SK/CZ/HU/RO;
6. versioned fallback pro ostatní Latin znaky;
7. převod separátorů na -;
8. collapse opakovaných -;
9. odstranění leading a trailing -;
10. schema a collision validation.

Prázdný výsledek MUST zablokovat publikaci. Kolize, včetně transliteračních kolizí typu HU kor × kór, MUST zablokovat publikaci. Systém MUST NOT řešit kolizi tichým doplněním -2, timestampu nebo entity ID.

4.8.3 Manuální změna

Slug change MUST být jediná atomická transakce:

1. validace nového slugu;
2. rezervace nové normalized path;
3. přepnutí current route;
4. vytvoření immutable aliasu ze starého slugu;
5. přímé nasměrování všech starších aliasů na nový current target;
6. invalidace old path, new path, entity metadata, alternates a sitemap; nastavení routeModifiedAt.

Alias MUST NOT odkazovat na jiný alias. Dříve publikovaný slug MUST NOT být znovu použit pro jinou entitu. Alias retention je navždy [AC]; Google dokládá potřebu držet permanentní redirecty nejméně 1 rok, projekt drží déle záměrně.

4.9 URL syntax a bezpečné parsování

4.9.1 Vrstvy a decode-once kontrakt

1. Ingress adapter validuje raw request-target a authority: malformed % encoding, percent-encoded / (%2F) nebo \ (%5C) uvnitř segmentu, invalid UTF-8 v encoding, délku (414 nad 2048 bytů). Next dostává už parsovaný nextUrl; raw request-target nelze v aplikaci garantovat, proto je tato vrstva MUST povinnost ingressu a MUST být wire-testována per adapter (release adapter: Docker reverse-proxy chain).
2. Proxy pracuje s framework-parsovaným nextUrl a MUST blokovat ~sf ve všech case a percent variantách včetně double-encoded %257E (4.17).
3. Resolver dostává App Router parametry dekódované právě jednou frameworkem; validuje dekódované hodnoty proti charset policy (control characters, bidi controls, zero-width → 400) a proti slug regexu. Downstream consumer MUST NOT volat další decodeURIComponent.
4. Wire test suite MUST pokrýt per adapter minimálně: %2F, %5C, %257E, invalid % (např. %zz), invalid UTF-8 (např. %C0%AF), bidi control (U+202E), zero-width (U+200B).

4.9.2 Pravidla

1. Každý path segment je percent-decodován právě jednou (frameworkem); dvojité dekódování MUST NOT nastat.
2. Malformed encoding, invalidní UTF-8, control characters, bidi controls a zero-width characters MUST vrátit 400 (na vrstvě, která je vidí; viz 4.9.1).
3. Empty, . a .. segmenty MUST být odmítnuty.
4. Veřejné URL MUST NOT používat fragment jako nositele entity, filtru, pagination nebo variant identity.
5. URL delší než 2048 bytů MUST být odmítnuta ingress vrstvou jako 414.
6. Uppercase static segment nebo entity slug smí dostat 308 pouze tehdy, když resolver jednoznačně nalezne current nebo alias target; jinak 404. Lowercase policy je scoped: platí jen pro statické segmenty a entity slugy.
7. Tokeny, order IDs, variant values a provider parametry MUST NOT být case-normalizovány ani case-redirectovány.

4.10 Query standard

4.10.1 Registr parametrů a canonical pořadí

Globální registr katalogových parametrů a jejich canonical pořadí:

page, sort, status, form, brand, ingredient, price_min, price_max, q, variant

1. Default page=1 a sort=recommended MUST být odstraněny z canonical URL.
2. Multi-value CSV hodnoty MUST být seřazeny a deduplikovány; prázdné CSV položky se zahazují; zůstane-li prázdný výsledek, request MUST vrátit 404.
3. Limity [AC]: nejvýše 20 parametrů na URL, nejvýše 10 hodnot na facet, nejvýše 256 bytů na hodnotu, q nejvýše 200 znaků.
4. Duplicate singleton parametr (např. dvě hodnoty page) MUST vrátit 404.

4.10.2 Per-kind allowlist

Route kind	Povolené parametry (mimo tracking)
Product detail	variant
Product index	page, sort, status, form, brand, ingredient, price_min, price_max
Category detail	page, sort, status, form, brand, ingredient, price_min, price_max
Brand detail	page, sort, status, form, ingredient, price_min, price_max
Collection detail	page, sort, status, form, brand, ingredient, price_min, price_max
Campaign detail	page, sort, status, form, brand, ingredient, price_min, price_max
Category/brand/collection/campaign index	žádné
Advice index	page
Advice article, information, static pages, homepage	žádné
Search	q, page, sort, status, form, brand, ingredient, price_min, price_max
Account orders	page
Payment return, provider callbacks	výhradně vlastní signed route schema; žádná generic normalizace
Reset password / review token	token dle route schema

1. Tracking parametry (4.10.5) jsou povoleny na všech veřejných routes kromě signed provider routes.
2. Známý parametr v nepovolené kombinaci (např. q na product detail, variant na kategorii) MUST vrátit 404; MUST NOT být tiše stripnut.
3. Neznámý non-tracking parametr, včetně uppercase varianty známého klíče, MUST být odstraněn jedním 308, pokud zbytek URL jednoznačně resolve; jinak 404. Platí pouze pro GET/HEAD (4.10.6).

4.10.3 Pagination

1. page MUST odpovídat ^[1-9][0-9]*$; page=01, page=0, page=+1, page=-1 MUST vrátit 404.
2. page=1 MUST být canonicalizováno na URL bez parametru.
3. page>=2 MUST být indexovatelné se self-canonical URL; to odpovídá primárnímu doporučení Google dávat každé stránce sekvence vlastní canonical (Pagination best practices, evidence E5).
4. page>=2 MUST NOT být v sitemapě [AC] a MUST NOT emitovat hreflang.
5. Stránka za poslední existující stránkou MUST vrátit 404; client-side oprava MUST NOT nahradit serverovou validaci.

4.10.4 Sort, facets a ceny

1. Enum hodnoty MUST být lowercase a case-sensitive; sort=RECOMMENDED MUST vrátit 404.
2. Facet nebo sort URL MUST emitovat noindex a MUST NOT emitovat canonical [AC]. Primární Google guidance pro faceted navigation nabízí jako alternativu canonical na unfiltered URL (evidence E4); projekt závazně volí deterministický noindex bez canonical, protože canonical je pouze konsolidační signál, nikoli direktiva, a kombinace noindex + canonical vysílá konfliktní signály. Jde o explicitní projektovou volbu, ne tvrzení Google.
3. Facet nebo sort URL MUST NOT být v sitemapě ani v indexovací interní navigaci.
4. Ceny MUST odpovídat ^[0-9]+(?:\.[0-9]{1,2})?$; price_min > price_max MUST vrátit 404.
5. SEO-promoted facet MUST být samostatná indexovatelná landing route (campaign/theme), nikoli výjimka v generické facet URL.

4.10.5 Search a tracking

1. Search route MUST emitovat noindex a MUST NOT být v sitemapě.
2. Zero-result search MAY vrátit 200, ale MUST zobrazit užitečné alternativy [AC].
3. Discovery produktů MUST NOT záviset pouze na interním search formuláři.
4. Povolené tracking parametry jsou utm_* do počtu 10, gclid a fbclid [AC].
5. Tracking parametry MUST NOT vstoupit do canonical, sitemap, hreflang ani generovaných interních odkazů; tracking-only request MUST canonicalizovat na clean URL.

4.10.6 HTTP metody a query redirecty

1. Query canonical redirecty (strip/sort/default removal) MUST být prováděny výhradně pro GET a HEAD.
2. Unsafe metoda (POST, PUT, PATCH, DELETE) na non-canonical veřejnou URL (alias, wrong case, nenormalizovaná query) MUST vrátit 404; MUST NOT být přesměrována ani tiše normalizována.
3. Server Actions operují na canonical URL aktuální stránky; provider/payment callbacks mají vlastní route schema (4.7.7) a vlastní zpracování metod.

4.11 Canonicalization

1. Canonical URL MUST používat HTTPS, canonical host, lowercase statické segmenty a slugy, žádný trailing slash kromě / a normalized query.
2. skipTrailingSlashRedirect: true MUST být zapnuto (ověřeno v config schema instalované verze; dnes v apps/herbatika/next.config.ts chybí — release blocker RB-5).
3. Resolver MUST složit host, case, trailing slash, alias a query normalizaci do jediného 308.
4. TLS redirect na ingressu MAY vytvořit jeden dodatečný hop; složená origin a entity chyba smí mít nejvýše dva hopy.
5. Alias redirect MUST vést přímo na current canonical URL; alias chains MUST NOT existovat.
6. Permanentní canonical změny MUST používat 308 (permanentRedirect před streamingem); dočasné flow změny 307, po POST 303.
7. Canonical redirecty MUST být prováděny pouze pro GET a HEAD; unsafe metody MUST NOT být automaticky přesměrovány podle alias history (4.10.6).
8. Missing entita MUST NOT být přesměrována na homepage nebo obecnou kategorii.

4.12 Canonical metadata

1. Každá indexovatelná stránka MUST emitovat absolutní self-canonical URL. Jde o projektovou MUST policy [AC]; Google canonical popisuje jako doporučený konsolidační signál, ne direktivu (evidence E3). Canonical MUST NOT být používán jako náhrada za crawl nebo index control.
2. Canonical, Open Graph URL, JSON-LD URL, sitemap URL a interní odkazy MUST pocházet z téhož builderu.
3. metadataBase MUST pocházet z validovaného market canonical originu (kontrakt 2.3); raw Host header MUST NOT přímo nastavovat metadataBase.
4. Route nastavující nested metadata MUST dodat celý požadovaný nested objekt (shallow merge sémantika); MUST NOT spoléhat na deep merge.
5. Metadata resolution MUST sdílet memoizované entity čtení s page renderem a být rozhodnuta před streamingem.
6. Při nejistém stavu MUST být výchozí metadata policy noindex, nikoli optimistické indexování.

4.13 Hreflang

1. Hreflang MUST být publikován pouze v HTML metadata [AC]. Google považuje HTML tagy, HTTP headers a sitemap za ekvivalentní metody, doporučuje zvolit jednu a jejich kombinace nepřináší benefit (evidence E6); HTML-only je projektová volba kvůli jednomu builderu a auditovatelnosti.
2. Hreflang URL MUST být absolutní; každý alternate set MUST obsahovat self-reference; vztahy MUST být reciproční (evidence E6).
3. Povolené kódy jsou sk-SK, cs-CZ, hu-HU, ro-RO.
4. Hreflang MUST odkazovat pouze na current canonical URL vracející 200.
5. Chybějící market equivalent MUST být vynechán; systém MUST NOT mechanicky použít stejný slug na jiné doméně ani fallbackovat na homepage jiného marketu.
6. Cross-domain canonical mezi překlady MUST NOT být použit.
7. x-default MUST NOT být v release emitován [AC] — neexistuje neutrální language selector; zavedení je vázáno na reálný selector post-release.
8. Hreflang MUST NOT být emitován pro search, facets, sort, page>=2, account, auth, cart, checkout ani token routes.
9. Ekvivalence MUST být určena explicitním URLR equivalence_key (seed: Medusa product ID; kategorie/CMS manuální mapping). V jednom (equivalence_key, market, kind) smí existovat nejvýše jedna current route.
10. Pro separate deployments MUST existovat sdílený read model nebo atomicky replikovaný snapshot URLR; jinak hreflang není deterministický a MUST NOT být emitován.

4.14 Indexace

Indexovatelné

homepage; type roots; current product, category, brand a collection detail; aktivní campaign podle explicitní policy; advice a informational content podle explicitní policy; public static pages; katalogová pagination page>=2; publikovaný vyprodaný produkt.

noindex

search; facets; sort variants; cart; checkout; account; auth; review token flows; provider/payment flows; dočasné utility pages.

1. noindex URL classes MUST zůstat crawlable; noindex URL MUST NOT být současně blokována v robots (robots block by zabránil přečtení noindex; evidence E7).
2. noindex URL MUST NOT být v sitemapě.
3. Search, facets a private flows MUST NOT být propagovány jako indexovatelné interní landing pages.
4. Citlivé informace MUST chránit autentizace a autorizace, nikoli robots directives (evidence E7).

4.15 Sitemap

1. Každý host MUST poskytovat vlastní /sitemap.xml (index) a shardy /sitemaps/{kind}-{n}.xml.
2. Sitemap MUST obsahovat pouze current canonical 200 URL daného hostu; aliasy, tombstones, redirects, 404, 410, noindex, facets, search a page>=2 MUST NOT být v sitemapě.
3. lastModified MUST odpovídat skutečné významné změně dle timestampového modelu 4.23.
4. Sitemap enumerace MUST být bounded a paginated; membership MUST být ověřena proti market a sales-channel availability (2.5).
5. Shardy SHOULD být uzavírány přibližně při 10 000 URL nebo 25 MB [AC]; implementace MUST respektovat protokolový limit 50 000 URL a 50 MB uncompressed na soubor (evidence E8).
6. Hreflang MUST NOT být duplikován do sitemap (4.13.1).
7. Sitemap MUST používat stejný URL builder jako metadata a navigace.
8. Vyprodaný publikovaný produkt zůstává v sitemapě [AC].

4.16 Robots

1. /robots.txt MUST být host-specific a MUST uvádět absolutní canonical URL host-specific sitemap.
2. Disallow MUST být použit pouze pro /~sf/ a /api/.
3. Search, facets, account, auth, cart, checkout a token routes MUST NOT být blokovány v robots; jejich indexaci řídí noindex (4.14.1).
4. Robots directives MUST NOT být používány jako bezpečnostní nebo deindexační mechanismus (evidence E7).

4.17 Systémové routes

Následující routes MUST zůstat technické a nelokalizované:

/robots.txt
/sitemap.xml
/sitemaps/{kind}-{n}.xml
/manifest.webmanifest
/feeds/products.xml
/api/...
/.well-known/...

1. Systémové routes MUST NOT kolidovat s entity slugy nebo localized static routes (collision validator 4.21).
2. /~sf je interní namespace; všechny přímé varianty — case (/~SF), percent-encoded (/%7Esf), double-encoded (/%257Esf) a jejich kombinace — MUST vrátit 404.
3. Proxy MUST tyto varianty blokovat před interním rewritem.
4. Metadata files MUST být vyňaty z commerce entity resolution.
5. Product feed MUST být market- a host-scoped.

4.18 HTTP status standard

Stav	Povinný výsledek
Canonical host/path/query nebo alias (GET/HEAD)	308
Dočasný navigační flow	307
Redirect po úspěšném POST	303
Malformed encoding/path/authority	400
Unknown slug, invalid segment, extra segment, invalid query, nepovolený známý parametr	404
Entita mimo market nebo sales channel	404
Cizí order nebo invalidní token	404
Public URLR tombstone bez náhrady	410 (gate G3; fallback 404, bod 5)
Skutečný nástupce entity	308
Unsafe metoda na non-canonical URL	404
Nepovolený host	421
URL nad limitem	414 (ingress)
URLR, Medusa nebo CMS unavailable/invalid-response	503

1. Backend failure MUST NOT být maskován jako 404; mapování řídí read contract 2.6. Retry MUST být bounded, s timeoutem a cancellation.
2. Existence entity MUST být rozhodnuta před prvním response flush; missing entity MUST vrátit skutečný status na drátě, nikoli klientskou error card s 200.
3. notFound() po zahájení streamingu MUST NOT být považováno za splnění hard-404 požadavku.
4. Redirect odstraněné entity na homepage nebo nesouvisející listing MUST NOT být použit.
5. 410 dispatch mechanismus je neprokázaný a je release blocker (RB-13, gate G3: 2026-08-14). Instalovaná verze nemá gone() API (HTTP-access-fallback obsahuje pouze notFound/forbidden/unauthorized) a dokumentace NextResponse.rewrite nedokládá, že response z již zvoleného route spustí nové App Router routování; Server Component rewrite API nemá. Závazný postup: wire experiment na release adapteru (Docker proxy chain) MUST prokázat současně: (a) veřejná URL beze změny, (b) tombstone HTML body, (c) status 410 na drátě před prvním flush, (d) funkční RSC navigaci na tombstone i z něj, (e) nezměněné renderování current routes. Projde-li, 410 se implementuje prokázaným mechanismem. Neprojde-li do G3, release závazně servíruje public tombstones jako 404 (bez redirectu, bez sitemap membership, stejná URLR sémantika) a 410 přechází do post-release backlogu spolu s případnou ingress/custom-server změnou.
6. 410 MUST NOT být používáno pro token, account nebo jiné privátní URL; ty vracejí jednotné 404.

4.19 Internal links

1. Všechny interní odkazy MUST používat shared URL builder; string concatenation lokalizovaných segmentů a slugů MUST NOT existovat (repo scan gate).
2. Server Components MUST používat typed RouteTarget; Client Components MUST dostat hotový href nebo serializovatelný RouteTarget.
3. Client MUST NOT odvozovat business market z window.location.
4. Internal links MUST mířit přímo na current canonical URL a MUST NOT obsahovat tracking parametry, aliasy ani default query values.
5. Navigace MUST signalizovat taxonomii crawlable odkazy, i když category hierarchy není součástí path.

4.20 Route resolution

Resolver MUST postupovat deterministicky:

1. ingress protocol, raw URL a length validation (4.9.1);
2. trusted host validation;
3. market resolution (kontrakt 2.3);
4. bezpečná syntax validace dle decode-once kontraktu;
5. exact localized static route match (včetně flow children);
6. localized type prefix → route kind;
7. jedno indexed URLR lookup + nejvýše jedno bounded equivalence lookup;
8. klasifikace current | alias | tombstone | missing (bez source read);
9. composed canonical redirect nebo hard status před streamingem;
10. market/sales-channel-scoped source read (read contract 2.6);
11. render.

Resolver MUST NOT provádět sequential probing typu product → category → brand → CMS; kind je znám z prefixu před URLR lookupem. Proxy MUST NOT číst URLR, Medusu ani CMS; smí být frameworkově async, ale projektová implementace zůstává statická.

4.21 Collision standard

Build-time a publish-time validator MUST pracovat s kompletní composed normalized public path per market a kontrolovat:

• static × static (včetně všech flow children: checkout kroky, account children, payment return, confirmation, reviews);
• prefix × static;
• current slug × current slug v témže kind;
• current slug × historical alias;
• prefix × historical alias;
• legacy prefix aliasy (/p, /c, /znacka, /blog, /reset-password) × current path;
• root alias snapshot (4.24) × current path;
• old-prefix + old-slug × current path;
• slug × reserved child každého namespace (např. /produkty/feed; validují se všechny statické child segmenty všech namespaces z registry, ne jen příklady);
• transliterační kolize;
• case-folded kolize;
• percent-equivalent kolize (včetně double-encoding);
• host přiřazený více marketům;
• duplicitní (equivalence_key, market, kind);
• route kind × source entity mismatch;
• direct nebo encoded ~sf varianty.

Reserved values zahrnují:

api
_next
~sf
.well-known
robots.txt
sitemap.xml
sitemaps
favicon.ico
manifest.webmanifest
feeds
.
..

Kolize MUST být hard failure. Runtime „first wins“ nebo filesystem precedence MUST NOT rozhodovat business URL.

4.22 Cache a invalidace

1. Každý market-dependent cache key MUST obsahovat market a podle potřeby sales channel ID.
2. URLR a entity cache MUST používat nejméně tagy: market:{market}, route:{market}:{kind}:{id}, route-path:{market}:{kind}:{slug}, equivalence:{key}, {entity}:{market}:{id}, sitemap:{market}.
3. Slug change MUST invalidovat starou i novou path, metadata, alternates a sitemap; změna sales-channel assignmentu MUST invalidovat availability, hreflang a sitemap.
4. Medusa/CMS webhook MUST vstoupit přes autentizovaný Route Handler a MUST volat revalidateTag(tag, "max") nebo jiný explicitní cache-life profile — instalovaná preview.5 signatura vyžaduje druhý argument. updateTag MUST být používán výhradně v Server Actions; v Route Handlers MUST NOT.
5. Release běží single-instance s default (process-local) cache handlerem (2.2); proto MUST NOT existovat druhá instance sdílející traffic. Multi-instance režim je podmíněn zvoleným custom cache handlerem s veřejným kontraktem, cross-instance tag propagation, shared Server Functions encryption key a deploymentId pro rolling deployments — vše post-release gate.
6. generateStaticParams MAY generovat pouze bounded hot set; dynamicParams MUST zůstat true; unbounded načtení celého katalogu v buildu MUST NOT být použito; prázdné pole generateStaticParams MUST NOT být použito při zapnutých Cache Components.
7. cacheComponents MUST být pro release vypnuto, pokud production-wire hard-status suite (gate G4: 2026-08-17) neprokáže skutečné 308, 404 a 410/404-fallback na drátě před response flush přes reálný proxy chain; dnešní cacheComponents: true v apps/herbatika/next.config.ts bez tohoto důkazu je release blocker (RB-5). Re-enable až po zelené suite.

4.23 Modifikační timestampy

URLR/read model MUST rozlišovat tři timestampy per (market, entita):

Timestamp	Mění se při	Používá
contentModifiedAt	významná obsahová změna entity/stránky (název, popis, media, složení listingu)	sitemap lastModified, metadata
taxonomyModifiedAt	přesun ve stromu, změna assignments, rank	invalidace breadcrumb/navigace/JSON-LD cache
routeModifiedAt	slug change, alias, index policy, tombstone	sitemap lastModified, alternates invalidace

1. Sitemap lastModified MUST být max(contentModifiedAt, routeModifiedAt) dané URL.
2. Category move MUST NOT automaticky posunout contentModifiedAt dotčených stránek; mění taxonomyModifiedAt a invaliduje cache. Změní-li move složení listingu kategorie, jde o obsahovou změnu listingu a nastaví se contentModifiedAt daného listingu.

[BleedingDev]

Plná normativní specifikace — část 02/5. Krátká implementační verze je v popisu issue; tato část je závazný zdroj při sporu.

---

4.24 Legacy new-site aliasy a root inventarizace

1. Legacy prefixové routy /p/, /c/, /znacka/, /blog/ a /reset-password MUST být převedeny na new-site aliasy: 308 přímo na nové canonical cesty, jeden hop, alias history retained.
2. Kořenový dynamický matcher /{slug} MUST NOT existovat — ani pro current routes, ani jako dynamický alias resolver; apps/herbatika/src/app/[slug]/page.tsx se ruší (release blocker RB-12).
3. Gate G2 (2026-08-08): inventarizace všech někdy publikovaných root CMS URL. Závazný výsledek: existují-li publikované root URL, vytvoří se build-time exact redirect snapshot — statická, konečná, collision-validovaná tabulka exact-match 308 redirectů kompilovaná do configu (žádný dynamický root matcher, žádné čtení URLR pro root); neexistují-li, zapíše se ověřený předpoklad a žádné root aliasy se nevytvářejí. Dynamické root aliasy z URLR jsou v obou případech zakázány.

---

5. Release gates a repository-delta blockery

Wire suite v této sekci znamená: test HTML requestu i RSC navigace přes skutečný release proxy chain (Docker), s asercí HTTP statusu na drátě před prvním bytem body.

ID	Blocker (evidence v repu)	Závislost	Acceptance criterion
RB-1	market-context.ts fallbackuje přes Accept-Language a default sk (apps/herbatika/src/lib/storefront/market-context.ts)	kontrakt 2.3	unknown host vrací 421 na drátě; žádná SK response pro neznámý host; unit + wire test
RB-2	i18n/request.ts načítá UI texty z Medusy (apps/herbatika/src/i18n/request.ts)	Next locale resources	UI/route texty se renderují z repo locale bundles ve všech 4 locale; žádný runtime fetch storefront-texts pro UI
RB-3	cms-client.ts natvrdo locale=sk (řádek 9)	kontrakt 2.3	CMS request nese locale marketu; integration test per market
RB-4	Payload locales default cs,sk,en, chybí hu,ro	CMS konfigurace + obsah	hu-HU a ro-RO obsah publikovatelný a servírovaný; explicitní publish state per market
RB-5	next.config.ts: cacheComponents: true (řádek 65), chybí skipTrailingSlashRedirect: true	gate G4	skipTrailingSlashRedirect: true v configu; G4 suite zelená, jinak cacheComponents OFF v release buildu
RB-6	neexistují App Router handlery robots/sitemap/manifest	URL builder + URLR	per-host robots/sitemap/manifest dle 4.15–4.17; sitemap validována proti market catalog snapshotu
RB-7	soft-404: unknown /p/{handle} končí klientskou „not found“ kartou s 200; unknown category renderuje listing shell bez serverového notFound(); connection() může předběhnout validaci checkout kroku	resolver před streamingem	wire suite prokazuje 404/410-fallback/308 před prvním bytem pro HTML i RSC; checkout step validace před connection()
RB-8	category/brand aliasy používají dočasný redirect() (307)	URLR alias tabulka	alias vrací 308 (permanentRedirect) v jednom hopu; wire test
RB-9	brand slug se generuje za runtime	URLR seed	brand lookup přes uložený slug; repo scan bez runtime slugifikace
RB-10	globální SDK singleton sdk.ts + build-time NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY v Docker/Netlify konfiguraci	kontrakt 2.3	per-market server SDK factory; klient obdrží jen key svého marketu; build artefakt neobsahuje ostatní klíče
RB-11	publishable-key.ts nevytváří ani neověřuje link key↔channel	validace 2.4	boot fail-fast při chybějícím/multi-channel linku; integration test pro 4 markety
RB-12	root app/[slug]/page.tsx existuje	gate G2	root dynamic route odstraněn; publikované root URL v build-time exact snapshotu s 308, nebo zapsaný ověřený předpoklad „žádné publikované“
RB-13	410 dispatch mechanismus neprokázán (žádné gone() API; rewrite z route nedoložen)	gate G3	wire důkaz dle 4.18.5 (a)–(e); jinak závazný fallback tombstone → 404 v release
RB-14	/store/brands vrací globální seznam; category/brand/collection bez availability linku	model 2.5	Store čtení market-scoped pro všechny kinds; entita mimo channel vrací 404 na drátě
RB-15	cms-client.ts kolabuje error i non-2xx na null	read contract 2.6	vypnutý backend → 503 na drátě; definitivní miss → 404; unit + wire testy rozlišení
RB-16	legacy prefixy /p, /c, /znacka, /blog, /reset-password jako current routes	alias tabulka 4.24	308 na nové cesty v jednom hopu; alias history v URLR

Gate kalendář: G1 sign-off segmentů 2026-08-07 → registry frozen; G2 root inventarizace 2026-08-08; G3 410 wire důkaz 2026-08-14; G4 cacheComponents hard-status suite 2026-08-17; release 2026-08-20.

---

6. Zamítnuté varianty

Následující varianty jsou závazně zamítnuty:

• app/_m/... jako interní route strom (_ je private folder a URL nevytvoří);
• root /{slug} jako společný CMS nebo entity namespace; dynamický root alias matcher z URLR;
• /p/, /c/, /znacka/, /blog/ a /reset-password jako cílová architektura (pouze new-site aliasy);
• singulární type prefixy;
• category segment v produktové URL; hierarchické category canonical URL;
• odvození kind sequential probingem product → category → brand → CMS;
• Unicode slugy jako projektová slug policy; runtime slugifikace; automatické suffixy -2;
• Medusa handle jako runtime URL autorita; URL registry nebo alias history uvnitř Medusy; duplikace category taxonomy v Next URLR;
• route a UI texty z Medusa storefront texts;
• locale prefixy v path; slovenský fallback pro ostatní markety;
• stejný slug na jiné doméně jako implicitní hreflang equivalent; homepage jako hreflang fallback; syntetické nebo slovenské x-default; cross-domain canonical mezi překlady; hreflang současně v HTML i sitemapě;
• canonical page>=2 na page 1; indexace všech facet kombinací; canonical na unfiltered URL jako řešení facetů (zvoleno noindex bez canonical, 4.10.4); canonical jako crawl-control mechanismus;
• robots block a noindex pro stejnou URL class; robots jako autentizační nebo deindexační mechanismus;
• redirect() s 307 pro trvalou alias history; config redirects() jako databáze dynamických aliasů; 301 jako default;
• blanket lowercase celé URL včetně tokenů a provider parametrů;
• 410 pro tokeny nebo privátní routes; 410 bez wire důkazu dispatch mechanismu;
• URLR/DB lookup v proxy.ts;
• přesměrování odstraněné entity na homepage nebo obecnou kategorii;
• multi-market publishable key; availability category/brand/collection derivovaná z produktové membership;
• null jako sjednocený výsledek backend čtení;
• jedno shared query schema pro všechny route kinds; tichý strip známého parametru v nepovolené kombinaci;
• revalidateTag bez cache-life profile argumentu v Route Handlers; updateTag mimo Server Actions;
• multi-instance deployment a Netlify storefront adapter v release bez prokázaného shared cache handleru;
• process-local cache jako URL autorita ve více instancích;
• samostatný router fork pro každý market;
• ad hoc skládání URL v komponentách, e-mailech nebo metadata;
• skrytý upgrade Next.js spolu s URL/SEO releasem;
• optional catch-all mega-dispatcher [[...path]] místo semantic interního ~sf stromu [AC].

---

7. Primární zdroje a značení [AC]

Přístup ke všem URL: 2026-08-05. [AC] = architecture choice projektu bez externí autority (mj.: ASCII slugy a limit 80; 5 navigačních úrovní; page>=2 mimo sitemap; facets noindex bez canonical; HTML-only hreflang; žádný x-default; shard close 10 000 URL/25 MB; vyprodaný produkt v sitemapě; alias retention navždy; tracking allowlist; query limity; ~sf strom).

ID	Tvrzení	Zdroj
E1	Význam MUST/SHOULD/MAY	RFC 2119, RFC 8174 (IETF)
E2	Chování instalované verze: skipTrailingSlashRedirect v config schema; HTTP-access-fallback pouze notFound/forbidden/unauthorized (žádné gone()); revalidateTag(tag, profile) signatura	Next.js v16.3.0-preview.5, tagovaný source v node_modules (závazná autorita)
E3	Canonical je konsolidační signál, ne direktiva	Google Search Central — Consolidate duplicate URLs, https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls
E4	Faceted navigation: Google uvádí i canonical na unfiltered URL; projekt volí noindex [AC]	Google Search Central — Faceted navigation, https://developers.google.com/search/docs/crawling-indexing/crawling-managing-faceted-navigation
E5	Každá stránka sekvence má mít vlastní canonical	Google Search Central — Pagination best practices, https://developers.google.com/search/docs/specialty/ecommerce/pagination-and-incremental-page-loading
E6	hreflang: HTML/HTTP header/sitemap jsou ekvivalentní metody; self-reference, reciprocita, absolutní URL	Google Search Central — Localized versions, https://developers.google.com/search/docs/specialty/international/localized-versions
E7	robots.txt není deindexační/bezpečnostní mechanismus; noindex vyžaduje crawlable URL	Google Search Central — robots.txt intro a Block indexing with noindex, https://developers.google.com/search/docs/crawling-indexing/robots/intro, https://developers.google.com/search/docs/crawling-indexing/block-indexing
E8	Sitemap limit 50 000 URL / 50 MB uncompressed	sitemaps.org protocol, https://www.sitemaps.org/protocol.html
E9	Permanentní redirecty držet nejméně 1 rok	Google Search Central — Redirects and Google Search, https://developers.google.com/search/docs/crawling-indexing/301-redirects
E10	NextResponse.rewrite nedokládá re-dispatch z již zvoleného route (základ RB-13)	Next.js docs — NextResponse, https://nextjs.org/docs/app/api-reference/functions/next-response
E11	Repo evidence blockerů: apps/herbatika/src/app/[slug]/page.tsx, apps/herbatika/next.config.ts (cacheComponents: true, řádek 65; chybějící skipTrailingSlashRedirect), apps/herbatika/src/lib/storefront/cms-client.ts (CMS_LOCALE = "sk", řádek 9), apps/herbatika/src/lib/storefront/market-context.ts, apps/herbatika/src/i18n/request.ts, apps/herbatika/src/lib/storefront/sdk.ts, apps/medusa-be/src/utils/publishable-key.ts, adresáře app/p, app/c, app/znacka, app/blog, app/reset-password	pracovní strom . (kořen repozitáře), ověřeno 2026-08-05

---

ČÁST B — Kompletní URL matice a konfigurace Herbatica

Závazné globální invarianty

• Každý canonical origin používá https, non-www host, lowercase statické segmenty a žádný koncový / mimo kořen. skipTrailingSlashRedirect: true je zapnuto; host, protokol, case, trailing slash, alias a query normalizace se skládají do jediného 308 ve status-owning vrstvě (viz níže).
• Market se určuje výhradně z allowlistovaného hostu:

Market	Locale	Canonical origin	Sales channel / publishable key / region
sk	sk-SK	https://herbatica.sk	právě jeden SK channel; server-only klíč pro sk
cz	cs-CZ	https://herbatica.cz	právě jeden CZ channel; server-only klíč pro cz
hu	hu-HU	https://herbatica.hu	právě jeden HU channel; server-only klíč pro hu
ro	ro-RO	https://herbatica.ro	právě jeden RO channel; server-only klíč pro ro

• Market-scoped Medusa runtime kontrakt. Existuje server-only, při bootu validovaná mapa market → publishableKey → salesChannelId → regionId. Každý serverový read dostává publishable key explicitně podle trusted marketu; klient obdrží pouze serverem vybraný veřejný klíč aktuálního trusted marketu a vytváří z něj market-scoped klienta. Globální singleton NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY a cache/query keys bez market dimenze jsou zakázané a jejich odstranění je release blocker. Startup check a integration test ověřují, že každý klíč je scoped právě na jeden sales channel; multi-channel klíč blokuje release.
• Fail-closed host resolution. Allowlist obsahuje právě čtyři canonical hosty výše. www.* varianty, alternativní spellingy (herbatika.*) a jakékoli další domény v allowlistu nejsou, dokud není doloženo DNS, TLS a provozní vlastnictví; po ověření patří výhradně do odděleného redirect-host registru (308 na canonical origin), nikdy mezi canonical hosty. Neznámý host vrací 421 fail-closed s minimálním tělem; jakýkoli Accept-Language, SK nebo default fallback v host resolution je pro production HTTP requesty zakázán a jeho odstranění ze současného resolveru je release blocker.
• Lokalizované prefixy a entity slugy jsou market-specific. Stejná entita nemusí existovat ve všech marketech a nemusí mít ekvivalentní slug.
• Kořenový dynamický namespace /{slug} neexistuje.
• URL registry (URLR), Next-owned model. Veřejné entity používají Next-owned URLR ve vlastním Postgres schématu s vlastními migracemi:
  • urlr_entity: kind, source_system, source_type, source_id, equivalence_key;
  • urlr_path: market, namespace, normalized_slug, state ∈ current|alias|tombstone, entity_id, target_path_id, published_at, retired_at;
  • DB invarianty: unikátní (market, namespace, normalized_slug); nejvýše jeden current path pro (market, kind, entity_id); nejvýše jeden záznam (market, kind, equivalence_key); alias target smí ukazovat pouze na current path téže entity; tombstone nemá target; reuse slugu pro jinou entitu a cykly jsou zakázány; source_type je povinný discriminant (mj. medusa_collection vs. cms_landing), takže runtime probing mezi zdroji neexistuje.
  • Publish, změna slugu a unpublish běží výhradně přes Next-owned, autentizované a auditované operační rozhraní s atomickými transakcemi; souběžné změny pokrývají concurrency testy. Ruční zásah mimo toto rozhraní je zakázán. Medusa zůstává vlastníkem katalogových a obchodních dat; paralelní URL/taxonomy systém v Medusa nevzniká.
• Vlastnictví textů a CMS transport. „CMS“ v této matici znamená vždy přímý server-only CMS adaptér s explicitním market locale. Storefront nesmí číst editorial/právní obsah přes Medusa /store/cms/* ani UI texty přes /store/storefront-texts; UI, system a route texty vlastní Next locale resources. Hardcoded CMS locale je zakázán; chybějící překlad nesmí fallbackovat na SK a blokuje publish dané stránky v daném marketu.
• Viditelnost odvozená z produktů (pravidlo V). Kategorie, značky a kolekce nemají doložené Medusa market/channel assignment fields; explicitní Medusa relace na sales channel se nezavádí. Binding pravidlo: existence v marketu = existence current URLR path (publish stav vlastní Next publish workflow); katalogová viditelnost a indexovatelnost se deterministicky odvozují z publikovaných produktů dostupných v sales channelu marketu. Prázdné listingy řeší pravidlo ∅ v legendě.
• Produktová URL nikdy neobsahuje kategorii. Kategorie používá vždy plochý tvar {prefix}/{slug} bez stromu předků.
• Každá publikovaná URL má nejvýše jeden current záznam. Změna slugu vytvoří přímý permanentní alias 308; alias chain je zakázán. Alias, host a canonical redirecty platí jen pro GET/HEAD; unsafe metody se nepřesměrovávají.
• Dříve publikovaná veřejná URL bez náhrady vrací 410. Nikdy nepublikovaná, neznámá nebo v daném marketu nedostupná entita vrací 404.
• Canonical, hreflang, Open Graph URL, JSON-LD URL, sitemap a interní odkazy používají jediný URL builder.
• Hreflang se emituje jen mezi skutečnými current 200 ekvivalenty podle equivalence_key; chybějící market se vynechá. x-default se neemituje. Cross-domain canonical mezi překlady je zakázán.
• Raw-path ochrana je rozdělená. Ingress adapter (Docker/Compose proxy chain; Zerops) kontroluje raw request-target a blokuje encoded/double-encoded separatory a namespace varianty; Proxy blokuje normalizovaný /~sf namespace. Acceptance matice per adapter povinně obsahuje: /~sf, /~SF, /%7Esf, /%7esf, /%257Esf, encoded slash a backslash, malformed %, invalid UTF-8 a dvojité dekódování. Netlify není doložený deployment; případný Netlify adapter je samostatná pozdější změna s vlastní raw-request/status suite.

Vlastnictví HTTP statusů (status-owning vrstva)

NextResponse.rewrite() z App Route Handleru není v v16.3.0-preview.5 podporován a Server Component nemůže vlastnit stavové kódy 410/503. Model „statická Proxy + status resolver v page + interní gone rewrite“ je proto zrušen. Binding model: proxy.ts je status-owning vrstva — běží asynchronně, provádí bounded URLR resolution (1 indexovaný lookup + nejvýše 1 equivalence lookup, explicitní timeout, žádný sequential probing) a vrací composed statusy před jakýmkoli App Router renderem a flushem. Kompatibilita se output: "standalone" a Docker/Compose i Zerops deploymenty zůstává zachována; custom Node front controller se nezavádí.

Status / třída	Vlastník	Chování
TLS/protocol redirect, 414, raw-target 400 (encoded/double-encoded separatory, ~sf varianty, malformed authority)	ingress adapter (Docker/Compose proxy chain; Zerops)	prázdné/minimální tělo; testováno wire testem per adapter
421 neznámý host	Proxy	minimální tělo, no-store, žádný language/default fallback
308 host/alias/segment/query normalizace	Proxy	prázdné tělo + Location; jeden hop (max 2 pouze s ingress TLS hopem); jen GET/HEAD
400 malformed encoding na parsované URL (encoded /, \, malformed %, invalid UTF-8, control/bidi/zero-width)	Proxy	minimální lokalizovaný chybový dokument; X-Robots-Tag: noindex, no-store
404 syntaktický, registry nebo URLR definitive miss; 410 tombstone	Proxy	reálný status před prvním bytem; minimální lokalizovaný dokument, noindex, no-store; alias/gone/missing se rozhodují bez source read
404 závislé na datech (page za posledním výsledkem, varianta cizího produktu, cizí objekt, invalidní token)	App Router notFound() v server entry před streamingem	reálný 404, lokalizovaná not-found stránka, noindex
503 resolve-phase (URLR timeout/5xx)	Proxy	minimální dokument, Retry-After, no-store; bounded timeout, žádný neomezený retry
Render-phase source failure (Medusa/CMS timeout/5xx po úspěšném resolve)	root error povrch App Routeru	kritické fetche route kindu proběhnou před prvním flush; selhání vyhodí typed error a vrátí chybový status 500 s noindex a no-store; nikdy 404, nikdy 200 vydávané za obsah

Zápis 503 v buňkách matice znamená failure outcome podle této tabulky: selhání v resolve fázi vrací 503 z Proxy; selhání při renderu vrací chybový povrch 500. Obě varianty jsou bez SEO povrchu. Acceptance fault-injektuje URLR, Medusa i CMS timeout a 5xx přes skutečný production server a proxy chain a měří status na drátě před prvním bytem; soft-404 (200 s klientskou error card) je release blocker.

Legenda matice

Parametry

• T — tracking allowlist: nejvýše 10 parametrů utm_*, dále gclid, fbclid; nikdy nejsou v canonical, interních odkazech ani sitemapě; nikdy nevyvolávají redirect; duplicitní a nadlimitní tracking klíče se pro render i canonical ignorují.
• L — listing: page, sort, status, form, brand, ingredient, price_min, price_max a T.
• L−brand — L bez brand, protože značka je určena cestou.
• Q — search: q, page, sort, status, form, brand, ingredient, price_min, price_max a T.
• V — variant={case-preserving-key} a T.
• P — přesné, route-specific provider parametry; nesmějí projít generickým strip/sort redirectem.
• — — žádné business parametry; veřejná obsahová stránka může přijmout pouze T.

Query SEO

• Clean URL a page=1 jsou totožné; page=1 se odstraní.
• page>=2 je indexovatelná self-canonical URL, ale není v sitemapě.
• Facety a sort jsou crawlable noindex bez canonical; kombinace s page>=2 zůstává noindex bez canonical.
• Tracking-only URL canonicalizuje na clean URL (canonical tagem, ne redirectem).
• Neznámý non-tracking parametr (včetně uppercase variant klíčů) se odstraní jedním 308.
• Neplatná hodnota známého parametru nebo neplatná kombinace vrací 404.
• page musí odpovídat ^[1-9][0-9]*$; stránka za posledním výsledkem vrací 404.
• variant, tokeny, public order IDs a provider hodnoty jsou case-preserving a nesmějí se lowercase-normalizovat ani redirectovat.

∅ — prázdný listing (soft-404 prevence)

• Publikovaná URL (current v URLR) s dočasně nulovým katalogovým výsledkem, ale obsahovou hodnotou → 200 s noindex, bez canonical, mimo sitemapu a mimo hreflang, dokud se výsledky nevrátí.
• Permanentně zrušená URL → 410, nebo skutečný 308 nástupce přes URLR transakci.
• Nikdy nepublikovaný nebo v marketu nedostupný objekt → 404.
• Indexovatelný prázdný 200 je zakázán.

TB — tokenový bezpečnostní profil

• Hlavičky: Cache-Control: private, no-store, Referrer-Policy: no-referrer, X-Robots-Tag: noindex, nofollow, noarchive.
• Zákaz prefetch (router i <link>) a analytických eventů obsahujících URL s tokenem.
• Token nesmí vstoupit do canonical, hreflang, OG URL, sitemap, metadata ani redirect targetu.
• Ingress log, Next access log, tracing a error reporting redigují path/query tokeny; log-redaction acceptance test je release gate.

Kolize

• S — celý statický path je rezervovaný v typed segment registry; kolize zastaví build/config validation.
• E — current slug, alias a tombstone musí být unikátní v (market, namespace); transliterační či historická kolize zastaví publish transakci.
• R — route child je rezervovaný uvnitř systémového namespace; neznámý child vrací 404.
• X — technický namespace je rezervovaný před veřejným resolverem.

Změny a odstranění

• ΔS — změna publikovaného statického segmentu vytvoří přímý 308 ze starého path.
• ΔE — atomická změna slugu přes URLR operační rozhraní: rezervace nového slugu, switch current, starý slug jako immutable přímý alias, invalidace old/new path, metadata, alternates a sitemap.
• ΔC — obsah se mění bez změny URL; změna lastModified invaliduje stránku a sitemapu. Unpublish dříve veřejné URL vytvoří 410.
• ΔU — žádná veřejná alias history uživatelského objektu; invalidní či cizí identifikátor vrací jednotné 404.
• ΔT — token se nikdy nepřesměrovává ani netombstonuje; invalidní, použitý nebo expirovaný token vrací stejné 404; platí TB.

---

Query kontrakt: hodnoty, vlastnictví a edge pravidla

Next vlastní URL tokeny; Medusa vlastní facet/business entity; mapping žije v typed facet registry per market (build-time validovaný, součást segment registry configu).

Parametr	Model hodnot	Vlastník tokenů	Market lokalizace	Mapping	Change policy
page	scalar, ^[1-9][0-9]*$; page=1 stripped	Next	invariantní	—	—
sort	enum seed: recommended (default, stripped), newest, price-asc, price-desc, name-asc, name-desc, bestsellers; lowercase case-sensitive	Next facet registry	market-invariantní ASCII tokeny (facety jsou noindex, lokalizace tokenů nemá SEO hodnotu; labels lokalizuje Next locale resources)	na Medusa/search sort výrazy	přidání = config change; přejmenování = token alias s 308 normalizací; odstranění = 404
status	multivalue CSV, enum seed: in-stock, sale, new	Next facet registry	invariantní tokeny, lokalizované labels	na Medusa availability/price-list/creation kritéria	jako sort
form	multivalue CSV, enum seed: capsules, tablets, powder, tea, oil, drops, syrup, cream	Next facet registry	invariantní tokeny, lokalizované labels	na Medusa product type/option přes facet registry	jako sort
brand	multivalue CSV; current brand slug daného marketu	URLR (brand entity)	market-specific current slug	na Medusa brand ID přes URLR entity	alias brand slug v query → jednohop 308 na current; neznámý → 404
ingredient	multivalue CSV; tokeny facet registru	Next facet registry	invariantní ASCII tokeny, lokalizované labels	na Medusa tag/metadata ID	jako sort
price_min, price_max	scalar, ^[0-9]+(\.[0-9]{1,2})?$, min≤max, měna implikovaná marketem	Next	invariantní	na Medusa price filtry v market currency	—
q	scalar free text, po trim ≤200 znaků, case-preserving	Next	uživatelský vstup	na search rozhraní	—
variant	scalar, opaque case-preserving klíč Medusa varianty; exact match	Medusa	žádná	na Medusa variant ID/SKU	nikdy alias, nikdy redirect; odstraněná varianta 404, produkt beze změny

Edge pravidla (uzavřená, deterministická pro normalizeQuery i collision validator):

• Duplicitní scalar klíč (page, sort, q, price_min, price_max, variant) → 404.
• Duplicitní multivalue klíč (status, form, brand, ingredient) → sloučení, sort + dedupe a jeden 308 na kanonickou CSV formu v jednom klíči.
• Prázdné CSV položky se zahazují; prázdná výsledná množina hodnot → 404.
• q chybí → 200 search formulář; q prázdné nebo whitespace-only po trim → 308 strip parametru; q přes 200 znaků → 404.
• page>=2 v kombinaci s facets/sort je povoleno a je noindex bez canonical; 404 za posledním výsledkem platí vždy.
• Invalid percent-encoding → 400 (dle tabulky vlastnictví statusů).
• Neznámý non-tracking klíč, včetně uppercase varianty známého klíče → 308 strip.
• Signed provider/payment parametry mají exact route schema a nikdy neprocházejí generickým strip/sort redirectem.
• variant nepříslušející produktu v path → 404 (App Router notFound()).

---

Registr lokalizovaných segmentů (návrh — proposed, unverified do sign-offu)

URL hodnoty jsou ASCII transliterace přirozených nativních názvů. Až do dokončení sign-offu je celý registr ve stavu proposed, unverified a žádná hodnota se nesmí vydávat za „verified“. Hodnoty † blokuje native editorial sign-off, hodnoty ‡ navíc legal sign-off; gate je 2026-08-07. Každá schválená hodnota musí mít evidovaného approvera, datum schválení a frozen registry hash; teprve pak smí být publikována. Browser test ověřuje viditelný nativní label s korektní diakritikou proti ASCII URL segmentu. Po první publikaci se každá změna řídí ΔS.

Klíč	SK	CZ	HU	RO
products	produkty†	produkty†	termekek† — Termékek	produse†
categories	kategorie†	kategorie†	kategoriak† — Kategóriák	categorii†
brands	znacky†	znacky†	markak† — Márkák	marci† — Mărci
collections	kolekcie†	kolekce†	gyujtemenyek† — Gyűjtemények	colectii† — Colecții
campaigns	akcie†	akce†	akciok† — Akciók	promotii† — Promoții
advice	poradna†	poradna†	tanacsok† — Tanácsok	sfaturi†
information	informacie†	informace†	informaciok† — Információk	informatii† — Informații
search	vyhladavanie† — Vyhľadávanie	vyhledavani†	kereses† — Keresés	cautare† — Căutare
cart	kosik†	kosik†	kosar† — Kosár	cos† — Coș
checkout	pokladna†	pokladna†	penztar† — Pénztár	finalizare-comanda†
account	ucet†	ucet†	fiok† — Fiók	cont†
reviews	recenzie†	recenze†	velemenyek† — Vélemények	recenzii†
about	o-nas†	o-nas†	rolunk† — Rólunk	despre-noi†
contact	kontakt†	kontakt†	kapcsolat†	contact†
faq	casto-kladene-otazky†	caste-dotazy†	gyakori-kerdesek†	intrebari-frecvente†
shipping	doprava†	doprava†	szallitas† — Szállítás	livrare†
returns	vratenie-tovaru†	vraceni-zbozi†	visszakuldes† — Visszaküldés	retururi†
terms	obchodne-podmienky‡	obchodni-podminky‡	altalanos-szerzodesi-feltetelek‡	termeni-si-conditii‡
privacy	ochrana-osobnych-udajov‡	ochrana-osobnich-udaju‡	adatvedelmi-tajekoztato‡	politica-de-confidentialitate‡
cookies	cookies‡	cookies‡	cookie-tajekoztato‡	politica-cookies‡
checkout.contact	kontakt†	kontakt†	kapcsolat†	contact†
checkout.shipping	doprava†	doprava†	szallitas†	livrare†
checkout.payment	platba†	platba†	fizetes†	plata†
checkout.review	kontrola†	kontrola†	ellenorzes†	verificare†
checkout.paymentReturn	navrat-z-platby†	navrat-z-platby†	fizetesi-visszateres†	retur-plata†
checkout.confirmation	potvrdenie-objednavky†	potvrzeni-objednavky†	rendeles-visszaigazolas†	confirmare-comanda†
account.lists	zoznamy†	seznamy†	listak†	liste†
account.orders	objednavky†	objednavky†	rendelesek†	comenzi†
account.settings	nastavenia†	nastaveni†	beallitasok†	setari†
account.login	prihlasenie†	prihlaseni†	bejelentkezes†	autentificare†
account.register	registracia†	registrace†	regisztracio†	inregistrare†
account.forgotPassword	zabudnute-heslo†	zapomenute-heslo†	elfelejtett-jelszo†	parola-uitata†
account.resetPassword	obnova-hesla†	obnova-hesla†	jelszo-visszaallitas†	resetare-parola†
reviews.product	produkt†	produkt†	termek†	produs†

---

Veřejné katalogové a obsahové URL

Page type	Shape a konkrétní SK/CZ/HU/RO příklady	Zdroj dat	Indexace	Canonical	Sitemap	Parametry	Missing outcome	Kolize	Změna nebo odstranění
Homepage	/ SK https://herbatica.sk/ CZ https://herbatica.cz/ HU https://herbatica.hu/ RO https://herbatica.ro/	Next market config, Next locale resources, CMS editorial blocks (server-only adaptér), Medusa katalogové výběry (market-scoped klíč)	index	self	ano	T	neznámý host 421; source failure 503	S	obsah ΔC; canonical host změna 308
Produktový index	/{products} SK /produkty CZ /produkty HU /termekek RO /produse	Next segment registry; Medusa market/channel-scoped katalog	clean a page>=2 index; facets/sort noindex	clean nebo self pro page>=2; facets/sort bez canonical	pouze clean root	L	source failure 503; page mimo rozsah 404	S	segment ΔS; listing obsah ΔC
Produkt detail	/{products}/{productSlug} SK /produkty/ashwagandha-bio-90-kapsul CZ /produkty/ashwagandha-bio-90-kapsli HU /termekek/bio-ashwagandha-90-kapszula RO /produse/ashwagandha-bio-90-capsule	URLR current/alias/equivalence; Medusa produkt, varianty, ceny, stock, channel availability; Medusa Translation (zapnutý modul; chybějící překlad blokuje publish v marketu)	index	self bez variant a tracking parametrů	ano, pouze current 200	V	unavailable/miss 404; tombstone 410; source failure 503	E	slug ΔE; metadata/availability ΔC; skutečný nástupce 308, jinak 410
Produktová varianta	Stejný produkt path s query: SK /produkty/ashwagandha-bio-90-kapsul?variant=SKU-AbC-01 CZ /produkty/ashwagandha-bio-90-kapsli?variant=SKU-AbC-01 HU /termekek/bio-ashwagandha-90-kapszula?variant=SKU-AbC-01 RO /produse/ashwagandha-bio-90-capsule?variant=SKU-AbC-01	Medusa variant ID/key; Next query parser a initial-state resolver	není samostatnou indexovatelnou entitou	canonical na základní produkt bez variant	ne	V	neznámá nebo produktu nepříslušná varianta 404; source failure 503	E na product path; key je case-preserving	varianta se nikdy nestává URL aliasem; odstraněná varianta 404, produkt zůstává beze změny
Kategorie index	/{categories} SK /kategorie CZ /kategorie HU /kategoriak RO /categorii	Next segment registry; Medusa product categories (tree, rank); market viditelnost dle pravidla V	index	self	ano	T	source failure 503	S	segment ΔS; strom/rank ΔC
Kategorie detail	/{categories}/{categorySlug} SK /kategorie/bylinne-caje CZ /kategorie/bylinne-caje HU /kategoriak/gyogyteak RO /categorii/ceaiuri-din-plante	URLR; Medusa kategorie, parent, rank; katalog a viditelnost dle pravidla V	clean a page>=2 index; facets/sort noindex; prázdný listing ∅	clean nebo self pro page>=2; facets/sort a stav ∅ bez canonical	pouze clean current URL mimo stav ∅	L	nikdy nepublikovaná/market-unavailable 404; tombstone 410; source failure 503	E	slug ΔE; přesun ve stromu URL nemění, pouze ΔC; odstranění 410 nebo pravý nástupce 308
Značky index	/{brands} SK /znacky CZ /znacky HU /markak RO /marci	Next segment registry; custom Medusa Brand module (/store/brands); market viditelnost dle pravidla V	index	self	ano	T	source failure 503	S	segment ΔS; obsah ΔC
Značka detail	/{brands}/{brandSlug} SK /znacky/weleda CZ /znacky/weleda HU /markak/weleda RO /marci/weleda	URLR; custom Medusa Brand module (/store/brands); market/channel-scoped produkty	clean a page>=2 index; facets/sort noindex; prázdný listing ∅	clean nebo self pro page>=2; facets/sort a ∅ bez canonical	pouze clean current URL mimo stav ∅	L−brand	nikdy nepublikovaná/market-unavailable 404; tombstone 410; source failure 503	E	slug ΔE; odstranění 410 nebo pravý nástupce 308
Kolekce index	/{collections} SK /kolekcie CZ /kolekce HU /gyujtemenyek RO /colectii	Next segment registry; Medusa kolekce; CMS SEO landing entries	index	self	ano	T	source failure 503	S; child namespace je společný pro kolekce a SEO landingy	segment ΔS; obsah ΔC
Kolekce detail	/{collections}/{collectionSlug} SK /kolekcie/podpora-imunity CZ /kolekce/podpora-imunity HU /gyujtemenyek/immunrendszer-tamogatasa RO /colectii/sustinerea-imunitatii	URLR (source_type = medusa_collection); Medusa collection membership a katalog; CMS volitelný editorial obsah	clean a page>=2 index; facets/sort noindex; prázdný listing ∅	clean nebo self pro page>=2; facets/sort a ∅ bez canonical	pouze clean current URL mimo stav ∅	L	nikdy nepublikovaná/market-unavailable 404; tombstone 410; source failure 503	E, společná slug unikátnost s evergreen SEO landingy	slug ΔE; membership/content ΔC; odstranění 410 nebo nástupce 308
Evergreen SEO landing	Stejný first-class namespace jako kolekce: SK /kolekcie/spanok-a-stres CZ /kolekce/spanek-a-stres HU /gyujtemenyek/alvas-es-stressz RO /colectii/somn-si-stres	URLR route kind collection, source_type = cms_landing (discriminant, žádný runtime probing); CMS vlastní editorial/SEO obsah a deklarativní filter definition; Medusa poskytuje katalogové výsledky	clean a page>=2 index; ad hoc facets/sort noindex; prázdný listing ∅	clean nebo self pro page>=2; facets/sort a ∅ bez canonical	pouze clean current URL mimo stav ∅	schválený subset L podle landing configu	miss 404; tombstone 410; source failure 503	E, discriminant source_type vylučuje probing mezi kolekcí a landingem	slug ΔE; pravidla/obsah ΔC; odstranění 410 nebo pravý nástupce 308
Kampaně index	/{campaigns} SK /akcie CZ /akce HU /akciok RO /promotii	Next segment registry; CMS kampaně; Medusa obchodní podmínky, ceny a eligible katalog	index	self	ano	T	source failure 503	S	segment ΔS; obsah ΔC
Kampaň detail	/{campaigns}/{campaignSlug} SK /akcie/letny-vypredaj CZ /akce/letni-vyprodej HU /akciok/nyari-akcio RO /promotii/reduceri-de-vara	URLR; CMS editorial obsah a období; Medusa katalogová/business pravidla	aktivní publikovaná kampaň index; ukončená archivní kampaň noindex	self po dobu indexovatelného 200; ukončená (noindex) a tombstone bez canonical	pouze aktivní current URL	schválený subset L	miss 404; tombstone 410; source failure 503	E	slug ΔE; po skončení zůstává archivní 200 noindex bez canonical a opustí sitemapu; hard removal 410; skutečný nástupce 308
Poradna / blog index	/{advice} SK /poradna CZ /poradna HU /tanacsok RO /sfaturi	Next segment registry; CMS market-locale article index	clean a page>=2 index	self, včetně page>=2	pouze clean root	page a T	source failure 503; page mimo rozsah 404	S	segment ΔS; obsah ΔC
Článek poradny / blogu	/{advice}/{articleSlug} SK /poradna/ako-vybrat-bylinny-caj CZ /poradna/jak-vybrat-bylinny-caj HU /tanacsok/hogyan-valasszunk-gyogyteat RO /sfaturi/cum-alegi-un-ceai-din-plante	URLR; CMS market-locale článek, metadata a publikace	index	self	ano	T	miss 404; tombstone 410; CMS failure 503	E	slug ΔE; obsah ΔC; unpublish 410; skutečný nástupce 308
Informace index	/{information} SK /informacie CZ /informace HU /informaciok RO /informatii	Next segment registry	neexistuje v release	žádný	ne	žádné	vždy 404	S	zavedení indexu je budoucí změna contractu; současný path nesmí být přidělen entitě
Obecná informační stránka	/{information}/{pageSlug} SK /informacie/velkoobchod CZ /informace/velkoobchod HU /informaciok/nagykereskedelem RO /informatii/comert-cu-ridicata	URLR; CMS market-locale obsah a metadata	index	self	ano	T	miss 404; tombstone 410; CMS failure 503	E	slug ΔE; obsah ΔC; unpublish 410
O nás	SK /o-nas CZ /o-nas HU /rolunk RO /despre-noi	Next segment registry a locale labels; CMS market-locale obsah	index	self	ano	T	nepublikovaný obsah 404; CMS failure 503	S	segment ΔS; obsah ΔC
Kontakt	SK /kontakt CZ /kontakt HU /kapcsolat RO /contact	Next segment registry a locale labels; CMS kontaktní obsah; serverový contact handler mimo page URL	index	self	ano	T	CMS failure 503; submit failure je aplikační chyba, ne missing page	S	segment ΔS; obsah ΔC
FAQ	SK /casto-kladene-otazky CZ /caste-dotazy HU /gyakori-kerdesek RO /intrebari-frecvente	Next segment registry; CMS market-locale otázky a odpovědi	index	self	ano	T	CMS failure 503	S	segment ΔS; obsah ΔC
Doprava	SK /doprava CZ /doprava HU /szallitas RO /livrare	Next segment registry; CMS market-locale obsah; Medusa shipping options jsou business data, nikoli URL data	index	self	ano	T	CMS failure 503	S	segment ΔS; obsah ΔC
Vrácení zboží	SK /vratenie-tovaru CZ /vraceni-zbozi HU /visszakuldes RO /retururi	Next segment registry; CMS market-locale obsah	index	self	ano	T	CMS failure 503	S	segment ΔS; obsah ΔC
Obchodní podmínky	SK /obchodne-podmienky CZ /obchodni-podminky HU /altalanos-szerzodesi-feltetelek RO /termeni-si-conditii	Next legal segment registry; CMS versionovaný market-locale právní obsah	index	self	ano	T	chybějící schválená verze blokuje publikaci; runtime failure 503	S	segment ΔS; nová právní verze ΔC bez změny URL
Ochrana osobních údajů	SK /ochrana-osobnych-udajov CZ /ochrana-osobnich-udaju HU /adatvedelmi-tajekoztato RO /politica-de-confidentialitate	Next legal segment registry; CMS versionovaný právní obsah	index	self	ano	T	chybějící schválená verze blokuje publikaci; runtime failure 503	S	segment ΔS; obsah ΔC
Cookies	SK /cookies CZ /cookies HU /cookie-tajekoztato RO /politica-cookies	Next legal segment registry; CMS právní obsah; consent UI v Next locale resources	index	self	ano	T	chybějící schválená verze blokuje publikaci; runtime failure 503	S	segment ΔS; obsah ΔC
Vyhledávání	/{search}?q= SK /vyhladavanie?q=ashwagandha CZ /vyhledavani?q=ashwagandha HU /kereses?q=ashwagandha RO /cautare?q=ashwagandha	Next query parser a SEO klasifikace; market/channel-scoped katalogové search rozhraní	vždy noindex; crawlable	žádný	ne	Q	q chybí → 200 formulář; prázdné/whitespace q → 308 strip; invalid hodnoty/page 404; backend failure 503; zero results 200	S; query schema exact	segment ΔS; žádná alias history pro search dotaz

---

Košík, checkout, účet, auth, objednávky a recenze

Page type	Shape a konkrétní SK/CZ/HU/RO příklady	Zdroj dat	Indexace	Canonical	Sitemap	Parametry	Missing outcome	Kolize	Změna nebo odstranění
Košík	SK /kosik CZ /kosik HU /kosar RO /cos	Next route/UI; Medusa market/channel-scoped cart (market-scoped klíč)	noindex; crawlable	žádný	ne	pouze exact cart/provider parametry, jinak —	chybějící cart vytvoří prázdný cart stav; backend failure 503	S	segment ΔS; cart ID nikdy není v URL
Checkout root	SK /pokladna CZ /pokladna HU /penztar RO /finalizare-comanda	Next checkout config; Medusa cart/order; payment/shipping providers	noindex; crawlable	žádný	ne	P	bez validního cartu řízený 307 do košíku; backend failure 503	S	307 na default step; segment ΔS
Checkout krok: kontakt	SK /pokladna/kontakt CZ /pokladna/kontakt HU /penztar/kapcsolat RO /finalizare-comanda/contact	Next step registry a locale resources; Medusa cart/customer data	noindex; crawlable	žádný	ne	P	invalid flow/cart 404 nebo řízený 307 na první dosažitelný krok	R	změna segmentu ΔS; obchodní stav URL nemění
Checkout krok: doprava	SK /pokladna/doprava CZ /pokladna/doprava HU /penztar/szallitas RO /finalizare-comanda/livrare	Next step registry; Medusa shipping options a cart	noindex; crawlable	žádný	ne	P	nedosažitelný krok 307 na první validní krok; backend failure 503	R	ΔS
Checkout krok: platba	SK /pokladna/platba CZ /pokladna/platba HU /penztar/fizetes RO /finalizare-comanda/plata	Next step registry; Medusa cart/payment session; payment provider	noindex; crawlable	žádný	ne	P	nedosažitelný krok 307; invalid provider state 404; backend failure 503	R	ΔS
Checkout krok: kontrola	SK /pokladna/kontrola CZ /pokladna/kontrola HU /penztar/ellenorzes RO /finalizare-comanda/verificare	Next step registry; Medusa cart totals a order preparation	noindex; crawlable	žádný	ne	P	nedosažitelný krok 307; backend failure 503	R	ΔS
Návrat z platby	SK /pokladna/navrat-z-platby CZ /pokladna/navrat-z-platby HU /penztar/fizetesi-visszateres RO /finalizare-comanda/retur-plata	Next provider adapter; Medusa payment session/order; payment provider	noindex; bez SEO povrchu; TB	žádný	ne	pouze exact, case-preserving P	invalid state 404; backend/provider failure 503; žádný token-state oracle	R	segment ΔS; provider hodnoty se nepřesměrovávají; po úspěšném dokončení 303 na potvrzení objednávky
Potvrzení objednávky	/{checkout}/{confirmation}/{publicOrderId}; guest s ?ot={orderToken} SK /pokladna/potvrdenie-objednavky/ORD-AbC123 CZ /pokladna/potvrzeni-objednavky/ORD-AbC123 HU /penztar/rendeles-visszaigazolas/ORD-AbC123 RO /finalizare-comanda/confirmare-comanda/ORD-AbC123	Next step registry a locale resources; Medusa order — přístup přes session ownership přihlášeného zákazníka, nebo přes guest order token ot	noindex; bez SEO povrchu; TB	žádný	ne	exact case-preserving ot + P	cizí/neznámé/chybně caseované ID nebo invalidní/použitý/expirovaný token → jednotné 404; backend failure 503	R; ID i token case-preserving	ΔU/ΔT; cílová destinace 303 z návratu z platby pro hosta i přihlášeného zákazníka; token nikdy v metadata, logu ani redirect targetu
Účet dashboard	SK /ucet CZ /ucet HU /fiok RO /cont	Next route/UI; Medusa customer/session	noindex; crawlable	žádný	ne	—	neautentizovaný uživatel 307 na localized login; backend failure 503	S	segment ΔS
Uložené seznamy	SK /ucet/zoznamy CZ /ucet/seznamy HU /fiok/listak RO /cont/liste	Next route/UI; Medusa/customer list service	noindex; crawlable	žádný	ne	route-specific pagination pouze pokud ji kontrakt deklaruje	neautentizovaný 307; neznámý seznam 404; backend failure 503	R	segment ΔS; objekty ΔU
Objednávky index	SK /ucet/objednavky CZ /ucet/objednavky HU /fiok/rendelesek RO /cont/comenzi	Next route/UI; Medusa customer orders market-scoped	noindex; crawlable	žádný	ne	route-specific page	neautentizovaný 307; backend failure 503	R	segment ΔS; objekty ΔU
Objednávka detail	/{account}/{orders}/{publicOrderId} SK /ucet/objednavky/ORD-AbC123 CZ /ucet/objednavky/ORD-AbC123 HU /fiok/rendelesek/ORD-AbC123 RO /cont/comenzi/ORD-AbC123	Medusa order načtená přes customer ownership a market/channel scope	noindex; bez SEO povrchu; TB	žádný	ne	exact provider parametry jen pro explicitní flow	cizí, neznámé nebo chybně caseované ID 404; backend failure 503	R; ID case-preserving	ΔU; nikdy 410 a nikdy redirect podle odhadnutého ID
Nastavení účtu	SK /ucet/nastavenia CZ /ucet/nastaveni HU /fiok/beallitasok RO /cont/setari	Next route/UI; Medusa customer profile	noindex; crawlable	žádný	ne	—	neautentizovaný 307; backend failure 503	R	segment ΔS
Přihlášení	SK /ucet/prihlasenie CZ /ucet/prihlaseni HU /fiok/bejelentkezes RO /cont/autentificare	Next auth UI; Medusa customer auth	noindex; crawlable	žádný	ne	pouze schválený bezpečný návratový parametr (interní path z allowlistu); žádná libovolná externí URL	auth failure zůstává 200 formulářový stav; backend failure 503	R	segment ΔS
Registrace	SK /ucet/registracia CZ /ucet/registrace HU /fiok/regisztracio RO /cont/inregistrare	Next auth UI; Medusa customer auth	noindex; crawlable	žádný	ne	pouze exact auth schema	business validation 200 formulářový stav; backend failure 503	R	segment ΔS
Zapomenuté heslo	SK /ucet/zabudnute-heslo CZ /ucet/zapomenute-heslo HU /fiok/elfelejtett-jelszo RO /cont/parola-uitata	Next auth UI; Medusa reset workflow	noindex; crawlable	žádný	ne	exact auth schema	odpověď nesmí prozradit existenci účtu; backend failure 503	R	segment ΔS
Obnova hesla	SK /ucet/obnova-hesla?token={token} CZ /ucet/obnova-hesla?token={token} HU /fiok/jelszo-visszaallitas?token={token} RO /cont/resetare-parola?token={token}	Next auth UI; Medusa reset-token workflow	noindex; bez SEO povrchu; TB	žádný	ne	exact case-preserving token schema	invalidní, použitý či expirovaný token vždy 404; backend failure 503	R	ΔT; token nesmí vstoupit do metadata, logovaných URL ani redirect targetu
Produktová recenze přes token	/{reviews}/{product}/{token} SK /recenzie/produkt/Rv-AbC123 CZ /recenze/produkt/Rv-AbC123 HU /velemenyek/termek/Rv-AbC123 RO /recenzii/produs/Rv-AbC123	Next review UI; review workflow a Medusa product reference	noindex; bez SEO povrchu; TB	žádný	ne	token v path je case-preserving; pouze exact review schema	invalidní, použitý či expirovaný token vždy 404; backend failure 503	R	ΔT; žádný canonical, hreflang, OG URL, sitemap nebo redirect

---

API a technické endpointy

Page type	Shape a konkrétní SK/CZ/HU/RO příklady	Zdroj dat	Indexace	Canonical	Sitemap	Parametry	Missing outcome	Kolize	Změna nebo odstranění
Storefront API	/api/{endpoint} na každém hostu, např. SK https://herbatica.sk/api/search-autocomplete CZ https://herbatica.cz/api/storefront-auth/session HU https://herbatica.hu/api/storefront-auth/login RO https://herbatica.ro/api/storefront/orders/ORD-AbC123/qr-payment	Next Route Handlers; Medusa/search/provider adaptéry podle endpointu (market-scoped klíč)	neindexovatelný technický povrch; robots Disallow: /api/	žádný	ne	pouze exact endpoint schema; žádná generická canonicalizace signed parametrů	neznámý endpoint 404; nepovolená metoda 405; cizí objekt 404; backend failure 503	X	kontrakt se verzuje explicitně; žádné SEO aliasy ani tombstones
Robots	/robots.txt na každém canonical hostu	Next market config a canonical URL builder	technický soubor	žádný	ne	žádné	neznámý host 421; config failure 503	X	obsah se mění bez URL; Disallow pouze /~sf/ a /api/; uvádí právě host-specific absolutní sitemap URL
Sitemap index	/sitemap.xml SK https://herbatica.sk/sitemap.xml CZ https://herbatica.cz/sitemap.xml HU https://herbatica.hu/sitemap.xml RO https://herbatica.ro/sitemap.xml	Next URLR enumerace, CMS a market/channel availability snapshot	technický XML soubor	žádný	je sitemap indexem	žádné	source failure 503; nikdy neúplný 200 vydávaný za kompletní sitemapu	X	stabilní URL; změna membership invaliduje sitemap:{market}
Sitemap shard	/sitemaps/{kind}-{n}.xml, např. SK /sitemaps/products-1.xml CZ /sitemaps/categories-1.xml HU /sitemaps/advice-1.xml RO /sitemaps/static-1.xml	Bounded/paginated Next enumerace current canonical 200 URL	technický XML soubor	žádný	odkazován sitemap indexem	žádné	neznámý kind/shard 404; source failure 503	X	shardování kolem 10 000 URL nebo 25 MB; odstraněný shard 404 až po odebrání z indexu
Web manifest	/manifest.webmanifest na všech hostech	Next market config a locale resources	technický soubor	žádný	ne	žádné	neznámý host 421; config failure 503	X	stabilní URL; host-specific name, locale a start URL
Product feed	/feeds/products.xml na všech hostech	Medusa market/channel-scoped katalog; Next feed serializer a canonical URL builder	technický feed, ne HTML index	žádný	ne	pouze explicitní feed schema	source failure 503; nikdy fallback na jiný market	X	stabilní URL; bounded/paginated generování a market-scoped cache
Interní resolver namespace	/~sf/{market}/{kind}/...; žádný veřejný příklad není validní	Výhradně interní rewrite target Proxy pro resolved current routes	nesmí být veřejně dostupný	žádný	ne	žádné veřejné	přímý přístup 404: raw encoded/double-encoded varianty blokuje ingress, normalizovaný namespace blokuje Proxy	X, včetně /~SF, /%7Esf, /%7esf, /%257Esf a ekvivalentů dle acceptance matice	nikdy nevytváří redirect ani veřejný alias
Chybové povrchy 404/410/500/503	render na požadované URL; žádná samostatná veřejná error URL	Next locale resources (lokalizovaný obsah); status vlastní vrstva dle tabulky Vlastnictví HTTP statusů	noindex (X-Robots-Tag i meta)	žádný	ne	žádné	n/a — jsou samy výsledkem	X	správný wire status před prvním bytem; Cache-Control: no-store; žádný canonical, hreflang, redirect ani JSON-LD; texty ΔC
Framework assets	/_next/*, /favicon.ico, statické asset paths	Next build/static assets	technický povrch	žádný	ne	framework-specific	neznámý asset 404	X	obsahově hashované assets expirují přirozeně; názvy jsou rezervované
Well-known endpointy	/.well-known/{name} pouze pro explicitně registrované integrace	Next Route Handler nebo statický soubor	technický povrch	žádný	ne	exact integrační schema	neregistrovaný název 404	X	změna podle integračního kontraktu; nikdy commerce entity namespace

---

Migrace dnešních new-site URL (immutable migration manifest)

Před releasem vzniká verzovaný, immutable migration manifest pokrývající každou dosud publikovanou new-site cestu. Každá cesta má právě jeden stav: 308, zachování, 404, nebo tokenová výjimka. Žádné alias chains — staré cesty vedou vždy přímo na current canonical. Redirecty platí jen pro GET/HEAD. Aliasy se seedují per market, kde byla cesta veřejně obsluhována; hosty, kde publikována nebyla, vracejí přirozeně 404. Nekompletní manifest (nerozhodnutá cesta) blokuje release.

Dnešní cesta	Stav	Cíl / chování
/p/{slug}	308	přímý alias na /{products}/{currentSlug}; seed z URLR importu
/c/{slug}	308	přímý alias na /{categories}/{currentSlug}
/znacka/{slug}	308	přímý alias na /{brands}/{currentSlug}
/blog, /blog/{slug}	308	na /{advice}, resp. /{advice}/{currentSlug}
root /{slug} (CMS stránky)	308	export všech root CMS slugů před odstraněním root [slug] routy; kontrola proti novým statickým cestám (kolize blokuje import a řeší se ručně v manifestu); seed přímých aliasů na /{information}/{slug} daného marketu
/search	308	na /{search} se zachováním validního q; unknown parametry strip
/faq	308 / zachování	na lokalizovanou FAQ cestu marketu (/casto-kladene-otazky, /caste-dotazy, …)
/o-nas	zachování (SK/CZ) / 308 (HU/RO)	SK/CZ current URL je identická; HU/RO alias na /rolunk, /despre-noi
/account/**	308	mapa sub-route → lokalizované /{account}/... cesty (dashboard, objednávky, seznamy, nastavení)
/auth/**	308	na lokalizované auth cesty (/{account}/{login}, /{account}/{register}, …)
/reset-password	tokenová výjimka	žádný redirect (token nesmí do redirect targetu, ΔT/TB); cesta zůstává obsluhována se stejnou jednotnou 404 sémantikou do expirace všech vydaných tokenů po cutoveru, poté 404
/checkout/**	308 + tokenová výjimka	obecné kroky 308 na /{checkout} (flow re-resolvuje krok); provider payment-return cesty zůstávají obsluhovány, dokud nejsou return URL přepnuté u providerů, poté 404; P parametry bez generické normalizace
/reviews/product/**	tokenová výjimka	žádný redirect (ΔT/TB); obsluha do expirace vydaných review tokenů, poté 404
/homepage-promo	308	na /; redirect se přesouvá z next.config.ts redirects() do alias registru

---

Canonical, hreflang a sitemap chování podle page type

URL třída	Robots metadata	Canonical	Hreflang	Sitemap
Homepage	index	self	všechny existující market homepage URL; self-reference	ano
Clean katalogový/content index	index	self	pouze skutečné ekvivalentní indexy; self-reference	ano
Entity detail	index	self	podle URLR equivalence_key; chybějící market se vynechá	ano
page>=2	index	self včetně page	ne	ne
Facet nebo sort URL	noindex	žádný	ne	ne
Prázdný publikovaný listing (∅)	noindex	žádný	ne	ne
Product ?variant=	indexační signál přes canonical základního produktu	základní produkt bez variant	ne pro variantní URL	ne
Tracking-only URL	podle clean cíle	clean URL bez tracking parametrů	podle clean URL	pouze clean URL
Search	noindex	žádný	ne	ne
Cart, checkout, account, auth, orders, potvrzení objednávky	noindex	žádný	ne	ne
Token routes (TB)	noindex, nofollow, noarchive	žádný	ne	ne
Aktivní kampaň	index	self	jen skutečné market ekvivalenty	ano
Ukončená archivní kampaň	noindex	žádný	ne	ne
Alias	žádný render	308 přímo na current canonical	pouze na cílové stránce	ne
Tombstone	410	žádný	ne	ne
Missing entity	404 plus noindex	žádný	ne	ne
Source failure	resolve-phase 503 (Proxy), render-phase 500 (error povrch); noindex, no-store	žádný nově generovaný SEO povrch	ne	ne

Interní odkazy a cross-domain přepnutí

• Interní odkazy vždy používají current canonical URL vytvořenou centrálním builderem; aliasy se nesmějí objevovat v navigaci, CMS renderu, metadata ani strukturovaných datech.
• Přepínač trhu používá URLR equivalence_key. Nesmí překládat URL mechanickou výměnou hostu ani opakovaným použitím stejného slugu.
• Seed equivalence_key: automatický seed z Medusa product ID je dovolen pouze tehdy, když tentýž Medusa produktový record je záměrně publikován ve více marketech. Oddělené marketové produkty vyžadují explicitní shared equivalence UUID přidělené v URLR operačním rozhraní. Import generuje report konfliktů; implicitní spojování záznamů podle handle, názvu nebo slugu je zakázáno. Kategorie a CMS entity mají výhradně manuální equivalence mapping.
• Pokud ekvivalent v cílovém marketu neexistuje, přepínač nabídne cílovou homepage jako explicitní uživatelskou navigační volbu; tato homepage se však nesmí emitovat jako hreflang ekvivalent stránky.
• Produktové breadcrumbs používají primary category z custom Medusa merchandising extension (validovaná metadata.primary_category_id; není standardní core field); deterministický fallback: nejhlubší dostupná leaf kategorie → nižší rank → nejnižší ID. Primary category ovlivňuje breadcrumb, structured data a navigaci, nikdy URL; URLR ji nevlastní.
• Kategorie mohou mít libovolnou datovou hloubku; fetch je bounded/paginated a navigace zobrazuje nejvýše pět úrovní. Přesun kategorie mění breadcrumbs, navigaci, structured data a lastModified, nikoli canonical URL.

---

ČÁST C — Next.js routing a datový kontrakt s Medusou

[BleedingDev]

Plná normativní specifikace — část 03/5. Krátká implementační verze je v popisu issue; tato část je závazný zdroj při sporu.

---

5. Specifikace routingu Next.js

5.1 Závazná oprava architektury a behaviorální autorita

Release 2026-08-20 MUST používat přesně připnutý Next.js 16.3.0-preview.5. Build MUST selhat, pokud:

• apps/herbatika/package.json neobsahuje přesně next: "16.3.0-preview.5";
• instalovaná verze v apps/herbatika/node_modules/next/package.json neodpovídá;
• zmizí podporované config položky skipProxyUrlNormalize nebo skipTrailingSlashRedirect;
• se bez samostatné schválené změny změní router/status chování.

Exact preview source je behaviorální autorita:

• instalovaný HTTP-access fallback podporuje pouze 401, 403 a 404; gone() ani obecné API pro 410/503 neexistuje;
• redirect() a permanentRedirect() podporují 307 a 308, ale ve streamovaném App Router response mohou přejít na client-side meta redirect;
• App Router Server Component nemůže po zahájení renderu interně rewrite-nout request do Route Handleru ani nastavit libovolný status;
• Pages Router getServerSideProps dostává Node res, může nastavit res.statusCode, vrátit notFound: true nebo redirect a preview source před odesláním HTML čeká na dokončení Pages renderu.

Původní návrh „App Router page resolver → interní rewrite na status/gone/route.ts“ je neplatný a MUST být odstraněn.

5.2 Závazné rozdělení routerů

Release používá hybridní projekt, ale s jediným veřejným HTML routerem:

• Pages Router vlastní všechny veřejné HTML stránky, protože musí spolehlivě vracet 308, 400, 404, 410 nebo 503.
• App Router vlastní pouze Route Handlers: API, payment callbacky, webhooky, robots, sitemap, manifest, feed a interní provozní endpointy.
• App Router HTML routes MUST NOT zůstat souběžně dostupné na veřejných cestách.
• App Router a Pages Router MUST NOT definovat stejnou výslednou interní pathname.

Toto je release architektonické rozhodnutí. Důvodem není SEO preference Pages Routeru, ale chybějící obecný hard-status mechanismus v App Routeru 16.3.0-preview.5.

Veřejné odkazy na Pages SSR routes MUST používat dokumentovou navigaci. Sdílený StorefrontLink pro tyto cíle vyrenderuje obyčejné <a href>, nikoli App Router RSC navigaci nebo Pages Router data-prefetch. Tím se garantuje, že resolver rozhoduje nad skutečným HTML requestem a konečný HTTP status není skrytý v /_next/data requestu.

RouteTarget proto obsahuje:

interface RouteTarget {
  kind: PublicRouteKind;
  params: Readonly<Record<string, string>>;
  query?: Readonly<Record<string, string | readonly string[]>>;
  navigation: "document" | "client";
}

Pro všechny veřejné HTML routes je v release navigation: "document".

5.3 Opravený interní route strom

src/
  proxy.ts

  pages/
    _app.tsx
    _document.tsx
    _error.tsx
    404.tsx

    ~sf/
      [market]/
        home.tsx

        products/
          index.tsx
        product/
          [slug].tsx

        categories/
          index.tsx
        category/
          [slug].tsx

        brands/
          index.tsx
        brand/
          [slug].tsx

        collections/
          index.tsx
        collection/
          [slug].tsx

        campaigns/
          index.tsx
        campaign/
          [slug].tsx

        advice/
          index.tsx
          [slug].tsx

        information/
          [slug].tsx

        search.tsx
        cart.tsx

        checkout/
          index.tsx
          [step].tsx
          result.tsx

        account/
          index.tsx
          section/
            [section].tsx
          order/
            [publicOrderId].tsx
          auth/
            [action].tsx

        reviews/
          product/
            [token].tsx

        static/
          [pageKey].tsx

  app/
    ~sf/
      [market]/
        system/
          robots/
            route.ts
          sitemap/
            index/
              route.ts
            shard/
              [shard]/
                route.ts
          manifest/
            route.ts
          product-feed/
            route.ts

    api/
      payments/
        [provider]/
          return/
            route.ts
      storefront-auth/
        ...
      search-autocomplete/
        route.ts
      revalidation/
        route.ts
      healthz/
        route.ts

Složka app/_m MUST NOT být použita, protože _-prefixovaná složka je private folder.

Pages Router potřebuje vlastní _app.tsx a _document.tsx; app/layout.tsx se na Pages routes nevztahuje. Oba routery MUST skládat UI ze společného storefront shellu, locale resources a design-system komponent. MUST NOT vzniknout Pages-specific kopie navigace, URL builderu nebo market konfigurace.

5.4 Rozdělení konfigurace

Statická route taxonomie a runtime deployment binding jsou oddělené:

interface MarketRouteDefinition {
  market: MarketCode;
  locale: Locale;
  countryCode: CountryCode;
  segments: StaticSegmentRegistry;
  checkoutSteps: Readonly<Record<CheckoutStepKey, string>>;
  checkoutResult: string;
  staticPages: Readonly<Record<StaticPageKey, string>>;
  historicalPaths: readonly StaticRoutePath[];
}

interface MarketDeploymentBinding {
  canonicalOrigin: URL;
  acceptedHosts: readonly string[];
  regionId: string;
  salesChannelId: string;
  publishableApiKey: string;
  publishableApiKeyId: string;
}

interface DeploymentRoutingConfig {
  allowedMarkets: readonly MarketCode[];
  bindings: Readonly<Partial<Record<MarketCode, MarketDeploymentBinding>>>;
}

Pravidla:

• allowedMarkets patří pouze do DeploymentRoutingConfig.
• publishableApiKey je hodnota posílaná v x-publishable-api-key.
• publishableApiKeyId je oddělené interní ID použité pro validační manifest a Admin/Query kontrolu.
• routeTaxonomyHash se počítá pouze ze statické taxonomie, lokalizovaných segmentů a historie statických aliases.
• deploymentBindingHash se počítá z runtime bindingu; místo hodnoty PAK obsahuje pouze fingerprint.
• Separate deployments stejného buildu MUST mít shodný routeTaxonomyHash, ale MAY mít rozdílný deploymentBindingHash.
• Všechny instance jednoho deploymentu MUST mít oba hashe shodné.
• NEXT_PUBLIC_* MUST NOT být autoritou pro market, origin, region, channel ani PAK.

Boot validace MUST ověřit:

1. každý povolený market má kompletní route definition a deployment binding;
2. canonical origin používá HTTPS mimo lokální vývoj;
3. host není přiřazen více marketům;
4. canonical host patří právě jednomu marketu;
5. PAK scope přesně odpovídá jednomu očekávanému sales channelu;
6. route a binding hash odpovídají deployment manifestu.

5.5 Hosty, DNS a deployment evidence

Repozitář prokazuje pouze:

• standalone Next.js server poslouchající na 0.0.0.0:3000;
• Docker Compose mapování jedné služby na jeden loopback port.

Repozitář neprokazuje produkční multi-host reverse proxy, TLS terminaci ani přepis x-forwarded-* hlaviček.

Proto:

• standalone služba je technicky schopná přijmout různé Host hlavičky;
• produkční host routing a trust boundary jsou samostatná provozní závislost;
• HOST_MARKET_MAP není důkaz vlastnictví DNS nebo TLS certifikátu;
• herbatika.*, www.* a jiné alias hosty MUST NOT vstoupit do acceptedHosts, dokud není ověřeno DNS, TLS a provozní vlastnictví;
• neověřený host vrací 421, nikoli 308;
• deployment marketu MUST NOT nastartovat jako production-ready, pokud není ověřen jeho canonical host.

Canonical origins zůstávají:

https://herbatica.sk
https://herbatica.cz
https://herbatica.hu
https://herbatica.ro

Alias host se smí redirectovat pouze po zařazení do ověřeného acceptedHosts.

5.6 next.config.ts

Release config MUST obsahovat:

{
  skipProxyUrlNormalize: true,
  skipTrailingSlashRedirect: true,
  redirects: async () => [],
  cacheComponents: false
}

redirects() MUST vracet prázdné pole. Současný redirect:

/homepage-promo → /#homepage-promo

MUST být odstraněn z next.config.ts, protože config redirects běží před Proxy a obcházejí host allowlist, market resolution a složenou canonicalization.

Veřejné business redirecty MUST NOT být v redirects() ani v rewrites(). headers() MAY obsahovat pouze statické bezpečnostní hlavičky, nikoli route rozhodování.

skipProxyUrlNormalize: true je povinné, aby Proxy viděla konzistentní URL tvar při direct requestu a Next client transition. Flag ale negarantuje dostupnost původních raw bytes. Malformed UTF-8, dvojité encodingy, raw authority, encoded slash/backslash a limit request-target zůstávají povinností ingress adapteru a wire testů.

5.7 Proxy matcher a trust boundary

Matcher MUST být statická build-time konstanta. Musí zahrnout:

• všechny veřejné HTML cesty;
• /robots.txt;
• /sitemap.xml;
• /sitemaps/*;
• /manifest.webmanifest;
• /feeds/products.xml;
• /favicon.ico;
• /.well-known/*;
• všechny varianty přímého /~sf.

Musí vyloučit:

• /_next/static/*;
• /_next/image/*;
• běžné veřejné assety;
• /api/*, jejichž handlers používají vlastní market/host boundary;
• interní health endpoint.

Server Functions na veřejných HTML routes jsou pro release zakázány. Mutace MUST vést přes explicitní /api Route Handlers. Tím nevznikne bezpečnostní závislost na tom, zda Proxy matcher pokrývá Server Function POST.

Proxy MUST:

1. scrubnout klientem dodané x-sf-*, x-market-code, x-sales-channel-id, x-canonical-origin a obdobné interní hlavičky;
2. získat host/protocol pouze z adapter-specific trusted origin resolveru;
3. vyřešit ověřený host na právě jeden market;
4. vrátit 421 pro syntakticky validní neznámý host;
5. zablokovat přímé /~sf, /~SF, /%7Esf a rozpoznatelné case/percent varianty;
6. staticky rozpoznat current nebo historický localized prefix;
7. nastavit důvěryhodné request headers s marketem, route key a původní veřejnou cestou;
8. rewrite-nout request na semantic Pages route;
9. rewrite-nout market-scoped system URLs na App Route Handlers;
10. pro unsafe metodu na HTML route vrátit 405 s Allow: GET, HEAD.

Proxy MUST NOT číst URLR, Medusa, CMS, katalog ani alias DB.

x-forwarded-host a x-forwarded-proto se smí použít pouze v adapteru, u něhož ingress:

• není veřejně obejitelný;
• vždy odstraní klientské hodnoty;
• nastaví vlastní canonical forwarding headers;
• je pokryt wire testem.

5.8 Resolution pipeline a hard statusy

Fáze A: ingress

Ingress MUST:

• validovat raw request-target a authority;
• odmítnout malformed %, invalid authority a raw control characters jako 400;
• odmítnout request-target delší než 2048 B jako 414;
• odmítnout raw encoded slash/backslash podle adapter policy;
• provést HTTPS redirect, pokud TLS není ukončeno před aplikací;
• přepsat trusted forwarding headers.

Fáze B: Proxy

Proxy provede pouze statické kroky popsané v §5.7. Host, case, trailing slash nebo historický prefix na entity requestu ještě nemusí vyvolat redirect; Proxy musí request doručit SSR resolveru, aby bylo možné složit všechny opravy do jednoho výsledného 308.

Fáze C: getServerSideProps

Každá Pages route používá společný SSR resolver:

1. načte důvěryhodný market context;
2. percent-decode provede právě jednou;
3. validuje segmenty a route-specific query;
4. rozpozná static route nebo entity kind;
5. provede jeden indexovaný URLR lookup;
6. vyřeší lifecycle, current slug, alias nebo tombstone;
7. provede nejvýše jeden bounded equivalence lookup;
8. načte source entity přes market-scoped reader;
9. sestaví canonicalization decision;
10. nastaví status nebo vrátí redirect ještě před React renderem.

Výsledek:

Stav	Pages/Proxy mechanismus
current canonical 200	{ props }
alias, host, case, slash nebo query oprava	GSSP redirect: { permanent: true }, výsledně 308
neplatný checkout step	GSSP temporary redirect, 307
definitivní miss	{ notFound: true }, 404
URLR retired/tombstone	res.statusCode = 410, status page props
backend timeout/5xx	res.statusCode = 503, Retry-After, status page props
syntaktická chyba dostupná až resolveru	res.statusCode = 400
neznámý host	Proxy 421
unsafe metoda na HTML route	Proxy 405
příliš dlouhá raw URL	ingress 414

Interní gone Route Handler MUST NOT existovat jako status workaround.

410, 400 a 503 status views MUST být renderovány přímo stejnou Pages route. Nesmějí vyvolat externí redirect.

503 MUST být odlišeno od definitivního miss pomocí typed reader výsledku:

type SourceReadResult<T> =
  | { kind: "found"; value: T }
  | { kind: "not-found" }
  | { kind: "unavailable"; retryAfterSeconds?: number }
  | { kind: "invalid-payload"; causeCode: string };

unavailable a invalid-payload vracejí 503, nikoli 404.

5.9 Jednohopová canonicalization

SSR resolver skládá do jednoho targetu:

• canonical protocol;
• canonical host;
• localized current static segments;
• current entity slug;
• lowercase statických segmentů a entity slugu;
• odstranění trailing slash;
• static nebo entity alias;
• normalizovanou query.

Běžný request smí mít nejvýše jeden 308. TLS redirect na ingressu smí přidat jeden předchozí hop.

Alias chains MUST NOT existovat.

Lowercase se vztahuje pouze na:

• route segment registry;
• entity slugy;
• versioned lowercase facet keys.

Case-preserving jsou:

• review/reset tokeny;
• public order IDs;
• variant hodnoty;
• signed provider parametry;
• opaque checkout result state.

Uppercase slug se redirectuje pouze tehdy, když lowercase lookup jednoznačně najde current nebo alias. Jinak vrací 404.

5.10 URL registry a lifecycle

Původní schéma s mutable canonical_path na alias řádku je zrušeno.

Logická route

url_route
- id
- market
- kind
- target_type: entity | static
- source_entity_id nullable
- static_route_key nullable
- equivalence_key nullable
- index_policy
- lifecycle: active | retired | superseded
- successor_route_id nullable
- created_at
- updated_at

Constraint:

target_type=entity  → source_entity_id NOT NULL, static_route_key NULL
target_type=static  → static_route_key NOT NULL, source_entity_id NULL

Entity slugy

url_entity_slug
- id
- market
- kind
- normalized_slug
- route_id nullable
- disposition: current | alias | gone
- created_at

Povinné DB invarianty:

• UNIQUE(market, kind, normalized_slug);
• UNIQUE(route_id) WHERE disposition = 'current';
• current a alias mají route_id NOT NULL;
• samostatný gone MAY mít route_id NULL;
• alias row je immutable;
• route market/kind musí odpovídat slug row;
• slug alias nemá uložený canonical target;
• canonical target se získá joinem na jediný current slug route;
• alias nikdy neodkazuje na alias.

Statické cesty a segmenty

Typed route registry obsahuje relation:

static_route_path
- market
- route_key
- parent_route_key nullable
- segment
- match_mode: exact | prefix
- disposition: current | alias
- introduced_in_version

Je to jediný zdroj pravdy pro current i historické:

• type prefixy;
• static pages;
• account/auth children;
• checkout kroky;
• legal paths;
• search;
• review path;
• historické /p, /c, /znacka, /blog.

Registry se kompiluje do immutable Proxy snapshotu a zahrnuje se do routeTaxonomyHash. Po publikaci se starý static segment mění na immutable alias; nesmí být odstraněn ani znovu použit pro jiný route key.

Lifecycle

• active: current path vrací 200, alias 308;
• retired: všechny current i historické slug paths vrací 410;
• superseded: všechny paths vrací přímý 308 na current path successor_route_id;
• samostatný gone vrací 410.

Slug transakce

1. zamknout route a relevantní slug namespace;
2. ověřit normalizaci a kolize;
3. změnit existující current row na alias;
4. vložit nový current row;
5. commitnout jako jedinou transakci;
6. invalidovat old path, new path, route, equivalence, metadata a sitemap.

Starý current row se nevkládá znovu a žádný alias se následně neupravuje.

5.11 Jediné URL API

parsePublicPath(input): ParsedPublicRoute
resolvePublicRoute(input): Promise<ResolvedPublicRoute>
buildPath(target, market): string
buildAbsoluteUrl(target, market): URL
normalizeQuery(kind, searchParams): NormalizedQueryResult
buildAlternates(target): Promise<AlternateMap>
classifySeo(route): SeoClassification
resolveNavigationMode(target): "document" | "client"

Stejný package subpath používají:

• Proxy parser;
• Pages SSR resolver;
• next/head;
• App Route Handlers;
• sitemap;
• robots;
• feed;
• interní odkazy;
• e-maily;
• payment return URL;
• testy.

typedRoutes ověřuje pouze filesystem route. Nenahrazuje business RouteTarget.

Client Components MUST dostat hotový href nebo serializovatelný RouteTarget. MUST NOT odvozovat market z window.location.

Současné payment-session.ts, které skládá return URL z window.location.origin, je release blocker. Payment URL MUST vzniknout na serveru z canonicalOrigin.

5.12 Query a facet resolution

Obecná pravidla

• duplicate scalar key (page, sort, q, variant) → 404;
• duplicate facet key (brand=a&brand=b) → 404;
• unknown non-tracking key → jeden 308 bez něj;
• tracking allowlist: utm_* nejvýše 10 položek, gclid, fbclid;
• canonical builder tracking parametry odstraní, ale zachová case-preserving hodnoty ostatních parametrů;
• page=1 a default sort se odstraní;
• invalidní hodnoty vrací 404.

Search

• /search bez q → 200, užitečný search form, noindex, bez canonical;
• q= nebo whitespace-only q → 308 na clean search path bez q;
• duplicate q → 404;
• zero-result query → 200, noindex, užitečné alternativy;
• q max 200 znaků.

Brand facet

brand je current brand URLR slug:

• max 10 hodnot;
• resolver provede jeden batch SQL lookup;
• unknown nebo retired hodnota → 404;
• alias nebo superseded hodnota → jeden složený 308 se všemi current hodnotami;
• mix current + alias hodnot se normalizuje jedním 308;
• hodnoty se deduplikují a řadí.

ingredient a form

Jde o versioned market facet keys vlastněné Next URL vrstvou a navázané na stabilní Medusa attribute/value IDs:

url_facet_value
- market
- facet_kind
- source_attribute_id
- source_value_id
- normalized_key
- disposition: current | alias | gone

Runtime slugifikace Medusa labelu MUST NOT existovat.

Pagination a facets

• clean page>=2: index, self-canonical, mimo sitemap;
• libovolný facet nebo sort, i v kombinaci s page: noindex, bez canonical;
• variant: canonical base produkt; hodnota zůstává case-preserving;
• page za poslední stránkou: 404.

5.13 Payment callback a checkout result

Nový callback tvar:

/api/payments/{provider}/return

Každý provider má exact schema:

• case-preserving query;
• povinnou signature/state validaci;
• explicitní allowlist parametrů;
• timeout;
• replay protection;
• žádný generický sorter nebo tracking stripper.

Po úspěšném zpracování callback vrátí 303 na lokalizovaný checkout result:

Key	SK	CZ	HU	RO
checkoutResult	vysledok	vysledek	eredmeny	rezultat

Výsledná cesta:

/{checkout}/{checkoutResult}

Stav výsledku se přenáší serverovou session nebo jednorázovým opaque state, nikoli nezvalidovanými provider parametry.

Současný /checkout/platba-navrat:

• je neveřejná compatibility route;
• nesmí mít canonical, hreflang, OG URL ani sitemap;
• nesmí projít generickou query normalizací;
• ověří provider a podpis stejným adapterem jako nový callback;
• po zpracování vrátí 303 na localized checkout result.

5.14 Metadata a SEO transport

Pages routes používají next/head, ale metadata vznikají ze stejného ResolvedPublicRoute a SeoClassification jako stránka.

Indexovatelná route MUST emitovat:

• absolutní self-canonical;
• Open Graph URL shodnou s canonical;
• JSON-LD URL shodnou s canonical;
• reciprocal hreflang pouze pro skutečné current ekvivalenty.

Pages Router nemá používat metadataBase; absolutní URL sestavuje buildAbsoluteUrl() z validovaného canonicalOrigin.

App Route Handlers metadata negenerují.

Token/account/auth/cart/checkout/search/facet routes:

• mají noindex;
• nemají canonical, hreflang, OG URL ani sitemap membership.

Review/reset token ani provider state MUST NOT vstoupit do:

• title;
• description;
• canonical;
• OG;
• JSON-LD;
• analytics page name;
• structured log context.

Tokenové stránky SHOULD nastavit Referrer-Policy: no-referrer.

5.15 System routing

Veřejná URL	Chování
/robots.txt	market-scoped Route Handler, absolutní sitemap URL
/sitemap.xml	market-scoped sitemap index
/sitemaps/{kind}-{n}.xml	existující shard 200; unknown shard 404
/manifest.webmanifest	market-specific name, start URL a icons
/feeds/products.xml	market/channel-scoped canonical product feed
/favicon.ico	shared asset; pouze ověřený host
/.well-known/*	explicitní allowlist; ostatní 404
/api/healthz	internal-only ingress health endpoint
/api/*	vlastní host/market/auth boundary

ACME challenge SHOULD být obsloužen ingress platformou. Next /.well-known/acme-challenge/* MUST NOT být implicitně povolen.

/api/healthz je mimo veřejný host routing a MUST být přístupný pouze z interní sítě nebo platform health checkeru.

5.16 Sitemap a robots

Sitemap Route Handler používá URLR a Medusa readers, nikoli filesystem discovery.

Každá URL v sitemapě musí být:

• current;
• canonical;
• indexovatelná;
• dostupná v marketu;
• dostupná v očekávaném sales channelu;
• samostatně ověřitelná jako 200.

Release crawler MUST s bounded concurrency provést request na každou sitemap URL ve staging snapshotu. Redirect, 404, 410 nebo 503 blokuje release.

robots.txt obsahuje:

Disallow: /~sf/
Disallow: /api/

Search, facets, account, auth, cart, checkout a token routes se v robots neblokují; používají noindex.

5.17 Cache a revalidace

Pages SSR responses jsou dynamické a MUST NOT být sdíleně cachovány jako HTML.

Data cache pravidla:

• URLR resolution pro release čte autoritativní Postgres/read replica; process-local cache MUST NOT být autoritou;
• shared cache MAY být použita až po prokázané distribuované invalidaci;
• source entity cache key obsahuje market a očekávaný salesChannelId;
• URLR alias/tombstone rozhodnutí nesmí při source failure degradovat na 404.

Povinné tagy:

market:{market}
route:{market}:{kind}:{routeId}
route-slug:{market}:{kind}:{slug}
static-route:{market}:{routeKey}
equivalence:{equivalenceKey}
facet:{market}:{facetKind}:{sourceId}
{entityKind}:{market}:{entityId}
sitemap:{market}

Multi-instance deployment MUST mít:

• shared cache handler;
• refreshTags() koordinaci;
• stejný NEXT_SERVER_ACTIONS_ENCRYPTION_KEY, pokud v projektu zůstanou Server Functions;
• stejný deploymentId;
• shodný route taxonomy a deployment binding hash.

cacheComponents je pro release OFF. Pages hard-status boundary na něm nesmí záviset. Re-enable je samostatná post-release změna.

5.18 Collision validator

Validator kontroluje normalizovanou celou public path i sibling namespaces.

Povinné kontroly:

• static × static;
• prefix × static page;
• current prefix × historical prefix;
• entity current × alias × gone;
• account sections × orders × auth actions;
• checkout steps × result/callback reserved keys;
• static pages × všechny type prefixy;
• review token path × entity prefixes;
• current/alias facet values;
• transliterační kolize;
• host přiřazený více marketům;
• duplicitní (market, kind, equivalence_key);
• route kind × source entity kind;
• /~sf case a percent variants.

Proxy rozhoduje business kind pomocí exact sibling registry. Obecný account [section] MUST NOT zachytit orders nebo auth action.

Reserved hodnoty:

api
_next
~sf
.well-known
robots.txt
sitemap.xml
sitemaps
favicon.ico
manifest.webmanifest
feeds
healthz
.
..

5.19 Úplný migration inventory současných routes

Release manifest MUST pokrýt 100 % současných filesystem a config routes. Build porovná manifest s Next route inventory a při chybějící položce selže.

Současná route	Binding
/	nový localized home target
/p/[handle]	entity compatibility alias → localized product, 308
/c/[slug]	entity compatibility alias → localized category, 308
/znacka	static alias → localized brands index, 308
/znacka/[slug]	entity alias → localized brand, 308
/blog	static alias → localized advice index, 308
/blog/[slug]	explicit CMS mapping → advice detail, 308; unknown 404
/[slug]	catch-all odstraněn; každý publikovaný CMS slug musí být explicitně inventarizován
/faq	static alias na localized FAQ, 308
/o-nas	static alias na localized about, 308
/search	static alias na localized search; složený 308 s query
/account	static alias na localized account, 308
/account/orders	static alias, 308
/account/orders/[id]	static prefix alias; ID case-preserving, 308
/account/lists	static alias, 308
/account/settings	static alias, 308
/auth/login	static alias na localized account auth, 308
/auth/register	static alias, 308
/auth/forgot-password	neveřejná compatibility rewrite, noindex
/auth/reset-password	neveřejná compatibility rewrite, noindex
/reset-password	neveřejná compatibility rewrite, noindex
/checkout	static alias na localized checkout, 308
/checkout/[step]	mapovaný step alias; unknown step 307 na default
/checkout/platba-navrat	payment compatibility handler, bez SEO povrchu
/reviews/product/[token]	internal compatibility rewrite, bez redirectu tokenu
/homepage-promo	typed static alias → canonical home s fragmentem; config redirect odstraněn
/api/search-autocomplete	zachovat explicitní Route Handler
/api/storefront-auth/*	zachovat explicitní auth API
/api/storefront/orders/[id]/qr-payment	zachovat; auth a ownership check
ostatní development-only route	explicitní manifest 404, nikoli implicitní přežití

U /[slug] musí cutover exportovat seznam skutečně publikovaných CMS slugů. Neinventarizovaný root slug vrací 404.

5.20 Lokalizované příklady a native sign-off

Následující hodnoty jsou navržené, neověřené. MUST NOT být v konečné sekci označeny jako „natural verified“, dokud nebude vyplněn reviewer locale, reviewer a datum.

Market	Reviewer locale	Reviewer	Datum	Stav
SK	sk-SK	nepřidělen	—	release blocker
CZ	cs-CZ	nepřidělen	—	release blocker
HU	hu-HU	nepřidělen	—	release blocker
RO	ro-RO	nepřidělen	—	release blocker

Navržené úplné URL:

Typ	SK	CZ	HU	RO
Produkt	https://herbatica.sk/produkty/ostropestrec-mariansky-kapsuly	https://herbatica.cz/produkty/ostropestrec-mariansky-kapsle	https://herbatica.hu/termekek/mariatovis-kapszula	https://herbatica.ro/produse/armurariu-capsule
Kategorie	https://herbatica.sk/kategorie/bylinne-caje	https://herbatica.cz/kategorie/bylinne-caje	https://herbatica.hu/kategoriak/gyogyteak	https://herbatica.ro/categorii/ceaiuri-din-plante
Značka	https://herbatica.sk/znacky/herbatica	https://herbatica.cz/znacky/herbatica	https://herbatica.hu/markak/herbatica	https://herbatica.ro/marci/herbatica
Checkout	https://herbatica.sk/pokladna	https://herbatica.cz/pokladna	https://herbatica.hu/penztar	https://herbatica.ro/finalizare-comanda
Account	https://herbatica.sk/ucet	https://herbatica.cz/ucet	https://herbatica.hu/fiok	https://herbatica.ro/cont
Legal	https://herbatica.sk/obchodne-podmienky	https://herbatica.cz/obchodni-podminky	https://herbatica.hu/altalanos-szerzodesi-feltetelek	https://herbatica.ro/termeni-si-conditii
Search	https://herbatica.sk/vyhladavanie?q=ostropestrec	https://herbatica.cz/vyhledavani?q=ostropestrec	https://herbatica.hu/kereses?q=mariatovis	https://herbatica.ro/cautare?q=armurariu

Native sign-off MUST rozhodnout zejména marci versus branduri, tanacsok, penztar, SK vyhladavanie a právní názvy. Oprava před první publikací alias nevytváří; oprava po publikaci ano.

5.21 Release wire acceptance suite

Suite MUST běžet přes skutečný Docker ingress a přes každý podporovaný platform adapter, včetně Netlify, pokud je podporovaným deployment targetem.

Povinné scénáře:

1. HTTP/1.1 i HTTP/2;
2. GET a HEAD parity; HEAD bez response body;
3. hard 308, 400, 404, 410, 414, 421, 503;
4. status rozhodnutý před prvním HTML flush;
5. přímý HTML request;
6. browser click z App route na Pages route jako hard document navigation;
7. browser click mezi Pages routes bez /_next/data nebo RSC prefetch;
8. explicitní request s RSC headers nesmí změnit status na soft 200;
9. /~sf, /~SF, /%7Esf, double encoding;
10. malformed %, invalid UTF-8, encoded / a \;
11. config redirect nesmí předběhnout Proxy;
12. host + case + slash + alias + query → právě jeden 308;
13. unsafe alias request → 405 a Allow: GET, HEAD;
14. backend timeout → 503, definitivní miss → 404;
15. retired current i všechny aliases → 410;
16. superseded route → přímý 308 na successor;
17. concurrent slug change → jediný current slug;
18. sitemap URL při samostatném requestu → current 200;
19. unknown sitemap shard → 404;
20. přímé assety fungují bez Proxy interference;
21. neověřený host → 421, nikoli SK fallback;
22. PAK se dvěma channels blokuje boot;
23. chybějící Translation record blokuje publish, i když Store API vrátí original content.

---

6. Medusa datový kontrakt

6.1 Základní invariant a PAK scope

Pro každý market platí:

verified canonical host
→ Next market
→ locale
→ country
→ Medusa region
→ publishable API key
→ přesně jeden expected sales channel

Store API request používá:

stable entity ID
+ market-specific publishable API key
+ locale
+ region_id nebo country_code podle endpointu a pricing potřeby

market a expectedSalesChannelId jsou interní assertions. sales_channel_id MUST NOT být automaticky posílán jako obecný Store API query parametr, protože standardní v2 scope je odvozen z x-publishable-api-key.

Custom /store routes MUST používat MedusaStoreRequest a číst:

req.publishable_key_context.sales_channel_ids

Route MUST ověřit, že množina přesně odpovídá [expectedSalesChannelId].

6.2 Boot validace PAK

Pouhý product request není důkazem, že PAK patří právě jednomu channelu. Release používá deploymentem podepsaný manifest:

interface PublishableKeyScopeManifest {
  generatedAt: string;
  publishableApiKeyId: string;
  publishableApiKeyFingerprint: string;
  salesChannelIds: readonly string[];
  signature: string;
}

Manifest vzniká z Medusa Admin/Query dat v deployment pipeline a je podepsán odděleným deployment signing key.

Next boot MUST:

1. ověřit signature;
2. ověřit publishableApiKeyId;
3. porovnat fingerprint nakonfigurované hodnoty;
4. ověřit přesnou množinu [expectedSalesChannelId];
5. odmítnout expirovaný nebo neaktuální manifest.

Integrační test navíc volá custom Store scope endpoint používající skutečný PAK context. Rozdíl mezi manifestem a runtime sales_channel_ids blokuje release.

Storefront Next deployment MUST NOT obsahovat obecný Medusa Admin credential.

6.3 Field-by-field kontrakt

Pole	Vlastník	Autoritativní zdroj	Fallback	Současný stav
marketCode	Next	route definition	žádný	Ano
locale	Next	route definition	žádný	Ano
countryCode	Next	route definition	žádný	Ano
canonicalOrigin	Next	runtime deployment binding	žádný	Částečně
acceptedHosts	Next/ops	DNS+TLS ověřený binding	žádný	Config existuje, ownership neprokázán
regionId	Medusa, binding Next	explicitní market binding	žádný	Region selection existuje
salesChannelId	Medusa, binding Next	signed PAK manifest	žádný	V market contextu chybí
publishableApiKey	Medusa/deployment	server runtime binding	žádný	Hodnota existuje
publishableApiKeyId	Medusa/deployment	signed manifest	žádný	Cílově povinné
product.id	Medusa	Store API	žádný	Ano
product.handle	Medusa	Store API	pouze seed URLR	Ano; dnes runtime identita
product.title	Medusa Translation	exact locale	žádný locale fallback	Translation zapnuta, současný reader locale neposílá
product.description	Medusa Translation	exact locale	prázdné pouze pokud pole není povinné	Stejný problém jako title
product publishability	Medusa	úspěšný ID lookup pod správným PAK	žádný	Standard Store middleware filtruje publishable produkty
product.updated_at	Medusa	standardní timestamp	žádný	Pole existuje, PRODUCT_DETAIL_FIELDS jej nevybírá
product channel visibility	Medusa	PAK-scoped ID lookup	žádný	PAK scope existuje; single-channel invariant neověřen
inventory availability	Medusa	PAK, region a stock-location scope	žádný	Částečně; současná pole načítají inventory data, korektnost netestována
product.categories[]	Medusa	native relationships	prázdné pole	Ano
primaryCategoryId	Medusa	validovaná metadata extension	deterministický fallback	Ne
category.id	Medusa	ProductCategory	žádný	Ano
category.name	Medusa Translation	exact locale	žádný locale fallback	Reader locale neposílá
category.description	Medusa Translation	exact locale	prázdné, pokud nepovinné	Reader locale neposílá
category hierarchy	Medusa	native parent relation	žádný	Ano
category channel availability	Medusa	explicitní Category↔SalesChannel link	žádný	Ne; release dependency
collection.id	Medusa	ProductCollection	žádný	Standardní model dostupný
collection display data	Medusa Translation	exact locale	žádný	Reader/route chybí
collection channel availability	Medusa	explicitní Collection↔SalesChannel link	žádný	Ne; release dependency
brand.id	Medusa custom Brand	custom Store API	žádný	Ano
brand.title	Medusa Translation	translatable Brand field	žádný	Ne; model má globální text
brand channel availability	Medusa	explicitní Brand↔SalesChannel link	žádný	Ne
brand publication state	Medusa	Brand business state	žádný	Ne
campaign ID	Medusa	custom StorefrontCampaign	žádný	Ne
campaign schedule	Medusa	StorefrontCampaign	žádný	Ne
campaign channel availability	Medusa	Campaign↔SalesChannel link	žádný	Ne
campaign landing content	CMS	localized CMS document	žádný	Nejednotné
current entity slug	Next URLR	url_entity_slug current	žádný	Ne
alias slug	Next URLR	immutable alias row	žádný	Ne
static aliases	Next	typed static_route_path	žádný	Ne
route lifecycle	Next URLR	active/retired/superseded	žádný	Ne
equivalence	Next URLR	explicit mapping	žádný	Ne
index policy	Next URLR	route policy	bezpečný noindex	Ne
CMS locale	Next request → CMS	exact market locale	žádný	Dnes napevno sk
UI/system labels	Next	locale resources	žádný	Částečně v Medusa storefront texts

6.4 Produktový reader

Po URLR resolve reader načítá produkt podle stabilního product.id, nikoli handle.

Povinný request context:

• PAK hodnota příslušného marketu;
• locale query nebo x-medusa-locale;
• region/country podle endpointu;
• explicitní timeout a cancellation signal.

Úspěšný ID lookup pod správným PAK je důkazem, že standardní Store middleware produkt považuje za publikovatelný a viditelný v alespoň jednom channelu PAK. Protože projekt vyžaduje přesně jeden channel na PAK, boot invariant převádí tento výsledek na market availability.

Reader MUST NOT požadovat product.status jako Store response field ani očekávat product.salesChannelAssignments v běžné Store odpovědi.

Výsledky:

• nalezený PAK-visible produkt → 200;
• nenalezený pod správným PAK → 404;
• URLR alias → 308 bez product readu;
• retired/tombstone → 410 bez product readu;
• timeout/5xx/invalid payload → 503;
• vyprodaný produkt → 200, indexovatelný, správná availability v UI a JSON-LD.

PRODUCT_DETAIL_FIELDS MUST zahrnout updated_at, pokud se používá pro lastModified.

Inventory korektnost musí integrační test ověřit pro:

• správný market PAK;
• region;
• stock-location vazbu channelu;
• backorder;
• managed/unmanaged inventory;
• variant bez inventory itemu.

6.5 Locale ve všech readerech

Každý Medusa katalogový reader MUST předat přesný BCP-47 locale:

sk-SK
cs-CZ
hu-HU
ro-RO

Priority Medusa jsou:

1. locale query;
2. x-medusa-locale.

Současné product a category SSR readers locale neposílají, a proto nejsou full-localized.

Medusa při chybějícím překladu vrací originální model value. Store response proto MUST NOT být použit jako důkaz translation coverage.

Publish gate musí číst Translation records přes Admin/Translation Module a pro každý market ověřit:

• existenci translation recordu;
• všechna povinná pole;
• neprázdnou hodnotu;
• správný locale code;
• správný reference ID/type.

Chybějící překlad blokuje publikaci entity v marketu, i když Store API vrátí fallback content.

6.6 Kategorie

Medusa zůstává jediným vlastníkem taxonomy:

• category entity;
• parent vztah;
• rank;
• product membership;
• localized name/description.

Pro market availability vznikne explicitní Medusa Category↔SalesChannel link. Jde o business assignment, nikoli URL systém.

Pravidla:

• bez linku na expected channel je kategorie 404;
• prázdná, ale explicitně channel-assigned a publikovaná kategorie MAY vrátit 200;
• product listing v kategorii se vždy načítá PAK-scoped;
• hierarchie a membership mohou být pro trhy rozdílné pomocí rozdílných standardních category IDs;
• cross-market ekvivalence těchto category IDs je explicitní URLR mapping;
• Next nesmí ukládat parent, rank ani membership.

Pokud jedna category ID sdílí více marketů, její native parent a membership jsou společné. Jakmile se mají lišit, MUST vzniknout samostatná Medusa category entity pro každý odlišný strom.

Současné načtení až 500 kategorií a hledání podle handle MUST být nahrazeno ID lookupem a bounded tree reads.

6.7 Kolekce

Standardní ProductCollection nemá doloženou přímou SalesChannel vazbu. Release proto přidává explicitní Collection↔SalesChannel link v Medusa.

Availability:

• collection route je dostupná pouze s expected channel linkem;
• produkty se načtou pod market PAK;
• prázdná explicitně publikovaná collection MAY vrátit 200;
• bez channel linku → 404.

Pokud membership standardní kolekce nemůže reprezentovat rozdílné market assignments, owning Medusa model MUST použít samostatné collection/product entity pro trhy. Next MUST NOT vytvářet vlastní collection membership.

6.8 Brand kontrakt — release blocker

Současný Brand model obsahuje pouze globální title, handle a atributy. Nemá:

• translatable field;
• publication state;
• Brand↔SalesChannel link.

/store/brands není channel-filtered. Pouze /store/brands/:id/products používá sales-channel product middleware.

Release binding:

1. Brand.title se označí .translatable();
2. Brand dostane explicitní publication state;
3. vznikne Brand↔SalesChannel link;
4. Store brand detail/list route používá MedusaStoreRequest;
5. route ověří req.publishable_key_context.sales_channel_ids;
6. vrací pouze safe storefront fields;
7. handle zůstává pouze URLR seed candidate.

Brand availability:

published Brand
+ Brand↔expectedSalesChannel link
= route eligible

Produktová existence sama o sobě není autoritou brand publication. PAK-visible product count může být použit pro listing count, nikoli jako náhrada explicitního assignmentu.

Do dokončení těchto bodů platí:

brand.title localization = Ne
brand market/channel availability = Ne

6.9 Campaign business model — release dependency

Standardní Medusa Promotion/Campaign model je určen pro discount pravidla, budget a schedule. Nemá veřejný landing content kontrakt ani doložený Store endpoint pro publikaci campaign listu.

Release zavádí Medusa-owned custom StorefrontCampaign:

storefront_campaign
- id
- status: draft | published | archived
- offer_active_from nullable
- offer_active_until nullable
- promotion_campaign_id nullable
- created_at
- updated_at

Vazby:

StorefrontCampaign ↔ SalesChannel
StorefrontCampaign ↔ CMS landing reference
StorefrontCampaign → optional standard Promotion Campaign

Safe custom Store reader smí zveřejnit pouze:

• ID;
• publication state;
• offer active interval;
• localized display reference;
• channel eligibility;
• updated_at.

MUST NOT zveřejnit interní promotion rules, budgets nebo neveřejné eligibility podmínky.

Landing route může zůstat 200 po skončení nabídky, pokud:

• status=published;
• CMS landing je publikovaný;
• channel link existuje.

offer_active_until mění obchodní stav UI, ne automaticky route lifecycle. 410 nebo successor redirect je explicitní URLR operace.

Pokud StorefrontCampaign nebude hotov a integračně otestován, campaign routes MUST být z release odstraněny, nikoli napojeny na neověřený Promotion model.

6.10 Primary category

primary_category_id je navržená Medusa merchandising extension, nikoli standardní field.

Validace:

• hodnota je string ID;
• kategorie patří produktu;
• kategorie je dostupná v aktuálním market/channel;
• neodkazuje na jiný market-specific taxonomy tree.

Fallback:

1. nejhlubší dostupná leaf;
2. nižší rank;
3. lexikograficky nejnižší stabilní category ID.

Primary category ovlivňuje pouze breadcrumb, navigační kontext a BreadcrumbList; nikdy produktovou URL.

6.11 CMS kontrakt a failure semantics

Současný CMS klient je nevyhovující, protože:

• locale je napevno sk;
• network exception, non-2xx a skutečný miss vrací stejný null;
• JSON je pouze castován.

Cílový kontrakt:

type CmsReadResult<T> =
  | { kind: "found"; value: T }
  | { kind: "not-found" }
  | { kind: "upstream-unavailable"; status?: number }
  | { kind: "invalid-payload"; validationCode: string };

Reader MUST:

• používat exact market locale;
• mít bounded timeout;
• rozlišit 404 od timeout/5xx;
• validovat JSON jako unknown;
• nepoužívat SK fallback;
• propagovat upstream-unavailable a invalid-payload jako storefront 503.

CMS vlastní:

• advice;
• information;
• legal content;
• editorial campaign landing.

Next vlastní jejich veřejnou URL a lifecycle mapping.

6.12 Equivalence a hreflang

Cross-market equivalence je vždy explicitní URLR hodnota.

Pro produkty může být Medusa product ID použit jako seed pouze tehdy, když jde skutečně o stejný obchodní produkt. Runtime shodné ID nesmí samo automaticky vytvářet hreflang.

Alternate route se emituje pouze pokud cílový market:

• má route stejného kind;
• má stejný equivalence_key;
• route lifecycle je active;
• current slug existuje;
• source reader vrátí found;
• expected channel scope je validní;
• route je indexovatelná;
• výsledná URL vrací 200.

Brand/category/collection IDs MAY být mezi markety rozdílné.

6.13 Event a invalidation kontrakt

Událost MUST obsahovat:

source
entityKind
entityId
changeType
affectedMarketCodes
occurredAt
eventId

Povinné změny:

Událost	Invalidace
product content/translation	product, metadata, sitemap
product channel assignment	product, alternates, category/brand/collection listing, sitemap
category parent/rank	breadcrumb, structured data, navigation
category channel link	category, alternates, sitemap
brand translation/channel link	brand, product metadata, alternates, sitemap
collection membership/channel link	collection, listing, sitemap
campaign status/schedule	campaign UI, metadata, sitemap dle lifecycle
CMS publish/unpublish	content route, alternates, sitemap
URLR slug transaction	old slug, new slug, route, alternates, sitemap
route retirement/successor	všechny historické paths, sitemap
equivalence změna	všechny alternates key
facet key změna	affected query redirects a cached listing

Handler MUST být idempotentní podle eventId, validovat payload jako unknown a mít bounded batch, retry a timeout.

Medusa event MUST NOT automaticky měnit slug. Slug change je explicitní Next URLR transakce.

6.14 Zakázané odpovědnosti Medusa

Medusa MUST NOT být autoritou pro:

• veřejnou pathname;
• localized type prefix;
• canonical host nebo URL;
• trailing slash;
• redirect status;
• alias history;
• tombstone;
• route successor;
• hreflang;
• sitemap membership;
• robots;
• index policy;
• query canonicalization;
• URL collision;
• UI/system route labels.

Medusa handle nebo URL-like metadata jsou pouze importní kandidáti.

Next MUST NOT ukládat:

• product/category/brand names;
• ceny;
• stock;
• taxonomy parent/rank;
• product memberships;
• SalesChannel assignments;
• promotion rules.

6.15 Evidence pro sekce 5–6

Claim	Typ	Zdroj	Stav	Confidence
Instalovaná verze je 16.3.0-preview.5	exact source	apps/herbatika/node_modules/next/package.json	VERIFIED	vysoká
Preview config podporuje oba skip flags	exact source	next/dist/server/config-schema.js	VERIFIED	vysoká
App HTTP fallback obsahuje jen 401/403/404	exact source	next/dist/client/components/http-access-fallback/http-access-fallback.js	VERIFIED	vysoká
GSSP dostává res, podporuje notFound a redirect	exact source + docs	next/dist/server/render.js; Next GSSP docs	VERIFIED	vysoká
Pages preview render před sestavením response čeká na allReady	exact source	next/dist/server/render.js	VERIFIED	vysoká
Config redirects běží před Proxy	framework docs	Next Proxy execution order	VERIFIED pro docs 16.3.0; preview potvrdit wire testem	středně vysoká
Proxy bez matcheru běží i na assety	framework docs	Next Proxy matcher docs	VERIFIED pro docs 16.3.0	vysoká
Cross-router navigace je hard navigation	framework docs	App Router migration guide	VERIFIED	vysoká
Multi-instance potřebuje shared cache, encryption key a deployment ID	framework docs	Next self-hosting guide	VERIFIED	vysoká
PAK je scoped na jeden nebo více channels	vendor docs	Medusa publishable key docs	VERIFIED	vysoká
Store custom route čte publishable_key_context.sales_channel_ids	vendor docs	Medusa sales-channel/PAK docs	VERIFIED	vysoká
Translation fallback vrací original content	vendor docs	Medusa storefront translation docs	VERIFIED	vysoká
Translation module je zapnut	repo source	apps/medusa-be/medusa-config.ts, src/config/modules.ts	VERIFIED	vysoká
Product/category readers locale neposílají	repo source	prefetch-product.ts, prefetch-category.ts	VERIFIED	vysoká
Brand není translatable ani channel-linked	repo source	brand.ts, brand Store middleware	VERIFIED	vysoká
CMS hardcoduje sk a slučuje failure s miss	repo source	cms-client.ts	VERIFIED	vysoká
Docker prokazuje jediný loopback-exposed standalone server	repo source	docker-compose.yaml, Herbatika Dockerfile	VERIFIED	vysoká
Produkční reverse proxy/TLS overwrite existuje	žádný důkaz	—	UNKNOWN	nízká
Vlastnictví alias domén	žádný DNS/TLS důkaz	—	UNKNOWN	nízká
HU/RO/SK localized segmenty jsou natural-approved	native sign-off chybí	—	UNKNOWN	nízká

Zdroje

• Next.js Proxy file convention, matcher, execution order a advanced flags
• Next.js getServerSideProps
• Next.js notFound
• Next.js permanentRedirect
• Next.js App Router migration a Pages/App coexistence
• Next.js self-hosting
• Next.js v16.3.0-preview.5 source tag
• Medusa publishable API keys
• Medusa publishable keys a sales channels
• Medusa storefront translations
• Medusa custom translatable models
• Medusa Promotion Module

---

ČÁST D — SEO pravidla, backlog, testy a evidence

[BleedingDev]

Plná normativní specifikace — část 04/5. Krátká implementační verze je v popisu issue; tato část je závazný zdroj při sporu.

---

7. SEO rozhodovací tabulka

7.1 Canonical, hreflang a indexace

Třída URL / stav	HTTP	Indexace	Canonical	hreflang	Sitemap	Závazné chování
Homepage	200	index	self	dostupné market equivalents + self	ano	Absolutní URL z canonical originu marketu; nikdy z raw Host ani z interní /~sf/... cesty.
Index prefixu /produkty, /kategorie, /znacky, /kolekcie, /akcie, /poradna a lokalizované ekvivalenty	200	index	self	pouze skutečné equivalents	ano	/informacie bez slugu vrací v release 404.
Produkt detail	200	index	self	pouze explicitně mapované equivalents	ano	Jedna canonical URL per market; kategorie MUST NOT být součástí URL.
Vyprodaný publikovaný produkt	200	index	self	pouze existující equivalents	ano	Dostupnost MUST odpovídat UI i structured data; vyprodání samo URL nemaže. [AC]
Kategorie	200	index	self	pouze explicitně mapované equivalents	ano	Plochá URL bez rodičovské hierarchie. Přesun ve stromu URL nemění.
Značka, kolekce, kampaň, poradna, informační stránka	200	index, pokud je publikovaná a obsahově užitečná	self	pouze explicitně mapované equivalents	ano	Neobsahová nebo nepublikovaná položka MUST NOT vracet indexovatelný 200.
Statická veřejná stránka	200	index podle centrální route policy	self	skutečné lokalizované equivalents	ano, je-li indexovatelná	Titulek, canonical, interní odkazy a alternates používají stejný route registry.
Pagination ?page=1	308 na čistou URL	—	—	—	—	Defaultní parametr se odstraní; tracking parametry se v Location zachovají.
Pagination ?page=N, N ≥ 2	200	index	self včetně page=N	ne	ne	Stránka MUST mít vlastní obsahový výřez a crawlable odkazy na sousední stránky. [AC]
Stránka pagination za koncem	404	ne	žádný	žádný	ne	Žádná client-side oprava na poslední stránku.
Facety	200	noindex	žádný	žádný	ne	URL zůstává crawlable; robots.txt ji MUST NOT blokovat.
Sort	200	noindex	žádný	žádný	ne	Default sort=recommended se odstraní; ostatní hodnoty se nesmějí dostat do interní discovery navigace.
Interní hledání	200	noindex	žádný	žádný	ne	Chybějící q nebo q prázdné po trimu = 200 search landing bez výsledků; duplicitní q = 404; zero-result stav je užitečný 200, nikoli soft-404. [AC]
Promoted facet landing page	200	index	self	skutečné equivalents	ano	Musí mít samostatnou stabilní route a kurátorovaný obsah; nesmí být pouze indexovanou facet query. [AC]
Product ?variant=…	200	canonicalizováno na produkt	base product URL	jako base produkt	ne jako samostatná URL	Varianta se musí otevřít přímo; klíč a hodnota jsou case-preserving.
Tracking parametry	200	podle čisté cílové stránky	čistá URL bez tracking parametrů	podle čisté URL	pouze čistá URL	utm_*, gclid, fbclid se zachovají pro atribuci, ale nesmějí vstoupit do canonical, alternates, sitemap ani interních odkazů.
Account, auth, cart, checkout	200, 303 nebo 307 podle flow	noindex	žádný	žádný	ne	Bez veřejného SEO povrchu; autentizace chrání data, robots.txt nikoli. [AC]
Review/token route	200 nebo jednotné 404	noindex	žádný	žádný	ne	Token MUST NOT vstoupit do metadata, logované SEO URL, OG URL ani alternates.
Current slug zadaný nekanonickým case nebo slash tvarem	308	—	—	—	—	Redirect pouze po jednoznačném resolve current/alias.
Historický alias	308	ne jako samostatná URL	cílová current URL	pouze na cíli	ne	Alias vede přímo na current canonical; alias chains MUST NOT existovat.
Odstraněná veřejná URL bez náhrady	410	ne	žádný	žádný	ne	Pouze URLR tombstone; nikdy pro tokeny nebo privátní flow. Mechanismus doručení 410 před streamingem prokazuje M00; do jeho úspěchu je implementační mechanismus UNKNOWN.
Odstraněná URL se skutečným nástupcem	308	—	—	—	ne	Nástupce musí být obsahově ekvivalentní, nikoli homepage nebo obecná kategorie.
Definitivně neznámá entita nebo entita mimo market/channel	404	ne	žádný	žádný	ne	URLR hit sám dostupnost nedokazuje; market/channel kontrola je povinná.
Backend unavailable (timeout, network, 5xx) nebo invalid-response	503	ne	žádný	žádný	ne	MUST NOT být maskováno jako 404; vyžaduje diskriminovaný fetch výsledek (7.8).
Neobsluhovaný host	421	ne	žádný	žádný	ne	Žádný SK ani Accept-Language fallback; garantovatelné jen pro hosty, které ingress skutečně routuje na aplikaci.
Malformed encoding/path	400	ne	žádný	žádný	ne	Raw-level případy vlastní ingress adapter; resolver defensivně odmítá zakázané znaky v již parsovaných hodnotách (7.5).
URL nad ingress limitem	414	ne	žádný	žádný	ne	Limit se ověřuje na raw request-target před Next resolverem.
Nepodporovaná HTTP metoda na veřejné page route	405 + Allow	ne	žádný	žádný	ne	Viz method contract v 7.5.
Přímý přístup k /~sf v libovolném case/encoding tvaru	404	ne	žádný	žádný	ne	Robots navíc obsahuje Disallow: /~sf/; robots není bezpečnostní kontrola.

[AC] označuje závaznou architecture choice, nikoli tvrzení o ranking faktoru.

7.2 Pravidla canonical

1. Každá indexovatelná stránka MUST mít absolutní self-canonical.
2. Canonical origin MUST pocházet z validovaného market configu, nikdy přímo z klientského Host a nikdy z interní /~sf/... cesty.
3. Canonical URL MUST používat HTTPS, canonical non-www host, lowercase statické segmenty a slugy, žádný trailing slash, standardizované percent-encoding a normalizované query.
4. Pro tentýž route target MUST canonical, og:url, primární JSON-LD url/@id, sitemap URL a interní odkazy používat tentýž builder a výslednou canonical URL. Ostatní JSON-LD URL a odkazy na jiné targety přirozeně nejsou rovny canonical aktuální stránky. [AC]
5. Facet, sort, search a privátní URL MUST používat noindex bez canonical. [AC]
6. Tracking-only URL MUST canonicalizovat na čistou URL bez tracking parametrů.
7. ?variant= MUST canonicalizovat na base product URL.
8. Pagination page ≥ 2 MUST mít self-canonical; canonical na page 1 je zakázán. [AC]
9. Překlady na jiných doménách MUST NOT používat cross-domain canonical. Jejich vztah vyjadřuje hreflang.
10. Canonical MUST NOT být používán jako náhrada za 404, 410, redirect, autentizaci nebo crawl control.
11. Resolver, metadata composition a builder MUST odvozovat veřejnou URL výhradně z Proxy kontraktu (7.5): validovaného x-sf-market, x-sf-canonical-origin a serializovaného původního public pathname.

7.3 Pravidla hreflang

Pravidlo	Závazek
Transport	Pouze HTML <link rel="alternate" hreflang="…">. [AC]
Hodnoty	sk-SK, cs-CZ, hu-HU, ro-RO.
URL	Absolutní current canonical URL cílového marketu.
Self-reference	Povinná.
Reciprocita	Každá zahrnutá dvojice musí být reciproční.
Ekvivalence	Pouze explicitní URLR equivalence_key; slug, název ani Medusa handle ekvivalenci nedokazuje. Seed z Medusa product ID platí pouze tehdy, když tentýž ověřený Medusa product record reprezentuje ekvivalent napříč channels; market-specific samostatné product records vyžadují explicitně přiřazený společný equivalence_key.
Chybějící ekvivalent	Záznam se vynechá; MUST NOT se použít homepage, stejný slug na jiné doméně ani jiná přibližná stránka.
Facety, sort, search, pagination page ≥ 2, account, auth, checkout, token routes	Bez hreflang.
x-default	V release MUST NOT být emitováno. [AC]
Sitemapy	hreflang se v nich v release neduplikuje. [AC]
Separate deployments	Musí používat sdílený URLR read model nebo atomicky publikovaný shodný snapshot.

7.4 Facety, sort, pagination a query

Canonical pořadí parametrů:

page, sort, status, form, brand, ingredient, price_min, price_max, q, variant

Precedence vyhodnocení (závazná): 1. malformed/invalid hodnota známého parametru → 404; 2. teprve poté strip unknown non-tracking parametrů a normalizace do composed 308; 3. render. Invalid známý parametr tedy MUST vyhrát nad strip redirectem.

Vstup	Výsledek
page=1	308 bez page
page=2	200, index, self-canonical, mimo sitemap
page=01, page=+1, page=-1, page=0, duplicitní page	404
page za koncem	404
sort=recommended	308 bez sort
Platný non-default sort	200, noindex, bez canonical
Neplatný nebo case-chybný enum	404
Duplicitní singleton key (sort, status, price_min, price_max, q, variant)	404
Opakovaný facet key (brand=a&brand=b)	404; CSV je jediný multi-value formát [AC]
CSV multi-value facet	trim, odstranění prázdných položek, deduplikace, lexikální seřazení
Validní, ale nekanonické CSV (pořadí, duplicity, whitespace)	jeden composed 308 na kanonickou formu
CSV po normalizaci prázdné	404
Cena	pouze ^[0-9]+(\.[0-9]{1,2})?$; min ≤ max
Neplatná cena nebo rozsah	404
Search bez q nebo q prázdné po trimu	200 search landing bez výsledků, noindex
Duplicitní q	404
Unknown non-tracking parametr včetně uppercase klíče	308 po odstranění
utm_*	povoleno nejvýše 10 položek; mimo canonical a interní odkazy
gclid, fbclid	povoleno; mimo canonical a interní odkazy
Tracking parametry při strip/normalizačním 308	zachovány v Location; nikdy nevstupují do canonical, alternates ani sitemap
Signed provider/payment parametry	přesné route-specific schema; žádný generický sort/strip redirect
Více než 20 query parametrů	404
Více než 10 hodnot jednoho facetu	404
Hodnota delší než 256 B (UTF-8 bytes po decode)	404
q delší než 200 Unicode code points (po decode)	404
Raw URL delší než 2048 B	414 na ingressu

Serializace query MUST odpovídat WHATWG URL Standard; test suite obsahuje golden fixtures pro mezery, Unicode a % encoding (U39).

7.5 Redirecty, normalizace, Proxy kontrakt a metody

Proxy → resolver request contract

• Proxy MUST odstranit všechny klientské varianty interních hlaviček a nastavit minimálně validované x-sf-market, x-sf-canonical-origin a serializovaný původní public pathname.
• Rewrite na /~sf/... MUST zachovat query beze ztráty pořadí a duplicit před validací; validace a normalizace probíhá až v resolveru.
• Resolver, metadata a builder MUST NOT odvozovat veřejnou URL z interní /~sf/... cesty ani z raw Host.
• Kontrakt MUST platit i pro RSC requesty a client navigation; ověřují to spoofing a rewrite-preservation testy (U33, U34, I37, E28).

Percent-decoding kontrakt

• Next předává již parsované nextUrl a route params; resolver MUST NOT bezpodmínečně volat další decodeURIComponent.
• Raw malformed %, encoded slash/backslash na raw úrovni a limit 2048 B vlastní ingress adapter (400/414); chování je platform-dependent a MUST být testováno per adapter (Docker proxy chain i Netlify).
• Resolver defensivně odmítá (400) zakázané znaky v již parsované hodnotě: separátory vzniklé z %2F/%5C, control, bidi, zero-width, invalid UTF-8. [AC] + ingress security contract.
• Testy MUST pokrýt %2F, %5C, %252F, malformed UTF-8 a rozdíly Docker/Netlify (U42, E16).

Redirecty a normalizace

Případ	Status	Pravidlo
HTTP → HTTPS	ingress permanent redirect	Smí vytvořit jediný dodatečný hop před aplikační canonicalizací.
www nebo vlastněný alias host → canonical host	308	Alias host musí mít ověřené vlastnictví a TLS; jinak 421.
herbatika.* → herbatica.*	308	Pouze pro domény zařazené v ověřeném allowlistu.
Trailing slash	308	Cíl bez slash; skipTrailingSlashRedirect: true, aby redirect skládal resolver.
Uppercase statický segment nebo slug	308	Pouze při jednoznačném current/alias resolve; jinak 404.
Token, public order ID, variant, provider parametry	bez case redirectu	Hodnoty jsou case-preserving.
Current slug v nekanonickém tvaru	308	Jeden hop na úplnou canonical URL.
Historický slug	308	Přímo na current canonical; žádný alias chain.
Dočasný checkout/auth flow	303 nebo 307	Podle HTTP metody a požadované změny metody.
Neplatný checkout step	307	Na marketový default step.
Veřejná tombstone URL	410	Mechanismus doručení před streamingem prokazuje M00; do jeho úspěchu UNKNOWN.
Skutečný nástupce	308	Jen obsahově odpovídající náhrada.
Unsafe metoda na alias/canonical URL	bez permanent redirectu	Alias a canonical redirecty jsou pouze pro GET/HEAD.
301	MUST NOT emitovat storefront core	[AC] Core standardizuje permanentní redirecty na 308; Google považuje 301 i 308 za permanentní signály.

Složená origin+path+alias+query chyba MUST být opravena jedním aplikačním 308. Pokud HTTPS řeší ingress, je povoleno nejvýše celkem dva redirect hopy.

Method/status contract veřejných page routes

Metoda	Chování
GET	Plný kontrakt této specifikace.
HEAD	Stejné statusy a headers jako GET, prázdné body; ověřuje wire suite.
POST	Povolen pouze pro platný Server Actions kontrakt Next.js; non-action POST na veřejnou page route → 405 + Allow: GET, HEAD.
PUT, PATCH, DELETE	405 + Allow: GET, HEAD; MUST NOT projít do interní route.
OPTIONS	204 + Allow: GET, HEAD na ingress/adapter vrstvě. [AC]

7.6 Interní odkazy

• Interní odkazy MUST používat current canonical URL z jediného builderu.
• MUST NOT obsahovat tracking parametry, default query hodnoty, historické aliasy, nekanonický host, trailing slash ani nekanonický case.
• Navigace, produktové karty, cart, objednávky, autocomplete, CMS odkazy, e-maily, breadcrumbs a domain switcher MUST používat stejný URL kontrakt.
• Product discovery MUST být možná crawlable odkazy z kategorií, značek, kolekcí a kampaní; nesmí záviset na interním hledání.
• Produktový breadcrumb používá Medusa primary category nebo deterministický fallback, ale kategorie se nikdy nepřidává do product URL.
• Category breadcrumbs a BreadcrumbList mohou vyjadřovat strom, přestože category URL zůstává plochá.
• Domain switcher smí odkázat pouze na skutečný equivalent. Pokud equivalent neexistuje, musí nabídnout explicitní market fallback UI, nikoli syntetickou URL.
• Fragment MUST NOT nést identitu entity, filtr ani stránkování.

7.7 Sitemap a robots

Sitemap

• Každý canonical host MUST publikovat /sitemap.xml jako sitemap index.
• Shardy používají /sitemaps/{kind}-{n}.xml.
• Jeden shard SHOULD zůstat přibližně pod 10 000 URL a 25 MB nekomprimovaných dat. [AC]
• Protokolové maximum 50 000 URL a 50 MB nekomprimovaných dat MUST být vždy dodrženo.
• Sitemap smí obsahovat pouze current canonical URL, které v daném marketu vracejí 200 a jsou indexovatelné.
• Sitemap MUST NOT obsahovat aliasy, tombstones, redirecty, 404, 410, facety, sort, search, pagination page ≥ 2, tracking URL, account, auth, cart, checkout, token routes ani interní /~sf.
• lastModified musí představovat skutečnou změnu indexovatelného obsahu, ne čas generování sitemap.
• Enumerace katalogu MUST být bounded a paginated.
• Market assignment nebo publishability změna MUST invalidovat příslušný shard a sitemap index.
• Sitemap URL, canonical a interní odkazy MUST vznikat ze stejného builderu.
• Sitemap a shard rewrites MUST fungovat na každém hostu; ověřuje E29.

Robots

Každý host publikuje market-specific robots.txt s absolutním odkazem na vlastní sitemap:

User-agent: *
Disallow: /~sf/
Disallow: /api/

Sitemap: https://{canonical-host}/sitemap.xml

• Facety, sort, search, pagination, account, auth, cart, checkout a token routes MUST NOT být blokovány v robots.txt, pokud se na nich spoléhá noindex.
• Robots.txt MUST NOT být používán k ochraně citlivých dat.
• Přímý přístup k /~sf a /api musí být bezpečně omezen i nezávisle na robots.txt.

7.8 Chybové stavy, diskriminovaný fetch kontrakt a soft-404

Každý zdrojový klient (URLR, Medusa, CMS) MUST vracet diskriminovaný výsledek, nikoli nullable hodnotu:

Diskriminátor	Význam	HTTP mapování
found	entita existuje a je publikovaná pro market/channel	200
missing	definitivní market-scoped miss	404
unavailable	timeout, network error, 5xx	503
invalid-response	odpověď porušuje schema kontrakt	503 + observability alert [AC]

Současný CMS klient převádí network error i každý non-2xx na null a toto rozlišení znemožňuje; nahrazení diskriminovaným kontraktem je součást M09.

Stav	Povinná odpověď
Definitivní URLR miss	404
Entita není publikovaná pro market/channel	404
Cizí nebo neexistující order ID	jednotné 404 bez information disclosure
Invalidní, expirovaný nebo použitý token	jednotné 404
URLR tombstone veřejné URL	410 (mechanismus dle M00)
URL má skutečného nástupce	308
URLR, Medusa nebo CMS unavailable/invalid-response	503
Zero-result interní search	užitečný 200 + noindex
Prázdná nebo odstraněná entity stránka vracející 200	zakázaný soft-404
Missing existence zjištěná až po streamingu	release blocker

Existence, alias, tombstone a market availability musí být rozhodnuty před prvním flush. Acceptance se měří HTTP statusem na drátě pro GET i HEAD, nikoli pouze 404 komponentou nebo <meta name="robots" content="noindex">.

7.9 Inventář současných publikovaných new-site URL a alias mapování

Repository dokládá tyto filesystem routes v apps/herbatika/src/app: [slug], account, api, auth, blog, c, checkout, faq, o-nas, p, reset-password, reviews, search, znacka. Pro každou publikovanou URL platí explicitní rozhodnutí (308, 410, zachování, nepublikovaný dev-only); alias platí pouze pro GET/HEAD:

Současná URL	Rozhodnutí	Cíl
/p/{handle}	308	/produkty/{slug} (lokalizovaný prefix marketu)
/c/{slug}	308	/kategorie/{slug} (lokalizovaný prefix marketu)
/znacka	308	/znacky
/znacka/{slug}	308	/znacky/{slug}
/blog	308	/poradna
/blog/{slug}	308	/poradna/{slug}
/search	308	lokalizovaná search route marketu (/vyhladavanie atd.); q se zachová
/faq	308	lokalizovaná FAQ route ze segment registry
/o-nas	zachování na SK, jinak 308	registry static page target; shoduje-li se s registry, alias nevzniká
/account/...	308 per-child	odpovídající /ucet/... child ze segment registry
/auth/..., /reset-password	308 per-child	odpovídající auth flow route ze segment registry
/checkout a kroky	308	lokalizovaný checkout; invalid step dále 307 na default
/reviews/...	308	`/recenzie
root /{slug} (CMS)	308 pouze pro publikované CMS slugy	/informacie/{slug}; neznámý slug 404; root dynamic route zaniká
/api/..., /favicon.ico, fonts	zachování	systémový povrch mimo veřejný lokalizovaný model
/homepage-promo	nepublikovaný dev-only	v repository existuje jen jako komponenta (homepage-promo-section.tsx), nikoli route; žádný alias se nevytváří

Mapování implementuje a testuje M22 (I44, E30); žádná položka nesmí zůstat nerozhodnutá.

---

9. Implementační backlog

9.1 MUST HAVE — release 2026-08-20

ID	Dodávka	Závislosti	Hlavní riziko	Akceptační kritéria
M00	Feasibility gate statusové architektury (nejpozději 2026-08-10)	production build 16.3.0-preview.5, Docker proxy chain, Netlify adapter	architektura není implementation-ready	V production buildu je na drátě prokázáno: current 200, alias 308, miss 404, tombstone 410, outage 503 před streamingem, pro GET i HEAD, včetně RSC navigace, na Dockeru i Netlify. Tvrzení „resolver předá řízení na interní gone Route Handler" není doloženo podporovaným API (Server Component nemůže vrátit libovolný Response, redirect() neumí interní rewrite, page.tsx nemůže koexistovat s route.ts na téže route); mechanismus 410/503 je do úspěchu M00 UNKNOWN. Pokud suite neprojde, MUST se změnit boundary: URLR lookup v Proxy/ingressu, podporovaný front controller, nebo jiný doložený mechanismus — a dokument se aktualizuje.
M01	Pin Next.js 16.3.0-preview.5 a version gate	lockfile, build pipeline	tichá změna frameworkového chování	Build i runtime hlásí přesný pin; CI odmítne jinou verzi; routing/metadata testy používají tagované/instalované chování.
M02	Typed market/origin/channel/key config	ověřené domény, Medusa konfigurace	cross-market data leak, chybný canonical origin, jeden globální key	Každý host mapuje právě jeden market, locale, country, region, salesChannelId a server-only publishable key; mechanismus market → publishableKey → exactly one channel je konkrétně určen včetně client-side Store API volání; market keys MUST NOT být jedna globální build-time NEXT_PUBLIC_* hodnota (dnes NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY vkládá Docker při buildu); unknown host 421; žádný language/SK fallback. Test dokazuje, že každý host posílá správný key a jiný market key nelze získat spoofingem.
M03	Static Proxy boundary + request contract	M02, ingress trust config	spoofed headers, DB lookup v Proxy, ztráta query	Proxy pouze allowlistuje host, odstraní klientské varianty interních hlaviček, nastaví validované x-sf-market, x-sf-canonical-origin a serializovaný původní public pathname, blokuje /~sf, rewrituje lokalizovaný prefix a metadata routes se zachováním pořadí a duplicit query; žádné URLR/Medusa/CMS čtení. Resolver/metadata/builder neodvozují veřejnou URL z /~sf/... ani z raw Host.
M04	Jediný typed segment registry	native sign-off, locale resources	rozdílné parser/build/link segmenty	Jeden config generuje parser, builder, navigaci, metadata, redirecty a test fixtures; žádné app-specific router forks.
M05	Shared URL API	M04	ad hoc URL assembly	parsePublicPath, resolvePublicRoute, buildPath, buildAbsoluteUrl, normalizeQuery, buildAlternates, classifySeo pokrývají všechny page types; repo scan nenajde ruční commerce URL skládání.
M06	Next-owned URLR schema a invarianty	Postgres provisioning, migrations	kolize, alias chains, neatomická změna slugu	Schema definuje field-by-field minimálně: market, kind, stable source ID/type, current_slug, immutable alias records, state current|tombstone|replacement, direct replacement target, equivalence_key, indexability override, timestamps/version a optimistic locking; unikátní current/alias per (market, kind); immutable alias; alias→current only; unique (equivalence_key, market, kind); diskriminovaný lookup výsledek; transakční pořadí změny slugu.
M07	Collision validator	M04, M06, transliterační tabulka	publikace nedostupné nebo nejednoznačné URL	Build/publish selže na static/entity/alias/reserved/case/transliteration/host/equivalence kolizi; stejný slug v různých namespaces projde; validace nezávisí na filesystem precedence.
M08	Resolver před streamingem	M00, M03, M05, M06	soft-404, meta redirect místo HTTP redirectu	Resolver provede nejvýše jeden indexed URLR lookup a jeden bounded equivalence lookup; 308, 404, 410 a 503 jsou na drátě před flush mechanismem prokázaným v M00.
M09	Market/channel-scoped source reads s diskriminovaným kontraktem	M02, M21, Medusa API	URL existuje mimo povolený channel; 503 maskované jako 404	Každý entity read ověřuje market a channel; URLR current záznam bez publishability vede na 404; URLR/Medusa/CMS klienti vracejí found | missing | unavailable | invalid-response (žádný nullable kontrakt; dnešní CMS klient převádí error i non-2xx na null a MUST být nahrazen); unavailable/invalid-response → 503.
M10	Canonical a metadata composition	M05, M08	divergentní URL signály	Každá indexovatelná route má absolutní self-canonical; pro tentýž route target sdílí canonical, og:url, primární JSON-LD url/@id, sitemap a interní odkazy tentýž builder a výslednou URL [AC]; privátní/noindex route nemá nechtěný SEO povrch.
M11	hreflang z explicitní ekvivalence	M06, M10	neexistující nebo nereciproční alternates	Pouze current 200 equivalents; self-reference a reciprocita; missing market vynechán; žádný x-default; product seed z Medusa ID jen při ověřeném sdíleném product record, jinak explicitní equivalence_key.
M12	Query normalizer a indexability classifier	M05	nekonečný crawl space, chybné canonical	Uzavřená pravidla 7.4 včetně duplicitních singletonů, zákazu opakovaného facet key, CSV composed 308, search q edge cases, jednotek limitů (code points vs UTF-8 bytes), precedence invalid-known před unknown-strip, zachování tracking při stripu a WHATWG golden fixtures.
M13	Alias, host, slash, case canonicalizace + method contract	M03, M06, M12, M22	redirect chains, ztráta query, token corruption	skipTrailingSlashRedirect: true; GET/HEAD canonicalizace jedním aplikačním 308; token/provider hodnoty case-preserving; alias chains nelze vytvořit; non-action POST/PUT/PATCH/DELETE → 405 + Allow; HEAD parita s GET.
M14	Sitemap index, shardy a robots	M05, M09, M10	cross-host URL, stale nebo neindexovatelné položky	Per-host sitemap obsahuje jen current canonical 200 indexable URL; robots uvádí správný absolutní sitemap origin a blokuje pouze /~sf/ a /api/; rewrites ověřeny na každém hostu.
M15	Cache keys, tagy a webhook invalidace	M06, M09, shared cache	stale alias, canonical, alternates nebo sitemap	Cache key vždy obsahuje market a podle potřeby channel; CDN/reverse-proxy cache keyuje podle hostu; slug/assignment/publishability/equivalence změna invaliduje old path, new path, metadata, alternates a sitemap.
M16	Plná lokalizace	M04, Medusa/CMS locale support	slovenský fallback v jiném marketu; HU/RO negarantovány	Route segmenty, UI, checkout, account, auth, CMS, katalog, metadata, structured data a právní stránky ve SK/CZ/HU/RO. Repository blockery: CMS_LOCALE = "sk" hardcode; compose default PAYLOAD_LOCALES: cs,sk,en a production default pouze en — HU/RO dnes nejsou garantovány. Acceptance ověřuje build-time i runtime Payload locales přesně sk,cs,hu,ro, data coverage každé lokalizované collection a zákaz fallbacku. Medusa Translation Store API může vracet originál jako fallback; publish gate validuje existenci skutečného překladu přes Translation data/admin kontrakt, nikoli pouze neprázdnou Store API hodnotu.
M17	Ingress raw-URL a host trust policy	deployment adapters	rozdílné Docker/Netlify chování	Každý adapter prokazatelně přepisuje forwarded headers, odmítá malformed authority, vrací 400/414 podle kontraktu na raw request-target a předává resolveru ověřený origin; resolver dělá pouze defensivní odmítnutí parsovaných hodnot (žádný druhý decode).
M18	Production hard-status gate	M00, production build, skutečný proxy chain	200 soft-404 kvůli PPR/streamingu	Suite pro 308, 404, 410, 503 proběhne na drátě před flush pro GET i HEAD. Pokud s cacheComponents neprojde, release build ho má vypnuté.
M19	Shared multi-instance runtime kontrakt	shared cache, secrets, deployment orchestrace	nekonzistentní cache a Server Functions	Instance sdílejí cache handler, tag koordinaci a encryption key; rolling deployment používá deploymentId; route-config hash je shodný; separate deployment běží se stejným buildem a ALLOWED_MARKETS subsetem.
M20	Kompletní automatizované SEO testy	M00–M22	regresní rozdíl mezi route typy a deploymenty	Zelené unit (U01–U42), integration (I01–I44) a production browser/wire E2E (E01–E30) pro multi-host i separate-deployment konfiguraci.
M21	Medusa market assignment kontrakty pro všechny typy	Medusa admin, M02	marketová dostupnost nedokazatelná pro ne-produktové entity	Field-by-field kontrakt určuje existující nebo navržený Medusa model/API pro marketovou dostupnost produktu (sales channel), kategorie, brandu, kolekce a kampaně (navržená channel-scoped assignment extension). Extension je Medusa-owned, adminovatelná, channel-scoped a neduplikuje taxonomy v URLR. Současný category fetch načítá globální tree a aktivní kategorii hledá jen podle handle — to marketovou kategorii nedokazuje a MUST být nahrazeno.
M22	New-site URL inventory a alias mapping	M04, M06, M13	ztráta již publikovaných URL	Každá skutečně publikovaná URL z inventáře 7.9 má implementované rozhodnutí (308/410/zachování/dev-only) včetně /blog → /poradna, /blog/{slug} → /poradna/{slug}, /znacka → /znacky, /znacka/{slug} → /znacky/{slug}; crawl legacy URL končí jedním aplikačním 308.

9.2 SHOULD HAVE

ID	Dodávka	Závislosti	Riziko při odkladu	Akceptační kritéria
S01	URLR a sitemap observability	M06, M14, M15	pozdní odhalení stale nebo konfliktních URL	Metriky pro resolver outcomes, redirect chains, URLR misses, invalid-response alerty, sitemap generation failures a invalidation lag; bez tokenů a PII.
S02	Canonical-link audit v CI	M05, M10	návrat ad hoc odkazů	CI prochází renderované route fixtures a odmítne alias, tracking, noncanonical host, slash nebo neznámý segment v interních odkazech.
S03	Sitemap membership audit proti market snapshotu	M09, M14	404 nebo cross-market URL v sitemap	Automatický audit ověří HTTP 200, canonical shodu, indexability a channel assignment každého vzorku/shardu.
S04	Kurátorované promoted facet landing pages	M12, CMS	obchodní tlak na indexaci generických facet URL	Každá indexovatelná facet tématika má samostatnou route, obsah, canonical a market mapping; běžná facet query zůstává noindex.
S05	Search-engine release monitoring	M10, M14	produkční chyby zachycené až pozdě	Po release se sledují sitemap fetch, server errors, duplicate canonical, soft-404 a hreflang chyby pro každý host.

9.3 LATER

ID	Dodávka	Závislosti	Riziko	Akceptační kritéria
L01	Neutrální market selector a x-default	samostatná neutrální veřejná URL	nesprávné použití homepage jako x-default	x-default se zapne pouze pro reálný selector bez automatického market fallbacku a se všemi recipročními alternates.
L02	Indexovatelný root /informacie a lokalizované ekvivalenty	dostatečný obsahový index	thin index page	Root má kurátorovaný obsah, self-canonical, interní discovery odkazy a sitemap membership; do té doby zůstává 404.
L03	Upgrade na stabilní Next.js	plná routing/metadata/status regression suite	změna preview chování před releasem	Upgrade je izolovaná změna; všechny M20 testy projdou na exact nové verzi.
L04	Opětovné zapnutí cacheComponents, pokud release běží bez něj	hard-status suite	návrat soft-404	Production-wire suite pro 308/404/410/503 prokáže status před flush na všech adaptérech.
L05	Rozšíření bounded hot-set prerenderingu	produkční data o návštěvnosti	unbounded build nebo cross-market cache	Hot set má explicitní limit, dynamicParams: true, market-scoped cache a nemění sitemap ani canonical kontrakt.

---

10. Testovací plán

10.1 Unit testy

ID	Oblast	Povinné případy
U01	Market config	Každá canonical doména mapuje právě jeden market; duplicitní host, market bez channelu, multi-channel publishable key nebo chybějící server-only key selže.
U02	Host parsing	Lowercase host, port stripping, IDN normalization, www, vlastněný alias, neznámý host, malformed authority.
U03	Trusted headers	Klientský x-market-code, klientské varianty x-sf-* a forwarded headers se zahodí; použije se pouze Proxy/ingress hodnota.
U04	Segment registry	Round-trip všech statických a dynamických page types pro SK/CZ/HU/RO; žádný locale prefix.
U05	Prefix roots	Všechny index roots resolve; /informacie root resolve jako release 404.
U06	Product/category policy	Product parser nepřijme kategorii v URL; category parser nepřijme hierarchické extra segmenty.
U07	Slug pipeline	NFKC, locale lowercase, SK/CZ/HU/RO transliterace, RO comma-below, separator collapse, prázdný výsledek, délka 80.
U08	Slug collision	kor versus kór, diakritické kolize, current/current, current/alias a alias/alias konflikt blokují publish.
U09	Reserved namespace	api, _next, ~sf, .well-known, metadata files, feeds, sitemaps, ., .., prázdný segment a reserved child jsou odmítnuty.
U10	Internal namespace	/~sf, /~SF, percent/case varianty a encoded tilde jsou klasifikovány jako externě nedostupné.
U11	Parsed-value validace	Zakázané znaky v již parsované hodnotě (control, bidi, zero-width, invalid UTF-8, separátory z %2F/%5C) vedou na 400; resolver nevolá druhý decode.
U12	URL builder/parser	parse(build(target)) vrací stejný typed target pro každý market a page type.
U13	Canonical builder	HTTPS, canonical host, lowercase static/slug, bez slash, stabilní encoding, absolutní URL; origin nikdy z raw Host ani /~sf cesty.
U14	Case policy	Statický segment/slug může být canonicalizován; token, order ID, variant a provider value se nemění.
U15	Query ordering	Přesné pořadí page, sort, status, form, brand, ingredient, price_min, price_max, q, variant.
U16	Pagination	Odstranění page 1; platné page ≥2; 01, +1, -1, nula, duplicita a overflow jsou 404.
U17	Facet CSV	Trim, deduplikace, sort, prázdné položky, prázdný výsledek, limit 10 hodnot.
U18	Cena	Platné desetinné formáty, max dvě desetinná místa, min ≤ max, neplatné formáty 404.
U19	Tracking	utm_* max 10, gclid, fbclid; nikdy v canonical, alternates, sitemap nebo interním builderu; zachování v strip 308 Location.
U20	Unknown parametry	Unknown non-tracking a uppercase klíče vedou na composed 308 po stripu; invalid známý parametr má přednost (404).
U21	Signed parametry	Provider/payment schema zachová přesný case, pořadí a hodnotu; generický normalizer se nepoužije.
U22	SEO classifier	Přesná matice index/noindex/canonical/hreflang/sitemap pro všechny route classes.
U23	Alternates	Self-reference, reciproční market map, chybějící equivalent vynechán, žádné x-default.
U24	Alias invariants	Alias vede přímo na current; alias chain, cycle, reuse a cross-kind mismatch selžou.
U25	Tombstones	Veřejná tombstone klasifikována 410; token ani privátní route se na tombstone nemapují.
U26	Status mapping	Definitivní miss 404; unavailable/invalid-response 503; unknown host 421; URL limit 414.
U27	Collision validator	Static×static, prefix×static, prefix×alias, old-prefix+old-slug, reserved child, host, transliterace a equivalence kolize.
U28	Internal links	Builder nikdy nevrátí alias, tracking, page 1, default sort, noncanonical host nebo trailing slash.
U29	Sitemap membership	Pouze current canonical indexable 200; aliasy, tombstones, page ≥2, facets a private routes odmítnuty.
U30	Cache keys/tags	Market a channel jsou součástí klíče; změna slugu generuje old/new/equivalence/entity/sitemap tagy.
U31	Proxy matcher	unstable_doesProxyMatch, rewrite a redirect výsledky pro assets, _next, API, robots, sitemap a veřejné routes.
U32	Locale completeness	Každý required route/UI/legal klíč existuje ve všech čtyřech locale resources; žádný SK fallback.
U33	Proxy header contract	Proxy nastaví validované x-sf-market, x-sf-canonical-origin a public pathname; spoofed klientské hodnoty jsou scrubnuty.
U34	Rewrite query preservation	Rewrite na /~sf zachová pořadí a duplicity query před validací; nic se neztratí ani nepřeuspořádá před normalizerem.
U35	Method classifier	GET/HEAD projdou; Server Actions POST projde; non-action POST, PUT, PATCH, DELETE → 405 + Allow: GET, HEAD.
U36	Duplicitní/opakované klíče	Duplicitní singleton (sort, status, price_min, price_max, q, variant) a opakovaný facet key → 404.
U37	CSV kanonická forma	Validní nekanonické CSV (pořadí, duplicity, whitespace) → jeden composed 308; search bez q/prázdné q → search landing; duplicitní q → 404.
U38	Jednotky limitů	q limit v Unicode code points po decode; hodnota limit v UTF-8 bytes po decode; hraniční fixtures.
U39	WHATWG golden fixtures	Serializace query s mezerami, Unicode a % encoding odpovídá WHATWG URL Standard.
U40	Diskriminovaný fetch kontrakt	found/missing/unavailable/invalid-response mapují na 200/404/503/503; nullable návrat neexistuje.
U41	Per-market publishable key	Key resolution je server-only; build neobsahuje market key jako NEXT_PUBLIC_* inline; každý market vrací svůj key.
U42	Encoded separators	%2F, %5C, %252F, malformed UTF-8 v parsovaných params → deterministické 400/404 dle kontraktu.

10.2 Integration testy

ID	Scénář	Očekávání
I01	Canonical host + trailing slash + uppercase alias + unknown query	Jeden aplikační 308 na úplnou canonical URL; maximálně další ingress TLS hop.
I02	Current product	200, self-canonical, správný market/channel, sitemap membership.
I03	Multi-category product	Jedna product canonical URL; categories pouze v breadcrumbs/internal links.
I04	Category move	URL beze změny; aktualizovaný breadcrumb/JSON-LD; invalidované cache tagy.
I05	Manual slug change	Atomická změna; old path okamžitě 308; new path 200; žádný mezistav nebo chain.
I06	Alias history	Několik historických slugů vede každý přímo na current canonical.
I07	Removed entity bez náhrady	URLR tombstone vede na skutečný 410 před renderem mechanismem prokázaným v M00.
I08	Removed entity s nástupcem	308 na konkrétní náhradu, nikdy homepage/obecná kategorie.
I09	Entita mimo channel	404, i když URLR current záznam existuje.
I10	URLR timeout	503, nikoli 404.
I11	Medusa/CMS unavailable i invalid-response	503, bez cached soft-404; non-2xx se nesmí zobrazit jako missing.
I12	Unknown host	421; Accept-Language ani SK fallback se nepoužije.
I13	Spoofed market header	Ignorován; market určí trusted host pipeline.
I14	Hreflang kompletní ekvivalence	Čtyři reciproční absolutní odkazy včetně self-reference.
I15	Hreflang chybějící ekvivalence	Chybějící market není emitován; žádná syntetická homepage URL.
I16	Cross-domain canonical	Každý překlad canonicalizuje pouze sám na sebe; žádný cross-domain canonical.
I17	Page 1	308 na URL bez page; tracking parametry zachovány v Location.
I18	Page 2	200, index, self-canonical s query, bez hreflang a sitemap membership.
I19	Page za koncem	404 na serveru; žádná client-side URL korekce.
I20	Facet/sort	200 + noindex, bez canonical/hreflang/sitemap; robots ji neblokuje.
I21	Search s výsledky	200 + noindex, bez canonical/hreflang/sitemap.
I22	Search bez výsledků, bez q, s prázdným q	Užitečný 200 + noindex; není klasifikován jako missing entity; duplicitní q → 404.
I23	Variant query	Base product canonical; správná varianta otevřená; case hodnoty zachován.
I24	Tracking query	Atribuční hodnoty dostupné aplikaci; canonical a odkazy jsou čisté.
I25	Invalid query	Known syntaktická chyba 404 má přednost; unknown parametr composed 308 strip.
I26	Token route	Bez canonical, hreflang, OG URL a sitemap; token není v metadata.
I27	Invalid/expired/used token	Stejná 404 odpověď bez rozlišení stavu.
I28	Unsafe metoda na alias	Žádný permanent redirect ani přehrání body na canonical endpoint.
I29	Internal namespace	Všechny case/percent varianty /~sf vracejí externí 404.
I30	Robots	Pouze /~sf/ a /api/ jsou Disallow; absolutní sitemap odpovídá hostu.
I31	Sitemap	Všechny URL mají správný host, 200, self-canonical a indexability; žádný alias nebo query class mimo policy.
I32	Sitemap pagination	Enumerace je bounded; shard limit nepřekročen; lastModified je obsahový timestamp.
I33	Cache isolation	Shodné entity ID ve dvou marketech nevrátí cross-market slug, metadata, cenu ani availability.
I34	Webhook invalidace	Slug/assignment/publishability změna invaliduje old/new URL, alternates a sitemap.
I35	Static route collision	Build/publish skončí hard failurem; runtime pořadí filesystem routes kolizi „nevyřeší“.
I36	Multi-host/separate parity	Stejný route target generuje stejné path/SEO výsledky; mění se pouze povolený host/runtime subset; route-config hash shodný.
I37	Header propagation přes RSC	x-sf-* kontrakt a public-path informace přežívají RSC requesty a client navigation; spoofing přes RSC request nefunguje.
I38	Method contract	Non-action POST, PUT, PATCH, DELETE na veřejné page routes vracejí 405 + Allow; HEAD má stejné statusy/headers jako GET a prázdné body.
I39	Publishable key per host	Každý host volá Store API se svým server-resolved key; jiný market key nelze získat spoofingem hosta ani headeru.
I40	CSV normalizace	Nekanonické CSV pořadí/duplicity/whitespace končí jedním composed 308 na kanonickou formu.
I41	Market assignment ne-produktových entit	Kategorie/brand/kolekce/kampaň nepřiřazená marketu vrací 404 přes navržený Medusa assignment kontrakt; globální tree lookup podle handle se nepoužívá.
I42	Diskriminovaný CMS kontrakt	Network error → 503; non-2xx → 503; definitivní CMS miss → 404; schema violation → 503 + alert.
I43	Equivalence bez sdíleného product record	Market-specific samostatné records bez explicitního equivalence_key negenerují hreflang.
I44	Legacy inventory mapping	Každá URL z 7.9 vrací rozhodnutý výsledek (308 na přesný cíl / zachování / 404 pro nepublikované), včetně /blog, /znacka, /search, /account, /auth, /checkout, /reviews, root /{slug}.

10.3 Browser a production-wire E2E

Testy se spouštějí proti production buildu přes skutečný ingress/proxy chain, samostatně pro single multi-host konfiguraci a pro každý separate-deployment market config; statusové scénáře běží pro GET i HEAD.

ID	Scénář	Ověření
E01	Homepage SK/CZ/HU/RO	HTTP 200, správné <html lang>, canonical host, lokalizovaná navigace, žádný locale prefix.
E02	Product detail SK/CZ/HU/RO	Initial response obsahuje canonical, metadata, JSON-LD a správné interní odkazy.
E03	Missing product	Status na drátě je 404 před flush; nikoli 200 s error card.
E04	Missing category	Skutečný 404 před flush.
E05	Missing CMS/advice page	Skutečný 404 před flush.
E06	Tombstone	Skutečný 410 před flush mechanismem prokázaným v M00; žádný 200 shell.
E07	Alias	Skutečný 308 Location header před renderingem; žádný HTML meta redirect.
E08	Redirect composition	Host/slash/case/alias/query chyba skončí jedním aplikačním hopem; celkem nejvýše dva s ingress TLS.
E09	Query preservation	Alias zachová pouze parametry povolené cílovým route schema; tracking nepřejde do canonical.
E10	Pagination	Page 1 redirect; page 2 self-canonical; out-of-range 404; browser neopravuje URL na poslední stránku.
E11	Facet/sort/search	Initial HTML obsahuje noindex; chybí canonical a hreflang; URL není blokována robots.txt.
E12	Domain switcher	Přechod vede na skutečný localized equivalent s odlišným slugem; chybějící equivalent negeneruje syntetický odkaz.
E13	Missing market assignment	Produkt dostupný na jednom hostu vrátí na jiném hostu 404; žádný cross-market cache leak.
E14	Token secrecy	Token není v title, canonical, hreflang, OG, JSON-LD ani sitemap; všechny invalidní stavy mají stejnou 404.
E15	Unknown host	421 pro hosty routované na aplikaci, testováno přímým Host headerem na origin i přes veřejný ingress; host, který ingress neroutuje, aplikace garantovat nemůže a testuje se na ingress vrstvě.
E16	Malformed raw URL	Adapter vrátí 400 pro invalid encoding/authority a 414 nad limitem; %2F, %5C, %252F a malformed UTF-8 se chovají per kontrakt na Dockeru i Netlify.
E17	/~sf bypass pokusy	Case, percent-encoding a normalizační varianty vracejí 404.
E18	Robots/sitemap per host	Každý host uvádí vlastní absolutní sitemap; sitemap URL neobsahují cizí doménu.
E19	Sitemap sample crawl	Reprezentativní URL vracejí 200, self-canonical a nejsou noindex.
E20	Backend outage	URLR/Medusa/CMS výpadek vrací 503, nikoli 404 nebo stale soft-404.
E21	Cache invalidation	Po změně slugu old URL 308, new URL 200, canonical/hreflang/sitemap jsou aktualizovány bez restartu.
E22	cacheComponents gate	Se zapnutou konfigurací musí E03–E08 prokázat status před flush; při neúspěchu release config obsahuje cacheComponents: false.
E23	Internal link crawl	Crawl homepage, indexů, kategorií, značek a kolekcí objeví canonical product URL bez závislosti na search.
E24	No redirect chains	Automatický crawl všech interních a sitemap URL nenajde chain delší než povolený ingress+app limit.
E25	M00 status suite	Current 200, alias 308, miss 404, tombstone 410, outage 503 před streamingem pro GET i HEAD, včetně RSC navigace, na Dockeru i Netlify.
E26	Host-keyed cache	CDN/reverse-proxy cache keyuje podle hostu; pokus o cross-host cache poisoning nevrátí cizí market obsah.
E27	HEAD parita	HEAD na reprezentativních route classes vrací prázdné body a stejné statusy/headers jako GET.
E28	RSC/client-nav propagace	Public-path a market kontrakt přežívá client-side navigaci; metadata i canonical zůstávají správné bez full reload.
E29	Sitemap/robots rewrites per host	/robots.txt, /sitemap.xml a shard rewrites fungují na každém hostu v multi-host i separate konfiguraci.
E30	Legacy URL crawl	Crawl inventáře 7.9 končí jedním aplikačním 308 na nové cesty; žádný chain, žádný 200 na zrušené legacy route.

10.4 Traceability akceptace

Backlog	Povinné testy
M00	E25, E16, E27
M01	U31, I36, E22
M02	U01–U03, U41, I09, I12–I13, I39, E13, E15
M03	U03, U10, U31, U33–U34, I13, I29, I37, E17, E28
M04	U04–U06, U32, I35, E01
M05	U12–U13, U28, I01, I36, E23
M06	U08, U24–U27, U40, I05–I08, E06–E07
M07	U08–U10, U27, I35
M08	U26, I07–I11, E03–E08, E25
M09	U01, U26, U40, I02, I09–I11, I42, E13, E20
M10	U13, U22, U28, I02, I16, E01–E02
M11	U23, I14–I16, I43, E12
M12	U15–U23, U36–U39, I17–I25, I40, E10–E11
M13	U14, U20–U21, U24, U35, I01, I05–I06, I28, I38, E07–E09, E27
M14	U29, I30–I32, E18–E19, E29
M15	U30, I33–I34, E21, E26
M16	U04, U32, I14, I36, E01–E02
M17	U02–U03, U11, U26, U42, I12–I13, E15–E17
M18	I07–I11, E03–E08, E20, E22, E25
M19	U30, I33–I34, I36, E21, E26, E29
M21	I09, I41, E13
M22	U24, I44, E30
M20	U01–U42, I01–I44, E01–E30

---

[BleedingDev]

Plná normativní specifikace — část 05/5. Krátká implementační verze je v popisu issue; tato část je závazný zdroj při sporu.

---

11. Evidenční příloha

Přístup ke všem externím zdrojům: 2026-08-05. Pro chování přesné verze je závaznou autoritou instalovaný balík apps/herbatika/node_modules/next a tagovaný source v16.3.0-preview.5; obecné nextjs.org/docs popisují stabilní řadu 16.3 a mají pro preview tag confidence nejvýše střední.

11.1 SEO a webové standardy

Claim	Typ	Zdroj URL / přesný název	Confidence
Canonical je signál pro výběr reprezentativní URL; redirect, canonical a sitemap lze používat konzistentně	primární search-engine dokumentace	How to specify a canonical URL with rel="canonical" and other methods — Google Search Central	vysoká
Canonical není vhodný jako obecný crawl-control mechanismus	primární search-engine dokumentace	How to specify a canonical URL with rel="canonical" and other methods — Google Search Central	vysoká
hreflang má používat plně kvalifikované URL a vzájemné odkazy mezi ekvivalenty	primární search-engine dokumentace	Tell Google about localized versions of your page — Google Search Central	vysoká
x-default označuje jazykově/regionálně nespecifickou variantu; jeho absence je přípustná	primární search-engine dokumentace + [AC]	Tell Google about localized versions of your page — Google Search Central	vysoká pro význam; rozhodnutí neemitovat je [AC]
Faceted navigation může vytvářet velký prostor URL a vyžaduje explicitní crawl/index policy	primární search-engine dokumentace	Managing crawling of faceted navigation URLs — Google Search Central	vysoká
Google již nepoužívá rel="next"/rel="prev" jako indexační signál; pagination stránky mohou být samostatné URL	primární search-engine dokumentace	Pagination, incremental page loading, and their impact on Google Search — Google Search Central	vysoká
Robots-blocked URL nemůže spolehlivě předat noindex, protože crawler pravidlo nemusí načíst	primární search-engine dokumentace	Robots Meta Tags Specifications — Google Search Central	vysoká
Robots.txt je crawl directive, nikoli mechanismus ochrany citlivých dat	primární search-engine dokumentace	Introduction to robots.txt — Google Search Central	vysoká
Sitemap má obsahovat canonical URL, které chce web zobrazovat ve výsledcích	primární search-engine dokumentace	Build and submit a sitemap — Google Search Central	vysoká
Sitemap protokol omezuje jeden soubor na 50 000 URL a 50 MB nekomprimovaných dat	otevřený protokol	Sitemaps XML format — sitemaps.org	vysoká
301 i 308 jsou permanentní redirecty použitelné jako silný canonical signál	primární search-engine dokumentace	Redirects and Google Search — Google Search Central	vysoká
308 Permanent Redirect zachovává metodu a obsah požadavku	IETF standard	RFC 9110: HTTP Semantics, Section 15.4.9 — 308 Permanent Redirect	vysoká
307 Temporary Redirect zachovává metodu (Section 15.4.8); 303 See Other obvykle převádí následné načtení na GET (Section 15.4.4)	IETF standard	RFC 9110: HTTP Semantics, Sections 15.4.8 and 15.4.4	vysoká
404 znamená nenalezený nebo nezveřejněný zdroj (15.5.5); 410 znamená, že zdroj byl odstraněn pravděpodobně trvale (15.5.11)	IETF standard	RFC 9110: HTTP Semantics, Sections 15.5.5 and 15.5.11	vysoká
400 Bad Request (15.5.1), 405 Method Not Allowed + Allow (15.5.6), 414 URI Too Long (15.5.15), 421 Misdirected Request (15.5.20), 503 Service Unavailable (15.6.4)	IETF standard	RFC 9110: HTTP Semantics	vysoká
Chybová stránka s HTTP 200 může být vyhodnocena jako soft-404	primární search-engine dokumentace	Soft 404 errors — Google Search Console Help	vysoká
HTTP 4xx URL nejsou indexovány; 5xx signalizuje dočasnou serverovou nedostupnost	primární search-engine dokumentace	HTTP status codes, and network and DNS errors — Google Search Central	vysoká
URL komponenty mají standardizované parsování a serializaci; WHATWG standard sám nedokládá odmítání encoded slash/backslash, bidi nebo zero-width — to je projektová politika	webový standard + [AC] + ingress security contract	URL Standard — WHATWG	vysoká pro parsování; odmítání vstupů je [AC]
Scheme a host jsou case-insensitive; normalizace path case je projektová politika, nikoli obecná vlastnost URI	IETF standard + [AC]	RFC 3986: Uniform Resource Identifier (URI): Generic Syntax, Section 6.2.2.1	vysoká
Slova v URL nejsou v této specifikaci tvrzena jako významný ranking faktor; lokalizované slugy jsou UX/IA rozhodnutí	[AC]	Závazný rozhodovací záznam — „URL keywords se neuvádí jako významný ranking faktor“	vysoká jako projektové omezení
Self-canonical na každé indexovatelné stránce	[AC] podporovaná doporučením	How to specify a canonical URL with rel="canonical" and other methods — Google Search Central	vysoká pro doporučení; MUST policy je [AC]
Pagination page ≥ 2 je indexovatelná se self-canonical a mimo sitemap	[AC]	Závazný rozhodovací záznam — „Facets / pagination / query“	vysoká jako binding policy
Facet/sort/search URL používají noindex bez canonical	[AC]	Závazný rozhodovací záznam — „Indexace query tříd“	vysoká jako binding policy
Vyprodaný publikovaný produkt zůstává indexovatelný a v sitemap	[AC]	Závazný rozhodovací záznam — „Vyprodaný produkt“	vysoká jako binding policy
Sitemap shard target 10 000 URL / 25 MB	[AC] pod protokolovým limitem	Sitemaps XML format — sitemaps.org	vysoká pro protokolový limit; target je [AC]
Aliasy se uchovávají navždy; Google minimálně doporučuje redirecty držet dlouhodobě	primární dokumentace + [AC]	Site Moves and Migrations — Google Search Central	vysoká pro dlouhodobý redirect; permanentní retention je [AC]

11.2 Next.js v16.3.0-preview.5

Claim	Typ	Zdroj URL / přesný název	Confidence
Autoritativní release je v16.3.0-preview.5; instalovaná verze ověřena	přesný release tag + installed package	Next.js v16.3.0-preview.5 — GitHub Release; apps/herbatika/node_modules/next/package.json ("version": "16.3.0-preview.5")	vysoká
Route sorting řadí static před dynamic/catch-all v sorted-routes	installed exact-version source	apps/herbatika/node_modules/next/dist/shared/lib/router/utils/sorted-routes.js; sorted-routes.ts — v16.3.0-preview.5	vysoká pro existenci a řazení; App Router-specific precedence není z tohoto souboru samostatně dokázána (střední) — collision validator M07 proto na filesystem precedence nespoléhá
_-prefixovaná App Router složka je private folder a nevytvoří URL segment	oficiální dokumentace (stabilní řada 16.3)	Project structure: Private folders — Next.js	střední pro preview tag; závěr potvrzuje zamítnutí app/_m/...
Proxy nahrazuje deprecated Middleware, běží před filesystem routingem a používá Node.js runtime	oficiální dokumentace (stabilní řada 16.3)	proxy.js — Next.js	střední pro preview tag
Proxy smí být async; zákaz URLR/DB lookupu je projektová boundary policy	framework docs + [AC]	proxy.js — Next.js	střední pro capability; zákaz je [AC]
permanentRedirect() používá 308 a redirect() 307 mimo Server Actions	installed exact-version source	apps/herbatika/node_modules/next/dist/client/components/redirect-status-code.js (TemporaryRedirect = 307, PermanentRedirect = 308); redirect.ts — v16.3.0-preview.5	vysoká
Redirect po zahájení streamingu může být vložen jako client meta redirect	oficiální dokumentace	redirect — Next.js	střední pro preview tag; wire testy E07/E25 to pokrývají přímo
notFound() přidává noindex	oficiální dokumentace	notFound — Next.js	střední pro preview tag
Streaming not-found může zachovat HTTP 200, zatímco non-streamed odpověď používá 404	oficiální dokumentace	not-found.js — Next.js	střední pro preview tag; přesné chování rozhoduje M00/M18 na drátě
HTTP-access-fallback exact verze obsahuje pouze statusy 404, 403, 401; žádné veřejné gone() API	installed exact-version source	apps/herbatika/node_modules/next/dist/client/components/http-access-fallback/http-access-fallback.js (HTTPAccessErrorStatus = { NOT_FOUND: 404, FORBIDDEN: 403, UNAUTHORIZED: 401 })	vysoká pro absenci API. Absence gone() nedokládá funkčnost žádného konkrétního 410 mechanismu; mechanismus 410/503 je UNKNOWN do úspěchu M00
Metadata API podporuje canonical, languages a metadataBase	docs + exact source types	generateMetadata — Next.js; metadata-interface.ts — v16.3.0-preview.5	vysoká pro tagovaný source
Metadata jsou shallow-merged; vnořené objekty mohou být přepsány	oficiální dokumentace	generateMetadata: Merging — Next.js	střední pro preview tag
Sitemap metadata route podporuje více sitemap souborů	oficiální dokumentace	sitemap.xml — Next.js	střední; přesné chování hlídá version gate a E29
Robots metadata route může publikovat absolutní sitemap URL	oficiální dokumentace	robots.txt — Next.js	střední pro preview tag
generateStaticParams se při ISR znovu nespouští	oficiální dokumentace	generateStaticParams — Next.js	střední pro preview tag
Cache invalidace může používat revalidateTag; přesné tagy jsou vhodnější než široké path invalidace	oficiální dokumentace	Revalidating — Next.js	střední pro preview tag
Self-hosting na více instancích vyžaduje koordinovaný cache handler a konzistentní runtime konfiguraci	oficiální dokumentace	Self-hosting — Next.js	střední pro preview tag
deploymentId pomáhá chránit rolling deployment před skew	oficiální dokumentace	deploymentId — Next.js	střední pro preview tag
typedRoutes typuje framework routes, nikoli business význam lokalizovaných segmentů	oficiální docs + [AC]	typedRoutes — Next.js	střední pro framework scope; doménové API je [AC]
skipTrailingSlashRedirect je dostupný v exact config schema	installed exact-version schema	apps/herbatika/node_modules/next/dist/server/config-schema.js (klíč přítomen); config-schema.ts — v16.3.0-preview.5	vysoká
Netlify Next.js adapter je samostatná platform vrstva s vlastním chováním raw requestů	platform dokumentace	Netlify Next.js overview	střední; wire chování ověřuje M17/E16/E25
Rozhodnutí vypnout cacheComponents, pokud hard-status suite neprojde, je release policy	[AC]	Závazný rozhodovací záznam — „cacheComponents gate“	vysoká jako binding policy

11.3 Projektová a datová evidence

Claim	Typ	Zdroj / název	Confidence
Herbatika používá Next.js 16.3.0-preview.5, typedRoutes, cacheComponents a standalone output	repository source	apps/herbatika/package.json; apps/herbatika/next.config.ts; instalovaný node_modules/next	vysoká
Repository obsahuje jeden Herbatika standalone-capable service na lokálním portu; Caddy nemá žádnou Herbatika host route ani čtyřdoménové směrování — multi-host ingress je cílová, dosud neimplementovaná topologie	repository source	docker-compose.yaml; docker-compose.prod.yaml; docker/development/caddy/Caddyfile (bez herbat* host route); docker/development/herbatika/Dockerfile	vysoká
Publishable key je dnes jedna globální build-time hodnota vkládaná Dockerem (ARG/ENV NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY); jeden multi-host proces proto neumí zvolit key per market	repository source	docker/development/herbatika/Dockerfile (řádky 87 a 95)	vysoká
Store requesty používají publishable-key scope; repository používá jeden globální key a neověřuje, že je připojen právě k jednomu sales channelu — Medusa v2 PAK může zahrnovat více channels, absence sales_channel_id query sama o sobě chyba není	repository source + primární Medusa dokumentace	apps/herbatika/src/lib/storefront/ssr/prefetch-product.ts; prefetch-category.ts; Medusa publishable keys and sales channels	vysoká
Současný market resolver fallbackuje přes Accept-Language	repository source	libs/storefront-i18n/src/core/markets.ts (getAcceptedLanguages, acceptLanguage parametr)	vysoká
Product flow může vracet soft-404: server page vždy renderuje client component a missing stav je 200 UI	repository source	apps/herbatika/src/app/p/[handle]/page.tsx (bez notFound); apps/herbatika/src/components/product-detail.tsx (controller.product ? null : (…) missing branch)	vysoká
Category flow může vracet soft-404: /c/[slug]/page.tsx neobsahuje notFound a aktivní kategorie se hledá jen podle handle v globálním tree (categoryByHandle.get(slug) ?? null), missing stav renderuje 200 UI	repository source	apps/herbatika/src/app/c/[slug]/page.tsx; apps/herbatika/src/components/category/use-category-listing-queries.ts (řádek 114); apps/herbatika/src/components/category-listing.tsx	vysoká
CMS locale je hardcoded na sk a CMS klient převádí network error i každý non-2xx na null (nelze odlišit 404 od 503)	repository source	apps/herbatika/src/lib/storefront/cms-client.ts (řádek 9 CMS_LOCALE = "sk"; return null větve řádky 48 a 52)	vysoká
Payload locales dnes negarantují HU/RO: compose default cs,sk,en, production default pouze en, Dockerfile ARG default en	repository source	docker-compose.yaml (řádek 227); docker-compose.prod.yaml (řádek 55); docker/development/payload/Dockerfile (řádky 63, 71)	vysoká
Medusa Translation Module existuje; Store API může vracet originální obsah jako fallback — publish gate proto validuje skutečný překlad přes Translation data/admin kontrakt	primární Medusa dokumentace	Medusa Translation Module	střední pro přesnou instalovanou verzi; ověření instalace zůstává release úkol M16
Brand slugy jsou odvozovány za runtime a kolize používají first wins	repository source	apps/herbatika/src/lib/storefront/brands.ts; brands.server.ts	vysoká
Root /[slug] vytváří globální CMS namespace	repository source	apps/herbatika/src/app/[slug]/page.tsx	vysoká
Současný routing helper není market-aware single source of truth	repository source	apps/herbatika/src/lib/routing.ts	vysoká
/homepage-promo není publikovaná route; existuje jen jako homepage komponenta	repository source	apps/herbatika/src/components/homepage/sections/homepage-promo-section.tsx; absence v src/app	vysoká
URLR jako Next-owned Postgres schema je projektová architektura	[AC]	Závazný rozhodovací záznam — „Medusa boundary“	vysoká jako binding policy
Flat category URL, product URL bez category a explicitní equivalence_key jsou projektová architektura	[AC]	Závazný rozhodovací záznam — „Produkt a kategorie“; „Canonical / hreflang“	vysoká jako binding policy
ASCII slug grammar, max 80 a zmrazená transliterace jsou provozní volba, nikoli ranking požadavek	[AC]	Závazný rozhodovací záznam — „Slug a alias pravidla“	vysoká jako binding policy
Alias retention navždy, alias→current only a zákaz reuse jsou projektové invarianty	[AC]	Závazný rozhodovací záznam — „Slug a alias pravidla“	vysoká jako binding policy
1 market = 1 publishable key = 1 sales channel je projektový invariant vynucený konfigurací a testem	[AC]	Závazný rozhodovací záznam — „Medusa boundary“	vysoká jako binding policy
primary_category_id a channel-scoped assignment extension pro category/brand/collection/campaign jsou navržená Medusa rozšíření, nikoli doložené standardní fields	[AC] + repository absence	Závazný rozhodovací záznam; M21	vysoká jako binding policy

11.4 Obecný e-commerce benchmark (nenormativní)

Srovnání s běžnými moderními e-commerce patterny; neslouží jako autorita, nemění binding decisions a nepoužívá Herbatica konkurenty:

Pattern	Běžná praxe moderních e-shopů	Toto rozhodnutí
Typed prefixes	Rozšířené jak prefixované (/products/…), tak root-level slugy; prefixy zjednodušují kolize a parsing	Lokalizované plurální prefixy [AC]
Kategorie	Obě varianty (flat i hierarchická path) běžné; hierarchická path komplikuje přesuny a duplikuje obsah	Flat category URL [AC]
Product canonical nezávislý na kategorii	Převažující praxe u multi-category katalogů	Shodné, závazné
Facets/sort	Převažuje omezení indexace facet prostoru (noindex, canonical, nebo robots dle strategie)	Crawlable + noindex bez canonical [AC]
Market domény	ccTLD per trh i path/locale prefixy jsou běžné; ccTLD bez prefixů odpovídá zadání one domain = one market	ccTLD, bez locale prefixů, hard boundary
Pagination	Samostatné indexovatelné ?page=N se self-canonical je běžný vzor po zrušení rel=prev/next	Shodné [AC]

---

12. Release-readiness checklist

Release 2026-08-20 je povolen pouze při splnění všech položek označených jako gate. Dokument smí nést status „binding, implementation-ready" až po úspěchu M00 a doplnění všech finálních sekcí (URL matrix s příklady po sign-off, route tree s prokázaným status mechanismem, field-by-field Medusa/URLR kontrakt).

Feasibility

• GATE, nejpozději 2026-08-10 (M00): V production buildu 16.3.0-preview.5 je na drátě prokázáno 200/308/404/410/503 před streamingem, pro GET i HEAD, včetně RSC navigace, přes Docker proxy chain i Netlify adapter. Při neúspěchu se mění boundary (URLR lookup v Proxy/ingressu, podporovaný front controller, nebo jiný doložený mechanismus) a dokument se reviduje.

Konfigurace a vlastnictví

• GATE: Next.js je přesně pinován na 16.3.0-preview.5; lockfile a CI zakazují tichý upgrade.
• GATE: Canonical origins jsou přesně https://herbatica.sk, https://herbatica.cz, https://herbatica.hu, https://herbatica.ro.
• GATE: Každý host mapuje právě jeden market, locale, country, region, salesChannelId a server-only publishable key.
• GATE: Market publishable keys nejsou globální build-time NEXT_PUBLIC_* hodnota; každý host prokazatelně posílá svůj key a cizí key nelze získat spoofingem.
• GATE: Publishable key použitý storefrontem je testem omezen právě na jeden sales channel.
• GATE: Marketová dostupnost kategorie, brandu, kolekce a kampaně má Medusa-owned, adminovatelný, channel-scoped assignment kontrakt (M21); globální tree lookup podle handle se nepoužívá.
• GATE: Každý povolený alias host má ověřené vlastnictví, DNS a TLS; ostatní hosty routované na aplikaci vracejí 421.
• GATE: Reverse proxy přepisuje x-forwarded-host, x-forwarded-proto a interní x-sf-* headers; klient je nemůže spoofovat, ani přes RSC requesty.
• GATE: Multi-host a separate-deployment config používají stejný build a stejný route registry; multi-host ingress topologie je implementována (dnes v repository neexistuje).

Lokalizace

• GATE, nejpozději 2026-08-07: SK/CZ/HU/RO segment registry má native editorial/legal sign-off; do té doby jsou segmenty vedeny jako „navržené, neověřené".
• GATE: Segment registry je po sign-off frozen; následná změna publikovaného segmentu vytváří alias.
• GATE: UI, checkout, account, auth, katalog, CMS, metadata, structured data a právní obsah mají všechny čtyři lokalizace.
• GATE: Payload locales jsou build-time i runtime přesně sk,cs,hu,ro (dnešní defaulty cs,sk,en / en nevyhovují) a data coverage každé lokalizované collection je ověřena.
• GATE: Chybějící povinný překlad blokuje publish; žádný tichý SK fallback; Medusa Translation publish gate validuje skutečný překlad, nikoli Store API fallback hodnotu.
• GATE: CMS request locale není hardcoded na sk.

Routing a URLR

• GATE: Veřejné root /{slug} neexistuje.
• GATE: Interní namespace používá routovatelný /~sf, nikoli private folder _m.
• GATE: Všechny přímé case/percent varianty /~sf vracejí 404.
• GATE: Proxy nečte URLR, Medusa, CMS ani jinou databázi a plní header contract (x-sf-market, x-sf-canonical-origin, public pathname) se zachováním query pořadí a duplicit.
• GATE: Resolver, metadata a builder neodvozují veřejnou URL z /~sf/... ani z raw Host.
• GATE: Resolver používá nejvýše jeden indexed URLR lookup a jeden bounded equivalence lookup.
• GATE: URLR schema obsahuje field-by-field kontrakt (market, kind, stable source ID/type, current slug, immutable aliasy, state, replacement target, equivalence key, indexability override, timestamps/version, optimistic locking) a diskriminovaný lookup výsledek.
• GATE: Alias chains, cycles, reuse a alias→alias jsou databázově i aplikačně zakázány.
• GATE: Změna slugu probíhá atomicky a starý slug se stane permanentním aliasem.
• GATE: Collision validator blokuje všechny definované namespace, transliterační, host a equivalence konflikty.
• GATE: Každá skutečně publikovaná legacy URL z inventáře 7.9 má implementované rozhodnutí (308/410/zachování/dev-only), včetně /blog → /poradna a /znacka → /znacky mapování.
• GATE: Repo scan nenajde ad hoc skládání veřejných commerce/content URL.

SEO výstupy

• GATE: Každá indexovatelná route má absolutní self-canonical.
• GATE: Pro tentýž route target používají canonical, og:url, primární JSON-LD url/@id, sitemap a interní odkazy tentýž builder a výslednou URL.
• GATE: Facets, sort, search a privátní routes mají noindex podle matice a nejsou blokovány robots.txt.
• GATE: Pagination page 1 redirectuje na čistou URL; page ≥2 má self-canonical a není v sitemap.
• GATE: Tracking a variant query nikdy nevstupují jako samostatné sitemap URL.
• GATE: Query pravidla 7.4 jsou uzavřena bez implicitních případů (duplicitní singletony, opakované facet keys, CSV kanonizace, q edge cases, jednotky limitů, precedence, tracking při stripu) a pokryta golden fixtures.
• GATE: hreflang obsahuje pouze skutečné current 200 equivalents, self-reference a reciprocitu; equivalence jen přes explicitní equivalence_key.
• GATE: Chybějící equivalent je vynechán; žádný homepage nebo same-slug fallback.
• GATE: x-default se v release neemituje.
• GATE: Každý host publikuje vlastní sitemap index, bounded shardy a robots s absolutní vlastní sitemap URL; rewrites ověřeny na každém hostu.
• GATE: Sitemap obsahuje pouze current canonical 200 indexable URL.

Statusy a redirecty

• GATE: skipTrailingSlashRedirect: true je zapnuto.
• GATE: Host, slash, case, alias a query canonicalizace tvoří jeden aplikační 308.
• GATE: Core neemituje 301; permanentní GET/HEAD redirect používá 308.
• GATE: Tokeny, order IDs, varianty a provider parametry nejsou case-normalizovány.
• GATE: Missing entity a market/channel miss vracejí skutečný 404.
• GATE: URLR tombstone vrací skutečný 410 mechanismem prokázaným v M00.
• GATE: URLR/Medusa/CMS klienti vracejí diskriminovaný výsledek; unavailable a invalid-response vracejí 503, nikoli 404.
• GATE: Non-action POST, PUT, PATCH, DELETE na veřejných page routes vracejí 405 + Allow; HEAD má paritu s GET a prázdné body.
• GATE: Token states mají jednotné 404; veřejná odpověď neprozrazuje validitu tokenu.
• GATE: Žádný missing route typ nevrací 200 soft-404 (dnešní product i category flow to porušují a MUST být nahrazeny).
• GATE: Redirect na homepage nebo nesouvisející kategorii pro odstraněnou entitu neexistuje.

Cache a provoz

• GATE: Každý relevantní cache key obsahuje market a podle potřeby salesChannelId; CDN/reverse-proxy cache keyuje podle hostu (test cross-host poisoning).
• GATE: Slug, alias, assignment, publishability a equivalence webhooky invalidují všechny odvozené výstupy.
• GATE: Více instancí sdílí cache handler, tag koordinaci a Server Functions encryption key.
• GATE: Rolling deployments používají deploymentId.
• GATE: Všechny instance hlásí shodný route-config hash; separate deployment běží se správným ALLOWED_MARKETS subsetem.
• GATE: Sitemap a generateStaticParams používají bounded/paginated reads.

Verifikační gate

• GATE, nejpozději 2026-08-17: Production-wire suite pro 308, 404, 410 a 503 prošla přes reálný Docker proxy chain, pro GET i HEAD.
• GATE, nejpozději 2026-08-17: Stejná raw URL/host/status suite prošla přes Netlify adapter.
• GATE: Pokud cacheComponents: true nesplní hard-status suite, release config jej má vypnutý.
• GATE: Všechny unit testy U01–U42 jsou zelené.
• GATE: Všechny integration testy I01–I44 jsou zelené.
• GATE: Všechny production browser/wire E2E testy E01–E30 jsou zelené pro multi-host i separate-deployment konfiguraci.
• GATE: Automatický crawl interních, sitemap i legacy URL nenalezl redirect chain, soft-404, cross-market URL, alias link ani rozporný canonical.
• GATE: Release artefakt obsahuje přesný config snapshot, segment registry hash, URLR migration version a výsledky M00 + hard-status suite.