Initial commit — Aspekter VA email builder

Full project: Svelte 5 frontend, Vite 7 backend API,
Pug email templates (email-gen), Docker deployment.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs/01-user-guide.md

@@ -0,0 +1,238 @@
+# Aspekter VA — Руководство пользователя
+
+## Что это такое
+
+Aspekter VA — визуальный конструктор email-рассылок для интернет-магазина VipAvenue. Позволяет собирать письма из готовых блоков, редактировать тексты, подставлять товары из фида, проверять орфографию и выгружать готовый HTML для отправки через Mindbox.
+
+Адрес: **https://aspekter.ru**
+
+---
+
+## Вход в систему
+
+1. Открыть https://aspekter.ru
+2. Ввести логин и пароль
+3. Нажать «Войти»
+
+При первом запуске создаётся учётная запись `admin` с временным паролем (выводится в консоль контейнера). После входа рекомендуется сменить пароль через панель администратора.
+
+Сессия живёт 7 дней. После этого потребуется повторный вход.
+
+---
+
+## Основной интерфейс
+
+### Страницы (навигация слева)
+
+| Страница | Назначение |
+|---|---|
+| **Конструктор** | Сборка письма из блоков |
+| **План** | Календарь рассылок из Yonote |
+| **Статистика** | Время работы над письмами |
+| **Настройки** | Параметры проекта |
+
+### Конструктор — левая панель
+
+- **Список блоков** — перетаскивание, добавление, удаление, изменение порядка
+- **Поля блока** — при выборе блока показываются редактируемые поля (тексты, ссылки, картинки, ID товаров)
+- **Пресеты** — сохранённые наборы блоков для быстрого старта
+
+### Конструктор — правая панель (превью)
+
+- **Превью письма** — iframe с отрендеренным HTML
+- **Масштаб** — ползунок 40–100%
+- **Кнопки Жен / Муж** — переключение гендерной версии превью
+- **Кнопка ⇅** — переставляет блоки для мужской/женской версии (flip)
+- **Копировать HTML** — копирует итоговый HTML в буфер обмена
+
+---
+
+## Работа с блоками
+
+### Добавление блока
+1. Нажать «+ Добавить блок» в левой панели
+2. Выбрать блок из списка (появится dropdown с иконками)
+3. Блок добавляется в конец списка
+
+### Редактирование полей
+Каждый блок раскрывается по клику. Внутри — поля:
+- **Текст** — многострочное поле, поддерживает пробелы и переносы
+- **Ссылка** — URL (кнопки, картинки, ссылки меню)
+- **ID товаров** — через запятую, подтягиваются из фида
+- **Картинка** — URL изображения
+
+### Перетаскивание
+Блоки можно перетаскивать за иконку ⠿ слева от названия.
+
+### Удаление
+Кнопка 🗑 справа от блока.
+
+### Секции внутри блока
+Некоторые блоки (например «Текст») состоят из секций. Секции можно:
+- Менять местами перетаскиванием
+- Удалять (кроме первой)
+- Добавлять новые
+
+---
+
+## Гендерная сегментация
+
+Письма VipAvenue отправляются в двух версиях: женской и мужской.
+
+### Как это работает
+- Каждое письмо собирается с набором блоков
+- **Кнопка «Жен» / «Муж»** — переключает превью на соответствующую версию (меняет header/footer и порядок блоков)
+- **Кнопка ⇅ (flip)** — физически переставляет блоки: блоки до разделителя и после меняются местами
+- **Разделитель (⊕)** — блок-разделитель, служит осью для flip. Устанавливается кнопкой ⊕ только на блоке типа «dividerVA»
+
+### Хедеры и футеры
+Настраиваются в разделе «Настройки» → «Гендерные пути»:
+- Хедер женский / мужской
+- Футер женский / мужской
+
+Выбираются из списка файлов в `email-gen/emails/vipavenue/parts/`.
+
+---
+
+## Товары из фида
+
+### Настройка фида
+В настройках проекта указывается URL XML-фида Mindbox. Фид кэшируется на 3 часа.
+
+### Подстановка товаров
+1. В блоке с товарами ввести ID через запятую
+2. Система найдёт товары в фиде и покажет превью (название, цена, картинка)
+3. Если товар не найден или недоступен — появится предупреждение
+
+### Замена товара
+Если товар недоступен, система предложит замену. Алгоритм подбора:
+- Тот же тип товара (+20 баллов)
+- Та же категория (+15)
+- Тот же бренд (+25)
+- Тот же гендер (+10)
+- Близкая цена (+0..10, исключение если >3x разница)
+- Тот же цвет (+5)
+
+### Пул ID
+В левой панели можно вести «Пул ID» — список товаров для быстрой вставки.
+
+---
+
+## Пресеты
+
+Пресет — сохранённый набор блоков с их содержимым.
+
+- **Сохранить** — кнопка «Сохранить как пресет», вводится название
+- **Загрузить** — выбрать из списка, блоки заменятся
+- **Удалить** — кнопка удаления в списке пресетов
+
+---
+
+## Письма (карточки рассылок)
+
+### Создание
+Каждая рассылка — карточка с полями:
+- Тема письма
+- Дата
+- Тег (категория)
+- Набор блоков
+
+### Список писем
+В левой панели — список карточек. Можно:
+- Создать новое письмо
+- Открыть существующее
+- Удалить
+- Просмотреть историю изменений
+
+### История
+Каждое сохранение создаёт снимок. Можно откатиться к предыдущей версии.
+
+---
+
+## Заметки
+
+В боковой панели есть раздел «Заметки» — текстовые заметки привязанные к проекту.
+- Создание, редактирование, удаление
+- Данные хранятся на сервере
+
+---
+
+## План рассылок
+
+Страница «План» подтягивает данные из Yonote (API). Показывает:
+- Календарь с отмеченными датами рассылок
+- Список с темами, статусами, датами
+- Уведомления о новых/удалённых рассылках (polling каждые 3 минуты)
+
+---
+
+## Проверка ссылок
+
+Кнопка «Проверить ссылки» в превью:
+- Находит все URL в сгенерированном HTML
+- Проверяет каждый (HEAD-запрос)
+- Показывает статус: ✅ работает, ❌ битая, ⚠️ редирект
+
+---
+
+## Проверка орфографии
+
+Использует Яндекс.Спеллер. Подсвечивает ошибки в превью красным волнистым подчёркиванием с подсказкой при наведении.
+
+---
+
+## Типографика
+
+Кнопка «Типограф» отправляет тексты блоков через сервис Артемия Лебедева (typograf.artlebedev.ru). Применяет:
+- Неразрывные пробелы после предлогов
+- Правильные кавычки «ёлочки»
+- Тире вместо дефиса
+- И другие правила русской типографики
+
+---
+
+## FTP / Галерея изображений
+
+### Настройка
+В настройках проекта → FTP:
+- Хост, порт, логин, пароль
+- Протокол (FTP / SFTP)
+- Удалённый путь
+- Публичный URL
+
+### Использование
+- Кнопка «Галерея» открывает модальное окно
+- Загрузка: выбрать файлы (множественный выбор), загрузка автоматическая
+- Копирование URL: клик по миниатюре
+- Удаление: кнопка на миниатюре
+
+---
+
+## Копирование HTML
+
+1. Нажать «Копировать HTML»
+2. HTML копируется в буфер обмена
+3. Вставить в Mindbox
+
+**Важно:** в сгенерированном HTML предлоги и короткие слова (≤3 символов) склеены со следующим словом через `<span style="white-space:nowrap">` — это предотвращает висячие предлоги в почтовых клиентах.
+
+---
+
+## Тема оформления
+
+Переключатель светлая/тёмная тема — в верхней панели. Настройка сохраняется в профиле пользователя на сервере.
+
+---
+
+## Администрирование
+
+Доступно только пользователям с ролью `admin`.
+
+### Управление пользователями
+- Создание новых пользователей (логин, пароль ≥8 символов, имя, роль)
+- Редактирование (смена пароля, имени, роли)
+- Удаление (нельзя удалить самого себя)
+
+### Роли
+- **admin** — полный доступ + управление пользователями
+- **user** — работа с конструктором