First Pack v1.0 — Документація та філософія проекту

Тут послідовно можна ознайомитись, як я то робив:
У розділі статей: eggfamily.com.ua/articles.html

Цей пак можу продати-або бартером віддати за 3 кг кави в зернах, чи ваша пропозицію, тут цінність не в грошах

Перший готовий генератор статичного сайту (Python SSG), створений як особистий простір для, можливо, майстрів, творців, колекціонерів та чогось нішевого. вам лише це потрібно стилістично, під себе візуально розгорнути. По-суті - це супер сайт візитка. Який має простір, для розширення Суть цього у філософії освоєння простору: про фізичний простір — то все зрозуміло: будуєш дім чи ходиш, літаєш на прогулянки. А от з віртуальним простором складніше: будь-яка суспільна мережа чи платформа є посередником, і ви лише стаєте її продуктом.

Це повноцінна CMS, яку я написав для себе. Вона працює, додав тестову базу database.json даних і СТАРТ.bat кнопку в корені: "Для запуску на Windows не потрібно нічого налаштовувати в консолі — просто натисніть СТАРТ.bat, і локальна копія сайту з адмінкою відкриється у вашому браузері."

---

Сенс цьго всього, про що я кажу тут: Не потребує щомісячної абонплати, крім оплати хостингу і домена в подальшому, і дає вам повний контроль над вашим майданчиком.

Додав README.md, ніби все детально описав, як розгорнути сайт. З кодом можете робити, що вам хочеться, я не патентую це все. Це перший такий пак, по суті, тестово зібрав. Буде час — подумаю, як його спростити ще більше для людини, яка взагалі не знає, що таке код, але поки мінімальні знання все ж таки будуть вам необхідні.

Ви купуєте лише пак, я не веду його підтримку. Якщо потрібна підтримка, чи ведення сайту, чи щодо розгортання, то пишіть окремо.

---

Повний текст інструкції (README.md):

