# Cleverphant consumer install — užduotis Claude'ui

**Kontekstas:**
- Esi aplanke `/Applications/XAMPP/xamppfiles/htdocs/cleverphant` (macOS + XAMPP).
- Kuriame **atskirą consumer instaliaciją** cleverphant.lt saito — tai **web tema virš standartinio CMS**
  (Pages override + News blog + FAQ + /kontaktai forma). Kodas iš privataus **Satis** Composer repo.
- **NEREIKIA:** `va-seglo/*`, `va-florial/*` — jų NEinstaliuok.
- Node/npm **nereikia** — temos assets ateina pre-built.

> ⚠️ Skirtingai nuo Seglo/Florial, Cleverphant yra CMS **tema**, ne savarankiškas produktas.
> Jos seederiai naudoja Pages / News / NewsCategories / Menus / Faq / Forms modulius — todėl juos BŪTINA įdiegti.

---

## Žingsniai

### 1. Host skeleton (jei aplankas tuščias)

```bash
composer create-project laravel/laravel .
```

### 2. composer.json — pridėk root lygyje

```jsonc
"minimum-stability": "dev",
"prefer-stable": true,
"repositories": [
    { "type": "composer", "url": "https://satis.viartas.com/" }
],
```

### 3. Require paketus

```bash
composer require \
  va-core/core va-core/auth va-core/users va-core/translations \
  va-modules/pages va-modules/news va-modules/menus va-modules/custom-links \
  va-modules/faq va-modules/forms \
  va-themes/viartas-default \
  va-themes/cleverphant
```

