ReČeK — Workflow: založení titulu a produktu z GUI (modul Agentura)

1 Otevření formuláře — načtení číselníků (ONIX & ostatní)

Když uživatel otevře formulář nového titulu/produktu, GUI si nejdřív načte data pro našeptávače a rozbalovací seznamy. Nic se nezakládá — jsou to čtecí (GET) volání, která naplní pole formuláře: role autorů, forma produktu, typ obsahu, stav vydání (vše z ONIX číselníků), dále vydavatele a osoby.

ONIX číselníky pro rozbalovací pole

Číselník = OnixCodetable (např. List 17 – role kontributora, List 150 – forma produktu, List 81 – typ obsahu, List 64 – stav vydání). Konkrétní hodnoty = OnixCodetableItem. GUI načte položky daného číselníku a nabídne je ve výběru; do titulu/produktu se pak ukládá jen id zvolené položky.

GET/onix-codetables GET/onix-codetable-items?query=…

Pole ve formuláři	ONIX číselník	Kam se uloží
Role autora	List 17 – Contributor role	`titleContributions[].roles[].role`
Forma produktu	List 150 – Product form	`product.form`
Typ obsahu	List 81 – Content type	`product.primaryContentType`
Stav vydání	List 64 – Publishing status	`product.publishingStatus`

Vydavatel a osoby pro našeptávače

Pole	Endpoint	Účel
Vydavatel (owner)	GET/agency-publishers/search	Výběr vlastníka titulu
Autor (osoba)	GET/persons · GET/persons/search-options	Našeptávač autorů

2 Přidání autora / kontributora

Autor není volný text — je to osoba (fyzická nebo právnická). Uživatel ho ve formuláři buď vybere z našeptávače (data z kroku 1), nebo — pokud neexistuje — rovnou založí novou osobu. Přiřazení k titulu se pak uloží jako součást těla titulu v poli titleContributions[] (krok 3).

Vybrat existující osobu

Z našeptávače — /persons / /persons/search-options (načteno v kroku 1). GUI si drží zvolené person.id.
Nebo založit novou osobu přímo z formuláře

Fyzická osoba (autor-člověk) nebo právnická osoba (korporace/instituce jako původce). Vrací id, které se použije v kontribuci.

POST/natural-persons POST/legal-persons
Zvolit roli (z ONIX List 17) a pořadí

Role se vybírá z číselníku načteného v kroku 1; ukládá se jako OnixCodetableItem. Kontributor se neposílá samostatně — je součástí těla titulu.

Struktura kontributora v těle titulu

// TitleDto.titleContributions[]
{
  "person": { "id": "<id z /natural-persons | /legal-persons>" },
  "sequenceNumber": 1,
  "roles": [
    { "role": { "id": "<OnixCodetableItem, List 17 – např. A01 autor>" } }
  ]
}

Doplňková pole: firstName / lastName / name (denormalizovaný zápis), biographicalNote, unnamedPerson (nejmenovaný přispěvatel jako ONIX kód).

Změnu údajů o už existující osobě lze nahlásit agentuře přes POST/natural-persons/report-change / POST/legal-persons/report-change.

3 Uložení titulu

Po vyplnění formuláře GUI uloží titul jedním voláním. Titul patří vydavateli (ownerId z kroku 1) a nese autory (titleContributions z kroku 2), názvy, jazyky a témata.

Vytvořit titul

V těle ownerId, names[], languages[], subjects[] a titleContributions[]. Odpověď obsahuje id nového titulu.

POST/titles
Případná úprava titulu

Optimistický zámek — v těle posílejte aktuální version.

PUT/titles/{id} GET/titles/{id}

4 Uložení produktu k titulu

Produkt je konkrétní vydání/forma titulu (tištěná kniha, e-kniha, audio…). Odkazuje na titul (title.id z kroku 3) a nese ONIX atributy z číselníků: forma (form), typ obsahu (primaryContentType), stav vydání (publishingStatus), rozsah, cena. GUI má dvě cesty:

Cesta A — nejdřív jen produkt, číslo zvlášť

POST/products — produkt vznikne bez čísla; ISBN/ISMN přidělíte samostatně v kroku 5.

Cesta B — uložit produkt a rovnou přidělit číslo (doporučeno pro GUI)

POST/products/create-with-number — jedním voláním založí produkt a pokusí se přidělit číslo.

Tělo ProductCreateWithNumberRequest: product, assignProductNumber=true, volitelně publisherPrefixId (konkrétní prefix z feasibility) a magnitude (velikost bloku pro nový prefix: 1 = 10, 2 = 100, 3 = 1000 čísel).

Klíčové chování: produkt se uloží vždy. Když přidělení čísla vyžaduje rozhodnutí uživatele (vytvořit nový prefix) nebo selže obchodní podmínka, odpověď vrátí productNumber: null a needsPublisherPrefix: true — produkt zůstává uložený, číslo se dořeší krokem 5.

