ESHOP Products¶

Tato dokumentace je první kurátorovaná vrstva nad původními návrhovými materiály a nad aktuálním stavem aplikace v app/.

Její cíl je:

• vysvětlit, co systém dělá a proč je rozdělený do domén,
• popsat základní obchodní logiku pro vývojáře i editorial/projektový tým,
• zafixovat aktuální stav public i admin API a databáze,
• oddělit to, co už je implementované, od toho, co je zatím návrh nebo plán.

Není to jen reference ke kódu. Je to i ochrana proti návratu do starého chaosu, kde nebylo jasné, co se smí, co se nesmí a kde je vlastně zdroj pravdy.

Co je tento projekt¶

ESHOP/products je headless PHP API pro produktový katalog. PostgreSQL je zdroj pravdy pro produktová data a Meilisearch je read model pro vyhledávání, ne zdroj pravdy.

Systém je navržený jako SQL-first aplikace bez ORM a bez velkého frameworku. Aplikace používá vlastní core/ vrstvu pro HTTP, routing, middleware pipeline a přístup do databáze.

Co jsme si vzali z jiných projektů¶

Projekt nestaví na jednom frameworku. Vzal si osvědčené koncepty z více e-commerce systémů a přizpůsobil je vlastnímu provozu.

• Vendure: rozdělení Product vs. ProductVariant, translation tabulky, kolekce a denormalizovaný search dokument.
• Medusa: samostatný pricing model přes price_set a price, oddělený inventory model, rezervace a multi-location sklad.
• Sylius: jasné rozlišení Option vs. Attribute, tedy co tvoří variantu a co je jen popisná vlastnost.
• Spree: resource-oriented REST API a čitelný styl endpointů.

Nejde o vendor-lock ani kopii cizího datového modelu. Jde o vlastní PostgreSQL-first architekturu, která přebírá jen to, co je pro náš provoz užitečné.

Jak dokumentaci číst¶

• Pokud potřebuješ rychle pochopit projekt, začni sekcemi Projekt a Architektura.
• Pokud řešíš, proč je model navržený přísně a kde jsou jeho hranice, otevři Proč to děláme a Guardrails a zákazy.
• Pokud neznáš doménu, pokračuj do Slovník pojmů a Moduly.
• Pokud řešíš tabulky nebo migrace, použij sekci Databáze.
• Pokud potřebuješ původní návrhové materiály, jsou zachované v sekci Zdrojové podklady.

Důležité upozornění¶

Tato dokumentace vědomě rozlišuje:

• aktuální stav = co je dnes v migracích a v aplikaci,
• cílový model = kam míří návrh v původních markdown souborech.

Pokud je mezi nimi rozdíl, ber jako zdroj pravdy pro implementaci nejdřív migrace a kód v app/.