VA.ASPEKTER/docs/02-developer-guide.md

# Aspekter VA — Руководство разработчика

## 1. Обзор архитектуры

Aspekter VA — монолитное web-приложение для сборки email-рассылок VipAvenue.

```
┌─────────────────────────────────────────────────┐
│                  Браузер                         │
│  App.svelte (UI) ←→ api.js (HTTP client)        │
└────────────────────┬────────────────────────────┘
                     │ HTTP
┌────────────────────▼────────────────────────────┐
│         builder (порт 6001)                      │
│  Vite dev server + API middleware                │
│  vite.config.js — весь backend (~1500 строк)     │
└────────────────────┬────────────────────────────┘
                     │ HTTP (внутренний)
┌────────────────────▼────────────────────────────┐
│      email-gen-api (порт 8787)                   │
│  server.js — Pug → HTML рендер                   │
│  email-gen/ — шаблоны, стили, миксины            │
└─────────────────────────────────────────────────┘
```

### Стек
- **Frontend:** Svelte 5 + Vite 7
- **Backend:** Vite middleware plugin (Node.js, встроен в dev-server)
- **Email рендер:** Pug шаблоны + email-templates (npm)
- **Хранение данных:** файловая система (JSON)
- **Инфраструктура:** Docker Compose, nginx reverse proxy

### Почему так устроено
Backend встроен как Vite middleware plugin, а не как отдельный сервер. Это значит:
- Один процесс, один порт
- HMR для фронтенда работает из коробки
- Нет CORS-проблем
- Но: vite.config.js не перезагружается через HMR — нужен `docker restart builder`

---

## 2. Структура файлов

```
VA.ASPEKTER/
├── docker-compose.yml          # Оркестрация контейнеров
├── deploy/
│   ├── nginx/                  # Nginx конфиг + лендинг
│   │   ├── nginx.conf
│   │   └── landing.html
│   └── email-gen-api/
│       ├── Dockerfile
│       └── server.js           # Standalone Pug render service
├── email-gen/                  # Git-репозиторий коллег (шаблоны)
│   └── emails/vipavenue/
│       ├── layout/layout.pug   # Базовый layout (width=600)
│       ├── blocks/block.pug    # Все блоки конструктора
│       ├── includes/mixins.pug # Pug миксины (товары, кнопки, preheader)
│       ├── css/style.css       # Стили (инлайнятся при рендере)
│       └── parts/              # Хедеры, футеры (по гендеру)
│           ├── header/
│           └── footer/
└── z51-pug-builder/            # Основное приложение
    ├── Dockerfile
    ├── package.json
    ├── vite.config.js          # ВЕСЬ BACKEND API (~1500 строк)
    ├── index.html              # Входная точка Vite
    ├── public/                 # Статика (favicon)
    ├── src/
    │   ├── App.svelte          # ВЕСЬ FRONTEND UI (~6400 строк)
    │   ├── app.css             # Все стили
    │   ├── main.js             # Точка входа Svelte
    │   └── lib/
    │       ├── api.js          # API-клиент (все эндпоинты)
    │       ├── parsing.js      # Парсинг Pug-блоков, миксинов, аргументов
    │       ├── spellcheck.js   # Проверка орфографии (Yandex Speller)
    │       └── utils.js        # Утилиты (normalizeNewlines, escapeRegExp, etc)
    └── data/                   # Данные (том Docker)
        ├── config.json         # Глобальный конфиг (Yonote токен, URL)
        ├── feed-cache.json     # Кэш товарного фида
        ├── render-cache.json   # Кэш рендера (Pug→HTML)
        ├── _system/
        │   ├── users.json      # Пользователи (логин, хэш пароля, роль)
        │   └── sessions.json   # Активные сессии
        └── vipavenue/          # Данные проекта
            ├── settings.json   # Настройки (блоки, FTP, гендер, фид)
            ├── block.pug       # Текущий пуг-файл конструктора
            ├── presets.json    # Пресеты
            ├── notes.json      # Заметки (индекс)
            ├── notes/          # Файлы заметок
            ├── stats.json      # Статистика времени
            ├── drafts/         # Черновики по пользователям
            └── letters/        # Карточки писем по пользователям
                └── {userId}/
                    ├── letters.json    # Индекс писем
                    ├── {id}.json       # Данные письма
                    └── {id}.history.json # История снимков
```