5 Přidělení čísla produktu (ISBN / ISMN)

Ruční přidělení má tři fáze: ověření proveditelnosti → náhled → přidělení. Feasibility lze volat i před vznikem produktu (jen z titulu), takže GUI dopředu ví, zda a z jakého prefixu jde číslo přidělit, a podle toho zobrazí volby ve formuláři produktu.

Ověřit proveditelnost (feasibility)

Jen z titleId. Řekne, zda lze přidělit, případně proč ne, a nabídne prefixy k výběru (prefixes[]) nebo příznak needsNewPrefix.

GET/product-numbers/assign/feasibility/{titleId}
Náhled přidělení (preview)

Ukáže konkrétní hodnotu, kterou by systém přidělil (agenturní + vydavatelský prefix + pořadové číslo), bez zápisu.

POST/product-numbers/assign/preview GET/product-numbers/assign/{productId}/by-product-id
Přidělit číslo (commit)

Zapíše číslo k produktu. Tělo ProductNumberAssignRequest: productId, publisherId (povinné), volitelně publisherPrefixId / agencyPrefixId / productNumberId, případně magnitude pro nový prefix.

POST/product-numbers/assign

Proč přidělení selže — kódy `reason` z feasibility

Reason	Význam
PUBLISHER_CLOSED	Vydavatel titulu je uzavřený.
DATA_NOT_CONFIRMED	Potvrzení dat garantem chybí nebo je starší než 1 rok.
NO_AGENCY_PREFIX	Pro registrační agenturu není nastaven agenturní prefix.
NO_AVAILABLE_NUMBERS	Aktivní prefix vydavatele nemá volná čísla.

needsNewPrefix = true (při canAssign = true): přidělit lze, ale je potřeba založit nový vydavatelský prefix — uživatel zvolí velikost bloku (magnitude). Jinak feasibility vrátí prefixes[] s volbami (každá má publisherPrefixId + čitelný label jako 978-80-7702).

Doplňkové operace nad čísly

Akce	Endpoint
Čísla přiřazená titulu	GET/product-numbers/by-title/{titleId}
Zrušit výběr čísla	POST/product-numbers/{id}/deselect
Blokovat / odblokovat číslo	PUT/product-numbers/{id}/block · PUT/product-numbers/{id}/unblock

6 Zviditelnění produktu ve veřejném katalogu

Produkt je po uložení defaultně privátní. Zveřejnění je změna dostupnosti na PUBLIC. Veřejný katalog čte z indexu (Solr), takže po hromadnějších změnách je vhodné spustit přeindexaci.

Nastavit dostupnost produktu na PUBLIC

Tělo ProductAccessibilityRequest: { "accessibility": "PUBLIC" } (hodnoty PUBLIC / PRIVATE). Po zveřejnění se plní publicTime.

PATCH/products/{id}/accessibility
(Volitelně) přeindexovat veřejný katalog

Admin operace pro obnovu vyhledávacího indexu.

POST/reindex
Ověřit ve veřejném pohledu

Veřejné čtení titulů, vydavatelů a autorů.

GET/titles/search GET/titles/{id}

Do veřejného katalogu se produkt dostane jen tehdy, když má přidělené číslo (krok 5) a dostupnost PUBLIC.

Stavový diagram celého toku

Cesta ručního založení jednoho titulu a produktu z GUI — od načtení číselníků po zveřejnění, včetně rozhodovacích uzlů u přidělení čísla.

číselníky / entity produkt & číslo ověření / rozhodnutí blokující stav zveřejněno

Přehled endpointů podle pořadí

#	Metoda	Cesta	Účel
1	GET	`/onix-codetables` · `/onix-codetable-items`	Hodnoty do rozbalovacích polí (role, forma, obsah, stav)
1	GET	`/agency-publishers/search`	Našeptávač vydavatele (owner)
1	GET	`/persons` · `/persons/search-options`	Našeptávač autora
2	POST	`/natural-persons` · `/legal-persons`	Založení nové osoby (autora)
3	POST	`/titles`	Uložení titulu (+ `titleContributions[]`)
4	POST	`/products`	Uložení produktu bez čísla
4+5	POST	`/products/create-with-number`	Produkt + přidělení čísla jedním voláním
5a	GET	`/product-numbers/assign/feasibility/{titleId}`	Ověření proveditelnosti
5b	POST	`/product-numbers/assign/preview`	Náhled přiděleného čísla
5b	POST	`/product-numbers/assign`	Přidělení ISBN/ISMN
6	PATCH	`/products/{id}/accessibility`	Zveřejnění (PUBLIC)
6	POST	`/reindex`	Přeindexace veřejného katalogu