# Cleverphant CHANGELOG — consumer upgrade notes

> ## ⚠️ Update naudok `cleverphant:upgrade` — **NE `cleverphant:install`**
>
> `cleverphant:install` yra **DESTRUKTYVUS** (task-34): jis PIRMA išvalo esamą web
> turinį (Pages / News / FAQ / meniu punktus) ir tik tada seeda savo. Pirmam
> diegimui — teisinga; kiekvieno deploy metu — **prarastum per admin redaguotą
> turinį**. Todėl atnaujinimui yra atskira, saugi komanda.
>
> **Standartinis update (VISADA tinka, leidžiamas kiekvieną deploy):**
>
> ```bash
> composer update
> php artisan migrate --force
> php artisan cleverphant:upgrade --force --force-forms   # --force-forms: kai užduotis keitė formos laukus
> php artisan themes:publish-assets
> php artisan vendor:publish --tag=package-assets --force
> php artisan optimize
> ```
>
> `cleverphant:upgrade` yra **idempotentinis ir turinio neliečia**. Jis absorbuoja:
> naujus permission'us (per `cms:sync-permissions`), naujas formų definicijas
> (`firstOrCreate` — per builder'į redaguotų NEperrašo; kai užduotis pakeitė
> ESAMOS formos laukus — pridėk **`--force-forms`**, kad definicija atsinaujintų),
> temos eilutę ir per-aplinkos temų default'us. Migracijas paima atskiras `migrate --force`
> (bėga PRIEŠ upgrade — schema turi egzistuoti anksčiau nei ją liečia seeder'iai).
> Pabaigoje jis atspausdina lentelę su turinio eilučių pokyčiu — sveikame
> pakartotiniame run'e VISI turinio pokyčiai = `0`.
>
> **Žemiau — TIK žingsniai, kurių ta komanda NEabsorbuoja** (turinio seed'as,
> naujas `.env`, Satis rebuild, breaking change). Jei užduoties čia nėra —
> vadinasi, standartinio update pakanka.

---

## 2026-08-26 — tinklaraštis 1:1 iš cleverphant.lt, „Ačiū" reakcija, ∞ ciklo galerija, `/pradeti` forma

**Rankinių žingsnių: DU** (žr. žemiau) — likusi dalis ateina su standartiniu update'u.

### 🔑 Rankiniai žingsniai

```bash
php artisan migrate --force
# ↑ dvi naujos stulpelių migracijos:
#   news_categories.prefixes_article_urls (va-modules/news-categories)
#   news.reactions_count                  (va-modules/news)

php artisan cleverphant:upgrade --force --force-forms --force-news
#   --force-forms : /pradeti forma vėl gauna dizaino UX (suskleidžiama grupė + post-submit apklausa)
#   --force-news  : VIENKARTINIS — pakeičia senus placeholder'inius straipsnius tikrais
```

⚠️ **`--force-news` naudok vieną kartą.** Jis perrašo kiekvieno straipsnio, kurio slug'as
sutampa su seed'intu, antraštę / turinį / slug'ą / datą. Kai instaliacija jau turi tikrus
straipsnius ir redaktorius juos taiso — daugiau šito flago nebejunk.

### Kas pasikeitė

**Tinklaraštis**
- Straipsniai — **1:1 iš cleverphant.lt** (`wp-json/wp/v2/tinklarastis`): tikros antraštės,
  tikri tekstai, tikros publikavimo datos. Anksčiau turinys buvo sugalvotas „brand voice"
  tekstas, todėl per jį buvo neįmanoma pasakyti, ar dizaino problema yra dizaine, ar
  rinkinyje. Paveikslai parsisiųsti į temą (`public/img/blog/`) — niekas nebehotlinkina
  senos svetainės.
- **URL'ai `/tinklarastis/{slug}`**, identiški gyviems. Mechanizmas: nauja „Tinklaraštis"
  konteinerinė kategorija su `prefixes_article_urls` — straipsnio URL sudedamas iš jos kelio.
- **Rikiavimas sutvarkytas.** Buvo „nuo seniausio": seed'intos datos ėjo priešinga tvarka nei
  realios, o kontroleris rikiavo teisingai. Dabar datos tikros.
- Straipsnyje **nebėra datos** ir **nebėra kategorijos** (nei breadcrumb'e, nei filtro chip'ų
  sąraše). Sąraše nebėra ir įžangos pastraipos.
- Naujas **„Ačiū" komponentas** straipsnio pabaigoje — tikras skaitiklis (`news.reactions_count`),
  POST į `web.news.reaction`, viena reakcija per sesiją, throttle 20/min. Veikia be JS
  (mygtukas tiesiog neaktyvus, skaičius matomas).
- Eiliškumas pabaigoje: **Ačiū → CTA → Kiti įrašai → Atgal**; „Atgal" veda į tinklaraštį.
- „Kiti įrašai" nebelieka tuščias: kai straipsnis nieko nesusiejęs rankomis, rodomi 3
  naujausi kiti (`NewsSlugResolver`).

**Puslapiai**
- **Požiūris** — nuimta „Kodėl tęsiame" laiko juosta. Ji priklauso ∞ ciklo puslapiui
  (dizaino šaltinyje yra tik ten), o dubliavimas ciklą darė pasikartojimu.
- **∞ Ciklas** — pridėta trūkusi **„Visi vienodai skirtingi!"** galerija: 3 juostos su
  realiomis mokyklų svetainių ekrano nuotraukomis.
- **/pradeti** — forma pagal dizainą: matomi tik būtini laukai, o „Kada planuojate",
  „Pageidaujama data" ir „Kas jums svarbiausia" suskleisti po **„Norite pasidalinti daugiau?"**;
  „Kaip apie mus sužinojote?" klausiama **po išsiuntimo**, ne formoje. Mygtukas — „Pateikti",
  dizaino navy spalva ir dydis (buvo `--clv-dark`, mažesnis). Puslapis nebeturi naujienlaiškio
  ir CTA juostos (kaip dizaine) — tam layout'e atsirado `bare-footer` sekcija.

**Footeris**
- External-link ikona liko **tik tikroms išorinėms nuorodoms**. Anksčiau CSS selektorius buvo
  `a[href^="https://"]`, o CMS'e ir vidinės nuorodos per `url()` išeina absoliučios — todėl
  ikoną gaudavo visas pirmas stulpelis. Dabar ženklinama `.is-external` klase +
  `target="_blank" rel="noopener"`.

### Bendrinių modulių pokyčiai (ateina kartu)
- `va-modules/news-categories`: `prefixes_article_urls` jungiklis + admino laukas; kategorijos
  pervadinimas/perkėlimas dabar persinchronizuoja ir jos straipsnių URL'us.
- `va-modules/news`: `reactions_count` + reakcijų endpoint'as; „Kiti įrašai" fallback'as.
  **Numatytoji elgsena nesikeičia** — be `prefixes_article_urls` URL'ai lieka ploki.

---

## SystemFindings/task-7 — `cleverphant:upgrade` dabar bėga per `deploy:sync`

**Rankinių žingsnių: NULIS.** Šis įrašas yra tam, kad žinotum, kas pasikeitė deploy'e.

Iki dabar `cleverphant:upgrade` deploy grandinėje **nedalyvavo**: `deploy:sync`
turėjo įrašytus ranka tik Seglo ir Florial žingsnius, o pridėti trečią reikštų
edit'inti `va-core/core` (foundation paketą) — todėl niekas to ir nepadarė, ir
consumer'is upgrade'ą paleisdavo tik per savo Forge skriptą.

Nuo task-7 produktas registruojasi **pats** (`ProductDeployHooks::register()` iš
`ThemeServiceProvider::boot()`), tad `composer sync` / `deploy:sync` dabar bėga:

```
… → db:seed → translations:* → seglo:install → florial:upgrade → cleverphant:upgrade → slugs:rebuild → …
```

- Įrištas **`cleverphant:upgrade --force`**, o **NE `cleverphant:install`** — dėl
  tiksliai tos priežasties, kurią rašo šio failo antraštė. Turinys neliečiamas.
- `--force-forms` **NEperduodamas**: per builder'į redaguota formos definicija
  paliekama ramybėje. Kai užduotis keičia ESAMOS formos laukus — kaip ir anksčiau,
  paleisk `php artisan cleverphant:upgrade --force --force-forms` rankomis.
- Jei tavo deploy skriptas jau kviečia `cleverphant:upgrade` atskirai — palik;
  komanda idempotentinė, dvigubas run'as yra no-op.

---

## PackageStructure Fazės 0–4 — chain'as UŽDARYTAS (išleista `v1.3.1`)

> **Vienas įrašas vietoj dvidešimt penkių.** Žemiau esantys per-task'iniai įrašai
> (`v1.3.0` task-21, `v1.3.1` task-22) lieka — juose yra detalės, kurių ši santrauka
> nepakartoja. Čia — kas išleista, kokia versija ir ką PRIVALAI paleisti.

**Išleistos versijos (Satis jau jas turi):**

| Train | Paketai | Versija |
|---|---|---|
| `cleverphant` | `va-themes/cleverphant` | **`v1.3.1`** |
| `foundation` | `va-core/*`, `va-cross/*`, `va-modules/*`, `va-shop/*`, `va-themes/{protera,viartas-default}` | **`v1.5.2`** |

**Ką chain'as pakeitė Cleverphant pusėje:** „Šablonas" tab'as (`PageTemplateController` +
formos + ekranai + 3 route'ai) persikėlė į **`va-modules/pages`**; mokyklų kortelių
repeteris liko temoje, bet kabinasi per naują `templateEditors()` seam'ą; trys migracijos
iškeliavo į lentelių savininkų paketus; temoje neliko NĖ VIENO route failo ir NĖ VIENOS
migracijos.

### 🔑 VIENINTELIS rankinis žingsnis

```bash
php artisan vendor:publish --tag=package-assets --force
```

Jis JAU stovi dokumentuotame update bloke (žr. viršų). Cleverphant'ui jis reikalingas ne
dėl temos, o dėl **`va-modules/faq`**: iki foundation `v1.5.2` tas paketas deklaravo
`faq-admin.js`, kurio jo paties build'as neišvedė — `/vendor/va-modules/faq/faq-admin.js`
šiame repo atsakydavo **404**. Nuo `v1.5.2` failas realiai build'inamas ir gyvena
`…/faq/assets/faq-admin.js`, bet be publish'o jo host'e nebus.

`vendor:publish --tag=lang --force` šiam chain'ui **NEREIKALINGAS** — ta eilutė deploy
bloke stovi dėl `va-core/translations` 1.1.0.

### 🔑 `va-modules/pages` PRIVALO iškeliauti KARTU su šia tema

Ne rekomendacija. Šioje versijoje tema **nebeturi** nei `PageTemplateController`, nei jo
route'ų, nei `repair_cleverphant_page_templates` migracijos — visa tai gyvena
`va-modules/pages ≥ 1.5.0`. Sena `va-modules/pages` + nauja tema = **„Šablonas" tab'o
nebėra niekur**, o `cleverphant::template-editors.mokyklos-cards` neturi, kas jį
`@includeIf`'intų. Abu paketai yra **skirtinguose train'uose** (`cleverphant` ir
`foundation`), tad lockstep jų negina — gina tik tai, kad `composer update` be
argumentų atnaujina abu. **Nedaryk `composer update va-themes/cleverphant` vieno.**

---

## 2026-08-21 (v1.3.1) — tema nebeturi NĖ VIENOS migracijos

**Standartinio update PAKANKA**, bet **`va-modules/pages` privalo iškeliauti KARTU su šia
tema** — migracija persikėlė ten (žr. įspėjimą apačioje).

`2026_07_02_000001_repair_cleverphant_page_templates` (vienkartinis pasenusių
`pages.template` reikšmių remontas) persikėlė į **`va-modules/pages`**. Priežastis ta pati,
kaip task-21 „Šablonas" tab'o: jis rašo į `pages` lentelę, o tą lentelę — ir joje esantį
`template` stulpelį — sukuria Pages modulis. Tema migracijų neturi (`.claude/module-structure.md` §5).

Failo **VARDAS nepakito** — keitėsi TIK direktorija.

> ### ⚠️ PO `composer update` — PIRMA `migrate:status`, TIK PASKUI `migrate`
>
> ```bash
> php artisan migrate:status | grep -i pending
> ```
>
> Turi būti **tuščia**. Laravel identifikuoja migraciją pagal VARDĄ, ne pagal kelią, tad
> perkeltas failas tavo `migrations` lentelėje jau yra ir pakartotinai NEBĖGS.
>
> **Jei matai „Pending" ties `repair_cleverphant_page_templates` — NEVYKDYK `migrate`.**
> Tai reikštų, kad į tavo instaliaciją atkeliavo failas kitu vardu, ir remontas įvyktų
> antrą kartą. Kreipkis — nevykdyk.
>
> Pati migracija ir po perkėlimo lieka saugi pakartoti (ji liečia tik eilutes, kurių
> `template` vis dar literalus `'default'`, ir dabar dar tikrina, ar `pages.template` bei
> `pages.slug` apskritai egzistuoja), bet ledger'is neturi to prireikti.

**⚠️ Kartu privalo iškeliauti:** `va-modules/pages` (ten dabar gyvena migracija).
Sena Pages versija + nauja tema = migracijos nebeįkelia NIEKAS, ir švariame diegime
`pages.template` remontas neįvyks.

**Nereikia:** `db:seed` · `cleverphant:install` · `npm run build` · `themes:publish-assets`
(seeder'iai, turinys ir asset'ai nepakito).

---

## 2026-08-21 (v1.3.0) — „Šablonas" tab'as persikėlė į `va-modules/pages`

**Standartinio update PAKANKA**, bet **`va-modules/pages`, `va-core/core` ir
`va-core/themes` privalo iškeliauti KARTU su šia tema** (žr. įspėjimą apačioje).

- **`PageTemplateController`, `PageTemplateForm` ir abu admin blade'ai išėjo iš temos.**
  Admin URL'ai, route name'ai, middleware ir HTML **nepakito** — pakito tik tai, kuris
  paketas juos veža. Priežastis: tema negali turėti nei controllerio, nei route'ų
  (`.claude/module-structure.md` §5), o rašomas stulpelis `pages.template_data` visada
  buvo Pages modulio.
- **`Routes/admin.php` ir `Routes/web.php` ištrinti.** `web.php` nuo task-4 neturėjo nė
  vieno route'o. Temoje nebeliko nė vieno route failo.
- **NAUJA — `templateEditors()`.** Mokyklų kortelių repeteris lieka temos, bet dabar
  deklaruojamas registre ir gyvena `cleverphant::template-editors.mokyklos-cards`
  (buvo `cleverphant::pages.admin._cards-repeater`).
- **Vertimai.** `template_tab`, `template_section_page`, `template_section_card`,
  `template_image_hint`, `template_image_search`, `template_image_none` **pašalinti** iš
  `cleverphant::messages` — juos dabar veža `pages::messages` (raktų vardai nepakito).
  `cards_*` ir `template_image_browse` lieka čia, nes juos skaito temos widget'as.

> ⚠️ **JEI OVERRIDE'INAI ŠABLONO TAB'O EKRANĄ — KELIAS PASIKEITĖ.** Iki šiol tai buvo
> `Resources/views/pages/admin/template.blade.php` ŠIOJE temoje. Nuo dabar bazinė versija
> yra `va-modules/pages/Resources/views/admin/template.blade.php`, o override'as toliau
> deda į tą patį `Resources/views/pages/admin/` — skirtumas tas, kad dabar tai TIKRAS
> override'as (§6.1), o iki šiol buvo vienintelė kopija. **Senoje vietoje paliktas failas
> ir toliau veiks kaip override'as — bet jei jo neatnaujinsi, praleisi modulio pataisas.**

> 🚨 **VISI KETURI PAKETAI PRIVALO IŠKELIAUTI KARTU.** Naujas `va-themes/cleverphant`
> (be `Routes/admin.php`) su SENU `va-modules/pages` → „Šablonas" tab'o route'ų nebus
> visai (`admin.pages.template` neegzistuoja) ir tab'o nuoroda krenta. Naujas
> `va-modules/pages` su SENA tema → route'ai užsiregistruotų DU kartus (tas pats
> method+URI, tad antras tiesiog pakeičia pirmą — veikia, bet controlleris ateitų iš
> temos). `va-core/{core,themes}` reikalingi dėl `templateEditors()` seam'o; be jų
> repeteris tyliai nebūtų rodomas (`method_exists` guard'ai — ne klaida, o tyla).

## 2026-08 (v1.2.1) — deploy hotfix

- **`view:cache` deploy fail** („Unable to locate component [edit-layout]"):
  `cleverphant::` VIEW namespace registruotas tik **ne-console** kontekste
  (`! runningInConsole()`). Admin „Šablonas" tab'o views naudoja viartas-default
  runtime komponentą `<x-edit-layout>`, kurio `view:cache` (console, be middleware)
  nemato → eager kompiliacija lūžo. Views renderinami tik per web admin request'us,
  tad console juos praleisti saugu.
- **`forms.created_by` FK fail** deploy metu: formų seeder'iai (contact/lead/newsletter)
  nebe hardcode'ina `created_by/updated_by = 1` → resolve'ina esamą user id
  (`User::query()->min('id')`, nullable FK). Consumer'iuose, kur admin ≠ id 1,
  nebekrenta.

## 2026-08 — formos per form-builder + naujienlaiškio admin + šriftai

**Reikalauja rankinių žingsnių** (standartinis update jų NEabsorbuoja pilnai):

- **Formų definicijos pakeistos** → `cleverphant:upgrade --force --force-forms`.
  Kontaktų + lead (`susipazinkime`) formos perdarytos į cleverphant.lt atitikmenį:
  10 matomų laukų, `Kada` + `Kaip apie mus sužinojote?` radio'ai; **NUIMTA**
  collapsible „Norite pasidalinti daugiau?", sąlyginis `kita_data`, `poreikis`,
  post-submit apklausa. BE `--force-forms` esamos formos lieka su sena definicija.
- **Naujienlaiškio admin punktas** → `php artisan migrate --force`.
  Nauja migracija įdeda „Prenumeratoriai" (`/admin/newsletter` — sąrašas + CSV
  eksportas) į admin sidebar DB meniu (sekcija „Turinio valdymas"). Modulis egzistavo
  seniai — tik nebuvo DB meniu, kai `MENUS_DB_DRIVEN=true`.

**Absorbuojama standartiniu update (`composer update` + publish):**

- Viešos formos renderinamos per `va-core/form-builder` (native 2-stulpeliai
  `col-md-6`, `input_type` email/url/date). Reikia naujų `va-core/form-builder`
  + `va-modules/forms` versijų.
- Notifikacijos laiškas `forms::mail.submission` → HTML (buvo raw Markdown);
  radio/select reikšmės rodomos žmogiškais label'ais.
- Self-host Inter 3.019 TTF + Cleverphant favicon → `themes:publish-assets`
  (kopijuoja `public/fonts` + `public/img`).
- Mokyklos šablono kortelių repeteris admin „Šablonas" tab'e.

## QA #8 — meniu iš realių puslapių

- `CleverphantMenusSeeder` (įrištas į `cleverphant:install`) perseed'ina `web.main` iš
  realių Cleverphant puslapių (Pradžia/Mokyklos/Požiūris/∞ ciklas/DUK/Tinklaraštis/
  Kontaktai) ir **numeta** generinio shop `web.brands` — `/admin/menus` rodo tik
  Cleverphant nav.
- Front nav DB-redaguojamas su `.env` `MENUS_DB_DRIVEN=true`; be jo — hardcoded (0 regresijos).
- **Update'e** (NE pilnas install): meniu perseed'ink saugiai, be turinio wipe —
  `php artisan db:seed --class="ViartasThemes\Cleverphant\Database\Seeders\CleverphantMenusSeeder" --force`.

## QA #9 — CKEditor WYSIWYG turinio laukas

- `form-builder` dabar deklaruoja `va-core/ckeditor` → puslapio „Turinys" laukas rodo
  CKEditor įrankių juostą (ne plika textarea su raw HTML). Ateina per `composer update`,
  assets per `vendor:publish --tag=package-assets` (į `public/vendor/ckeditor`). Jei
  `composer update` meta „va-core/ckeditor not found" → trūksta Satis'e (kaip form-builder).

## Turinio atnaujinimas (kai jo tikrai reikia)

`cleverphant:upgrade` **niekada** neseeda Pages / News / FAQ. Jei užduotis atvežė
naujo turinio (arba diegi tuščią saitą), rinkis sąmoningai:

| Komanda | Ką daro | Kada |
|---|---|---|
| `cleverphant:install --additive --force` | **Nedestruktyvi.** Seeda TIK trūkstamas eilutes (`firstOrCreate`), esamų neliečia. | Turinio „papildymas" gyvame saite |
| `cleverphant:install --force` | **DESTRUKTYVI.** Išvalo ne-Cleverphant web turinį ir seeda iš naujo. | Pirmas diegimas / sąmoningas reset'as |
| `cleverphant:seed-pages --force` | Perrašo 9 Cleverphant puslapių eilutes (id išsaugomas). | Kai reikia atstatyti puslapių kanoninį turinį |

⚠️ `--force` prie `cleverphant:install` reiškia DU dalykus: praleidžia destruktyvų
patvirtinimą IR perrašo slug'ą atitinkančias FAQ/News/formų eilutes. Su
`--additive` jis lieka nedestruktyvus turiniui, kurio dar nėra, bet **perrašo**
esamas FAQ/News/formų eilutes — jei to nenori, leisk be `--force`
(reikės atsakyti į patvirtinimą interaktyviai).

---

## task-44 — `cleverphant:upgrade` + deploy un-gate

- **Vienkartinis:** atnaujink Forge deploy skriptą pagal [`INSTALL.md`](INSTALL.md)
  („Forge / production deploy"). Anksčiau `cleverphant:install` buvo **marker-gated**
  (`if [ ! -f storage/app/.viartas-installed ]`) → bėgo TIK pirmą kartą, todėl
  vėlesnės užduotys (nauji permission'ai, formų definicijos, temos eilutė)
  consumer'io nepasiekdavo. Dabar `cleverphant:upgrade --force` paleidžiamas
  **kiekvieną deploy**, o marker'is dengia tik tikrą first-time bootstrap'ą
  (`CmsBootSeeder` + `cleverphant:install`).
- Marker'io trinti NEREIKIA — jis toliau teisingai saugo pirmojo karto seed'ą
  (ir, svarbiausia, neleidžia destruktyviam install'ui pasikartoti).

## task-43 — naujienlaiškis per Forms builder'į

- **Absorbuojama** `cleverphant:upgrade` (`newsletter` formos definicija seed'inama
  `firstOrCreate`). Kol ji neužseed'inta, footer'io blokas veikia per seną tiesioginį
  POST — prenumeruoja, tik apeina builder'į.
- **Vienkartinis (assets):** `php artisan themes:publish-assets` — be jo naršyklė
  gauna seną `cleverphant.js` bundle'ą ir inline success eilutė nepasirodo.
  (Standartiniame update jis jau yra.)

## task-41 / task-42 — `/pradeti` + `/kontaktai` formos

- **Absorbuojama** `cleverphant:upgrade` (`susipazinkime` + `kontaktai` definicijos).
- ⚠️ Jei definicijos JAU egzistuoja ir nori naujausios task-42 versijos
  (`url` laukas, suskleidžiama grupė, po-submit klausimas), reikia **force** refresh'o —
  upgrade jo sąmoningai nedaro (neperrašinėja per builder'į redaguoto turinio):
  ```bash
  php artisan tinker --execute="app(\ViartasThemes\Cleverphant\Database\Seeders\CleverphantContactFormSeeder::class)->force()->run();"
  ```

## task-36 — Cleverphant = default web tema

- **Absorbuojama** `cleverphant:upgrade` (temos eilutė + `cleverphant:activate` +
  `themes:sync-defaults`). Rankinio `UPDATE themes` nebereikia.