---

## 3. Docker — контейнеры и тома

### Контейнеры

| Контейнер | Образ | Порт | Назначение |
|---|---|---|---|
| `builder` | z51-pug-builder/Dockerfile | 6001→5173 | Vite dev server + API |
| `email-gen-api` | deploy/email-gen-api/Dockerfile | (внутренний) 8787 | Pug→HTML рендер |
| nginx | (отдельно) | 80/443 | Reverse proxy |

### Тома builder

| Хост | Контейнер | Режим | HMR? |
|---|---|---|---|
| `./z51-pug-builder/src` | `/app/src` | rw | ✅ Мгновенно |
| `./z51-pug-builder/vite.config.js` | `/app/vite.config.js` | rw | ❌ Нужен restart |
| `./z51-pug-builder/data` | `/app/data` | rw | — |
| `./email-gen` | `/email-gen` | rw | ❌ Нужен build |

### Тома email-gen-api

| Хост | Контейнер |
|---|---|
| `./email-gen` | `/workspace/email-gen` (rw) |
| Named volume | `/workspace/email-gen/node_modules` |

### Правила пересборки (КРИТИЧЕСКИ ВАЖНО)

**`docker compose build && docker compose up -d` нужен при:**
- Изменения в `email-gen/` (pug шаблоны, миксины, стили)
- Изменения в `deploy/email-gen-api/server.js`
- Изменения в `z51-pug-builder/Dockerfile`
- Изменения в `z51-pug-builder/package.json` (новые зависимости)

**`docker compose restart builder` нужен при:**
- Изменения в `z51-pug-builder/vite.config.js`

