Nasazení a vývoj

Tato příručka popisuje proces vývoje, buildování a nasazení UpSearch Plugin.

Vývojové prostředí

Požadavky

• Node.js 14.19.3 (doporučeno použít Volta)
• npm

Environment proměnné

Vytvořte soubor .env v kořenu projektu:

API_TOKEN=vas_api_token           # Token pro přístup k UpSearch API
POEDITOR_TOKEN=poeditor_token     # Token pro POEditor (překlady)
POEDITOR_PROJECT_ID=project_id    # ID projektu v POEditor

info

Tyto proměnné jsou potřeba pouze pro vývoj, ne pro produkční build.

Instalace závislostí

npm install

Spuštění dev serveru

npm run dev

Otevře se vývojový server na http://localhost:8080/ s demo stránkami.

Spuštění Storybook

npm run storybook

Storybook s UI komponentami běží na http://localhost:6006/.

Build

Produkční build

npm run build

Vytvoří produkční build ve složce build/:

• upSearchSuggest.js - Komponenta našeptávače
• upSearchResults.js - Komponenta výsledků
• upsearch.css - Styly
• storybook/ - Storybook dokumentace

Pouze aplikace (bez Storybook)

npm run build-app

Build s ZIP archivem

npm run dist

Git Workflow

Větve

• master - Hlavní větev se stabilní verzí scriptu
• subdomena_domena_koncovka - Zákaznické větve (např. www_fotoskoda_cz)

Vytvoření zákaznické verze

1. Vytvořte novou branch z master větve:

   git checkout master
   git checkout -b www_nazev_domeny_cz

2. Upravte deploy properties (testing.properties a production.properties):

   # testing.properties
   remote.dir=/data/www/cdn2.upsearch.cz/projects/www_nazev_domeny_cz/
   
   # production.properties
   remote.dir=/data/www/cdn.upsearch.cz/projects/www_nazev_domeny_cz/

3. Vytvořte deploy projekty v PHPCI na https://deploy3.praguebest.cz/:

   • Admin options → Add Project
   • Typ: GitLab
   • URL: git@gitlab.praguebest.cz:internal/upsearch-plugin.git
   • Název: např. UpSearch Plugin - NazevKlienta - testing/production
   • PHPCI config: zkopírujte z phpCiConfigTesting.yml nebo phpCiConfigProduction.yml
   • Branch: název vaší branch
   • Skupina: UpSearch

4. Nastavte webhooky v GitLab (Settings → Webhooks):

   • URL: https://deploy3.praguebest.cz/webhook/gitlab/<project_id>
   • Testing: Trigger = Push events, Branch = vaše branch
   • Produkce: Trigger = Tag push events

5. Vytvořte složku na serveru v projects/ (např. www_nazev_domeny_cz)

Deploy

Testing

Push do branch automaticky spustí deploy na testing CDN:

git push origin www_nazev_domeny_cz

Výsledek bude dostupný na: https://cdn2.upsearch.cz/projects/www_nazev_domeny_cz/

Produkce

Tag push spustí deploy na produkční CDN:

# Formát tagu: <branch_name>/<tag_name>
git tag www_nazev_domeny_cz/v1.0.0
git push origin www_nazev_domeny_cz/v1.0.0

Výsledek bude dostupný na: https://cdn.upsearch.cz/projects/www_nazev_domeny_cz/

Pojmenování tagů

Název tagu musí mít formát <branch_name>/<tag_name>, např.:

• master/v1.0.1
• www_fotoskoda_cz/v1.0.1

Lokalizace

Přidání nového textu

1. Použijte FormattedMessage nebo formatMessage v kódu:

   <FormattedMessage
     defaultMessage="Hledat..."
     description="Placeholder pro vyhledávací pole"
   />

2. Extrahujte texty:

   npm run trans:extract

3. Nahrajte do POEditor a přeložte

4. Stáhněte překlady a zkompilujte:

   npm run trans:download
   npm run trans:compile

Přidání nového jazyka

1. Přidejte JSON soubor do src/app/i18n/translated/
2. Spusťte kompilaci: npm run trans:compile
3. Přidejte jazyk do src/app/i18n/translations.ts

API

Frontend komunikuje s backendem přes REST API (https://api.upsearch.cz).

Generování API klienta

API klient je generovaný z OpenAPI specifikace:

npm run generate-api

Výstup je v src/app/api/client-generated/.

Skripty

Skript	Popis
npm run dev	Spustí dev server
npm run build	Vytvoří produkční build
npm run build-app	Build pouze aplikace
npm run storybook	Spustí Storybook
npm run lint	Spustí ESLint
npm run format	Formátuje kód pomocí Prettier
npm run trans:extract	Extrahuje texty pro překlad
npm run trans:compile	Zkompiluje překlady
npm run generate-api	Vygeneruje API klienta