API a routy

Stav dokumentu: Částečně — veřejné stránky kolem katalogu, zpracování, symptomů/témat, sezóny a regionů jsou implementované; REST /api/* zbývá. Správa obsahu (chráněné rozhraní) je jen v 32-admin.md.

Kontrola zapracování

§1 Veřejné routy — část hotová (viz níže v souboru)
§2 Rozhraní editora — výhradně 32-admin.md (v repu zatím žádné /admin)
§3 Veřejné REST /api/… (plán); interní údržba POST /__internal/herb-maintenance volitelná přes secret
§4 Filtrování /byliny (q, month, part, region, pm, topic, topicScope, science, scienceMin, studyType, safety, spiritual)
§5 Detail byliny z D1
§6 Přehledové stránky sezóny a regionů (/sezona, /region + detail) — hotové; alias /co-sbirat/:month přesměruje na /sezona/:month; alias /byliny-na-zpracovani/:slug přesměruje na /zpracovani/:slug; /ritualy (knihovna spirituálních návodů) je routováno. Ostatní aliasy typu /byliny-v/:region zatím ne

1. Veřejné routy

/
/dokumentace
/dokumentace/:slug
/robots.txt
/sitemap.xml
/byliny
/byliny/:slug
/zpracovani
/zpracovani/:slug
/byliny-na-zpracovani/:slug
/recepty
/symptomy
/symptomy/:slug
/sezona
/sezona/:month
/co-sbirat/:month
/ritualy
/ritualy/:slug
/region
/region/:slug
/vyhledavani         (plán)

Implementováno:

/zpracovani, /zpracovani/:slug a SEO alias /byliny-na-zpracovani/:slug (301 na kanonický detail metody) — katalog způsobů zpracování, odkazy na byliny, /byliny?pm=<slug> a přehled editorských receptů napojených na metodu (data herb_method_recipes, migrace 0015_herb_method_recipes.sql). Sloupce času přípravy a bezpečnostního souhrnu metody: migrace 0024_processing_method_prep_safety_summary.sql; ikony a srovnání metod: app/lib/processing-method-meta.ts. V hlavičce: „Zpracování“.
/recepty — agregovaný přehled všech publikovaných řádků herb_method_recipes s odkazem na kartu byliny a na detail způsobu zpracování (app/db/recipes.server.ts). V hlavičce: „Recepty“.
/symptomy a /symptomy/:slug — témata z topics s vazbami přes herb_topic_links na publikované byliny; na detailu tématu je vidět link_type (včetně kulináře, kosmetiky, aromaterapie). /symptomy?q= — filtrování výpisu podle názvu, slug nebo popisu (app/lib/fold-for-search.ts). V hlavičce: „Symptomy“. Migrace: 0011_herb_topic_links_seed.sql, vědecké vazby 0012_…, 0013_…, ukázkové lifestyle vazby 0014_herb_topic_lifestyle_links.sql.
/sezona a /sezona/:month (1–12) — rozcestník měsíců, rychlá navigace po roce a rozšířený měsíční přehled: části rostliny v období sběru, náhled zpracování, stupeň bezpečnosti; odkazy na /byliny?month=&part=. <title> a <meta name="description"> (včetně zkrácení na cca 160 znaků) pro /sezona i /sezona/:month v app/routes/sezona._index.tsx a sezona.$month.tsx; na stránce měsíce H2 nad tabulkou přehledu. Alias /co-sbirat/:month přesměruje na /sezona/:month. V hlavičce: „Sezóna“.
/ritualy a /ritualy/:slug — knihovna strukturovaných spirituálních / rituálních návodů (spiritual_guides, migrace 0016_spiritual_guides.sql), odděleně od vědeckého obsahu; v hlavičce: „Rituály“. Propojení z karty byliny, má-li návod herb_id.
/region a /region/:slug — regiony s výskytem publikovaných bylin a stejná logika jako /byliny?region=<slug>. V hlavičce: „Regiony“.

2. Rozhraní editora (`/admin`)

Plánované cesty a API pod /api/admin/ jsou evidované pouze v 32-admin.md. Žádná z těchto cest zatím v repu neexistuje.

3. Resource / API routy

Veřejné REST endpointy níže jsou zatím plán (viz 21-tech-spec.md).
POST /__internal/herb-maintenance — cron / ruční údržba (vyžaduje HERB_CRON_SECRET pro ruční volání).

/api/herbs
/api/herbs/:slug
/api/search
/api/filters
/api/regions
/api/topics
/api/processing-methods
POST /__internal/herb-maintenance

Endpointy /api/admin/*: 32-admin.md §4.

Worker endpoint pro ruční spuštění údržby D1 (stejná logika jako plánovaný cron): hlavička Authorization: Bearer <HERB_CRON_SECRET>, vyžaduje nastavený secret v prostředí Workeru. Veřejné REST cesty /api/… výše jsou zatím v plánu.

4. Příklad filtrování (implementace v aplikaci)

Query parametry na /byliny (lze kombinovat s vyhledáváním):

/byliny?q=kopřiva&month=5&part=kvet&region=cr&pm=caj&pm=tinktura&topic=stres&topicScope=science&science=substantial&scienceMin=moderate&studyType=clinical_trial&safety=caution&spiritual=1

Parametr	Význam
`q`	Textové vyhledávání (český / latinský / alternativní název z `herb_names`)
`month`	Měsíc 1–12; bylina má v `harvest_periods` období sběru, které tento měsíc pokrývá (včetně přesahu přes rok). Spolu s `part` musí jeden řádek `harvest_periods` splnit obojí.
`part`	`plant_parts.slug` z řádku sběru (`harvest_periods`); bez `month` stačí libovolný měsíc v řádku s touto částí.
`region`	`regions.slug` z výskytu (`herb_regions`), např. `cr` = Česká republika
`pm`	`processing_methods.slug` — parametr lze zopakovat (`pm=a&pm=b`). Bylina projde, pokud má na kartě alespoň jeden z uvedených způsobů (OR). Jedna hodnota `pm=caj` zůstává podporovaná.
`topic`	`topics.slug` — bylina má v `herb_topic_links` vazbu na dané téma (stejná sada jako `/symptomy/:slug`)
`topicScope`	`all` (výchozí) — libovolný `link_type` u vybraného tématu; `tradition` — `link_type IN ('traditional','spiritual')`; `science` — `link_type = 'scientific'`; `lifestyle` — `link_type IN ('culinary','cosmetic','aromatherapy')`. Bez `topic` se parametr v dotazu ignoruje.
`science`	`any` (výchozí / vynechání) — bez filtru podle karty; `substantial` — existuje publikovaný řádek `scientific_evidence` s `evidence_level` jiným než `unknown` a `narrative` (konkrétní množina v kódu: `SUBSTANTIAL_SCIENCE_CATALOG_EVIDENCE_LEVELS` v `app/lib/claim-labels.ts`); `none` — žádný takový řádek.
`scienceMin`	Platí jen při `science=substantial`. Užší množina `evidence_level` jednoho řádku: `preliminary` (výchozí, shodné s dosavadním „substantial“), `moderate`, `strong`, `review` — viz `SCIENCE_MIN_TIER_LEVELS` v `app/lib/claim-labels.ts`.
`studyType`	Jeden slug `scientific_evidence.study_type` (hodnoty z katalogu v UI). Při `science=substantial` musí stejný řádek splnit i zvolenou úroveň z `scienceMin`. Při `science=none` se parametr ignoruje. Při `science=any` stačí libovolný publikovaný řádek s tímto typem.
`safety`	Shoda `LOWER(TRIM(herbs.safety_level))` u publikované byliny (hodnoty z dat v rozbalovacím seznamu).
`spiritual`	`1` / `true` / `yes` — bylina má alespoň jeden publikovaný záznam v `spiritual_uses`. Jinak se neaplikuje.

Témata / symptomy: výpis a průchod tématem je na /symptomy a /symptomy/:slug. Katalog /byliny umí totéž téma použít jako filtr přes topic a topicScope (viz tabulka výše).

Starší příklad z dokumentace:

/byliny?region=ceska-republika&month=5&processing=caj&topic=spanek

5. Příklad detailu byliny

/byliny/kopriva-dvojdoma

Loader načte mimo jiné jádro herbs, alternativní názvy, podobné byliny (herb_similar → publikované cíle), výskyt, sběr, skladování, zpracování (včetně volitelného editorského receptu herb_method_recipes u řádku herb_processing_methods), spirituální a vědecké záznamy, obrázky, bezpečnostní upozornění a volitelné texty lékových interakcí / fotosenzitivity na herbs (viz 12-katalog-a-karta-byliny.md §6). V sekci „Vědecké poznatky“ a „Bezpečnost“ jsou rozbalovací legendy významu štítků (app/components/herb-detail-legends.tsx, slovníček app/lib/claim-labels.ts). Migrace 0023_slug_normalization.sql sjednocuje v D1 textové slugy safety_level, evidence_level, study_type, warning_type a severity (trim + lowercase; synonymum safe u bylin).

6. SEO landing pages a přehledové routy

Přehled sezóny a regionů jako vlastní cesty — viz §1 (/sezona, /region).
Alias /co-sbirat/:month → /sezona/:month (přesměrování).
Alias /byliny-na-zpracovani/:slug → /zpracovani/:slug (301), viz §1.
Další krátké aliasy níže jsou návrh; zatím nejsou routovány.

/byliny-na/:slug
/byliny-v/:region