[# Python SSG — Static Site Generator для інтернет-простору
Модель обробки замовлень та оплати
Проєкт використовує модель "Direct-to-Seller" (пряма взаємодія з продавцем), що має свої особливості:

Без автоматичних платежів: У систему спеціально не інтегровані сторонні платіжні шлюзи (Stripe, LiqPay тощо). Це зроблено для забезпечення максимальної швидкості роботи сайту, повної приватності даних та відсутності комісій за транзакції.

Не для мас-маркету: Дане рішення не розраховане на агресивну масову комерцію з сотнями автоматичних продажів на годину. Це інструмент для нішевого діалогу з клієнтом, тай взагалі не на комерцію, а більше на блог і проживання буття тут і зараз

Гнучкість розрахунків: Оплата зазвичай відбувається за схемою:

Клієнт оформлює замовлення через кошик.

Ви отримуєте дані замовлення.

Ви самостійно виставляєте рахунок (IBAN), або відправляєте з післяплату поштою

Довіра та безпека: Клієнтам не потрібно вводити дані банківських карток на сайті





Повноцінна CMS на Python + Flask для генерації статичного сайту.


---

## Зміст

1. [Швидкий старт](#швидкий-старт)
2. [Структура проекту](#структура-проекту)
3. [Налаштування (config.py)](#налаштування)
4. [Адмінки — повний опис](#адмінки)
5. [Наповнення контентом](#наповнення-контентом)
6. [Зміна візуалу сайту](#зміна-візуалу)
7. [Email сповіщення](#email-сповіщення)
8. [Акції та ціни](#акції-та-ціни)
9. [Замовлення та коментарі](#замовлення-та-коментарі)
10. [Деплой на хостинг](#деплой)
11. [Конвертери даних](#конвертери)
12. [Безпека](#безпека)

---

## Швидкий старт

```bash
# 1. Встановити залежності
pip install -r requirements.txt

# 2. Налаштувати config.py (назва магазину, URL, тощо)

# 3. Заповнити дані
echo "your-admin-password" > data/password.txt
echo "your@email.com" > data/notify_email.txt

# 4. Запустити
python generator.py

# 5. Відкрити адмінку

```

---

## Структура проекту

```
буде у файлі
```

---

## Налаштування
Увага!! зараз він заточений, щоб ви могли перевірити роботоздатність алгоритму статично на пк, тому потрібно буде внести зміни в ньому згідно до вашого хостингу, де буде сайт
Відкрийте `config.py` і заповніть:

import os

# ==============================================================================
# ОСНОВНІ НАЛАШТУВАННЯ 
# ==============================================================================
STORE_NAME    = "Назва вашого сайту"
BASE_URL      = "https://your-domain.com"
CURRENCY      = "₴"

# Контакти
TELEGRAM_LINK = "https://t.me/your_username"
PHONE         = "+380XXXXXXXXX"
PHONE_DISPLAY = "+38 (0XX) XXX-XX-XX"

# ==============================================================================
# ШЛЯХИ ТА СИСТЕМА (cPanel / Local)
# ==============================================================================
# ПРИМІТКА: Для cPanel використовуйте повний шлях, наприклад:
# /home/YOUR_USERNAME/YOUR_PROJECT_FOLDER/data/
BASE_DIR = os.path.dirname(os.path.abspath(__file__))

DATA_DIR    = os.path.join(BASE_DIR, 'data')
IMAGES_DIR  = os.path.join(BASE_DIR, 'images')
WWW_DIR     = os.path.join(BASE_DIR, 'www')

# Файли бази даних
DB_FILE            = os.path.join(DATA_DIR, 'database.json')
ORDERS_FILE        = os.path.join(DATA_DIR, 'orders.json')
TESTIMONIALS_FILE  = os.path.join(DATA_DIR, 'testimonials.json')
COMMENTS_FILE      = os.path.join(DATA_DIR, 'comments.json')

# ==============================================================================
# БЕЗПЕКА ТА API
# ==============================================================================
це буде у файлі
---

## Адмінки

це буде у файлі

---

### 📝 Статті (`/admin/articles/`)

Статті формують блог сайту. Відображаються на сторінці `/articles.html` і в слайдері на головній.

**Додати статтю:**
1. **+ Нова стаття**
2. Заголовок, короткий опис (preview), основний текст (підтримує HTML)
3. Зображення (конвертується в WebP автоматично)
4. Збереження → автоматична генерація сайту

**Текст статті — HTML прямо у вікні адмінки**

Поле "Текст (HTML)" в адмінці статей — це звичайний textarea, але він рендерить весь введений HTML як є. Пишіть теги прямо у вікні — вони відображатимуться на сайті з повним форматуванням.

> **Важливо:** Текст статті рендериться через Jinja2 фільтр `| safe` — це означає що весь HTML відображається без екранування. Будь-який валідний HTML тег і inline CSS будуть працювати.

---

### 💬 Відгуки (`/admin/reviews/`)

**Модерація нових відгуків:**
Покупці залишають відгуки через форму на сторінці `/testimonials.html`. Відгуки потрапляють зі статусом "pending" і відображаються у жовтому блоці "Очікують модерації".
---

### 🗨️ Коментарі (`/admin/comments/`)

Покупці можуть залишати коментарі до кожної статті.

**Модерація:**
- Нові коментарі потрапляють в "Очікують модерації"
---

### 📋 Замовлення (`/admin/orders/`)

Замовлення надходять при оформленні через кошик. Зберігаються в `data/orders.json`.

**Управління замовленням:**
- Фільтри: Всі / Нові / В обробці / Виконані / Скасовані
- Статуси: 🆕 Нове → 🔄 В обробці → ✅ Виконано / ❌ Скасовано
- Поле **Нотатка** — для трек-номера або приміток
- 🗑️ Видалити — прибирає замовлення зі списку

**Експорт:**
- 📥 **Excel** — завантажує CSV файл з усіма замовленнями (відкривається в Excel)

**Налаштування сповіщень:**
- 📧 **Сповіщення** — змінити email для отримання листів про нові замовлення

---

## Наповнення контентом

### Додавання товарів

**Через адмінку** (рекомендовано):

**Масовий імпорт з маркетплейса
```bash
# Завантажте XML/YML 
python prom_to_db.py prom_export.xml
```
**Масовий імпорт з Excel/CSV:**
```bash
python prom_to_db.py my_products.csv
```
CSV має містити колонки: `Назва, Ціна, Категорія, Опис, Кількість, Артикул, Фото`

**Завантаження фото з URL:**
```bash
python download_images.py
# Читає URL з database.json і завантажує в images/
```

### Структура database.json

```json
{
  "categories": {
    "101": { "name": "Категорія", "parent": null },
    "102": { "name": "Підкатегорія", "parent": "101" }
  },
  "products": [
    {
      "id": "1001",
      "name": "Назва товару",
      "vendor": "Артикул",
      "cat_id": "101",
      "price": "350",
      "old_price": "500",
      "quantity": 1,
      "slug": "1001-nazva-tovaru",
      "imgs": ["foto1.webp", "foto2.webp"],
      "main_img": "foto1.webp"
    }
  ],
  "articles": [
    {
      "title": "Заголовок статті",
      "preview": "Короткий опис",
      "content": "
Текст статті в HTML
",
      "date": "23.03.2026",
      "slug": "zaholovok-statti",
      "image": "foto.webp"
    }
  ]
}
```

### Зображення

Всі фото зберігаються в папці `images/`. Формат: **WebP** (автоматична конвертація в адмінці).

| Файл | Розмір | Призначення |
|---|---|---|
| `favicon.png` | 64×64 | Іконка браузера |
| `logo.webp` | 300×300 | Логотип магазину |
| `no-image.webp` | 400×400 | Заглушка без фото |
| `default-share.jpg` | 1200×630 | OG image для соцмереж |

---

## Зміна візуалу сайту

### Кольори і шрифти

Основні кольори визначені через CSS змінні в `css/base.css`:

```css
:root {
    --accent: #4f46e5;        /* Фіолетовий — основний колір кнопок */
    --accent-hover: #4338ca;  /* Hover стан */
    --text: #1e293b;          /* Основний текст */
    --text-muted: #64748b;    /* Другорядний текст */
    --border: #e2e8f0;        /* Колір рамок */
    --bg: #f8fafc;            /* Фон сторінки */
    --white: #ffffff;
}
```

Змініть `--accent` щоб змінити основний колір всього сайту.

### Структура CSS файлів

| Файл | Що редагувати |
|---|---|
| `css/base.css` | Header, footer, навігація, кошик, кнопки |
| `css/style.css` | Загальні компоненти (картки, бейджі) |
| `css/index.css` | Головна сторінка (hero, вітрина) |
| `css/category.css` | Сітка товарів, фільтри, картки |
| `css/product.css` | Сторінка товару, галерея, ціна |
| `css/article.css` | Окрема стаття |
| `css/articles.css` | Список статей |
| `css/testimonials.css` | Сторінка відгуків |

### Зміна навігації (base.html)

Основна навігація знаходиться в `templates/base.html`:

```html

```

### Зміна Footer (base.html)

```html

```

### Головна сторінка (index.html)

Секція hero (великий банер вгорі):
```html

    
Ваш заголовок
    
Ваш опис

```

Стилізація hero в `css/index.css` — шукайте `.hero-section`.

### Сторінка товару (product.html)

Інформація про доставку і повернення:
```html

    
🚚 Доставка: Ваш текст про доставку
    
↩️ Повернення: 14 днів.

```

---

## Email сповіщення

Листи надсилаються через SMTP при:
- 🛒 Нове замовлення
- ⭐ Новий відгук (pending)
- 💬 Новий коментар

**Змінити email** прямо в адмінці: `/admin/orders/` → 📧 Сповіщення.

---

## Акції та ціни

### Запустити акцію
### Скасувати акцію

1. 🏷️ **Акція** → у вікні показуються активні акції
2. **↩️ Скасувати** → ціни відновлюються автоматично

### Відображення на сайті

При активній акції показується:
- **-10%** (або +%, або "Акція") — червоний бейдж біля ціни
- **~~стара ціна~~** — перекреслена
- **7д** — кількість днів до кінця акції (якщо є термін)

---

## Замовлення та коментарі

### Як надходять замовлення

Покупець заповнює форму → `/api/order` → `data/orders.json` → Email сповіщення.
Google Sheets **не потрібен**.

### Як надходять коментарі

Покупець залишає коментар → `/api/comment` → `data/comments.json` (статус `pending`) → Email → Модерація в адмінці.
Google Script **не потрібен**.

### Як надходять відгуки

Покупець заповнює форму → `/api/reviews` → `data/testimonials.json` (статус `pending`) → Email → Модерація в адмінці.
Formspree **не потрібен**.

---

## Деплой
буде у файлі
### Генерація і деплой

```bash
# Генерує статичний сайт в www/
python generator.py

# Копіює www/ → public_html (тільки змінені файли)
python deploy.py

# Перевірити що зміниться без копіювання
python deploy.py --check

# Копіювати все + видалити зайве з public_html
python deploy.py --clean
```

Або через адмінку: 🔄 **Згенерувати** → 🚀 **Деплой**.

### Структура на сервері

```
буде у файлі
---

## Конвертери
Це бонус, який потребує допрограмування вам самим, під вашу потребу
### Міграція з іншої системи

> 📄 Детальна інструкція для всіх форматів: **[MIGRATION.md](MIGRATION.md)**
>

## Технічний стек

- **Backend:** Python 3.9+, Flask, Jinja2
- **Frontend:** Vanilla JS, CSS3
- **Хостинг:** cPanel + LiteSpeed/Apache, Passenger WSGI
- **Захист форм:** Google reCAPTCHA v3
- **Email:** SMTP через cPanel email акаунт
]
    

Примітка: цей файл надано для ознайомлення з логікою роботи системи.