Leadra - платформа по поиску лидов в Telegram

Leadra

Платформа для генерации и обработки лидов из Telegram: мониторинг чатов, сбор участников, базы контактов, автоматизация и биллинг. Основное приложение — Next.js на домене app.leadra.ru; публичный маркетинг — leadra.ru / lead-gen landing.

Оглавление

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

Возможности

Lead Gen — views (?view=)

В коде нет режима «демо без MongoDB». Данные читаются и пишутся в реальные коллекции (lead_gen_*, пользователи, подписки и т.д.).

Админка

Навигация: src/components/admin/AdminSidebar.tsx. Доступ по заголовку x-admin-token = ADMIN_SECRET (и NEXT_PUBLIC_ADMIN_SECRET на клиенте).

Стек

Требования

• Node.js ≥ 22, pnpm ≥ 9
• MongoDB 7 (локально: 127.0.0.1:27017, БД leadramongodb)
• Redis 7 — для email-platform / очередей (если работаете с этим модулем)
• Telegram Bot token — выдаёт администратор out-of-band
• Секреты админки / JWT / шифрование — только из env, не из репозитория

Доступ к репозиторию

Клонирование по SSH (канонический remote origin):

git clone ssh://git@gitverse.ru:2222/spacemod/leadra.ru.git
cd leadra.ru

Секреты окружения и доступы к prod/staging выдаются администратором вне git.

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

1. Зависимости

pnpm install

2. Env

cp env.example .env.local
# заполните REQUIRED-поля; секреты не коммитить

3. Инфраструктура

Рекомендуется локальный MongoDB (Docker или mongod), не cloud Atlas как основной путь:

# пример: MongoDB без auth на localhost
# URI: mongodb://127.0.0.1:27017/leadramongodb

Redis при необходимости — локально на 127.0.0.1:6379.

4. Dev-сервер

pnpm dev
# приложение: http://localhost:3000

Альтернативы: pnpm dev:web, pnpm pm2:dev (см. package.json).

Не используйте mock/fallback-данные вместо MongoDB. Приложение рассчитано на реальную БД.

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

Канонический шаблон: env.example.

Host API tokens / APP_ID / прод-credentials — только out-of-band от владельца репозитория.

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

.
├── apps/lead-gen-landing/   # отдельный landing Lead Gen
├── docs/                    # операционные и продуктовые документы
├── harvester/               # сбор данных WB (legacy / смежный контур)
├── scripts/                 # утилиты, deploy, экспорт
├── src/
│   ├── app/                 # Next.js App Router (pages + api)
│   │   ├── admin/           # админка
│   │   ├── modules/         # lead-gen, subscription
│   │   └── api/             # REST handlers
│   ├── components/
│   ├── modules/email-platform/
│   └── lib/
├── ecosystem.config.cjs     # PM2 production
├── env.example
└── package.json

Скрипты

Выгрузка контактов Lead Gen с локальной MongoDB (консоль):

node scripts/export-lead-gen-contacts-xlsx.cjs --local <telegramUserId> <projectId>

См. src/app/modules/lead-gen/docs/EXPORT_CONTACTS_CONSOLE.md.

Production deploy

• Процессы: PM2 (ecosystem.config.cjs), Node + Next на порту 3000 (за reverse-proxy).
• БД: MongoDB leadramongodb; credentials только из env на сервере (в репозитории hardcoded URI запрещены).
• Runbook: docs/deploy/ (в т.ч. устранение 502), scripts/deploy-app-leadra-server.sh.
• Перед релизом: заполненный .env.production на хосте, pnpm build, проверка health API.

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

1. Не коммитить .env* с секретами.
2. Не деплоить с fallback-паролями в коде (их убрали; env обязателен).
3. После ротации секретов — обновить env на всех хостах и перезапустить PM2.

Git workflow

Ветки: master (prod) · develop · feature/*.

git checkout develop
git pull origin develop
git checkout -b feature/short-name
# …работа…
git push -u origin feature/short-name
# merge --no-ff feature → develop → master (по согласованию владельца)

• Не пушить в synology (локальный backup remote).
• Не коммитить напрямую в master / develop.
• Conventional commits: feat|fix|docs|refactor|chore|test(scope): …

Troubleshooting

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

1. Секреты только в локальном .env.local / серверном .env.production — не в git.
2. Не вставлять API keys, URI с паролем, shop_id в PR и docs.
3. Считайте, что любые секреты, когда-либо попадавшие в историю git, скомпрометированы — владелец должен ротировать их до выдачи доступа.
4. Admin token не хардкодить: только process.env.ADMIN_SECRET.

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

В корне репозитория среди markdown остаётся только этот README.md.

Контакты

Операционные доступы и прод-секреты — у владельца репозитория. Публичные продуктовые домены: leadra.ru, app.leadra.ru.