**Kas ką duoda:**
- `va-core/core` — bazinė infra + admin aplinka (`/admin`)
- `va-core/auth` — login (**būtinas**)
- `va-core/users` — users + roles
- `va-core/translations` — vertimų UI
- `va-modules/pages` — CMS puslapiai (Cleverphant juos override'ina; traukia `va-modules/grid-builder`)
- **Ateina per `va-core/core`:** `va-core/module-manager` + `va-cross/{media,seo,geo,microdata,cms-badges,logs}` (nebereikia vardyti)
- `va-modules/news` (+ `news-categories` automatiškai) — News blog'as
- `va-modules/menus` — meniu (Cleverphant seeder'is tvarko meniu punktus)
- `va-modules/faq`, `va-modules/forms` — DUK + /kontaktai forma
- `va-themes/viartas-default` — **admin tema** (kad `/admin` renderintųsi)
- `va-themes/cleverphant` — pati Cleverphant web tema

**Neįtraukta sąmoningai:** `va-seglo/*`, `va-florial/*`.

> ℹ️ `va-modules/{pages,news,menus,custom-links,faq,forms}` dabar yra **`va-themes/cleverphant` HARD priklausomybės** (jos naudojamos temos seederiuose/provider'iuose be guard'ų) — t.y. `composer require va-themes/cleverphant` juos traukia **savaime**. Aukščiau jie išvardyti aiškumui; jei kada nors norėtum minimalaus require, užtenka `va-core/{auth,users,translations} va-themes/{viartas-default,cleverphant}`.

Provideriai registruojasi per Laravel auto-discovery — `bootstrap/providers.php` **neliesk**.

### 4. .env

```env
APP_NAME=Cleverphant
APP_URL=http://cleverphant.test
# LT svetainė — valdo cms.default_locale (env('APP_LOCALE','lt')). NE 'en'!
APP_LOCALE=lt
APP_FALLBACK_LOCALE=lt

DB_DATABASE=cleverphant
DB_USERNAME=root
DB_PASSWORD=

# PRIVALOMA: User modelis gyvena va-core/users pakete (NĖRA App\Models\User CMS
# funkcijoms). Be šito Spatie guard resolvinasi tuščias → seed'as krenta su
# „GuardDoesNotMatch: should use guard `` instead of `web`". Dvigubi \\ — .env
# escape (→ vienas \).
AUTH_MODEL="ViartasCore\\Users\\Models\\User"

# Cleverphant nav + admin meniu iš DB (be šito nav nerodo).
MENUS_DB_DRIVEN=true
```

> ⚠️ **`AUTH_MODEL` ir `APP_LOCALE=lt` yra PRIVALOMI** — dažniausios prod deploy
> klaidos: be `AUTH_MODEL` → seed'as krenta ties `UsersSeeder` (guard); su
> `APP_LOCALE=en` → visi turinio URL'ai 404 (route'ai registruoti en-default, o
> nav generuoja lt slug'us).

### 5. DB + vhost (jei dar nėra)

- Sukurk `cleverphant` DB (utf8mb4).
- XAMPP vhost: `cleverphant.test` → `.../cleverphant/public`; `/etc/hosts`: `127.0.0.1 cleverphant.test`; restart Apache.

### 6. Bootstrap

```bash
# Ištrink Laravel skeleton migracijas — paketai jas tiekia patys (users/cache/jobs);
# kitaip `migrate` lūžta „SQLSTATE[42S01]: Table 'cache' already exists":
rm -f database/migrations/0001_01_01_*_create_users_table.php \
      database/migrations/0001_01_01_*_create_cache_table.php \
      database/migrations/0001_01_01_*_create_jobs_table.php

# XAMPP/macOS: storage/ + bootstrap/cache rašomi Apache (daemon) vartotojui —
# kitaip login meta 500 su klaidinančiu „tempnam(): file created in temp directory":
chmod -R a+rwX storage bootstrap/cache

php artisan key:generate
php artisan storage:link
php artisan migrate

# BAZĖ: locales + admin@viartas.lt + roles + bazinis CMS turinys + temų eilutės + route vertimai.
# CmsBootSeeder dabar class_exists-guarded → saugu subsete (praleidžia neįdiegtus seederius).
php artisan db:seed --class="ViartasCore\Core\Database\Seeders\CmsBootSeeder" --force

# Cleverphant baseline (Pages/News/FAQ/kontaktai override + tema + auto-activate).
# --force: komanda destruktyvi (išvalo Protera-era turinį) + turi interaktyvų patvirtinimą;
# --force praleidžia gate'ą (saugu švarioje DB). Ji PATI kviečia cms:sync-permissions IR cleverphant:activate.
php artisan cleverphant:install --force

# FRONTEND (Node/npm NEREIKIA):
php artisan themes:publish-assets                          # temų assets (cleverphant build+img + viartas-default)
php artisan vendor:publish --tag=package-assets --force    # visų paketų admin assets
php artisan optimize:clear                                 # švieži config/route/view cache
```

> ⚠️ `cleverphant:install` PIRMA **išvalo** esamą web turinį (Protera-era Pages/News/Faq/Menus),
> po to seeda savo. Švarioje DB tai nekenkia. Ir jis pats iškviečia `cms:sync-permissions` + `cleverphant:activate`.
> Valymas destruktyvus **by-default** (`--additive` opt-out'ina; `--dry-run` peržiūri), naudoja
> slug-allowlist wiper'į (`CleverphantContentWiper`) — laiko savo 10 puslapių, valo kitus.
>
> ℹ️ **Cross-product:** analogišką švaraus single-theme state'o valymą turi ir kitos temos, bet kaip
> **opt-in** flagą: Florial — `florial:seed-content --fresh`, Seglo — `seglo:install --wipe-foreign`
> (bendras `ViartasCore\Core\Support\ForeignCmsContentWiper`, purge-then-reseed). Cleverphant lieka
> destruktyvus-by-default + allowlist, nes jo Pages seeder yra `firstOrCreate` (saugo admin edits).
>
> ℹ️ **Meniu** (`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` liekaną — todėl `/admin/menus` rodo tik Cleverphant nav. Front
> nav pagal nutylėjimą hardcoded (per-locale); DB-redaguojamas kai `.env` `MENUS_DB_DRIVEN=true`.
> Prod'e, kad NEtrintum turinio, meniu perseed'ink atskirai:
> `php artisan db:seed --class="ViartasThemes\Cleverphant\Database\Seeders\CleverphantMenusSeeder" --force`.
>
> ℹ️ `CmsBootSeeder` sukuria locales, `admin@viartas.lt` ir bazinį CMS (Pages/News/Menus), ant kurio Cleverphant deda savo override. (Jei puslapiai neatsiseeda — `php artisan cleverphant:seed-pages --force`.)
>
> ✅ **Nebereikia rankomis (sutvarkyta paketuose po Satis rebuild):**
> - `cms:sync-permissions` — `cleverphant:install` pats jį kviečia (atskiro žingsnio nereikia).
> - `tags` lentelė kuriama savaime (migracija core'e) — nebereikia `vendor:publish Spatie\Tags`.
> - Puslapių `{any}` catch-all registruojasi savaime — nebereikia redaguoti `AppServiceProvider`.
> - `themes:publish-assets` kopijuoja ir `public/img` — nebereikia atskiro `--tag=va-themes-cleverphant-assets`.
>
> Šviežias `composer require` (3 žingsnis) traukia naujausias versijas. Jei diegi ant seno checkout'o — `composer update -W` prieš bootstrap.

---

## Prisijungimas + aplinkos

**Super admin (sukuria `CmsBootSeeder`):** `admin@viartas.lt` / **`password`** (super-admin rolė).

| Aplinka | URL | Kam |
|---|---|---|
| **Web saitas** | `http://cleverphant.test/` | Vieša cleverphant.lt svetainė (cleverphant web tema) |
| **Admin CMS** | `http://cleverphant.test/admin` | pages/news/users/roles/temos (super-admin) |

> ⚠️ `.env`: `AUTH_MODEL="ViartasCore\\Users\\Models\\User"`, `APP_LOCALE=lt`, `APP_FALLBACK_LOCALE=lt`.
> ⚠️ Po `composer create-project` ištrink `routes/web.php` skeleton welcome route (P6).

## Verifikacija

- **Web saitas:** `http://cleverphant.test` → Cleverphant dizainas (index, /duk, /kontaktai, news).
- **Puslapiai + paveiksliukai:** `/mokyklos`, `/poziuris`, `/pristatymas`, `/begalinis-ciklas` → 200 ir img'ai kraunasi (ne broken-image ikonos).
- Login: `admin@viartas.lt` / `password`.
- **Admin:** `http://cleverphant.test/admin` → `/admin/puslapiai`, `/admin/naujienos`.

## Jei kažkas lūžta

- `composer require` „package not found" → Satis neturi grandinės (`va-core/*`, `va-modules/*`). Pranešk kuris trūksta.
- Seeder „class not found" (pvz. Menus/Faq/Forms) → trūksta atitinkamo `va-modules/*` paketo. Po composer fix'o jie ateina per `va-themes/cleverphant` require — `composer update -W` turėtų juos įtraukti.
- **Migrate `1050 Table 'cache'/'users'/'jobs' already exists`** → neištrinai Laravel skeleto migracijų (žr. 6 žingsnį); ištrink ir `php artisan migrate:fresh --force`.
- **`cleverphant:install` → `Table 'tags' doesn't exist`** → sena paketų versija (dabar `tags` migracija yra core'e): `composer update -W`, tada `php artisan migrate`.
- **VISI puslapiai 404 (išskyrus `/`, `/duk`, `/tinklarastis`, `/admin`)** → catch-all neregistruotas (dabar registruojasi savaime): `composer update -W` + `php artisan optimize:clear`. `route:list` turi rodyti `web.catchall`.
- **Turinio paveiksliukai broken (`/vendor/va-themes/cleverphant/img/*` 404/500)** → perleisk `php artisan themes:publish-assets` (dabar jis kopijuoja ir `img/`).
- **Apache po vhost pridėjimo dar rodo kitą docroot/saitą** → Apache neperkrauta: `sudo /Applications/XAMPP/xamppfiles/bin/httpd -k graceful` (ar `-k restart`). `.test` resolvinasi per `/etc/resolver/test` — `/etc/hosts` nereikia.
- Web env rodo Protera, ne Cleverphant → paleisk `php artisan cleverphant:activate` + `php artisan optimize:clear`.
- Migrate/route klaidos → `php artisan optimize:clear` ir bandyk vėl.

## Pabaigus

Trumpai atsiskaityk: kokie paketai įsidiegė, ar `cleverphant.test` rodo Cleverphant dizainą, ar admin veikia.

---

## Forge / production deploy

> ### ⛔ PRIEŠ PIRMĄ DEPLOY (privaloma — kitaip pirmas deploy kris ir paliks dalinius duomenis)
>
> Forge naują site'ą po sukūrimo **iškart bando deploy'inti su DEFAULT `.env` ir
> DEFAULT deploy script'u**. Su default `.env` (be `AUTH_MODEL`, `APP_LOCALE=en`)
> seed'as **krenta viduryje** (`UsersSeeder` guard → paskui `MenusSeeder` duplicate
> ir t.t.), o `.viartas-installed` flag'as NEsukuriamas → kiekvienas retry vėl
> leidžia first-install seeder'ius **ant dalinių duomenų** → kaupiasi kolizijos.
>
> **Todėl PRIEŠ paleidžiant deploy (arba iškart po site sukūrimo, jei auto-deploy
> jau bandė):**
> 1. **Nustatyk `.env`** (Forge → site → Environment) — bent šie:
>    ```dotenv
>    APP_NAME=Cleverphant
>    APP_LOCALE=lt
>    APP_FALLBACK_LOCALE=lt
>    AUTH_MODEL="ViartasCore\\Users\\Models\\User"
>    MENUS_DB_DRIVEN=true
>    ```
> 2. **Įdėk žemiau esantį Deploy Script** (Forge → site → Deploy Script) — su
>    `.viartas-installed` marker'iu.
> 3. **Tik tada** paleisk deploy.
>
> **Jei pirmas deploy jau krito** (žr. „Recovery" žemiau) — reikia švaraus starto.

Cleverphant (consumer app) Forge deploy — **be `npm build`** (assets pre-built per `vendor:publish`). Forge → site → **Deploy Script**:

```bash
cd $FORGE_SITE_PATH
git pull origin $FORGE_SITE_BRANCH
$FORGE_COMPOSER install --no-dev --no-interaction --prefer-dist --optimize-autoloader

$FORGE_PHP artisan storage:link
$FORGE_PHP artisan migrate --force

# FIRST install — TIK vieną kartą. cleverphant:install yra DESTRUKTYVUS (išvalo
# esamą web turinį), todėl jis PRIVALO likti už šito marker'io.
if [ ! -f storage/app/.viartas-installed ]; then
    $FORGE_PHP artisan vendor:publish --tag=cms-database-seeder --force
    $FORGE_PHP artisan db:seed --class="ViartasCore\Core\Database\Seeders\CmsBootSeeder" --force
    $FORGE_PHP artisan cleverphant:install --force
    mkdir -p storage/app && touch storage/app/.viartas-installed
fi

# KIEKVIENĄ deploy — saugus, idempotentinis sync (turinio NELIEČIA):
# formų definicijos + temos eilutė + cms:sync-permissions + aktyvi tema.
$FORGE_PHP artisan cleverphant:upgrade --force

# Bazinės global validation/auth lang eilutės + modelių aptikimas (va-core/translations 1.1.0).
# --force saugu: per-projekto vertimų pataisos yra DB (language_lines), ne failuose.
$FORGE_PHP artisan vendor:publish --tag=lang --force
$FORGE_PHP artisan translations:sync-models

$FORGE_PHP artisan themes:publish-assets
$FORGE_PHP artisan vendor:publish --tag=package-assets --force
$FORGE_PHP artisan optimize

( flock -w 10 9 || exit 1; sudo -S service $FORGE_PHP_FPM reload ) 9>/tmp/fpmlock
```

> Po pirmo deploy — nieko rankomis (first-install blokas automatiškas). `.env`: `APP_URL`, DB, `AUTH_MODEL`, `APP_LOCALE=lt`, `MENUS_DB_DRIVEN=true`.
>
> ⚠️ **Repo prielaida:** Forge deploy'ina iš git — repo turi turėti ištrintas Laravel skeleto migracijas `0001_01_01_*` (6 žingsnis). Catch-all ir `tags` migracija dabar ateina iš paketų (nebereikia nieko commitinti į hostą).

### Recovery — pirmas deploy krito su dalinių duomenų kolizijom

Simptomai (fresh site, pirmas deploy kelis kartus krito): `GuardDoesNotMatch`
(be `AUTH_MODEL`), tada `SQLSTATE 1062 Duplicate entry 'web.brands-web'`
(`MenusSeeder` re-run ant dalinės DB — `firstOrCreate` nemato soft-deleted eilutės),
ir/arba visi turinio URL'ai 404 (`APP_LOCALE=en` → locales neaktyvios).

**Priežastis:** deploy krito PRIEŠ `touch .viartas-installed`, tad first-install
seeder'iai kartojosi ant dalinių duomenų. `cleverphant:upgrade` NEsutvarko — reikia
švaraus starto.

**Sprendimas (Forge SSH, `current/` viduje) — TIK jei DB dar be realaus turinio:**

```bash
cd ~/<site>/current

# 0) Įsitikink kad .env jau turi AUTH_MODEL + APP_LOCALE=lt + MENUS_DB_DRIVEN=true
php artisan config:clear

# 1) ŠVARUS STARTAS — ištrina VISKĄ + re-migrate
php artisan migrate:fresh --force

# 2) Seed clean (vieną kartą, jokių kolizijų)
php artisan db:seed --class="ViartasCore\Core\Database\Seeders\CmsBootSeeder" --force
php artisan cleverphant:install --force

# 3) Pažymėk įdiegta — nutraukia deploy retry ciklą (MenusSeeder nebesikartos)
mkdir -p storage/app && touch storage/app/.viartas-installed

# 4) Finalize
php artisan cleverphant:upgrade --force
php artisan themes:publish-assets && php artisan vendor:publish --tag=package-assets --force
php artisan optimize && php artisan storage:link
```

> Po to `getActiveTags()` nebe tuščias → turinio route'ai registruojasi → 404 dingsta.
> ⚠️ `migrate:fresh` **ištrina viską** — naudok TIK fresh install (be realaus turinio).

---

## Atnaujinimas (update)

Po dev serverio užduočių consumer'is atsinaujina **viena komanda** —
`cleverphant:upgrade`. Ji idempotentinė, **turinio neliečia** ir saugi leisti
kiekvieną deploy (Forge skriptas ją jau leidžia — žr. aukščiau):

```bash
composer update
php artisan migrate --force
php artisan cleverphant:upgrade --force
php artisan vendor:publish --tag=lang --force        # bazinės validation/auth/passwords/pagination (lt+en) į global lang/
php artisan translations:sync-models                 # modelių stulpelių aptikimas /admin/translations/modeliai
php artisan themes:publish-assets
php artisan vendor:publish --tag=package-assets --force
php artisan optimize
```

> 🆕 **`--tag=lang` + `sync-models` (nauja nuo `va-core/translations` 1.1.0):**
> - `vendor:publish --tag=lang` nukopijuoja **bazinius global vertimų failus** (`validation.php`/`auth.php`/`passwords.php`/`pagination.php`, lt+en) į consumer `lang/`. Tai ištaiso raw `validation.required` formose ir `/admin/vartotojai/sukurti`. `--force` **saugu perrašyti** — per-projekto pataisos gyvena **DB** (`language_lines` overlay), ne failuose.
> - `translations:sync-models` aptinka `va-modules/*/src/Models` (nauji `model_paths` default'ai) → `/admin/translations/modeliai` nebeaptinka 0.

**Ką ji sinchronizuoja:** viešų formų definicijas (`kontaktai` / `susipazinkime` /
`newsletter`, `firstOrCreate` — per builder'į redaguotų NEperrašo), Cleverphant
`themes` eilutę + web default'ą, `cms:sync-permissions` (route-derived
permission'us, incl. kiekvienos būsimos užduoties naujus) ir per-aplinkos temų
default'us. Pabaigoje spausdina lentelę su turinio eilučių pokyčiu — sveikame
run'e visi turinio pokyčiai `0`.

> ⚠️ **NEnaudok `cleverphant:install` atnaujinimui** — jis destruktyvus (išvalo
> Pages/News/FAQ ir seeda iš naujo). Turinio seed'as, jei jo tikrai reikia, yra
> atskiras, sąmoningas žingsnis — žr. [`CHANGELOG.md`](CHANGELOG.md)
> („Turinio atnaujinimas").

**Rankiniai žingsniai, kurių komanda NEabsorbuoja** (naujas `.env`, Satis rebuild,
vienkartinis turinio seed'as) fiksuojami [`CHANGELOG.md`](CHANGELOG.md) faile.
Jei užduoties ten nėra — standartinio update pakanka.
