API a routy

Stav dokumentu: Částečně — veřejné stránky kolem katalogu, zpracování, symptomů/témat, sezóny a regionů jsou implementované; admin a REST /api/* zbývají.

Kontrola zapracování

§1 Veřejné routy — část hotová (viz níže v souboru)
§2 Admin routy
§3 Veřejné REST /api/… (plán); interní údržba POST /__internal/herb-maintenance volitelná přes secret
§4 Filtrování /byliny (q, month, region, pm, topic, topicScope, science, spiritual)
§5 Detail byliny z D1
§6 Přehledové stránky sezóny a regionů (/sezona, /region + detail) — hotové; aliasy SEO typu /co-sbirat/:month / /byliny-v/:region zatím ne

1. Veřejné routy

/
/roadmap
/dokumentace
/dokumentace/:slug
/robots.txt
/sitemap.xml
/byliny
/byliny/:slug
/zpracovani
/zpracovani/:slug
/symptomy
/symptomy/:slug
/sezona
/sezona/:month
/region
/region/:slug
/vyhledavani         (plán)

Implementováno:

/zpracovani a /zpracovani/:slug — katalog způsobů zpracování, odkazy na byliny a /byliny?pm=<slug>. V hlavičce: „Zpracování“.
/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 (např. tradiční / spirituální / vědecký). V hlavičce: „Symptomy“. Migrace se seedem: 0011_herb_topic_links_seed.sql, ukázkové vědecké vazby: 0012_herb_topic_scientific_link_sample.sql, 0013_herb_topic_scientific_expand.sql.
/sezona a /sezona/:month (1–12) — rozcestník měsíců a seznam bylin se stejnou logikou jako /byliny?month=. V hlavičce: „Sezóna“.
/region a /region/:slug — regiony s výskytem publikovaných bylin a stejná logika jako /byliny?region=<slug>. V hlavičce: „Regiony“.

2. Admin routy

Žádná z níže uvedených cest zatím v repu neexistuje.

/admin
/admin/byliny
/admin/byliny/new
/admin/byliny/:id
/admin/studie
/admin/spiritualni-pouziti
/admin/zpracovani
/admin/obrazky
/admin/import
/admin/cache

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
/api/admin/cache-purge
/api/admin/reindex
POST /__internal/herb-maintenance

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&region=cr&pm=caj&pm=tinktura&topic=stres&topicScope=science&science=substantial&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)
`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'`. 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.
`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í, 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-mvp-1.md §6).

6. SEO landing pages a přehledové routy

Přehled sezóny a regionů jako vlastní cesty — viz §1 (/sezona, /region).
Krátké / kanonické aliasy níže jsou návrh; zatím nejsou routovány (můžou později přesměrovat na /byliny?… nebo na stránky z §1).

/byliny-na/:slug
/co-sbirat/:month
/byliny-v/:region
/byliny-na-zpracovani/:slug