← Zpět k uživatelské příručce

Technická dokumentace

Technická Dokumentace

Daniely Uploader — co aplikace dělá a jak funguje

K čemu je to dobré

Slouží k práci s produkty pro e-shop (typicky Shoptet): máte data ve struktuře JSON, potřebujete je vyexportovat do CSV ve stejném formátu, jaký používá váš import nebo konverzní služba.
Ukládá produkty lokálně do SQLite databáze na vašem počítači — nic nemusí „běžet v cloudu“, pokud nechcete.
Nabízí jednoduché webové rozhraní (v prohlížeči): přehled produktů, založení nového produktu, nastavení, skladové prefixy.

Hlavní části aplikace

Přehled produktů (dashboard)

Vidíte dva seznamy: Nové produkty a Archiv — abyste si uklizené rozlišili, co ještě aktivně řešíte, a co už máte „odbyté“.
U každého řádku je kód, název, datum vytvoření; vnitřní ID je schované v nenápadném tooltipu (najetí myší).
Můžete označit řádky a:
stáhnout CSV jen pro vybrané,
archivovat vybrané z „Nových“,
vrátit z archivu vybrané z archivu.
Po úspěšném stažení CSV z přehledu aplikace automaticky přesune odpovídající produkty do archivu (nemusíte na to znovu klikat).
Tabulky jsou stránkované (např. po 25 položkách), aby se dlouhé seznamy dobře četly.
Odkaz „otevřít“ vede na detail produktu v JSON podobě (spíš pro pokročilé / napojení).

Nový produkt

Formulář vychází ze šablony polí podle vašeho vzorového JSONu — takže struktura odpovídá tomu, co pak půjde do CSV / do obchodu.
Nejdřív vyberete typ ze skladu (prefix) — aplikace z něj vygeneruje produktový kód ve tvaru PREFIX-00001 (čísla jdou v databázi za sebou pro každý prefix).
Kalkulátor ceny: zadáte obvykle nákupní cenu a hodiny práce; z nastavení (mzda, přirážky, sleva) se dopočítají prodejní / akční ceny a max. sleva — nemusíte to počítat ručně.
Jsou tam přepínače pro akční a tip štítek (zapnuto = uloží se aktivní stav a datum platnosti).
Rozměry balíku mají výchozí hodnoty a kontrolu proti pravidlům „standardní zásilky“ (limity dopravce v cm).
Můžete nahrát obrázky na FTP (pokud máte v .env nastavené přihlašovací údaje) — doplní se URL do polí obrázků.
Volitelně můžete nechat vygenerovat texty přes AI (OpenAI klíč v .env) do popisů a SEO polí.
Zbytek polí je v sekci „Ostatní hodnoty“, aby hlavní obrazovka nebyla přeplněná.
Část polí je jen ke čtení ve formuláři — buď se počítá z kalkulačky, nebo je při uložení doplní nebo přepíše globální nastavení (např. texty dostupnosti, kategorie, jednotky pcs). To je záměr: jednotný obchodní rámec.

Sklad (warehouse)

Ukládáte prefixy (např. typ zboží / skladová řada), podle kterých se generují unikátní kódy produktů.
Prefixy jsou normalizované (velká písmena, povolené znaky) — méně chyb při importu.

Nastavení

Globální údaje pro kalkulátor (mzdy, přirážky, počáteční sleva).
Výchozí datumy (kolik dní dopředu se předvyplní u akcí / novinek).
Texty dostupnosti a výchozí kategorie pro nové produkty.
URL obchodu — základ pro skládání veřejných odkazů k obrázkům po nahrání na FTP.

Data a soubory

Produkty leží v SQLite (soubor databáze v projektu, typicky ve složce data).
Každý produkt má JSON blob se všemi poli pro export; archiv je jen příznak v databázi — data se nemazala, jen se řádek přesune v přehledu.
CSV export odpovídá logice „hlavička + řádky“ jako u konverzního endpointu (oddělovač středník).

API (stručně)

