chore: repo cleanup + docs for admin API and DB schema (v1.2.8)

- 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
2026-08-09 00:22:22 +01:00
parent 338a700b3a
commit d7680357af
13 changed files with 517 additions and 1192 deletions
--- a/README.md
+++ b/README.md
@@ -70,8 +70,11 @@ curl -o /dev/null -w "%{http_code}\n" http://localhost:3000/login  # новая
 | `SUPER_ADMIN_IDS` | — | ID супер-админов |
 | `SUPPORT_LINK` | — | Ссылка на поддержку |
 | `DEFAULT_LANGUAGE` | — | Язык по умолчанию (`en`, `es`, `de`; по умолчанию `en`) |
+| `HEALTH_PORT` | — | Порт health-сервера бота (по умолчанию 3001) |
 | `SSH_HOST_IP` | — | Куда Tor перенаправляет SSH (по умолчанию host.docker.internal) |
-| `SHOP_CONTAINER` | — | Имя контейнера магазина (по умолчанию telegram_shop_prod) |
+| `SHOP_CONTAINER` | — | Имя контейнера админки (onion target; по умолчанию tg_shop_admin) |
+| `CHATBOT_API_ENDPOINT` | — | OpenAI-совместимый endpoint чатбота (fallback) |
+| `CHATBOT_API_KEY` | — | API-ключ чатбота (fallback) |
 | `WG_ENABLED` | — | `true` / `false` (по умолчанию `false`) |
 | `WG_PRIVATE_KEY` | — | Приватный ключ WireGuard |
 | `WG_PUBLIC_KEY` | — | Публичный ключ WireGuard |
@@ -287,37 +290,45 @@ src/i18n/
 ## Структура проекта

 ```
-├── src/
-│   ├── config/           # Конфигурация (БД, крипто)
-│   ├── context/          # Контекст и состояния бота
-│   ├── handlers/         # Обработчики команд
+├── src/                    # Telegram-бот (Node.js)
+│   ├── config/             # Конфигурация (БД, крипто)
+│   ├── context/            # Контекст и состояния бота
+│   ├── handlers/           # Обработчики команд
 │   │   ├── adminHandlers/  # Обработчики админа (Telegram)
-│   │   └── userHandlers/    # Обработчики пользователя
-│   ├── i18n/              # Интернационализация
-│   │   ├── index.js         # tForUser(), tForLang(), LANGUAGE_NAMES
-│   │   └── locales/         # en.json, es.json, de.json (201 ключ)
-│   ├── middleware/        # Промежуточные обработчики
-│   ├── migrations/        # Миграции БД
-│   ├── models/            # Модели данных
-│   ├── router/            # Роутинг callback/text бота
-│   ├── services/          # Бизнес-логика (вкл. chatbotService, leadService)
-│   ├── utils/             # Утилиты (логирование, валидация, ошибки)
-│   ├── healthServer.js    # Минимальный HTTP /health (Docker healthcheck)
-│   └── index.js           # Точка входа
-├── admin-next/            # НОВАЯ админ-панель (Next.js 16 + Prisma + shadcn/ui)
+│   │   └── userHandlers/   # Обработчики пользователя
+│   ├── i18n/               # Интернационализация
+│   │   ├── index.js        # tForUser(), tForLang(), LANGUAGE_NAMES
+│   │   └── locales/        # en.json, es.json, de.json
+│   ├── middleware/         # Промежуточные обработчики
+│   ├── migrations/         # Миграции БД (001–014)
+│   ├── models/             # Модели данных
+│   ├── router/             # Роутинг callback/text бота
+│   ├── services/           # Бизнес-логика (вкл. chatbotService, leadService)
+│   ├── utils/              # Утилиты (логирование, валидация, ошибки)
+│   ├── __tests__/          # Юнит-тесты (vitest)
+│   ├── healthServer.js     # Минимальный HTTP /health (Docker healthcheck)
+│   └── index.js            # Точка входа
+├── admin-next/             # Админ-панель (Next.js 16 + Prisma + shadcn/ui)
 │   ├── prisma/schema.prisma  # Схема БД (та же SQLite, что у бота)
-│   ├── src/app/api/          # 45 API-роутов (каталог, заказы, лиды, чатбот)
-│   ├── src/components/       # 76 UI-компонентов (dashboard, wallets, leads...)
+│   ├── src/app/api/          # 45 API-роутов (см. docs/API.md)
+│   ├── src/components/       # UI-компоненты (dashboard, wallets, leads...)
 │   └── Dockerfile            # Multi-stage Next.js standalone
-├── tor-proxy/             # Tor прокси для SSH и админки
-│   ├── Dockerfile         # Alpine + Tor образ
-│   ├── entrypoint.sh      # Генерация torrc, валидация env vars
-│   ├── get-onions.sh      # Скрипт обновления .env с onion-адресами
-│   └── hosts/             # Директория для onion-hosts.txt
-├── wg/                    # WireGuard конфигурация
-│   └── start.sh           # Скрипт запуска контейнера
-├── db/                    # SQLite база данных (volume)
-├── uploads/               # Загруженные фото (volume)
+├── docs/                   # Документация
+│   ├── API.md              # Справочник REST API админки
+│   └── DATABASE.md         # Структура БД (схема, связи, примечания)
+├── tor-proxy/              # Tor прокси для SSH и админки
+│   ├── Dockerfile          # Alpine + Tor образ
+│   ├── entrypoint.sh       # Генерация torrc, валидация env vars
+│   ├── get-onions.sh       # Скрипт обновления .env с onion-адресами
+│   └── hosts/              # Директория для onion-hosts.txt
+├── wg/                     # WireGuard конфигурация
+│   └── start.sh            # Скрипт запуска контейнера
+├── tests/                  # Web-тестирование (visual regression, E2E)
+│   ├── scripts/            # Скрипты тестов (Playwright, pixelmatch)
+│   └── visual/             # baseline/current/diff скриншоты
+├── docker/                 # Дополнительные compose-конфиги (web-testing)
+├── db/                     # SQLite база данных (volume)
+├── uploads/                # Загруженные фото (volume)
 ├── Dockerfile              # Multi-stage сборка магазина
 ├── docker-compose.yml      # Конфигурация трёх контейнеров (бот, админка, tor)
 ├── install.sh              # Установщик (POSIX sh)
@@ -326,6 +337,14 @@ src/i18n/
 └── package.json
 ```

+## Документация
+
+| Документ | Содержание |
+|---|---|
+| [`docs/API.md`](docs/API.md) | Справочник REST API админ-панели: все эндпоинты, методы, query-параметры, коды ошибок |
+| [`docs/DATABASE.md`](docs/DATABASE.md) | Структура БД: таблицы, колонки, связи, примечания |
+| [`VERSION.md`](VERSION.md) | История версий и changelog |
+
 ## Разработка

 ```bash