ЕстьБЕНЗ - народная карта наличия топлива

ЕстьБЕНЗ (estbenz.ru)

Народная live-карта наличия топлива на АЗС России: водители отмечают «есть» / «нет» / очередь, сервис показывает свежие статусы на карте и в SEO-каталоге.

Версия: 0.1.0 · Package manager: pnpm · Репозиторий: приватный (клон по SSH выдает владелец)

Оглавление

• Возможности
• Админ-панель
• Стек
• Требования
• Доступ к коду
• Локальная разработка
• Переменные окружения
• Структура проекта
• Скрипты
• Продакшен-деплой
• Git workflow
• Troubleshooting
• Безопасность для внешних разработчиков
• Документация

Возможности

Модули (src/modules/)

Подробности — в src/modules/*/README.md.

Админ-панель

Вход: /admin/login · пароль из ADMIN_PASSWORD (только env).

Навигация задаётся в src/components/admin/admin-shell.tsx и admin-ads-nav.tsx.

Стек

Карта в проде — MapLibre (не Leaflet). Leaflet-код в репозитории помечен deprecated.

Требования

• Node.js 22+
• pnpm 9+ (на сервере используется pnpm 11)
• Docker Desktop (локально: Postgres+PostGIS + Redis)
• Git + SSH-доступ к remote (выдаёт владелец)

Доступ к коду

Клон только по SSH (URL выдаёт владелец репозитория out-of-band):

git clone <SSH_CLONE_URL>
cd estbenz.ru   # или имя каталога клона

Публичные web-URL git-хостинга в документации не публикуются.

Локальная разработка

Инфраструктура — локальный Docker, не managed cloud.

cp .env.example .env
# Заполните минимум: ADMIN_PASSWORD, AUTH_SECRET
# openssl rand -hex 32

pnpm install
pnpm db:up          # Postgres :5433, Redis :6380
pnpm db:migrate

# Опционально — данные:
# pnpm import:osm
# pnpm import:osm:russia --mode=zones

pnpm dev            # http://localhost:3000

Redis в compose проброшен на хост как 6380 → в .env: REDIS_URL=redis://localhost:6380.

Создание админа — только через ADMIN_PASSWORD в .env. Паролей в коде нет.

Для сборки/dev с российскими CA (нужны некоторым импортам):

# сертификаты: deploy/certs/russian_trusted_*.pem
# NODE_EXTRA_CA_CERTS уже указан в .env.example и в скрипте pnpm dev

WS гонок (опционально): RACE_WS_PORT=3005, клиент NEXT_PUBLIC_RACE_WS_URL=ws://localhost:3005.

Переменные окружения

Источник истины: .env.example.

Required (минимум для локального web)

Recommended

Production-only / выдаёт администратор

Секреты не коммитить. Реальные токены выдаются out-of-band.

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

├── deploy/                 # Nginx, SSH, Tor, bootstrap, remote-deploy
├── docs/                   # ТЗ, аудиты, планы
├── prisma/                 # schema + migrations
├── public/                 # статика, PWA, иконки
├── scripts/                # импорты, демоны, утилиты
├── src/
│   ├── app/                # Next.js App Router (страницы + API)
│   ├── components/         # UI, карта, админка, промо
│   ├── lib/                # общие утилиты
│   └── modules/            # доменные модули (+ README)
├── docker-compose.yml      # Postgres 5433 + Redis 6380
├── ecosystem.config.cjs    # PM2 (web + workers + tor)
└── .env.example

Скрипты

Полный список — в package.json → scripts.

Продакшен-деплой

Целевая архитектура: VPS · Nginx · PM2 · PostgreSQL+PostGIS · Redis · Tor (отдельный SOCKS на worker) · Let's Encrypt.

Критичные правила:

1. .env не деплоится через rsync — живёт только на сервере.
2. На проде в DATABASE_URL обязательны connection_limit / pool_timeout (см. комментарий в .env.example).
3. Деплой: bash deploy/deploy.sh (rsync → remote-deploy.sh → build → migrate → PM2).
4. Каталог на сервере: /var/www/estbenz.ru.
5. Web слушает :3000 (PM2 estbenz-web); гонки WS — :3005 (проксируется nginx).

Подробный runbook: deploy/README.md.

Доступ к SSH/деплой-ключу выдаёт владелец. Приватный ключ deploy/ssh/id_ed25519_estbenz в git не хранится.

Git workflow

Ветки (целевая модель):

Правила:

• Не коммитить напрямую в master / develop
• Flow: feature/* → merge --no-ff → develop → merge --no-ff → master
• Conventional commits: feat|fix|docs|refactor|chore|test(scope): …
• Не коммитить .env, приватные ключи, дампы

Важно: на remote сейчас может существовать только master. Ветку develop создаёт владелец при онбординге (Phase 5).

Troubleshooting

Безопасность для внешних разработчиков

1. Не коммитить секреты. .env — только локально / на сервере.
2. Токены MAX / Telegram / OpenRouter / SMTP / DGIS / Benzup — только out-of-band от владельца.
3. Не использовать прод-SSH-ключ команды; запрашивать персональный доступ.
4. Не включать mock/fallback данных станций — работа только с реальной БД.
5. Перед push: git status / git diff — нет ли .env, ключей, дампов.

Если нашли секрет в истории git — сразу сообщите владельцу (нужна ротация).

Документация

Лицензия

Private. Все права принадлежат владельцу проекта.