# ELFBAR Ukraine (elfbar.org.ua)

> Офіційний інтернет-магазин електронних сигарет ELF BAR та суміжної продукції в Україні (Київ та доставка по всій країні). Сайт: https://elfbar.org.ua. Стек: Next.js 15 (App Router), React 19, Tailwind CSS, Google Sheets як CMS, Telegram для замовлень, Nova Poshta для доставки. Деплой: Coolify (Docker), авто-деплой з GitHub `main`.

Цей файл допомагає LLM-агентам і асистентам коректно розуміти сайт, його URL, дані, обмеження та правила роботи з кодом. Доповнює `robots.txt` і `sitemap.xml`.

## Для кого цей файл

- AI-агенти, що аналізують або рекомендують товари/сторінки магазину
- Агенти, що пишуть або ревʼюють код репозиторію
- Асистенти підтримки/контенту, що працюють з каталогом і SEO

## Канонічні URL

- Сайт: https://elfbar.org.ua
- Sitemap: https://elfbar.org.ua/sitemap.xml
- Robots: https://elfbar.org.ua/robots.txt
- Цей файл: https://elfbar.org.ua/llms.txt
- Репозиторій: https://github.com/advplus/elfbar-org-ua

## Мова та аудиторія

- Основна мова інтерфейсу та контенту: **українська** (`lang="uk"`)
- Гео: Україна (Київ, Харків, Одеса та інші міста)
- Валюта цін: **UAH (грн)**
- Бренд у UI: ELFBAR Ukraine / elfbar.org.ua

## Карта важливих сторінок

### Комерційні (індексуються)

