d7680357af
- remove stale docs/admin-frontend-spec.md (old Express/EJS admin), unused templates/ (SmartAdmin copy), dead scripts/sync-agents.cjs, committed dev.pid - add docs/API.md (admin REST API reference) and docs/DATABASE.md (DB schema) - refresh .env.example: drop stale ADMIN_PORT/SHOP_CONTAINER, add ADMIN_URL, HEALTH_PORT, DEFAULT_LANGUAGE, CHATBOT_API_* - add npm run lint so Gitea workflows pass - rebrand web-testing suite from APAW to telegram-shop
208 lines
13 KiB
Markdown
208 lines
13 KiB
Markdown
# Telegram Shop — Admin API Reference
|
||
|
||
Актуальная документация по REST API админ-панели (`admin-next/`, Next.js 16 + Prisma).
|
||
|
||
- **Базовый URL**: `http://<host>:3000`
|
||
- **Формат**: JSON (`Content-Type: application/json`)
|
||
- **Аутентификация**: cookie `admin_token` (httpOnly, 24ч), устанавливается через `POST /api/auth/login`
|
||
|
||
## Аутентификация
|
||
|
||
| Метод | Путь | Описание |
|
||
|---|---|---|
|
||
| POST | `/api/auth/login` | Вход по токену. Body: `{ "token": "..." }`. Rate-limit: 5 попыток / 15 мин на IP (429). Устанавливает cookie `admin_token` |
|
||
| GET | `/api/auth/session` | Проверка сессии. Ответ: `{ "role": "admin" \| "super_admin" }` (401 если нет/просрочен) |
|
||
| POST | `/api/auth/logout` | Выход, удаляет cookie |
|
||
|
||
### Роли
|
||
|
||
- `admin` — обычный администратор
|
||
- `super_admin` — доступ к seed-фразам, экспорту, импорту, очистке БД
|
||
|
||
Роль определяется при входе: если `SUPER_ADMIN_SECRET` не задан или равен `ADMIN_SECRET` — все админы получают `super_admin`. Иначе роль `super_admin` даёт только вход по `SUPER_ADMIN_SECRET`.
|
||
|
||
**Все эндпоинты ниже требуют cookie `admin_token`** (иначе 401). Эндпоинты с пометкой 🔒 требуют роль `super_admin` (иначе 403).
|
||
|
||
## Дашборд и статистика
|
||
|
||
### GET `/api/stats/dashboard`
|
||
Сводная статистика для дашборда:
|
||
- counts: `totalUsers`, `totalProducts`, `totalPurchases`, `totalSubcategories`, `bannedUsers`, `activeWallets`
|
||
- статусы покупок: `completedPurchases`, `pendingPurchases`, `cancelledPurchases`
|
||
- метрики: `totalRevenue` (сумма completed), `aov`, `conversionRate`
|
||
- временные ряды: `revenueByDay`, `purchasesByDay`, `newUsersByDay` (последние 30 дней)
|
||
- `topProducts`, `recentPurchases`, `recentUsers`
|
||
|
||
## Каталог
|
||
|
||
### GET `/api/catalog/tree`
|
||
Полное дерево каталога: локации, категории, подкатегории с `_count` (вложенные сущности).
|
||
|
||
### Локации
|
||
|
||
| Метод | Путь | Описание |
|
||
|---|---|---|
|
||
| GET | `/api/locations/bulk` | Список локаций (с `_count` категорий/товаров) |
|
||
| POST | `/api/locations/bulk` | Создать. Body: `{ country, city, district }` |
|
||
| PUT | `/api/locations/[id]` | Обновить. Body: `{ country?, city?, district? }` |
|
||
| PATCH | `/api/locations/[id]` | Переключить `is_active` (0/1) |
|
||
| DELETE | `/api/locations/[id]` | Удалить (409 если есть связанные сущности) |
|
||
|
||
### Категории
|
||
|
||
| Метод | Путь | Описание |
|
||
|---|---|---|
|
||
| GET | `/api/categories/bulk` | Список категорий (с локацией и `_count`) |
|
||
| POST | `/api/categories/bulk` | Создать. Body: `{ name, locationId }` |
|
||
| PUT | `/api/categories/[id]` | Обновить. Body: `{ name?, locationId? }` (409 при дубликате в локации) |
|
||
| PATCH | `/api/categories/[id]` | Переключить `is_active` |
|
||
| DELETE | `/api/categories/[id]` | Удалить (409 если есть связанные сущности) |
|
||
|
||
### Подкатегории
|
||
|
||
| Метод | Путь | Описание |
|
||
|---|---|---|
|
||
| GET | `/api/subcategories/bulk` | Список подкатегорий |
|
||
| POST | `/api/subcategories/bulk` | Создать. Body: `{ name, categoryId }` |
|
||
| PUT | `/api/subcategories/[id]` | Обновить. Body: `{ name?, categoryId? }` |
|
||
| PATCH | `/api/subcategories/[id]` | Переключить `is_active` |
|
||
| DELETE | `/api/subcategories/[id]` | Удалить |
|
||
|
||
### Товары
|
||
|
||
| Метод | Путь | Описание |
|
||
|---|---|---|
|
||
| GET | `/api/products/bulk` | Список. Query: `loc`, `cat`, `sub`, `search`, `page`, `limit` (≤100). Ответ: `{ data, total, page, limit }` |
|
||
| POST | `/api/products/add` | Создать. Body: `{ locationId, categoryId, subcategoryId?, name, description?, privateData?, price, quantityInStock?, photoUrl?, hiddenPhotoUrl?, hiddenCoordinates?, hiddenDescription?, isMono? }`. Обязательны: `locationId, categoryId, name, price`. `isMono=1` → `quantityInStock=999999` |
|
||
| GET | `/api/products/[id]` | Детали товара (с category, subcategory, location) |
|
||
| PUT | `/api/products/[id]` | Обновить (частично) |
|
||
| DELETE | `/api/products/[id]` | Удалить |
|
||
| POST | `/api/products/[id]/clone` | Клонировать (имя получает суффикс `(Copy)`) |
|
||
|
||
## Пользователи
|
||
|
||
| Метод | Путь | Описание |
|
||
|---|---|---|
|
||
| GET | `/api/users/bulk` | Список. Query: `search` (username/telegramId), `status` (0/2), `page`, `limit` (≤100). Ответ: `{ data, total, page, limit }` |
|
||
| GET | `/api/users/[id]` | Детали: пользователь + кошельки + последние 20 покупок + связанный лид |
|
||
| POST | `/api/users/[id]` | Обновить (username, country, city, district, notes и т.д.) |
|
||
| PATCH | `/api/users/[id]` | Переключить `status` (0=active, 2=blocked) |
|
||
| POST | `/api/users/[id]/adjust-balance` | Изменить баланс. Body: `{ amount: number, currency: "total_balance" \| "bonus_balance" }`. Пишет audit-запись |
|
||
| POST | `/api/users/batch-status` | Массово сменить статус. Body: `{ userIds: number[], newStatus: 0 \| 2 }` |
|
||
|
||
## Кошельки
|
||
|
||
| Метод | Путь | Описание |
|
||
|---|---|---|
|
||
| GET | `/api/wallets/bulk` | Пользователи, у которых есть кошельки. Query: `search`. Ответ: `{ users, totalWallets, totalBalance }` |
|
||
| GET | `/api/wallets/[userId]` | Кошельки конкретного пользователя |
|
||
| GET | `/api/wallets/overview` | Сводка: суммы и количество по типам (BTC/LTC/ETH/USDT/USDC), последние 20 комиссионных выплат |
|
||
| GET | `/api/wallets/seeds` | 🔒 Seed-фразы всех кошельков (пишет audit `seed_phrase_viewed`) |
|
||
| GET | `/api/wallets/export-seeds` | 🔒 Экспорт seed-фраз в CSV (Content-Disposition: attachment) |
|
||
| POST | `/api/wallets/record-payment` | Записать комиссионную выплату. Body: `{ paidAmount: number, note? }` |
|
||
|
||
## Покупки
|
||
|
||
| Метод | Путь | Описание |
|
||
|---|---|---|
|
||
| GET | `/api/purchases/bulk` | Список. Query: `status` (pending/completed/cancelled), `from`, `to` (YYYY-MM-DD), `page`, `limit` (≤100). Ответ: `{ data, total, page, limit }` |
|
||
| PATCH | `/api/purchases/[id]` | Сменить статус. Body: `{ status: "completed" \| "cancelled" }`. Только для `pending` |
|
||
| POST | `/api/purchases/batch-status` | Массово. Body: `{ purchaseIds: number[], status: "completed" \| "cancelled" }` (обновляет только pending) |
|
||
|
||
## Транзакции
|
||
|
||
| Метод | Путь | Описание |
|
||
|---|---|---|
|
||
| GET | `/api/transactions/bulk` | Список. Query: `userId`, `page`, `limit` (≤100, по умолчанию 20). Ответ: `{ data, total, page, limit }` |
|
||
|
||
## Лиды и чат
|
||
|
||
### Лиды
|
||
|
||
| Метод | Путь | Описание |
|
||
|---|---|---|
|
||
| GET | `/api/leads/bulk` | Список. Query: `search` (name/phone/email/telegram/telegramId), `status`, `page`, `limit` (≤100). Ответ: `{ data, total, page, limit }` |
|
||
| GET | `/api/leads/[id]` | Детали лида + связанный пользователь (баланс, покупки, кошельки) |
|
||
| PUT | `/api/leads/[id]` | Обновить (name, phone, email, telegram, status, notes, customFields и т.д.) |
|
||
| GET | `/api/leads/[id]/activity` | Активность: `{ hourly: number[24], yearly: { "YYYY-MM-DD": count }, total }` (по audit_log) |
|
||
| GET | `/api/leads/[id]/sessions` | Чат-сессии лида с распарсенными сообщениями |
|
||
|
||
### Чат (публичный виджет)
|
||
|
||
| Метод | Путь | Описание |
|
||
|---|---|---|
|
||
| POST | `/api/chat` | Отправить сообщение в чат-виджет. Body: `{ sessionId?, message, language?, device?, ip?, country? }`. Создаёт/обновляет `ChatSession`, извлекает данные лида (имя/телефон/email/telegram), вызывает ИИ-провайдера, при `chatbot_sleep_mode` отвечает sleep-сообщением |
|
||
|
||
### Оператор
|
||
|
||
| Метод | Путь | Описание |
|
||
|---|---|---|
|
||
| POST | `/api/operator` | Подключение/отключение оператора. Body: `{ sessionId, action: "connect" \| "disconnect", operatorName }`. Пишет audit `operator_connect` |
|
||
|
||
## Чатбот (настройки)
|
||
|
||
| Метод | Путь | Описание |
|
||
|---|---|---|
|
||
| GET | `/api/admin/chatbot` | Настройки чатбота из `site_settings` (ключи `chatbot_*`), API-ключ маскируется |
|
||
| PUT | `/api/admin/chatbot` | Обновить настройки. Валидация: `chatbot_temperature` 0–2, `chatbot_max_tokens` 50–4000, `chatbot_max_history` 1–50 |
|
||
| GET | `/api/chatbot/models?endpoint=&apiKey=` | Список моделей провайдера через OpenAI-совместимый `/models`. Без query — берёт сохранённые настройки. Поддерживает OpenAI (`data[]`) и Ollama (`models[]`) |
|
||
|
||
Ключи настроек чатбота (defaults):
|
||
`chatbot_enabled`, `chatbot_sleep_mode`, `chatbot_sleep_message`, `chatbot_system_prompt`, `chatbot_temperature` (0.7), `chatbot_max_tokens` (1024), `chatbot_max_history` (20), `chatbot_knowledge_base`, `chatbot_provider` (ollama), `chatbot_api_endpoint`, `chatbot_api_key`, `chatbot_model`.
|
||
|
||
## Аудит
|
||
|
||
| Метод | Путь | Описание |
|
||
|---|---|---|
|
||
| GET | `/api/audit/bulk` | Журнал аудита. Query: `page`, `limit` (≤200, по умолчанию 100), `userId`, `from`, `to`, `search`, `action`. Ответ: `{ data, total, page, limit }` |
|
||
|
||
## Локализация (i18n)
|
||
|
||
| Метод | Путь | Описание |
|
||
|---|---|---|
|
||
| GET | `/api/locales` | Все переводы: `{ en: {...}, es: {...}, de: {...} }` |
|
||
| PUT | `/api/locales` | Обновить ключ. Body: `{ lang, key, value }` |
|
||
|
||
## Настройки
|
||
|
||
| Метод | Путь | Описание |
|
||
|---|---|---|
|
||
| GET | `/api/settings` | Список настроек (секреты маскированы, список в `_masked`) |
|
||
| PUT | `/api/settings` | Обновить. Body: `{ key, value }`. Ответ: «Settings saved. Restart required.» |
|
||
| GET | `/api/settings/export` | Полный экспорт БД в JSON (users, wallets, purchases, categories, subcategories, locations, products, auditLogs, commissionPayments, userStates) |
|
||
| POST | `/api/settings/import` | 🔒 Импорт (заглушка: «Import not yet implemented») |
|
||
|
||
## Seed / Demo
|
||
|
||
| Метод | Путь | Описание |
|
||
|---|---|---|
|
||
| GET | `/api/seed/data` | Проверка: `{ seeded: boolean }` (есть ли пользователи) |
|
||
| POST | `/api/seed/demo` | Заполнить демо-данными. Body: `{ reauthToken }` (повторный ввод секрета) |
|
||
| POST | `/api/seed/clear` | 🔒 Очистить все данные. Body: `{ reauthToken }`. Пишет audit `clear_all` |
|
||
|
||
## Корневой
|
||
|
||
| Метод | Путь | Описание |
|
||
|---|---|---|
|
||
| GET | `/api` | Служебный ответ (health API) |
|
||
|
||
## Коды ошибок
|
||
|
||
| Код | Значение |
|
||
|---|---|
|
||
| 400 | Невалидный запрос / отсутствуют обязательные поля |
|
||
| 401 | Нет cookie `admin_token` или токен невалиден/просрочен |
|
||
| 403 | Недостаточно прав (нужен `super_admin`) |
|
||
| 404 | Сущность не найдена |
|
||
| 409 | Конфликт (дубликат, есть связанные записи) |
|
||
| 429 | Слишком много попыток входа |
|
||
| 500 | Внутренняя ошибка |
|
||
|
||
## Соглашения
|
||
|
||
- Пагинация: `page` (с 1), `limit` (кап зависит от эндпоинта: 50/100/200)
|
||
- Даты: `from`/`to` в формате `YYYY-MM-DD` (to инклюзивно до конца дня)
|
||
- `is_active`/`status` пользователей: `0` = активно, `2` = заблокировано
|
||
- Статусы покупок: `pending` / `completed` / `cancelled`
|
||
- Статусы лидов: `new` / `contacted` / `qualified` / `lost` / `spam`
|