Kromě stránek v prohlížeči existují REST endpointy: uložení produktu, export CSV, archivace, seznam produktů, konverze JSON → CSV atd.
To umožňuje v budoucnu napojit skripty nebo jiné nástroje — ale pro běžnou práci stačí webové rozhraní.

Co aplikace není

Není to plnohodnotný e-shop ani administrace Shoptetu — je to nástroj na přípravu a export dat a lokální evidenci produktů podle vaší šablony.
Nepřihlašuje uživatele — počítá se s tím, že ji spouštíte sami na důvěryhodném počítači / serveru.

Tento text má čtenáři rychle vysvětlit smysl a tok práce; technické názvy polí a mapování UI → JSON najdete v dokumentu k mapování polí formuláře.

Technická dokumentace:

Nový produkt — mapování polí (UI → JSON / CSV / databáze)

Základní pravidla

Klíče v exportu (CSV) a v uloženém JSON jsou anglické (odpovídají polím ve Shoptet feedu / šabloně output_example.json).
Ve formuláři se u většiny polí zobrazuje český popisek; technický název pole je v atributu data-key u inputu (stejný jako klíč v JSON).
V SQLite tabulce products je:
sloupec §H0§ — celý objekt produktu jako JSON (všechny tyto klíče),
sloupec §H0§ — kopie kódu z JSON (code) pro rychlé vyhledávání,
sloupce §H0§, §H1§, §H2§, §H3§ — správa záznamu (do CSV z exportu produktu jako takové není hlavička „archived“, export jde z těla data).

Jediné pole bez klíče v JSON: při uložení z webu se posílá §H0§ (prefix ze skladu). Do databáze se neukládá — server z něj vygeneruje §H1§ (PREFIX-00001) a ten už je v JSON.

Český popisek ↔ klíč JSON (kompletní mapa ve formuláři)

Popisek v UI (cs)	Klíč JSON / CSV
Kód	`code`
Párový kód	`pairCode` (včetně mezery na konci — historický klíč ve vzoru)
Název	`name`
Krátký popis	`shortDescription`
Popis	`description`
Meta popis	`metaDescription`
Výchozí obrázek	`defaultImage`
Obrázek 1 (URL) … 7	`image`, `image2` … `image7`
Výchozí kategorie	`defaultCategory`
Cena	`price`
Standardní cena	`standardPrice`
Nákupní cena	`purchasePrice`
Akční cena	`actionPrice`
Akce do	`actionUntil`
Max. sleva (%)	`maxDiscount`
Sklad	`stock`
Dostupnost skladem	`availabilityInStock`
Dostupnost při vyprodání	`availabilityOutOfStock`
Hmotnost (kg)	`weight`
Výška / Hloubka / Šířka (cm)	`height`, `depth`, `width`
Související produkt … 4	`relatedProduct` … `relatedProduct4`
Alternativní produkt	`alternativeProduct`
Akční štítek — aktivní / platí do	`actionFlagActive`, `actionFlagValidUntil` (UI: přepínač + skrytá pole)
Tip štítek — aktivní / platí do	`tipFlagActive`, `tipFlagValidUntil`
Novinka — aktivní / platí do	`newFlagActive`, `newFlagValidUntil`
SEO titulek	`seoTitle`
Množství v balení	`packageAmount`
Měřené množství	`measureAmount`
Jednotka měř. množství	`measureAmountUnit`
Jednotka balení	`packageAmountUnit`

Pokud ve schématu přibude nový klíč z output_example.json a nemá řádek v tabulce výše, ve formuláři se zobrazí technický název klíče (nahrazení mezer podtržítkem).

Speciální bloky (nejsou běžné `data-key` řádky)

