From f90af4c78e0f38c9be98670659bf75e6c778fae0 Mon Sep 17 00:00:00 2001
From: NW <nw@softuniq.eu>
Date: Wed, 5 Aug 2026 12:07:56 +0100
Subject: [PATCH] docs(admin): frontend spec for admin panel + endpoint
 architecture (issue #131)

---
 docs/admin-frontend-spec.md | 750 ++++++++++++++++++++++++++++++++++++
 1 file changed, 750 insertions(+)
 create mode 100644 docs/admin-frontend-spec.md

diff --git a/docs/admin-frontend-spec.md b/docs/admin-frontend-spec.md
new file mode 100644
index 0000000..f5f8af8
--- /dev/null
+++ b/docs/admin-frontend-spec.md
@@ -0,0 +1,750 @@
+# Админ-панель Telegram Shop — Техническое описание фронтенда и API
+
+> **Назначение документа**: комплексное ТЗ для отдела фронтенда по реализации полноценного админ-кабинета поверх существующего бэкенда.
+> **Версия бэкенда**: v1.2.4 (2026-08-05)
+> **Дата**: 2026-08-05
+> **Статус**: актуально на момент передачи
+
+---
+
+## Оглавление
+
+1. [Обзор системы](#1-обзор-системы)
+2. [Технологический стек](#2-технологический-стек)
+3. [Архитектура развёртывания](#3-архитектура-развёртывания)
+4. [Доступ и безопасность](#4-доступ-и-безопасность)
+5. [Схема базы данных](#5-схема-базы-данных)
+6. [Карта эндпоинтов (полная)](#6-карта-эндпоинтов-полная)
+7. [Спецификация экранов](#7-спецификация-экранов)
+8. [Роли и права](#8-роли-и-права)
+9. [Формат данных](#9-формат-данных)
+10. [Существующие ограничения и подводные камни](#10-существующие-ограничения-и-подводные-камни)
+11. [Требования к новому фронтенду](#11-требования-к-новому-фронтенду)
+12. [API-контракты JSON (дополнить бэкенду)](#12-api-контракты-json-дополнить-бэкенду)
+13. [Чек-лист приёмки](#13-чек-лист-приёмки)
+
+---
+
+## 1. Обзор системы
+
+Telegram Shop — это **Telegram-бот-магазин** (Node.js) с **встроенной админ-панелью** на Express + EJS (шаблон SmartAdmin). Продажи идут через Telegram-бота, админка управляет всем магазином через браузер.
+
+Бизнес-сущности:
+
+| Сущность | Описание |
+|---|---|
+| **Users** | Покупатели из Telegram (id, ник, локация, статус, балансы, язык) |
+| **Locations** | Гео-иерархия: Страна → Город → Район (округа) |
+| **Categories / Subcategories** | Категории товаров, привязанные к локации; подкатегории внутри категории |
+| **Products** | Товары: цена, остаток, публичное фото, скрытый контент (фото/координаты/описание), private-заметки, цифровые (mono) |
+| **Purchases** | Заказы: пользователь, товар, валюта, tx_hash, количество, сумма, статус |
+| **Crypto Wallets** | Криптокошельки пользователей (BTC/LTC/ETH/USDT/USDC), с зашифрованными seed-фразами |
+| **Transactions** | Ончейн-транзакции пользователей |
+| **Commission payments** | Платежи комиссии владельцу платформы (SaaS-модель) |
+| **Audit log** | Журнал действий админов |
+| **Locales (i18n)** | JSON-файлы переводов бота (en/es/de), редактируются из админки |
+
+**Ключевой факт**: бот и админка живут в **одном процессе** и используют **одну SQLite-базу** (`db/shop.db`) — поэтому любые изменения в админке мгновенно видны боту и наоборот. Отдельного REST API **нет** — админка рендерит EJS на сервере и ходит в БД напрямую.
+
+---
+
+## 2. Технологический стек
+
+### Текущий (серверная часть — НЕ трогать без отдельной задачи)
+
+| Слой | Технология |
+|---|---|
+| Язык | Node.js ≥ 18 (ES Modules, `"type": "module"`) |
+| Web-фреймворк | Express 4 |
+| Шаблонизация | EJS + `express-ejs-layouts` (layout: `views/layout.ejs`) |
+| Шаблон UI | SmartAdmin (собственные партиалы в `views/partials/`, SCSS в `public/sass/`, сборка `smartapp.min.css`) |
+| БД | SQLite через `better-sqlite3` (обёртка `db.runAsync/allAsync/getAsync` в `src/config/database.js`) |
+| Загрузка файлов | Multer (только картинки jpeg/png/webp/gif, ≤ 10 МБ) в `uploads/` |
+| QR | `qrcode` (для seed-фраз) |
+| CDN-ресурсы | Bootstrap 5.3.2, FontAwesome 6.4.2 с jsDelivr (только в legacy-`layout.js`) |
+
+### Текущий фронтенд (что есть)
+
+- **Два параллельных набора вьюх**:
+  1. **EJS-шаблоны** (`views/*.ejs`) — используются роутами (dashboard, users, wallets, purchases, audit, settings, categories, locations, payment-wallets, seed, locales, catalog, products, product-edit, user-detail).
+  2. **JS-рендер-функции** (`views/*.js`) — legacy/дублирующий слой, возвращающий HTML-строки (`layout()`, `renderCatalog()`, `renderWalletLayout()` и т.д.). **На практике роуты рендерят EJS; JS-слой частично устарел** (дублирует catalog и wallets). Новый фронтенд их не использует.
+- Статика: Bootstrap 5 (SmartAdmin-тема), ApexCharts, jQuery, FontAwesome, собственные скрипты `public/scripts/`.
+- AJAX-вызовы есть только в нескольких местах (catalog-модалка, wallets-обновление балансов, locales).
+
+---
+
+## 3. Архитектура развёртывания
+
+```
+Internet
+   │
+   ├── HTTPS/LAN ───────────────► telegram_shop_prod :3001  (Express: бот + админка)
+   │
+   └── Tor Network ──► tor-proxy ──► HiddenService :80 ──► telegram_shop_prod :3001
+                                          (admin onion-адрес, работа без HTTPS)
+```
+
+- Единственный контейнер `telegram_shop_prod` (node:22-alpine) слушает порт `3001` (`ADMIN_PORT`).
+- Доступ к админке: напрямую `http://host:3001` или через `.onion` (Tor Browser).
+- Volume: `db/` (SQLite), `uploads/` (фото товаров, отдаются через `/uploads`), `.env` (только чтение).
+- WireGuard опционален (`WG_ENABLED`).
+
+**Следствие для фронтенда**: админка доступна по **HTTP без HTTPS** (в т.ч. через Tor). Это накладывает жёсткие ограничения:
+- нельзя использовать Secure-куки;
+- нельзя полагаться на Origin-проверку (Tor) — CSRF реализован вручную (см. §10);
+- весь JS/CSS должен быть либо локальным, либо закешированным (CDN может быть недоступен из Tor).
+
+---
+
+## 4. Доступ и безопасность
+
+### 4.1. Аутентификация (важно для фронта)
+
+Реализована в `src/admin/auth.js`. **Не JWT, а самописный HMAC-токен**:
+
+| Параметр | Значение |
+|---|---|
+| Кука | `admin_token` (httpOnly, `sameSite=false`, maxAge 24ч) |
+| Формат токена | `base64(payload).hmac_sha256(payload)` |
+| Payload | `{ role, jti, iat, exp }` |
+| Секрет | `ADMIN_SECRET` (env) |
+| Вход | POST `/login` с полем `token` (пароль = админ-токен) |
+| Выход | GET `/logout` |
+
+Роли (определяются **каким секретом залогинились**):
+
+| Роль | Условие | Права |
+|---|---|---|
+| `admin` | токен = `ADMIN_SECRET` | Все страницы, кроме seed-выгрузки |
+| `super_admin` | токен = `SUPER_ADMIN_SECRET` (если задан и ≠ ADMIN_SECRET) | + просмотр/экспорт seed-фраз, комиссии |
+
+При `SUPER_ADMIN_SECRET` не заданном — **все админы считаются супер-админами** (`config.SUPER_ADMIN_IDS` по умолчанию = `ADMIN_IDS`, но роли в админке задаются именно через секреты, не через `ADMIN_IDS`).
+
+Rate-limit логина: 5 попыток / 15 минут с IP.
+
+**Деструктивные действия** (`/seed/*`) требуют повторного ввода токена в поле `reauth_token` (middleware `requireReAuth`).
+
+### 4.2. Защита статики и загрузок
+
+- `/uploads/*` — только после `requireAuth`, заголовки `X-Content-Type-Options: nosniff` + `Content-Disposition: attachment` (фото не рендерятся inline из uploads, только скачивание).
+- Файлы uploads именуются `{timestamp}-{hex}.{ext}`, MIME-белый список.
+- CSRF: заглушка (`csrf.js` возвращает пустой токен и no-op) — **сознательно отключено ради совместимости с Tor**. См. §10.
+
+### 4.3. Существующие уязвимости, которые фронтенд не должен усугублять
+
+1. Нет реальной CSRF-защиты — все POST-формы уязвимы к cross-site-запросам. В новом фронте использовать токены, если бэкенд их вернёт, иначе как минимум не убирать подтверждения на деструктив.
+2. Некоторые вьюхи выводят данные с ручным `esc()`/`escapeHtml()`; часть EJS использует `<%= %>` (экранируется) — но есть места с `JSON.stringify` прямо в `<script>` (инъекция через данные). Новому фронту: **все данные из API экранировать на клиенте**.
+3. Пароль админа (ADMIN_SECRET) отправляется как обычное поле формы.
+4. Seed-фразы — сверхчувствительные данные; показывать только super_admin, с аудитом (logAudit: `seed_phrase_viewed`, `seed_phrase_qr_viewed`, `csv_seed_export`), желательно с подтверждением.
+
+---
+
+## 5. Схема базы данных
+
+Источник истины: `src/migrations/*.js` (001–012). SQLite, FK включены, WAL-режим.
+
+### 5.1. `users`
+
+| Колонка | Тип | Описание |
+|---|---|---|
+| `id` | INTEGER PK AUTOINCREMENT | Внутренний ID |
+| `telegram_id` | TEXT UNIQUE NOT NULL | ID в Telegram (строка!) |
+| `username` | TEXT | Ник |
+| `country` / `city` / `district` | TEXT | Гео из бота (снимок) |
+| `status` | INTEGER DEFAULT 0 | `0`=активен, `2`=заблокирован, прочее=удалён |
+| `total_balance` | REAL DEFAULT 0 | Основной баланс в USD |
+| `bonus_balance` | REAL DEFAULT 0 | Бонусный баланс в USD |
+| `language` | TEXT DEFAULT 'en' | Язык бота (`en`/`es`/`de`) |
+| `language_set` | INTEGER DEFAULT 0 | Флаг выбора языка |
+| `created_at` | DATETIME | Регистрация |
+
+### 5.2. `crypto_wallets`
+
+| Колонка | Тип | Описание |
+|---|---|---|
+| `id` | INTEGER PK | |
+| `user_id` | INTEGER FK→users (CASCADE) | |
+| `wallet_type` | TEXT | BTC/LTC/ETH/USDT/USDC (+ архивные с суффиксом `#N`, отфильтровываются `NOT LIKE '%#_%'`) |
+| `address` | TEXT | Адрес |
+| `derivation_path` | TEXT | Derivation path |
+| `mnemonic` | TEXT | **Зашифрована** (`encrypt(mnemonic, user_id)`) |
+| `balance` | REAL DEFAULT 0 | Кэш баланса (обновляется с блокчейна) |
+| `created_at` | DATETIME | |
+| UNIQUE | (user_id, wallet_type) | |
+
+### 5.3. `transactions`
+
+| Колонка | Тип | Описание |
+|---|---|---|
+| `id` | INTEGER PK | |
+| `user_id` | INTEGER FK | |
+| `wallet_type` | TEXT | |
+| `tx_hash` | TEXT | |
+| `amount` | REAL | |
+| `created_at` | DATETIME | |
+
+### 5.4. `locations`
+
+| Колонка | Тип | Описание |
+|---|---|---|
+| `id` | INTEGER PK | |
+| `country` | TEXT NOT NULL | |
+| `city` | TEXT NOT NULL | |
+| `district` | TEXT NOT NULL | Район (может быть пустой строкой) |
+| `is_active` | INTEGER NOT NULL DEFAULT 1 | Отключённые локации скрыты из бота |
+| `created_at` | DATETIME | |
+| UNIQUE | (country, city, district) | |
+
+### 5.5. `categories`
+
+| Колонка | Тип | Описание |
+|---|---|---|
+| `id` | INTEGER PK | |
+| `location_id` | INTEGER FK→locations (CASCADE) | |
+| `name` | TEXT NOT NULL | |
+| `is_active` | INTEGER NOT NULL DEFAULT 1 | |
+| `created_at` | DATETIME | |
+| UNIQUE | (location_id, name) | |
+
+### 5.6. `subcategories`
+
+| Колонка | Тип | Описание |
+|---|---|---|
+| `id` | INTEGER PK | |
+| `category_id` | INTEGER FK→categories (CASCADE) | |
+| `name` | TEXT NOT NULL | |
+| `is_active` | INTEGER NOT NULL DEFAULT 1 | |
+| `created_at` | DATETIME | |
+| UNIQUE | (category_id, name) | |
+
+### 5.7. `products`
+
+| Колонка | Тип | Описание |
+|---|---|---|
+| `id` | INTEGER PK | |
+| `location_id` | INTEGER FK→locations (CASCADE) | |
+| `category_id` | INTEGER FK→categories (CASCADE) | |
+| `subcategory_id` | INTEGER FK→subcategories (SET NULL) | |
+| `name` | TEXT NOT NULL | |
+| `description` | TEXT | Публичное описание |
+| `private_data` | TEXT | Внутренние заметки (не показывать) |
+| `price` | REAL NOT NULL CHECK (price > 0) | USD |
+| `quantity_in_stock` | INTEGER DEFAULT 0 | Остаток |
+| `photo_url` | TEXT | Публичное фото (URL или `/uploads/...`) |
+| `hidden_photo_url` | TEXT | Фото после покупки |
+| `hidden_coordinates` | TEXT | Координаты после покупки (`lat,lng`) |
+| `hidden_description` | TEXT | Текст после покупки |
+| `is_mono` | INTEGER DEFAULT 0 | **Цифровой товар**: бесконечный остаток (`1` ⇒ stock=999999, в боте продаётся без складских проверок) |
+| `created_at` | DATETIME | |
+
+### 5.8. `purchases`
+
+| Колонка | Тип | Описание |
+|---|---|---|
+| `id` | INTEGER PK | |
+| `user_id` | INTEGER FK→users (CASCADE) | |
+| `product_id` | INTEGER FK→products (CASCADE) | |
+| `wallet_type` | TEXT | Валюта оплаты |
+| `tx_hash` | TEXT | Хэш транзакции |
+| `quantity` | INTEGER CHECK (quantity > 0) | |
+| `total_price` | REAL CHECK (total_price > 0) | USD |
+| `purchase_date` | DATETIME | |
+| `status` | TEXT DEFAULT 'pending' | `pending` / `completed` / `cancelled` |
+
+### 5.9. `commission_payments`
+
+| Колонка | Тип | Описание |
+|---|---|---|
+| `id` | INTEGER PK | |
+| `total_balance_usd` | REAL NOT NULL | Снимок баланса на момент платежа |
+| `commission_rate` | REAL NOT NULL | % комиссии |
+| `commission_amount_usd` | REAL NOT NULL | Начисленная комиссия |
+| `paid_amount_usd` | REAL NOT NULL | Фактически уплачено |
+| `wallet_count` | INTEGER NOT NULL | Кошельков на момент |
+| `note` | TEXT | |
+| `created_at` | DATETIME | |
+
+### 5.10. `audit_log`
+
+| Колонка | Тип | Описание |
+|---|---|---|
+| `id` | INTEGER PK | |
+| `action` | TEXT NOT NULL | Слаг действия: `balance_adjust`, `csv_seed_export`, `seed_phrase_viewed`, `seed_phrase_qr_viewed`, `login` и т.д. |
+| `admin_id` | TEXT NOT NULL | Роль или ID |
+| `details` | TEXT | JSON-строка с контекстом |
+| `created_at` | DATETIME | |
+
+### 5.11. `user_states`
+
+| Колонка | Тип | Описание |
+|---|---|---|
+| `chat_id` | TEXT PK | |
+| `state_data` | TEXT | JSON состояния диалога бота |
+| `updated_at` | INTEGER | |
+
+---
+
+## 6. Карта эндпоинтов (полная)
+
+Базовый URL: `http://<host>:3001`. **Все маршруты, кроме `/login`, `/logout`, `/health`, требуют куки `admin_token`** (redirect на `/login`).
+
+Легенда: 🔓 — только super_admin · ⚠️ — деструктивно, требует `requireReAuth` · 📁 — загрузка файла · 🔁 — редирект после POST.
+
+### 6.1. Служебные
+
+| Метод | Путь | Назначение |
+|---|---|---|
+| GET | `/health` | Health-check → `{ status:'ok', uptime }` |
+| GET | `/login` | Страница логина (поле `token`) |
+| POST | `/login` | Вход; body `{ token }`; 429 при rate-limit; 401 неверный токен |
+| GET | `/logout` | Выход + инвалидация jti |
+| GET | `/error` (рендер) | Страница ошибки (глобальный обработчик) |
+
+### 6.2. Dashboard (роут: `routes/dashboard.js`)
+
+| Метод | Путь | Ответ |
+|---|---|---|
+| GET | `/` | EJS `dashboard` со статами и данными графиков |
+
+Query-параметры-флеши: `?seeded=1`, `?cleared=1` (показывают сообщения).
+
+**Данные, передаваемые в шаблон** (это и есть «API» дашборда):
+
+| Поле | Тип | Содержимое |
+|---|---|---|
+| `stats.totalUsers` | int | Всего пользователей |
+| `stats.totalProducts` | int | Всего товаров |
+| `stats.totalPurchases` | int | Всего покупок |
+| `stats.totalRevenue` | float | Выручка по `status='completed'` |
+| `stats.totalSubcategories` | int | Подкатегорий |
+| `stats.aov` | float | Средний чек (completed) |
+| `stats.conversionRate` | float % (1 знак) | Купившие / все пользователи × 100 |
+| `stats.completedPurchases` / `pendingPurchases` / `cancelledPurchases` | int | Сплит по статусам |
+| `chartData.days` | string[] | Последние 7 дат `YYYY-MM-DD` |
+| `chartData.days30` | string[] | Последние 30 дат |
+| `chartData.revenueData` | number[] | Выручка по дням (7д) |
+| `chartData.revenueData30` | number[] | Выручка по дням (30д) |
+| `chartData.usersData` | number[] | Новые пользователи по дням (7д) |
+| `chartData.topProducts` | `{name, qty, revenue}[]` | Топ-5 товаров за 30д (по кол-ву) |
+| `chartData.topSpenders` | `{username, spent}[]` | Топ-5 покупателей за 30д |
+| `chartData.revenueByCategory` | `{name, revenue}[]` | Выручка по категориям за 30д |
+| `chartData.topCountries` | `{country, count}[]` | Топ-5 стран из locations |
+| `activities` | `{type, id, username, item, total_price, date}` (или `{type:'audit', ...}`) | Последние 10 completed-покупок; если пусто — последние 10 audit_log |
+| `wallets` | `{wallet_type, count, total}[]` | Сводка кошельков по валютам (верхний регистр) |
+| `commission` | `{enabled, rate, due, currentCommission, lastPaidAmount, totalBalance}` | SaaS-комиссия: начислено/оплачено/к оплате |
+
+### 6.3. Catalog (роут: `routes/catalog.js` — дерево; `routes/catalogProducts.js` — товары)
+
+Дерево: Страна → Город → Район(location) → Категории → Подкатегории.
+
+| Метод | Путь | Body / Param | Назначение |
+|---|---|---|---|
+| GET | `/catalog` | query: `?loc=`, `?cat=`, `?sub=` (фильтры), `?msg=&msg_type=` (флеш) | EJS `catalog` + `treeHtml` + `products` |
+| POST | `/catalog/locations` | `country, city, district?` | + локация |
+| POST | `/catalog/locations/add-city` | `country, city` | + город (district='') |
+| POST | `/catalog/locations/add-district` | `country, city, district` | + район |
+| POST | `/catalog/locations/:id/update` | `country, city, district` | Переименование |
+| POST | `/catalog/locations/:id/toggle` | — | Вкл/выкл `is_active` |
+| POST | `/catalog/locations/:id/delete` | — | Удаление (запрещено при наличии категорий/товаров) |
+| POST | `/catalog/categories` | `name, location_id` | + категория |
+| POST | `/catalog/categories/json` | JSON `{name, location_id}` | + категория (AJAX, возвращает объект категории) |
+| POST | `/catalog/categories/:id/update` | `name, location_id?` | Переименование/перенос |
+| POST | `/catalog/categories/:id/toggle` | — | Вкл/выкл |
+| POST | `/catalog/categories/:id/delete` | — | Удаление (блокируется при товарах) |
+| POST | `/catalog/categories/:id/subcategories` | `name` | + подкатегория |
+| POST | `/catalog/categories/:id/subcategories/json` | JSON `{name}` | + подкатегория (AJAX) |
+| POST | `/catalog/subcategories/:id/update` | `name` | Переименование |
+| POST | `/catalog/subcategories/:id/toggle` | — | Вкл/выкл |
+| POST | `/catalog/subcategories/:id/delete` | — | Удаление (блокируется при товарах) |
+| POST | `/catalog/products` | multipart: поля товара + `photo_file`, `hidden_photo_file` | + товар |
+| POST | `/catalog/products/:id/edit` | multipart: поля товара + файлы | Обновление |
+| POST | `/catalog/products/:id/delete` | — | Удаление товара |
+| GET | `/catalog/products/:id/json` | — | **AJAX**: товар с `country, city, district, category_name, subcategory_name` |
+
+**Поля формы товара** (обязательные: `name, price>0, description, photo`):
+
+`name, price, quantity_in_stock, description, photo_url, hidden_photo_url, hidden_coordinates, hidden_description, private_data, category_id, subcategory_id?, location_id?, is_mono`
+
+Логика:
+- `is_mono=1` ⇒ `quantity_in_stock` принудительно `999999`.
+- Если `location_id` не передан — берётся `location_id` категории.
+- Файл заменяет URL (`photo_url`), если загружен.
+- JSON-ответы: `{error: '...'}` при 400.
+
+### 6.4. Products (роут: `routes/products.js` — упрощённый, дублирует catalog)
+
+| Метод | Путь | Назначение |
+|---|---|---|
+| GET | `/products` | EJS `products` (таблица до 100 товаров) |
+| POST | `/products` | + товар (без файлов; `photo_url` обязателен) |
+| GET | `/products/:id/edit` | EJS `product-edit` |
+| POST | `/products/:id/update` | Обновление |
+| POST | `/products/:id/delete` | Удаление |
+
+> **Рекомендация фронту**: считать **catalog** основным экраном товаров; `/products` — legacy-дубль.
+
+### 6.5. Categories (роут: `routes/categories.js` — плоские таблицы)
+
+| Метод | Путь | Назначение |
+|---|---|---|
+| GET | `/categories` | EJS `categories` + `subcategoriesByCategory`, флеши `?error=`, `?success=` |
+| POST | `/categories` | + категория (`name, location_id`) |
+| POST | `/categories/:id/update` | `name, location_id` |
+| POST | `/categories/:id/toggle` | Вкл/выкл |
+| POST | `/categories/:id/delete` | Удаление (блок при товарах; удаляет и подкатегории) |
+| POST | `/categories/:id/subcategories` | + подкатегория |
+| POST | `/categories/subcategories/:id/update` | `name` |
+| POST | `/categories/subcategories/:id/toggle` | Вкл/выкл |
+| POST | `/categories/subcategories/:id/delete` | Удаление (блок при товарах) |
+
+### 6.6. Locations (роут: `routes/locations.js`)
+
+| Метод | Путь | Назначение |
+|---|---|---|
+| GET | `/locations` | EJS `locations` с `category_count`, `product_count` |
+| POST | `/locations` | + локация |
+| POST | `/locations/:id/update` | `country, city, district` |
+| POST | `/locations/:id/toggle` | Вкл/выкл |
+| POST | `/locations/:id/delete` | Блок при категориях/товарах |
+
+### 6.7. Users (роут: `routes/users.js`)
+
+| Метод | Путь | Назначение |
+|---|---|---|
+| GET | `/users` | EJS `users` (последние 100, `ORDER BY id DESC`) |
+| GET | `/users/:id` | EJS `user-detail` + последние 20 покупок с `product_name` |
+| POST | `/users/:id/toggle-status` | Бан/разбан (`status` 0↔2) |
+| POST | `/users/:id/adjust-balance` | `amount, currency` (`total_balance`|`bonus_balance`); пишет audit `balance_adjust`; редирект на `/users/:id` |
+
+### 6.8. Wallets (роут: `routes/wallets.js`) 🔓 для seed-части
+
+| Метод | Путь | Назначение |
+|---|---|---|
+| GET | `/wallets` | EJS `wallets`; query `?user=`, `?seeds=1`; полный срез: `users` (с `wallet_count`), `wallets` выбранного юзера, `stats` (см. ниже) |
+| POST | `/wallets/record-payment` | `paid_amount, note` → запись в `commission_payments`; редирект `/wallets?payment=recorded` |
+| POST | `/wallets/export-seeds` 🔓 | CSV всех кошельков с расшифрованными seed-фразами; audit `csv_seed_export` |
+| GET | `/wallets/refresh-balances/:userId` | **AJAX**: обновить балансы с блокчейна; ответ JSON см. ниже |
+| GET | `/wallets/seed/:walletId` 🔓 | **AJAX**: расшифрованная seed-фраза + derivation; audit `seed_phrase_viewed` |
+| GET | `/wallets/seed-qr/:walletId` 🔓 | **AJAX**: PNG QR-код seed-фразы (image/png); audit `seed_phrase_qr_viewed` |
+
+**Формат `stats`** (передаётся в шаблон wallets):
+
+| Поле | Тип | Описание |
+|---|---|---|
+| `totals` | `{btc,ltc,eth,usdt,usdc}` | Суммы балансов по валютам |
+| `walletCounts` | `{...}` | Кол-во кошельков по валютам |
+| `usdValues` | `{...}` | USD-оценка по валютам (курсы с CoinGecko) |
+| `totalUsd` | float | Итог в USD |
+| `prices` | `{btc,ltc,eth}` | Текущие курсы |
+| `totalWallets` | int | Активных кошельков |
+| `commissionRate` | float | % |
+| `currentCommission` | float | Ставка × totalUsd |
+| `lastPaidAmount` | float | Последняя оплата |
+| `commissionDue` | float | max(0, current − last) |
+| `commissionEnabled` | bool | |
+| `commissionWallets` | `{BTC,LTC,USDT,USDC,ETH}` | Адреса для оплаты комиссии |
+| `totalUsers` | int | |
+| `payments` | `commission_payments[]` | Последние 20 платежей |
+| `seedsPaid` | bool | lastPaid ≥ current |
+
+**Формат `refresh-balances` (JSON)**:
+
+```json
+{
+  "wallets": [{ "id", "wallet_type", "address", "balance", "usdValue", "created_at" }],
+  "totalBalance": 123.45,
+  "balances": { "BTC": { "amount", "usdValue" }, ... },
+  "timestamp": "ISO",
+  "error": "Blockchain API unavailable — showing cached balances"   // опционально
+}
+```
+
+**Формат `seed/:walletId` (JSON)**: `{ walletId, walletType, address, derivationPath, mnemonic, userId, username }` (404 `{error}` при отсутствии).
+
+**Логика разблокировки seed**: кнопка «Unlock» доступна, только если `seedsPaid` (комиссия оплачена). Параметр `?seeds=1` открывает таблицу всех seed-фраз.
+
+### 6.9. Purchases (роут: `routes/purchases.js`)
+
+| Метод | Путь | Назначение |
+|---|---|---|
+| GET | `/purchases` | EJS `purchases` (последние 200, JOIN product_name) |
+
+### 6.10. Audit (роут: `routes/audit.js`)
+
+| Метод | Путь | Назначение |
+|---|---|---|
+| GET | `/audit` | EJS `audit` (последние 200 записей `audit_log`) |
+
+### 6.11. Settings (роут: `routes/settings.js`)
+
+| Метод | Путь | Назначение |
+|---|---|---|
+| GET | `/settings` | EJS `settings`; флеши `?saved=1`, `?error=1` |
+| POST | `/settings` | Обновление `.env` |
+
+**Редактируемые ключи** (только они; остальные строки `.env` не трогаются):
+
+`BOT_TOKEN, SUPPORT_LINK, ADMIN_IDS, SUPER_ADMIN_IDS, WG_ENABLED, WG_ENDPOINT, WG_ADDRESS, WG_PUBLIC_KEY, WG_DNS, ADMIN_PORT, ADMIN_URL, CATALOG_PATH, GITEA_API_URL`
+
+**Никогда не перезаписываются** (показываются как `•••••••`): `ENCRYPTION_KEY, ADMIN_SECRET, GITEA_TOKEN, WG_PRIVATE_KEY, WG_PRESHARED_KEY, COMMISSION_*`.
+
+⚠️ Изменения применяются только **после рестарта контейнера** (сообщение об этом на странице).
+
+### 6.12. Payment Wallets (роут: `routes/paymentWallets.js`)
+
+| Метод | Путь | Назначение |
+|---|---|---|
+| GET | `/payment-wallets` | EJS `payment-wallets` — **только чтение** конфига `COMMISSION_WALLETS` (адреса для уплаты комиссии владельцу) |
+
+### 6.13. Seed & Reset (роут: `routes/seed.js`) ⚠️ requireReAuth
+
+| Метод | Путь | Назначение |
+|---|---|---|
+| GET | `/seed` | EJS `seed` (форма с подтверждением токеном) |
+| POST | `/seed/seed-demo` | **Полная очистка БД + заливка демо-данных**. Body: `reauth_token` |
+| POST | `/seed/clear-all` | **Полная очистка всех таблиц**. Body: `reauth_token` |
+
+Очищаемые таблицы: `purchases, transactions, crypto_wallets, audit_log, user_states, products, subcategories, categories, users, locations, commission_payments` + сброс `sqlite_sequence`.
+
+### 6.14. Locales (роут: `routes/locales.js`)
+
+| Метод | Путь | Назначение |
+|---|---|---|
+| GET | `/locales` | EJS `locales` + `sections` (ключи верхнего уровня из `en.json`) |
+| POST | `/locales/save` | JSON `{lang, key, value}` (точечный путь, напр. `menu.shop`); запись в `src/i18n/locales/{lang}.json`; 400 при неверном `lang` |
+
+Языки: `en`, `es`, `de` (`AVAILABLE_LANGUAGES`). Структура файлов — вложенные объекты; ключ в запросе — dot-path.
+
+---
+
+## 7. Спецификация экранов
+
+### 7.1. Login (`/login`)
+- Одно поле `token` (пароль-токен), кнопка Submit.
+- Ошибки: `401 Invalid token`, `429 Too many attempts...` (15 мин).
+- После успеха — redirect `/`.
+- Подсказка: если `SUPER_ADMIN_SECRET` задан — вход с ним даёт роль super_admin.
+
+### 7.2. Dashboard (`/`)
+KPI-карточки:
+- Пользователи всего, Товары, Покупки всего, Выручка ($, completed), Средний чек ($), Конверсия (%), Сплит по статусам (completed/pending/cancelled), Подкатегории.
+
+Графики (данные готовы в `chartData`):
+1. Выручка 7 дней (line/area) — `days` × `revenueData`.
+2. Выручка 30 дней (line/area) — `days30` × `revenueData30`.
+3. Новые пользователи 7 дней (bar) — `days` × `usersData`.
+4. Топ-5 товаров (bar) — `topProducts`.
+5. Топ-5 покупателей (bar) — `topSpenders`.
+6. Выручка по категориям (pie/donut) — `revenueByCategory`.
+7. Топ-5 стран (bar) — `topCountries`.
+
+Блоки: Активность (последние покупки/аудит), Сводка кошельков по валютам, SaaS-комиссия (enabled/rate/due/последняя оплата).
+
+### 7.3. Catalog (`/catalog`) — самый сложный экран
+Две колонки:
+- **Слева — дерево**: accordion Страна → Город → Район → Категория → Подкатегория. У каждого узла:
+  - счётчик товаров (включая подкатегории),
+  - бейдж «Disabled» у неактивных,
+  - inline-формы: переименовать, вкл/выкл (⏻), добавить ребёнка, удалить (✕, с confirm).
+- **Справа — таблица товаров** (до 200): ID, фото (40×40), название, категория, подкатегория, цена $, остаток (∞ для mono), действия: ✎ Edit (модалка), ✕ Delete (confirm).
+- Фильтры через клик по узлам дерева (`?loc=`, `?cat=`, `?sub=`).
+- **Модалка товара** (Add/Edit): каскадные селекты Страна→Город→Район→(Категория фильтруется по району)→Подкатегория; inline-создание категории/подкатегории через `fetch` к `/json`-эндпоинтам; чекбокс «Digital Product (infinite stock)» блокирует поле остатка; загрузка 2 фото (public, hidden) или URL; поля скрытого контента (фото, координаты, описание) и private_data.
+- Флеш-сообщения: `?msg=` + `?msg_type=` (success/error/info).
+
+### 7.4. Products (`/products`) — legacy
+Простая таблица (ID, фото, название, категория, цена, остаток, действия) + формы Add/Edit на отдельных страницах. **Фронту: экран можно заменить ссылкой на Catalog.**
+
+### 7.5. Categories (`/categories`)
+Плоские таблицы: категории (с локацией и product_count) + подкатегории (сгруппированы по категориям). Действия: add/edit/toggle/delete. Ошибки через `?error=` (с счётчиком блокирующих товаров), успех через `?success=`.
+
+### 7.6. Locations (`/locations`)
+Таблица: Страна/Город/Район, category_count, product_count, is_active, действия add/edit/toggle/delete. Ошибки/успехи как у Categories. Заблокированное удаление — с подсказкой «Remove categories/products first».
+
+### 7.7. Users (`/users`, `/users/:id`)
+- Список (100): ID, Telegram ID, username, страна, город, статус (badge Active/Blocked/Deleted), баланс $, кнопки View и Ban/Unban.
+- Детальная (`/users/:id`): профиль + таблица покупок (20) + **форма корректировки баланса** (amount + выбор `total_balance`/`bonus_balance`) + audit-запись.
+
+### 7.8. Wallets (`/wallets`)
+- Слева: поиск + список пользователей (статус, число кошельков), выбор `?user=`.
+- Справа: карточка балансов выбранного (Main/Bonus/Available/Status), таблица кошельков (тип, адрес — клик=копировать, баланс 8 знаков, дата), кнопка «Refresh balances» (fetch `/wallets/refresh-balances/:userId`).
+- **Owner Summary** (для всех): Total USD, Users, Active Wallets, Commission Due; таблица «Balances by Currency»; блок комиссии: rate, total, full commission, last paid, due, форма «Record Payment» (paid_amount, note), адреса для оплаты (клик=копировать); таблица Payment History (delta между платежами).
+- **Seed Phrases** (super_admin, если комиссия оплачена): кнопка «Unlock», таблица всех seed-фраз (user, type, address, derivation, mnemonic — клик=копировать), кнопка «Export All Seeds as CSV» (`/wallets/export-seeds`). Если не оплачено — предупреждение и заблокированная кнопка.
+
+### 7.9. Purchases (`/purchases`)
+Таблица (200): ID, user (ссылка), product, qty, цена, валюта, дата, статус (badge completed/pending/failed). **Нет фильтров и действий — только просмотр.**
+
+### 7.10. Audit (`/audit`)
+Таблица (200): action, admin_id, details (JSON-строка), created_at. Только просмотр.
+
+### 7.11. Settings (`/settings`)
+Форма с секциями:
+- Bot: `BOT_TOKEN` (placeholder-маска), `SUPPORT_LINK`, `ADMIN_IDS`, `SUPER_ADMIN_IDS`.
+- WireGuard: `WG_ENABLED` (checkbox), `WG_ENDPOINT`, `WG_ADDRESS`, `WG_PUBLIC_KEY`, `WG_DNS`.
+- Admin: `ADMIN_PORT`, `ADMIN_URL`, `CATALOG_PATH`, `GITEA_API_URL`.
+- Только для чтения (маскированные `•••••••`): `ENCRYPTION_KEY`, `ADMIN_SECRET`, `GITEA_TOKEN`, `WG_PRIVATE_KEY`, `WG_PRESHARED_KEY`, `COMMISSION_*`.
+- Предупреждение: «Restart the application to apply changes».
+
+### 7.12. Payment Wallets (`/payment-wallets`)
+Таблица адресов комиссии (BTC/LTC/USDT/USDC/ETH) — только чтение; ссылка на Settings.
+
+### 7.13. Locales (`/locales`)
+- Таблица: строки = ключи из `en.json` (секции-заголовки), колонки = языки en/es/de.
+- Редактирование значения: inline (fetch POST `/locales/save` `{lang, key, value}`).
+- Требование: 3 языка всегда синхронны по набору ключей; добавление ключа в одном — добавить в остальных (200+ ключей).
+
+### 7.14. Seed & Reset (`/seed`)
+Две опасные кнопки: «Seed Demo Data» и «Clear All Data». Обе требуют повторный ввод токена (`reauth_token`). В UI — двойное подтверждение (модалка + поле токена), предупреждение о необратимости.
+
+---
+
+## 8. Роли и права
+
+| Возможность | admin | super_admin |
+|---|---|---|
+| Все страницы, кроме seed-выгрузки | ✅ | ✅ |
+| Просмотр/экспорт seed-фраз (`/wallets/seed*`, `export-seeds`) | ❌ (401/403) | ✅ |
+| Запись комиссионных платежей | ✅ (форма на /wallets) | ✅ |
+| Seed & Reset (`/seed/*`) | ✅ (с reauth) | ✅ (с reauth) |
+
+Middleware: `requireAuth` (все роуты после `/login`), `requireSuperAuth` (seed-эндпоинты), `requireReAuth` (seed/reset).
+
+---
+
+## 9. Формат данных
+
+- Деньги: USD, `REAL`. Выводить `$X.XX`.
+- Крипто-балансы: до 8 знаков, обрезать хвостовые нули.
+- Даты: `DATETIME` SQLite (`YYYY-MM-DD HH:MM:SS`, UTC). На клиенте конвертировать в локальное время.
+- Фото: абсолютный путь (например `/uploads/...`) или внешний URL. В таблицах — превью 40–50px.
+- Status пользователя: `0` активен, `2` заблокирован, иное — удалён.
+- Status покупки: `pending` | `completed` | `cancelled`.
+- `is_mono`: `1` = цифровой (бесконечный остаток, показывать ∞).
+- Флеш-сообщения: через query-параметры (`?msg=`, `?error=`, `?success=`, `?seeded=1`, `?cleared=1`, `?saved=1`, `?payment=recorded`).
+
+---
+
+## 10. Существующие ограничения и подводные камни
+
+1. **Нет REST API.** Всё — SSR EJS + формы + редкие fetch. Для полноценного SPA бэкенду нужны JSON-эндпоинты (предложены в §12) — **отдел фронтенда не должен проектировать свой API без согласования с бэкендом**.
+2. **CSRF отключён** (заглушка). Новая админка не должна полагаться на Origin/SameSite; если оставляем формы — обязательны серверные токены или хотя бы подтверждения на деструктив.
+3. **Работа через Tor**: нельзя полагаться на внешние CDN (Bootstrap/FontAwesome/ApexCharts должны быть локальными), нельзя требовать HTTPS/WSS, куки `Secure` не работают.
+4. **Нет пагинации** нигде (LIMIT 100/200 фиксирован). При росте данных списки «режутся» — фронт может предложить пагинацию, но это потребует новых query-параметров на бэкенде.
+5. **Дублирование каталога**: `/catalog` (богатый) и `/products` (бедный) — менять оба или убрать один (решение за продуктом).
+6. **Фото из uploads отдаются с `Content-Disposition: attachment`** — их нельзя показывать `<img>` inline из `/uploads/` (скачаются как файл). В таблицах товаров фото берутся из `photo_url`, который может указывать на внешний URL или `/uploads/...` — при `/uploads` превью не отобразится в браузере. Для галереи товаров нужно либо отдельный inline-эндпоинт, либо хранить публичные фото вне uploads (например, статика `public/img/products/`).
+7. **Нет нотификаций/вебхуков** — dashboard статичен до перезагрузки.
+8. **Settings перезаписывают `.env`** — изменения требуют рестарта; форма должна явно это сообщать.
+9. **Seed/Reset опасны** — полная очистка БД; в новом UI обязателен confirm + reauth (уже реализовано на бэкенде).
+10. **i18n-файлы — живые данные** админки; редактирование без синхронизации ключей ломает бота (fallback на `en`).
+11. Legacy JS-слой (`views/*.js`) частично дублирует EJS — **не использовать как источник истины**, ссылаться на роуты и EJS.
+
+---
+
+## 11. Требования к новому фронтенду
+
+### 11.1. Целевой стек (рекомендация)
+- SPA на Vue 3 или React (или продолжение SSR EJS, если команда не готова к SPA).
+- Все ассеты **локальные** (сборка в `public/dist`), без CDN — совместимость с Tor.
+- Адаптивность: админкой пользуются с десктопа и планшета.
+- Тёмная/светлая тема (SmartAdmin уже имеет темы — можно переиспользовать SCSS-переменные).
+- Charts: ApexCharts (уже есть в проекте) или ECharts.
+
+### 11.2. Обязательные экраны (приоритет)
+1. **Dashboard** — KPI + 7 графиков (данные в §6.2).
+2. **Catalog** — дерево + таблица товаров + модалка товара с каскадными селектами и загрузкой 2 фото.
+3. **Users + User detail** — список, бан/разбан, корректировка баланса.
+4. **Wallets** — пользователь + кошельки + Owner Summary + комиссия + seed (super_admin).
+5. **Purchases** — таблица со статусами.
+6. **Audit** — журнал.
+7. **Categories / Locations** — CRUD + toggle.
+8. **Settings** — форма .env с масками секретов.
+9. **Locales** — редактор переводов на 3 языка.
+10. **Seed & Reset** — подтверждённая деструктивная панель.
+11. **Login / Logout**.
+
+### 11.3. UI/UX-требования
+- Все деструктивные действия — confirm-модалка (не `window.confirm`).
+- Все флеш-сообщения — toast/alert с автоскрытием.
+- Каскадные select'ы — с загрузкой и disabled-состояниями.
+- Копирование адресов/seed — по клику с визуальной обратной связью «Copied!».
+- Пустые состояния («No products found», «No users», «No wallets yet»).
+- Загрузочные спиннеры на fetch-запросах.
+- Ошибки API (400/401/403/404/500) — понятные сообщения пользователю.
+- Валидация форм на клиенте (price>0, name required, photo required, amount>0) + серверная.
+- Хлебные крошки, поиск по меню (уже есть в SmartAdmin).
+- Индикация роли (admin/super_admin) в шапке; скрывать seed-раздел для обычных админов.
+
+### 11.4. Интеграционные требования
+- Авторизация: работа с кукой `admin_token`; при 401/403 от `/wallets/seed*` — редирект на `/login` или сообщение о недостатке прав.
+- Все POST-формы в SPA отправлять с `Content-Type: application/x-www-form-urlencoded` или `multipart/form-data` в зависимости от бэкенд-роута (см. §6).
+- Не вводить собственный роутинг API-путей — строго использовать карту §6 (или согласованные новые из §12).
+- Реализовать обработку флеш-query-параметров на клиенте.
+
+### 11.5. Что НЕ делать
+- Не разворачивать отдельный фронтенд-сервер (админка живёт в контейнере бота; статика отдаётся из `src/admin/public`).
+- Не менять схему БД без миграций и без бэкенда.
+- Не показывать seed-фразы не-super_admin.
+- Не загружать фото в произвольные пути — только через существующий multipart-роут `/catalog/products` (+ file input) или `/products`.
+
+---
+
+## 12. API-контракты JSON (дополнить бэкенду)
+
+Для SPA-режима предлагаются **новые** JSON-эндпоинты (требуют реализации на бэкенде — вне зоны ответственности фронта, но контракты фиксируем заранее). Все — под `requireAuth`, префикс `/api`.
+
+| Метод | Путь | Ответ |
+|---|---|---|
+| GET | `/api/stats` | Агрегат дашборда (поля из §6.2) |
+| GET | `/api/users?search=&page=&limit=` | Пагинированный список пользователей |
+| GET | `/api/users/:id` | Профиль + балансы |
+| POST | `/api/users/:id/toggle-status` | `{ok:true}` |
+| POST | `/api/users/:id/adjust-balance` | body `{amount, currency}` → `{ok:true, newBalance}` |
+| GET | `/api/catalog/tree` | Дерево (страна→город→район→категория→подкатегория) с is_active и счётчиками |
+| GET | `/api/products?loc=&cat=&sub=&page=&limit=` | Пагинированный список товаров |
+| GET | `/api/products/:id` | Товар целиком (вкл. скрытый контент и private_data) |
+| POST | `/api/products` | Создание (JSON или multipart) |
+| PUT | `/api/products/:id` | Обновление |
+| DELETE | `/api/products/:id` | Удаление |
+| GET | `/api/locations` | Список с counts |
+| POST/PUT/DELETE | `/api/locations...` | CRUD |
+| GET | `/api/categories` / `/api/subcategories` | Списки с counts |
+| POST/PUT/DELETE | `/api/categories...` | CRUD |
+| GET | `/api/purchases?status=&page=&limit=` | Пагинированные покупки с фильтром по статусу |
+| PATCH | `/api/purchases/:id/status` | Смена статуса (требует согласования с ботом — статусы влияют на доставку контента!) |
+| GET | `/api/wallets/overview` | Owner summary + комиссия + платежи |
+| GET | `/api/wallets?userId=` | Кошельки пользователя |
+| POST | `/api/wallets/refresh` | body `{userId}` → свежие балансы |
+| POST | `/api/wallets/record-payment` | body `{paidAmount, note}` |
+| GET | `/api/wallets/seeds` 🔓 | Список seed-фраз |
+| GET | `/api/wallets/seeds/:id` 🔓 | Одна seed-фраза |
+| GET | `/api/wallets/seeds/:id/qr` 🔓 | PNG QR |
+| GET | `/api/audit?page=&limit=` | Пагинированный аудит |
+| GET/POST | `/api/locales` | Чтение/сохранение ключей (как `/locales/save`) |
+| GET/PUT | `/api/settings` | Чтение маскированных / запись разрешённых ключей |
+| POST | `/api/seed/demo`, `/api/seed/clear` ⚠️ | с `reauth_token` |
+| GET | `/api/session` | Текущая роль (admin/super_admin) для условного рендера |
+
+⚠️ **Важно**: PATCH статуса покупки должен быть синхронизирован с `purchaseService` (доставка скрытого контента происходит при `completed`).
+
+---
+
+## 13. Чек-лист приёмки
+
+- [ ] Логин/логаут работают; роль super_admin корректно отображается.
+- [ ] Dashboard: все KPI и 7 графиков рендерятся без ошибок.
+- [ ] Catalog: дерево полностью управляемо (add/rename/toggle/delete на всех 4 уровнях), товары CRUD с загрузкой 2 фото, каскадные селекты, mono-флаг.
+- [ ] Users: список, детальная, бан/разбан, корректировка баланса с audit.
+- [ ] Wallets: выбор пользователя, обновление балансов (fetch), Owner Summary, запись комиссии, история платежей, seed-блок с правами и QR/CSV.
+- [ ] Purchases: таблица со статусами и ссылками на пользователей.
+- [ ] Audit: журнал читается, details парсится.
+- [ ] Categories/Locations: CRUD с блокировками удаления и понятными ошибками.
+- [ ] Settings: сохраняются только разрешённые ключи; секреты маскированы.
+- [ ] Locales: inline-редактирование всех 3 языков, dot-path ключей.
+- [ ] Seed & Reset: двойное подтверждение, reauth-токен, предупреждения.
+- [ ] Все деструктивные действия с confirm; все флеши; все пустые состояния.
+- [ ] Работает через Tor (без CDN-зависимостей), тёмная тема.
+- [ ] Нет утечек seed/private_data/масок в DOM для не-super_admin.
+- [ ] Нет XSS: все данные экранированы на клиенте (в т.ч. из `JSON` в `<script>`).
+
+---
+
+*Документ подготовлен на основе фактического кода: `src/admin/server.js`, `src/admin/routes/*.js`, `src/admin/auth.js`, `src/admin/views/*.ejs`, `src/migrations/*.js`, `src/config/*.js`, `src/services/*.js`. При изменении бэкенда — перегенерировать разделы 6–7.*