**Ничего не нужно (HMR подхватит):**
- Изменения в `z51-pug-builder/src/` (App.svelte, app.css, lib/*.js)

> **НЕ использовать** `docker cp` или `docker exec` для правки исходников на проде. Только редактировать на хосте, тома примонтированы.

---

## 4. Backend API — все эндпоинты

Весь API реализован в `vite.config.js` как Vite middleware plugin.

### Авторизация (без аутентификации)

| Метод | URL | Описание |
|---|---|---|
| POST | `/api/auth/login` | Вход: `{login, password}` → cookie `va_token` |
| POST | `/api/auth/logout` | Выход: удаляет cookie |
| GET | `/api/auth/me` | Текущий пользователь (или 401) |
| PUT | `/api/auth/preferences` | Сохранить тему/activePage/zoom |

### Администрирование (role: admin)

| Метод | URL | Описание |
|---|---|---|
| GET | `/api/admin/users` | Список пользователей |
| POST | `/api/admin/users` | Создать: `{login, password, name, role}` |
| PUT | `/api/admin/users/:id` | Обновить пользователя |
| DELETE | `/api/admin/users/:id` | Удалить (нельзя удалить себя) |

### Проект (все требуют аутентификации)

| Метод | URL | Описание |
|---|---|---|
| GET | `/api/projects` | Список проектов (всегда `["vipavenue"]`) |
| GET | `/api/project/:name` | Данные проекта (блок, настройки, черновик, пресеты, письма, заметки) |
| PUT | `/api/project/:name/block` | Сохранить block.pug |
| PUT | `/api/project/:name/block-custom` | Сохранить кастомный блок |
| PUT | `/api/project/:name/settings` | Сохранить настройки |
| PUT | `/api/project/:name/draft` | Сохранить черновик |
| PUT | `/api/project/:name/presets` | Сохранить пресеты |

### Письма

| Метод | URL | Описание |
|---|---|---|
| GET | `/api/project/:name/letter/:id` | Получить письмо |
| PUT | `/api/project/:name/letter` | Сохранить: `{id, ...data}` |
| DELETE | `/api/project/:name/letter/:id` | Удалить |
| GET | `/api/project/:name/letter/:id/history` | История снимков |
| PUT | `/api/project/:name/letter/:id/history` | Добавить снимок |

### Заметки

| Метод | URL | Описание |
|---|---|---|
| GET | `/api/project/:name/notes` | Индекс заметок |
| PUT | `/api/project/:name/notes` | Сохранить индекс |
| GET | `/api/project/:name/note/:id` | Получить заметку |
| PUT | `/api/project/:name/note` | Сохранить: `{id, ...data}` |
| DELETE | `/api/project/:name/note/:id` | Удалить |

### Рендер email

| Метод | URL | Описание |
|---|---|---|
| POST | `/api/project/:name/render-email` | Рендер Pug→HTML. Body: `{projectSlug, pug, preheader, gender}` |

**Цепочка рендера:**
1. Frontend отправляет Pug-код + preheader + gender
2. Backend формирует hash, проверяет кэш
3. Если кэш-промах → отправляет в email-gen-api
4. email-gen-api: записывает `letters/let.pug`, генерирует `html.pug`, запускает `email-templates` → `public/index.html`
5. Backend читает HTML, обрабатывает Mindbox-теги (подставляет товары), применяет nowrap
6. Возвращает `{html, previewHtml, unavailableProducts}`

### Товарный фид

| Метод | URL | Описание |
|---|---|---|
| POST | `/api/project/:name/feed-refresh` | Очистить кэш фида, перезагрузить |
| POST | `/api/project/:name/feed-lookup` | Найти товары по ID: `{ids: [...]}` |
| POST | `/api/project/:name/feed-suggest` | Подобрать замену: `{productId, excludeIds, search}` |

Фид кэшируется на 3 часа. XML парсится regex-ом (не DOM), поддерживается windows-1251.

### FTP/SFTP

| Метод | URL | Описание |
|---|---|---|
| POST | `/api/project/:name/ftp/test` | Проверить подключение |
| POST | `/api/project/:name/ftp/upload` | Загрузить файл: `{imageData, fileName, folder}` |
| POST | `/api/project/:name/ftp/list` | Список файлов: `{folder}` |
| POST | `/api/project/:name/ftp/delete` | Удалить файл: `{folder, fileName}` |

### Прочее

| Метод | URL | Описание |
|---|---|---|
| GET | `/api/config` | Глобальный конфиг (Yonote, upload URL) |
| PUT | `/api/config` | Сохранить конфиг |
| GET | `/api/yonote/status` | Статус подключения Yonote |
| GET | `/api/yonote/databases` | Список баз Yonote |
| GET | `/api/yonote/database/:id/properties` | Свойства базы |
| GET | `/api/yonote/database/:id/rows` | Строки базы |
| POST | `/api/yonote/row/update` | Обновить строку: `{rowId, values}` |
| POST | `/api/upload-image` | Загрузить изображение: `{imageData, fileName}` |
| POST | `/api/check-links` | Проверить ссылки: `{urls: [...]}` |
| GET | `/api/parts-files` | Список pug-файлов из parts/ |
| GET | `/api/parts-file-read?path=...` | Прочитать parts-файл |
| POST | `/api/parts-file-write` | Записать parts-файл |
| GET | `/api/project/:name/stats` | Статистика проекта |
| POST | `/api/project/:name/stats` | Сохранить запись статистики |
| GET | `/api/stats` | Вся статистика (все проекты) |

---

## 5. Frontend — архитектура

### Общая структура

Весь UI — один файл `App.svelte` (~6400 строк). Это монолит. Причина — проект начинался как прототип и вырос.

### Ключевые модули (lib/)

**api.js** — HTTP-клиент. Все функции `api*()` вызывают `apiRequest()` который делает `fetch()` с `Content-Type: application/json` и обрабатывает ошибки.

**parsing.js** — парсинг Pug-кода:
- `parseBlocks(text)` — разбивает Pug на блоки по `//` комментариям
- `buildBaseSchema(content, blockName, mixinRules)` — строит схему полей блока (какие поля редактируемые)
- `parseSections(content)` — разбивает блок на секции для drag-n-drop
- `findMixinArgRange(line, argIndex)` — находит позицию аргумента миксина в строке
- `extractMixinArgValue()` / `replaceMixinArgQuoted()` — чтение/запись аргументов

**spellcheck.js** — `checkSpelling(text)` отправляет в Yandex Speller, `injectSpellMarks(html, errors)` подсвечивает ошибки в превью.

**utils.js** — `normalizeNewlines()`, `escapeRegExp()`, `unquoteValue()`, `downloadFile()`.

### State management

Svelte 5 reactive `let` переменные. Ключевые группы:

| Группа | Переменные | Описание |
|---|---|---|
| UI | `activePage`, `theme`, `sidebarTab`, `settingsBlockIndex` | Состояние интерфейса |
| Данные | `assembledBlocks`, `presets`, `planRows`, `allStats` | Основные данные |
| Рендер | `renderedHtml`, `previewHtml`, `autoRenderTimer` | Результат рендера |
| Гендер | `currentGenderVersion`, `segmentFlipped` | Гендерная сегментация |
| Фид | `feedProducts`, `unavailableProducts` | Товары |
| Письма | `currentLetterId`, `letterName` | Текущее письмо |
| Настройки | `settings` | settings.json проекта |

### Ключевые функции

| Функция | Назначение |
|---|---|
| `loadProject()` | Загрузка проекта при старте |
| `rebuildOutput()` | Пересборка Pug из блоков → рендер |
| `renderEmail()` | Отправка Pug на сервер для рендера |
| `assembleGenderVersion(target)` | Сборка гендерной версии |
| `flipSegmentOrder()` | Переключение порядка блоков (⇅) |
| `addBlock(name)` / `removeBlock(id)` | Управление блоками |
| `updateBlockContent(id, content)` | Обновление содержимого блока |
| `saveDraft()` | Автосохранение черновика |
| `copyHtml()` | Копирование HTML в буфер |
| `handlePreviewElementClick(data)` | Клик по элементу в превью → фокус на поле |

### Реактивные вычисления ($:)

```javascript
$: settingsBlockName = allBlocks[settingsBlockIndex]?.name
$: settingsTemplate = getEffectiveTemplate(settingsBlockName)
$: baseSchema = buildBaseSchema(settingsTemplate, settingsBlockName, ...)
$: allBlocks = [...blockTemplates, ...customBlocksList]
$: productOptionsList = (settings.productOptions || []).map(...)
```

---

## 6. Email rendering pipeline

### Полная цепочка

```
1. App.svelte: assembleGenderVersion() + rebuildOutput()
   ↓ Собирает Pug из блоков
2. App.svelte: apiRenderEmail(name, {projectSlug, pug, preheader, gender})
   ↓ HTTP POST
3. vite.config.js: /api/project/:name/render-email
   ↓ pugHash() → проверка кэша
   ↓ Если промах:
4. vite.config.js → HTTP POST email-gen-api:8787/render
   ↓ {projectSlug, pug, preheader, gender, genderPaths}
5. email-gen-api/server.js:
   a) Записывает letters/let.pug (содержимое из конструктора)
   b) rewriteHtmlPug() — генерирует html.pug с правильным header/footer
   c) renderWithNode() — вызывает email-templates (Pug → HTML)
   d) Читает public/index.html → возвращает HTML
6. vite.config.js:
   a) Кэширует HTML
   b) processMindboxTags() — подставляет товары из фида
   c) applyNowrap() — склеивает предлоги с nowrap-спанами
   d) Возвращает {html, previewHtml, unavailableProducts}
7. App.svelte: показывает превью в iframe
```

### Кэш рендера
- Ключ: `md5(slug + pug + gender + genderPaths)`
- Максимум 30 записей (LRU)
- Персистится в `data/render-cache.json`
- Инвалидируется при смене Pug-кода, гендера или путей header/footer

### Mindbox-обработка
- Замена `@{for...}@{end for}` блоков
- Извлечение ID товаров из `GetByValue('12345')`
- Подстановка данных из фида (цена, название, картинка, URL)
- Отслеживание недоступных товаров

### Nowrap-обработка
- Только для текстовых блоков (span с классом `h3`)
- Оборачивает `предлог + слово` в `<span style="white-space:nowrap">`
- Использует placeholder-подход чтобы избежать двойной обработки

---

## 7. Гендерная сегментация — техническая реализация

### Данные
```json
// settings.json → genderPaths
{
  "headerFemale": "./parts/header/header-woman",
  "headerMale": "./parts/header/header-man",
  "footerFemale": "./parts/footer/footer-woman",
  "footerMale": "./parts/footer/footer-man"
}
```

### Цепочка передачи gender

1. **App.svelte** → `apiRenderEmail(..., { gender: 'female'|'male' })`
2. **vite.config.js** → читает `genderPaths` из settings.json, форвардит в email-gen-api
3. **email-gen-api/server.js** → `rewriteHtmlPug(projectDir, preheader, gender, genderPaths)` — записывает `html.pug` с нужным include header/footer
4. Pug рендерит HTML с правильным header/footer

### Кэш
`pugHash(slug, pug, gender, genderPaths)` — gender и genderPaths включены в ключ, female/male кэшируются отдельно.

### Flip (⇅)
- `flipSegmentOrder()` в App.svelte
- Находит блок-разделитель с `swapCenter = true`
- Блоки до разделителя и после меняются местами
- `segmentFlipped` (bool) отслеживает состояние toggle

---

## 8. Авторизация и безопасность

### Аутентификация
- **Хэширование:** scrypt (salt 16 bytes, key length 64)
- **Сессии:** случайный токен 32 bytes hex, хранится в Map + файл sessions.json
- **Cookie:** `va_token`, HttpOnly, SameSite=Strict, Secure, Max-Age=7d
- **Brute-force:** 5 попыток на IP за 15 минут

### Middleware стек (порядок важен!)
1. Security headers (X-Content-Type-Options, X-Frame-Options, Referrer-Policy)
2. Auth endpoints (/api/auth/*) — без проверки сессии
3. CSRF проверка (origin/referer vs host)
4. Auth middleware — проверка cookie → req.user
5. Admin middleware (/api/admin/*) — проверка role=admin
6. Uploads middleware (/uploads/*) — статика с проверкой path traversal
7. API middleware — основные эндпоинты

### Защита от атак
- **Path traversal:** `sanitizeFileId()` для всех файловых ID, `getProjectDir()` проверяет startsWith
- **SSRF:** фильтрация приватных IP (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16)
- **CSRF:** проверка origin/referer на state-changing запросах
- **XSS:** не применимо (внутренний инструмент, HTML генерируется из шаблонов)

---

## 9. Настройки проекта (settings.json)

```json
{
  "globalSpacing": 40,
  "blocks": {
    "Текст": { "spacing": 20, "template": "..." },
    "Кнопка": { "spacing": 10 }
  },
  "genderPaths": {
    "headerFemale": "./parts/header/header-woman",
    "headerMale": "./parts/header/header-man",
    "footerFemale": "./parts/footer/footer-woman",
    "footerMale": "./parts/footer/footer-man"
  },
  "feedUrl": "https://...",
  "ftpConfig": {
    "host": "...",
    "port": 21,
    "user": "...",
    "password": "***",
    "protocol": "ftp",
    "remotePath": "/images",
    "publicUrl": "https://..."
  },
  "mixinRules": [
    { "mixin": "buttonRounded", "argIndex": 0, "type": "mixin-text", "label": "Текст кнопки" }
  ],
  "productOptions": [
    { "code": "showPrice:true", "label": "Показывать цену", "defaultEnabled": true }
  ],
  "customBlocks": [
    { "id": "...", "name": "Мой блок", "content": "..." }
  ]
}
```

---

## 10. email-gen — шаблоны (репозиторий коллег)

### Структура
```
email-gen/emails/vipavenue/
├── layout/layout.pug       # Основной layout, table width=600
├── blocks/block.pug        # Все блоки (//Текст, //Кнопка, //Товары, etc)
├── includes/mixins.pug     # Pug-миксины (+products, +buttonRounded, +preheader, etc)
├── css/style.css           # CSS (инлайнится при рендере)
└── parts/
    ├── header/             # Хедеры (header-woman.pug, header-man.pug, header-dark.pug)
    └── footer/             # Футеры (аналогично)
```

### Как добавить новый блок
1. Добавить секцию в `blocks/block.pug`:
   ```pug
   //Мой новый блок
   tr
     td.paddingWrapper
       +defaultTable("100%")
         tr
           td(align="center")
             span.font.h3.blackText Текст блока
   ```
2. Пересобрать контейнеры: `docker compose build && docker compose up -d`
3. Блок появится в конструкторе

### Preheader
- Миксин `+preheader(text)` в mixins.pug
- Формат: `{текст} <vk-snippet-end>&#10240;×130`
- `#MAILRU_PREHEADER_TAG#` в pug заменяется на `<vk-snippet-end>` в server.js

---

## 11. Деплой

### Сервер
- IP: определяется из конфига
- Проект: `/opt/va/` (или аналогичный путь)
- Nginx: reverse proxy → localhost:6001

### Обновление кода

**Frontend (App.svelte, app.css, lib/*.js):**
```bash
# Файлы примонтированы через том — просто редактируй на хосте
# HMR подхватит автоматически
```

**Backend (vite.config.js):**
```bash
# Файл примонтирован, но Vite не перечитывает конфиг
docker compose restart builder
```

**Шаблоны email (email-gen/):**
```bash
docker compose build && docker compose up -d
```

**email-gen-api/server.js:**
```bash
docker compose build email-gen-api && docker compose up -d email-gen-api
```

### Первый запуск
```bash
git clone <repo>
cd VA.ASPEKTER
docker compose build
docker compose up -d
# Смотреть логи для временного пароля admin:
docker compose logs builder | grep "Временный пароль"
```

---

## 12. Известные особенности и ограничения

### Архитектурные
- **Монолит:** App.svelte ~6400 строк, vite.config.js ~1500 строк. Декомпозиция не проводилась.
- **Файловое хранилище:** нет БД, всё в JSON. Race condition при параллельных записях теоретически возможен (writeFileSync без блокировки).
- **Single-project:** код спроектирован под vipavenue. Мультипроектность убрана, но следы остались (PROJECT_NAME constant).

### Рендер
- **Кэш:** 30 записей LRU. При изменении CSS в email-gen кэш не инвалидируется (нужно очистить вручную или пересобрать).
- **Mindbox-теги:** парсятся regex-ом, не DOM. Если формат тегов изменится — сломается.
- **XML-фид:** парсится regex-ом. CDATA, вложенные теги с одинаковым именем — потенциально проблемны.

### Фронтенд
- **Svelte 5:** используется Svelte 5, но не все runes-паттерны применены. `ensureSchema()` мутирует block.schema напрямую.
- **MutationObserver:** на document.body с subtree=true. Debounce 200ms добавлен, но это всё равно потенциальная нагрузка.

### TODO (отмечено в коде)
- Google Sheets → Yonote API миграция (поиск по `TODO: YONOTE`)
- Пользовательские настройки (тема, zoom) частично перенесены на сервер, localStorage ещё используется как fallback
- Pull email-gen из git — функция запланирована, но не реализована

---

## 13. Conventions

### Именование
- localStorage ключи: `va-*` (va-active-page, va-theme, va-plan-cache, va-previewZoom)
- Cookie: `va_token`
- CSS классы: `va-spell` (spellcheck), `vaclick` (preview detection)
- Docker: `vaaspekter-builder-1`, `vaaspekter-email-gen-api-1`

### Форматирование кода
- 2 пробела отступ
- Одинарные кавычки в JS
- Без точек с запятой (semicolons) — inconsistent, в некоторых местах есть

### Git
- `email-gen/` — это отдельный git-репозиторий коллег, вложен как поддиректория (НЕ submodule)
- Основной репозиторий: `VA.ASPEKTER/`