UI blok	Vazba na data
Sklad → Typ produktu	Výběr prefixu; při uložení: `warehousePrefix` v POST. Server doplní §H1§. Náhled `code` v poli Kód (`field-code`); lze upravit (FTP).
Nákupní cena (výpočet) / Odpracované hodiny	Pomocné vstupy nejsou v JSON. Počítají se z nich §H0§, §H1§, §H2§, §H3§, §H4§ (viz níže).
Akční štítek / Tip štítek	Přepínač: vypnuto → `actionFlagActive` / `tipFlagActive` prázdné + datum prázdné. Zapnuto → skryté `…Active` = `1`, datum v `…ValidUntil`.
Obrázky (FTP)	Používá §H0§ pro složku na FTP; URL se mohou propsat do `image`…
AI generování	Vyplní `shortDescription`, `description`, `metaDescription`, `seoTitle` (podle odpovědi API).

Pořadí na obrazovce (zjednodušeně)

Sklad (prefix)
Název
Kalkulátor (nákup + hodiny) → doplní cenová pole
Akční štítek, Tip štítek
Množství v balení, Sklad, Hmotnost
Rozměry (height, depth, width) + kontrola zásilky
Obrázky, AI
Accordion Ostatní hodnoty — zbývající klíče ze schématu + na konci měření/jednotky dle formTailKeys

Uvnitř accordionu je pořadí řádků dáno seznamem klíčů ve schématu s výjimkou už vykreslených polí (viz kód: preferredOrder, formPrimaryTopKeys, formTailKeys).

Která pole jsou jen pro čtení ve formuláři (přesto mají klíč v JSON)

Tyto inputy mají readonly — uživatel je nemění přímo, hodnoty se počítají nebo přepisují (část při uložení na serveru):

Klíč	Proč
`price`, `purchasePrice`, `standardPrice`, `actionPrice`, `maxDiscount`	Z kalkulátoru (vzorce z Nastavení). `maxDiscount` se znovu dopočítá i na serveru z `price` a `purchasePrice`.
`availabilityInStock`, `availabilityOutOfStock`	Při uložení se nahradí texty z Globální nastavení.
`defaultCategory`	Při uložení se nahradí kategorií z nastavení.
`measureAmount`, `measureAmountUnit`, `packageAmountUnit`	Při uložení vynuceno: `measureAmount` = `1`, jednotky = `pcs`.
`newFlagActive`	Při uložení vynuceno na `1` (řetězec).

Editovatelné mimo jiné: name, texty popisů, stock, weight, rozměry, packageAmount, code (po generování), příznaky akce/tip (přepínačem), newFlagValidUntil, actionUntil, související kódy, obrázky atd.

Vzorce kalkulátoru ceny (soulad UI ↔ uložená čísla)

Z Nastavení se berou: hourlyWage, hourlyWageMultiplicator, marginMultiplicator, initialSale.

§H0§ = nákup × marginMultiplicator + hodiny × hourlyWage × hourlyWageMultiplicator
§H0§ = nákup + hodiny × hourlyWage
§H0§ = stejné jako price
§H0§ = price × initialSale
§H0§ = \((price - purchasePrice) / price × 100\) (2 des. místa; při price ≈ 0 prázdné)

(Nákup a hodiny = pole „Nákupní cena (výpočet)“ a „Odpracované hodiny“ — nejsou v JSON.)

Úpravy při uložení nového produktu (server)

Po sestavení těla z formuláře se v tomto pořadí aplikuje mimo jiné:

§H0§ — přepočet maxDiscount z price a purchasePrice.
§H0§ — přepsání availabilityInStock / availabilityOutOfStock.
§H0§ — přepsání defaultCategory.
§H0§, §H1§, §H2§, §H3§ — jednotky pcs, measureAmount = 1, packageAmount normalizováno (≥ 1, jinak 1).
§H0§ — doplnění actionUntil, pokud chybí.
§H0§ — newFlagActive = 1.
Přidělení §H0§ z vybraného prefixu skladu (pokud jde o webové uložení).

Související produkty (`relatedProduct` …)

Po výběru prefixu ve skladu může klient načíst poslední kódy a předvyplnit relatedProduct–relatedProduct4. Uživatel může hodnoty změnit; klíče v JSON zůstávají stejné.

Tento dokument popisuje stav aplikace Daniely Uploader (formulář Nový produkt, SQLite, export CSV z objektu §H0§). Při změně šablony §H1§ se může seznam klíčů ve formuláři rozšířit.