- [Головна](https://elfbar.org.ua/): хіти, новинки, SEO-текст
- [Каталог](https://elfbar.org.ua/catalog): усі товари, фільтри, навігація по категоріях (`?category=slug`, `?search=...`)
- [Категорія](https://elfbar.org.ua/{categorySlug}): список товарів серії (slug з Google Sheets Sheet2)
- [Товар](https://elfbar.org.ua/{categorySlug}/{productSlug}): картка, ціна, наявність, опис, відгуки, schema Product
- [Про магазин](https://elfbar.org.ua/about)
- [Доставка та оплата](https://elfbar.org.ua/delivery)
- [FAQ](https://elfbar.org.ua/faq)
- [Гарантія](https://elfbar.org.ua/warranty)
- [Політика конфіденційності](https://elfbar.org.ua/privacy)
- [Контакти](https://elfbar.org.ua/contact)

### Службові (не для SEO / noindex або disallow)

- [Кошик](https://elfbar.org.ua/cart)
- [Оформлення замовлення](https://elfbar.org.ua/checkout)
- API під `/api/*` (не індексувати)

## Як влаштовані дані (Google Sheets)

Товари **не** в SQL БД. Джерело правди — Google Spreadsheet.

| Аркуш | Призначення |
|-------|-------------|
| Sheet1 | Товари: id, category, title, price, description, inStock, brand, flavor, nicotine, puffs, power, image URL, seoTitle, seoMetaDescription, rating, reviewCount |
| Sheet2 | Категорії: category, **slug**, h1, description, seoTitle, seoMetaDescription |
| Sheet3 | Відгуки (з модерацією) |
| orders | Замовлення (запис з сайту) |
| clients | Клієнти (запис/оновлення з сайту) |
| redirects | Редиректи old → new URL |

### Критичні правила slug

1. **categorySlug товару** має збігатися зі **slug з Sheet2** (не з автотранслітом назви).
2. URL товару: `/{categorySlug}/{productSlug}`.
3. Відомі 301 з історичних slug:
   - `/yelf-bar-lush-king-pro-40000/*` → `/lush-king/*`
   - `/yelf-bar-e-shisha-12000/*` → `/e-shisha/*`
   - `/kartrydzhy-elf-x/*` → `/kartridzhi-elf-x/*`
4. Product slug генерується з назви (legacy-трансліт, зокрема `Є` → `ye`, тому багато URL `yelf-bar-...`). **Не міняти slugify без 301**, інакше зламається SEO.

### Оновлення даних на сайті після правок у таблиці

- ISR + in-memory/file cache: **~3 хвилини** (`ISR_REVALIDATE_SECONDS = 180`).
- Миттєве оновлення (після edit у Sheets):

```bash
curl "https://elfbar.org.ua/api/revalidate?secret=REVALIDATE_SECRET"
```

- Endpoint чистить `clearSheetsCache()` і робить `revalidatePath` для `/`, `/catalog`, layout, dynamic routes, API.
- Нові **зображення** товарів: зазвичай потрібен rebuild/деплой (`download-images` на full build; Docker Coolify часто `build:no-images` — картинки з `public/` або зовнішніх URL).

## Замовлення та інтеграції

- Кошик: Redux + localStorage (клієнт).
- Checkout: форма + **Нова Пошта** (місто/відділення) → `POST /api/order`.
- Замовлення: Telegram + запис у Google Sheets (orders/clients).
- Відгуки: `POST /api/reviews` (+ перерахунок рейтингу).
- Аналітика: Google Analytics `G-QXDPWEKDED`.

## Контакти (публічні, з футера)

- Телефон: +380684613838 / (068) 461-38-38
- Email: elfxpro.ua@gmail.com
- Telegram: https://t.me/advplus (також у schema: t.me/elfbar_kyiv)
- Instagram: https://www.instagram.com/elfbar.kyiv.ua/
- Адреса (у футері): Київ, вул. Лятошинського, 24

## API (коротко)

| Метод | Шлях | Опис |
|-------|------|------|
| GET | `/api/products` | Повний список товарів (кеш ~3 хв) |
| GET | `/api/categories` | Категорії |
| GET | `/api/search?q=&limit=` | Легкий пошук для header autocomplete |
| POST/GET | `/api/revalidate?secret=` | Скидання кешу Sheets + ISR |
| POST | `/api/order` | Оформлення замовлення |
| POST | `/api/reviews` | Новий відгук |
| GET | `/api/health` | Healthcheck (Docker/Coolify) |

Не вигадуйте ендпоінти, яких немає в `src/app/api/`.

## Структура коду (для coding-агентів)

```
src/
  app/                 # Next.js App Router
    (site)/            # Публічні сторінки + layout
    api/               # Route handlers
  components/          # UI (Header, Catalog, Product, Checkout, Home…)
  lib/
    googleSheets.ts    # Читання/запис Sheets, clearSheetsCache, slugify
    seo.ts             # SITE_URL, ISR, absoluteUrl
    novaPoshta.ts
    telegram.ts
  redux/               # Лише cart
  middleware.ts        # Редиректи з redirects.json
public/
  images/products/downloaded/  # Локальні фото + image-map.json
  llms.txt             # Цей файл
```

### Env (Coolify / `.env`)

- `GOOGLE_SHEETS_SPREADSHEET_ID`
- `GOOGLE_SHEETS_CLIENT_EMAIL`
- `GOOGLE_SHEETS_PRIVATE_KEY` (з `\n` для переносів)
- `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`
- `REVALIDATE_SECRET`

### Команди

```bash
npm run dev              # розробка
npm run build:no-images  # Docker/Coolify build
npm run build            # + download-images.js
npm start
```

## Правила для AI-агентів (обовʼязково)

1. **Не вигадуйте** наявність, ціни, смаки — беріть з живих сторінок або `/api/products`. Дані змінюються.
2. **Не індексуйте/не цитуйте як канон** `/cart`, `/checkout`, `/api/*`.
3. При зміні URL/slug — плануйте **301** і оновлення sitemap.
4. При зміні даних у Sheets без деплою — нагадуйте про `/api/revalidate` або очікування ~3 хв.
5. Не додавайте знову template-сміття NextCommerce (blog demo, shop-with-sidebar, auth, wishlist тощо) — воно було видалене.
6. Layout сайту: server `(site)/layout.tsx` + client `Providers`; Header/Footer — острови.
7. SEO: canonical через Metadata API; Product schema з **absolute** image URL (`src/lib/seo.ts` → `absoluteUrl`).
8. Безпека: не комітьте `.env`, private key, `REVALIDATE_SECRET`.
9. Мова UI-текстів для користувача: **українська**.
10. Товар 18+: не позиціонуйте як для неповнолітніх; не давайте інструкцій для незаконного продажу.

## Обмеження та відомі нюанси

- Частина URL категорій історично з префіксом `yelf-bar-` через транслітерацію «Є».
- `categorySlug` без збігу з Sheet2 → 404 категорії (вже виправлено маппінгом; не ламати).
- Пошук у header: `/api/search` (debounce), не повний каталог на кожне завантаження.
- ISR stale-while-revalidate може показувати старі HTML кілька хвилин після TTL, поки не прийде revalidate.
- README у репо може бути частково застарілим (старий домен elfxpro) — **канон домену: elfbar.org.ua**.

## Optional

- [Sitemap XML](https://elfbar.org.ua/sitemap.xml): повний список URL товарів і категорій
- [Каталог](https://elfbar.org.ua/catalog): головна точка входу в асортимент
- [FAQ](https://elfbar.org.ua/faq): відповіді покупцям (schema FAQPage)
- [GitHub](https://github.com/advplus/elfbar-org-ua): вихідний код

---

Оновлюйте цей файл при зміні URL-схеми, CMS, деплою або критичних бізнес-правил.