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>
This commit is contained in:
Sergey Zotov
243
z51-pug-builder/README.md
Normal file
243
z51-pug-builder/README.md
Normal file
@@ -0,0 +1,243 @@
|
||||
# Z51 Pug Builder — руководство по интерфейсу
|
||||
|
||||
Этот файл описывает **интерфейс** и **логику использования** конструктора писем. Здесь нет технических деталей реализации — только то, как устроена работа в UI, где что находится и зачем это нужно.
|
||||
|
||||
---
|
||||
|
||||
## 1. Общая идея
|
||||
|
||||
Конструктор собирает письмо из блоков, взятых из `block.pug`. Каждый блок — это кусок Pug-кода, размеченный комментарием `//Название`. В интерфейсе вы выбираете нужные блоки, редактируете только важные поля (текст, ссылки, изображения, ID и т.п.), а на выходе получаете собранный Pug-файл.
|
||||
|
||||
Главная выгода: быстро собирать письма без ручного копирования и без риска повредить структуру шаблона.
|
||||
|
||||
---
|
||||
|
||||
## 2. Навигация по интерфейсу
|
||||
|
||||
Верхняя панель (шапка) содержит:
|
||||
- **Иконка дискеты** — открывает поле для названия пресета и сохранение пресета.
|
||||
- **Иконка папки** — переход на страницу пресетов.
|
||||
- **Сборка** — основная страница сборки письма.
|
||||
- **Настройки** — управление проектом и шаблонами.
|
||||
- **Переключатель темы** — светлая/тёмная.
|
||||
- **Назад / Сброс** — только на странице сборки.
|
||||
|
||||
В левом сайдбаре:
|
||||
- **Название проекта** (крупно, окрашено акцентом) или логотип.
|
||||
- **Выбор проекта**.
|
||||
- **Добавить блок** (выпадающий список).
|
||||
- **Быстрые кнопки блоков**.
|
||||
- Счётчик общего количества блоков.
|
||||
|
||||
---
|
||||
|
||||
## 3. Страница «Сборка»
|
||||
|
||||
Это основной экран для работы с письмом.
|
||||
|
||||
### 3.1. Добавление блоков
|
||||
- Через выпадающий список «Добавить блок».
|
||||
- Через быстрые кнопки (настраиваются в настройках проекта).
|
||||
- Через кнопку «+» внизу каждого блока — добавляет новый блок **после текущего**.
|
||||
|
||||
Новые блоки открываются сразу (развернуты).
|
||||
|
||||
---
|
||||
|
||||
### 3.2. Карточка блока
|
||||
Каждый блок — это карточка с:
|
||||
- названием блока;
|
||||
- кнопками **вверх / вниз / удалить**;
|
||||
- полями редактирования;
|
||||
- чекбоксом «Отступ после блока» + поле значения (если включено);
|
||||
- кнопками «PUG» и «+» (добавление блока после).
|
||||
|
||||
В любой момент можно раскрыть/свернуть блок по клику на его заголовок.
|
||||
|
||||
---
|
||||
|
||||
### 3.3. Поля редактирования
|
||||
Интерфейс не показывает весь код, а только полезные поля.
|
||||
|
||||
Типы полей:
|
||||
- **Текст** — содержимое внутри строк Pug.
|
||||
- **Ссылки** — `href`.
|
||||
- **Картинки** — `src`.
|
||||
- **Кнопки** — если в блоке есть `+buttonRounded(...)`, показываются отдельные поля для текста и ссылки.
|
||||
- **Товары** — если есть `+productsX`, показывается поле «ID товаров».
|
||||
|
||||
Поля автоматически определяются из шаблона блока, но их можно включать/выключать и переименовывать в настройках.
|
||||
|
||||
---
|
||||
|
||||
### 3.4. Форматирование текста
|
||||
Для текстовых полей есть панель действий:
|
||||
- **T** — типограф.
|
||||
- **Ж** — жирный текст.
|
||||
- **•** — маркер.
|
||||
- **<li>** / **</li>** — списки.
|
||||
- **A + URL** — ссылка.
|
||||
- **Глаз** — предпросмотр HTML.
|
||||
|
||||
---
|
||||
|
||||
### 3.5. Абзацы в блоке «Текст»
|
||||
Блок «Текст» поддерживает несколько абзацев:
|
||||
- Кнопка **«Абзац»** добавляет новый абзац.
|
||||
- У каждого дополнительного абзаца есть кнопка удаления.
|
||||
- Между абзацами автоматически вставляется `+spacerLine(20)`.
|
||||
|
||||
---
|
||||
|
||||
### 3.6. Списки (нумерованные и маркированные)
|
||||
Для блоков списков:
|
||||
- Редактируются только **тексты пунктов**.
|
||||
- Картинки маркеров/цифр скрыты и не редактируются.
|
||||
- Кнопка **«Пункт»** добавляет новый пункт.
|
||||
- Кнопка **×** удаляет пункт.
|
||||
|
||||
При добавлении блока со списком создаётся только **первый пункт**, остальные добавляются вручную.
|
||||
|
||||
---
|
||||
|
||||
### 3.7. Отступы
|
||||
- **Глобальный отступ** задаётся в настройках.
|
||||
- У каждого блока можно включить/выключить отступ и задать своё значение.
|
||||
- Для некоторых блоков отступ не добавляется автоматически (Разделитель, Отступ 20/40).
|
||||
|
||||
---
|
||||
|
||||
### 3.8. Итоговый Pug
|
||||
Правый блок — это итоговый Pug-код:
|
||||
- он обновляется при любом изменении;
|
||||
- можно **копировать** или **скачивать**;
|
||||
- при редактировании блок подсвечивается и прокручивается в Pug-окне.
|
||||
|
||||
---
|
||||
|
||||
## 4. Страница «Настройки»
|
||||
|
||||
Настройки делятся на вкладки:
|
||||
|
||||
### 4.1. Общие
|
||||
**Источник блоков**
|
||||
- Загрузка нового `block.pug`.
|
||||
- Перезагрузка текущего источника.
|
||||
|
||||
**Поля блока**
|
||||
- Выбор любого блока.
|
||||
- Включение/выключение полей.
|
||||
- Переименование подписи поля.
|
||||
|
||||
---
|
||||
|
||||
### 4.2. Глобальные блоки
|
||||
- Список всех блоков проекта.
|
||||
- Для каждого блока можно редактировать Pug-шаблон напрямую.
|
||||
- Настроить отступ по умолчанию для конкретного блока.
|
||||
|
||||
---
|
||||
|
||||
### 4.3. Текущий проект
|
||||
Настройки внешнего вида проекта:
|
||||
- Название проекта (в левом верхнем углу).
|
||||
- Цвет акцентов (через палитру или HEX).
|
||||
- Логотип проекта (загрузка изображения).
|
||||
|
||||
Логотип хранится в настройках проекта.
|
||||
|
||||
---
|
||||
|
||||
### 4.4. Быстрые блоки
|
||||
- Выбор блоков, которые появятся слева как быстрые кнопки.
|
||||
- Можно добавлять/удалять элементы.
|
||||
|
||||
---
|
||||
|
||||
### 4.5. Новый проект
|
||||
- Создание нового проекта.
|
||||
- Каждый проект имеет собственный `block.pug`, настройки, пресеты и сборки.
|
||||
|
||||
---
|
||||
|
||||
## 5. Пресеты
|
||||
|
||||
Пресет — это сохранённая сборка письма.
|
||||
|
||||
### Как работают пресеты
|
||||
- Сохраняются через иконку дискеты в шапке.
|
||||
- Открываются через страницу «Пресеты».
|
||||
- При сохранении, если имя уже существует — система спрашивает, **обновить или создать новый**.
|
||||
- При открытии пресета его имя автоматически подставляется в поле сохранения.
|
||||
|
||||
### На странице пресетов
|
||||
- Отображаются название и дата/время сохранения.
|
||||
- Есть поиск по названию.
|
||||
- Есть сортировка: сначала новые / сначала старые.
|
||||
|
||||
---
|
||||
|
||||
## 6. Подсказки и наведение
|
||||
|
||||
Все кнопки и поля имеют всплывающие подсказки (`title`), чтобы быстро понимать назначение элемента.
|
||||
|
||||
---
|
||||
|
||||
## 7. Выгоды использования конструктора
|
||||
|
||||
- **Быстрее сборки** — письмо собирается за минуты.
|
||||
- **Нет ошибок в структуре Pug** — редактируются только нужные фрагменты.
|
||||
- **Один интерфейс для всех проектов**.
|
||||
- **Удобное сохранение и повторное использование** через пресеты.
|
||||
- **Гибкая настройка под разные команды и бренды**.
|
||||
|
||||
---
|
||||
|
||||
## 8. Типовые сценарии
|
||||
|
||||
### 8.1. Быстрая сборка письма с нуля
|
||||
1) Перейдите в «Сборка».
|
||||
2) Добавьте блоки через быстрые кнопки или выпадающий список.
|
||||
3) Заполните поля (текст, ссылки, ID товаров).
|
||||
4) Проверьте итоговый Pug справа.
|
||||
5) Скопируйте или скачайте итоговый файл.
|
||||
|
||||
### 8.2. Сборка письма по шаблону (пресету)
|
||||
1) Откройте страницу «Пресеты».
|
||||
2) Найдите нужный пресет через поиск.
|
||||
3) Нажмите «Открыть».
|
||||
4) Отредактируйте детали и сохраните обратно.
|
||||
|
||||
### 8.3. Обновление существующего пресета
|
||||
1) Откройте пресет.
|
||||
2) Внесите изменения.
|
||||
3) Нажмите иконку дискеты — имя пресета подставится автоматически.
|
||||
4) Подтвердите обновление в диалоге.
|
||||
|
||||
### 8.4. Настройка быстрых блоков
|
||||
1) Перейдите в «Настройки» → «Быстрые блоки».
|
||||
2) Выберите нужные блоки и нажмите «Добавить».
|
||||
3) Удалите ненужные кнопки через «×».
|
||||
4) Эти кнопки появятся слева в «Сборке».
|
||||
|
||||
### 8.5. Добавление абзацев в текстовом блоке
|
||||
1) Откройте блок «Текст».
|
||||
2) Нажмите «Абзац».
|
||||
3) Заполните новый пункт текста.
|
||||
4) При необходимости удалите абзац кнопкой «×».
|
||||
|
||||
### 8.6. Работа со списками
|
||||
1) Добавьте блок «Маркированный список» или «Нумерованный список».
|
||||
2) Заполните первый пункт.
|
||||
3) Добавьте новые пункты кнопкой «Пункт».
|
||||
4) Удалите лишние пункты кнопкой «×».
|
||||
|
||||
### 8.7. Создание нового проекта
|
||||
1) Откройте «Настройки» → «Новый проект».
|
||||
2) Введите имя проекта, нажмите «Добавить».
|
||||
3) Загрузите `block.pug` для нового проекта.
|
||||
4) Настройте быстрые блоки, цвета и поля.
|
||||
|
||||
---
|
||||
|
||||
Если нужно — могу добавить в интерфейс отдельную страницу «Справка» с этим текстом.
|
||||
Reference in New Issue
Block a user