telegram-shop/README.md

# Telegram Shop Bot

Телеграм-бот для организации онлайн-продаж через Telegram с поддержкой криптовалют и WireGuard VPN.

## Возможности

- Каталог товаров с категориями и фильтрацией по локациям
- Покупки с оплатой криптовалютами (BTC, ETH, LTC, USDT, USDC)
- Управление криптокошельками (создание, пополнение, баланс)
- История транзакций и покупок
- SaaS-система с автоматическим расчётом комиссий
- Админ-панель на порту 3001
- WireGuard VPN для безопасных транзакций

## Быстрый старт (одна команда)

### Требования

- Любое устройство с Docker: x86_64 (PC, сервер) или ARM64 (Orange Pi, Raspberry Pi)
- 512 МБ RAM минимум (Orange Pi Zero 2 поддерживается)

### Установка

```bash
git clone <repo-url> && cd telegram-shop
bash install.sh
```

Скрипт автоматически:
1. Определит архитектуру (x86_64 / ARM64 / ARMv7)
2. Установит Docker если не установлен
3. Создаст `.env` из шаблона
4. Проверит обязательные переменные
5. Соберёт Docker-образ под текущую архитектуру
6. Запустит контейнер и проверит health-check

### Ручная установка

```bash
# 1. Клонировать
git clone <repo-url> && cd telegram-shop

# 2. Создать .env из шаблона
cp .env.example .env
nano .env  # заполнить BOT_TOKEN, ADMIN_IDS, ENCRYPTION_KEY

# 3. Собрать и запустить
docker compose up -d --build

# 4. Проверить статус
docker compose ps
curl http://localhost:3001/health
```

## Настройка .env

Скопируйте `.env.example` в `.env` и заполните:

| Переменная | Обязательно | Описание |
|---|---|---|
| `BOT_TOKEN` | ✅ | Токен Telegram бота (@BotFather) |
| `ADMIN_IDS` | ✅ | ID администраторов через запятую |
| `ENCRYPTION_KEY` | ✅ | Ключ шифрования (32 байта hex) |
| `SUPER_ADMIN_IDS` | — | ID супер-админов |
| `SUPPORT_LINK` | — | Ссылка на поддержку |
| `WG_ENABLED` | — | `true` / `false` (по умолчанию `false`) |
| `WG_PRIVATE_KEY` | — | Приватный ключ WireGuard |
| `WG_PUBLIC_KEY` | — | Публичный ключ WireGuard |
| `WG_PRESHARED_KEY` | — | Pre-shared ключ WireGuard |
| `WG_ENDPOINT` | — | Адрес сервера WireGuard |
| `WG_ADDRESS` | — | Адрес интерфейса WireGuard |
| `WG_DNS` | — | DNS для WireGuard |

Генерация ключа шифрования:
```bash
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

## Поддерживаемые устройства

| Устройство | Архитектура | RAM | Статус |
|---|---|---|---|
| PC / Сервер | x86_64 | ≥ 512 МБ | ✅ |
| Orange Pi Zero 2 | ARM64 (H616) | 512 МБ | ✅ |
| Raspberry Pi 4 | ARM64 | ≥ 1 ГБ | ✅ |
| Raspberry Pi 3 | ARM64 | 1 ГБ | ✅ |
| Raspberry Pi 2 | ARMv7 | 1 ГБ | ✅ |

Docker автоматически собирает нативные модули (`better-sqlite3`, `tiny-secp256k1`) под архитектуру хоста.

## Архитектура Docker

```
┌─────────────────────────────────────────────┐
│  telegram_shop_prod (node:22-alpine)        │
│  ┌──────────────┐  ┌─────────────────────┐ │
│  │ Builder      │  │ Runtime              │ │
│  │ python3, g++ │→ │ bash, curl,         │ │
│  │ make, gcc    │  │ wireguard-tools,    │ │
│  │ npm install  │  │ iptables, bind-tools │ │
│  └──────────────┘  └─────────────────────┘ │
│                     Port 3001 (localhost)     │
│                     Limit: 384MB RAM          │
└─────────────────────────────────────────────┘
     ↑ Volumes: db/, uploads/, .env
```

### Файлы

| Файл | Назначение |
|---|---|
| `Dockerfile` | Multi-stage сборка (builder + runtime) |
| `docker-compose.yml` | Конфигурация контейнера |
| `install.sh` | Автоматический установщик |
| `.dockerignore` | Исключения из Docker-образа |
| `.env.example` | Шаблон переменных окружения |
| `wg/start.sh` | Скрипт запуска (WireGuard + Node.js) |

## Команды управления

```bash
# Запуск
docker compose up -d

# Пересборка после изменений
docker compose up -d --build

# Логи
docker compose logs -f

# Стоп
docker compose down

# Рестарт
docker compose restart

# Статус
docker compose ps

# Health-check
curl http://localhost:3001/health
```

## WireGuard

WireGuard по умолчанию отключен (`WG_ENABLED=false`). Для включения:

1. Установите `WG_ENABLED=true` в `.env`
2. Заполните ключи WireGuard в `.env`
3. Перезапустите: `docker compose restart`

Контейнер требует `NET_ADMIN` и `sysctl net.ipv4.conf.all.src_valid_mark=1` для WireGuard. Эти привилегии заданы в `docker-compose.yml`.

## Безопасность

- `.env` монтируется только для чтения (`:ro`)
- Порт 3001 привязан к `127.0.0.1` (доступен только с хоста)
- Нативные модули компилируются в builder-стейдже (чистый runtime)
- `devDependencies` не попадают в production-образ
- Тестовые файлы исключены из Docker-образа (`.dockerignore`)
- `node_modules` хоста не попадают в образ (`.dockerignore`)

## Структура проекта

```
├── src/
│   ├── admin/          # Админ-панель (Express)
│   ├── config/         # Конфигурация (БД, крипто)
│   ├── context/         # Контекст и состояния бота
│   ├── handlers/        # Обработчики команд
│   ├── middleware/      # Промежуточные обработчики
│   ├── migrations/      # Миграции БД
│   ├── models/          # Модели данных (SQLite)
│   ├── router/          # Роутинг Express
│   ├── services/        # Бизнес-логика
│   ├── utils/           # Утилиты
│   └── index.js         # Точка входа
├── wg/                 # WireGuard конфигурация
│   └── start.sh         # Скрипт запуска контейнера
├── db/                 # SQLite база данных (volume)
├── uploads/            # Загруженные фото (volume)
├── Dockerfile          # Multi-stage сборка
├── docker-compose.yml  # Конфигурация контейнера
├── install.sh          # Установщик (POSIX sh)
├── .dockerignore       # Исключения из образа
├── .env.example        # Шаблон переменных
└── package.json
```

## Разработка

```bash
# Установка зависимостей
npm install

# Запуск в режиме разработки
npm run dev

# Тесты
npm test
```

## Лицензия

MIT