Инструкции по установке Silent Meadow¶

Системные требования¶

Минимальные требования¶

Python: 3.11 или выше
Node.js: 20.x или выше
PostgreSQL: 15 или выше
Redis: 7.0 или выше
Оперативная память: 4 GB
Свободное место на диске: 10 GB

Создание нового проекта¶

Silent Meadow - это standalone проект. Создайте структуру с нуля:

# Создать директорию проекта
mkdir silent-meadow
cd silent-meadow

# Инициализировать git
git init
git branch -M main

# Создать структуру
mkdir -p backend/app/{models,api,services,core}
mkdir -p frontend/src/{pages,components,lib}
mkdir docs

# Создать .gitignore (скопировать из репозитория)

Backend Setup (FastAPI)¶

1. Установка зависимостей¶

cd backend

# Создать виртуальное окружение
python3.11 -m venv venv

# Активировать виртуальное окружение
source venv/bin/activate  # macOS/Linux
# ИЛИ
venv\Scripts\activate     # Windows

# Обновить pip
pip install --upgrade pip

# Установить зависимости
pip install -r requirements.txt

# Установить дополнительные зависимости для разработки
pip install -r requirements-dev.txt

2. Установка PostgreSQL¶

macOS (Homebrew)¶

brew install postgresql@15
brew services start postgresql@15

# Создать базу данных
createdb silent_meadow

Ubuntu/Debian¶

sudo apt update
sudo apt install postgresql-15 postgresql-contrib

# Запустить сервис
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Создать базу данных
sudo -u postgres createdb silent_meadow
sudo -u postgres createuser silent_user
sudo -u postgres psql -c "ALTER USER silent_user WITH PASSWORD 'your_password';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE silent_meadow TO silent_user;"

Windows¶

Скачать установщик: https://www.postgresql.org/download/windows/
Установить PostgreSQL 15
Использовать pgAdmin для создания БД silent_meadow

3. Установка Redis¶

macOS (Homebrew)¶

brew install redis
brew services start redis

Ubuntu/Debian¶

sudo apt update
sudo apt install redis-server

# Запустить сервис
sudo systemctl start redis
sudo systemctl enable redis

Windows¶

Скачать Memurai: https://www.memurai.com/
Или использовать WSL2 + Ubuntu

4. Настройка переменных окружения¶

Создайте файл .env в директории backend/:

# Database
DATABASE_URL=postgresql+asyncpg://silent_user:your_password@localhost:5432/silent_meadow

# Redis
REDIS_URL=redis://localhost:6379/0

# JWT
SECRET_KEY=your-secret-key-change-this-in-production
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30

# Avito API
AVITO_CLIENT_ID=your_avito_client_id
AVITO_CLIENT_SECRET=your_avito_client_secret
AVITO_USER_ID=your_avito_user_id
AVITO_WEBHOOK_SECRET=random_secret_string_for_webhooks

# Циан API
CIAN_API_KEY=your_cian_api_key
CIAN_USER_ID=your_cian_user_id

# Yandex Maps API
YANDEX_MAPS_API_KEY=your_yandex_maps_api_key

# Telegram CRM Bot
TELEGRAM_CRM_BOT_TOKEN=your_telegram_bot_token
TELEGRAM_CRM_CHAT_ID=your_telegram_group_chat_id

# Leadgen Platform
LEADGEN_PLATFORM_URL=https://leadgen-platform.example.com
LEADGEN_PLATFORM_API_KEY=your_leadgen_api_key  # Если требуется auth

# OpenAI API
OPENAI_API_KEY=sk-your-openai-api-key

# Environment
ENVIRONMENT=development  # development, staging, production
DEBUG=True
LOG_LEVEL=INFO

5. Запуск миграций базы данных¶

# Применить существующие миграции
alembic upgrade head

# Создать новые миграции для моделей недвижимости
alembic revision --autogenerate -m "Add real estate models (Property, House, AvitoAd)"

# Применить новые миграции
alembic upgrade head

6. Импорт данных участков¶

# Запустить скрипт парсинга данных с t-lug.ru
python -m app.scripts.import_properties

# Или импортировать из CSV (если есть)
python -m app.scripts.import_from_csv --file data/properties.csv

7. Запуск backend сервера¶

# Development mode (hot reload)
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Production mode
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

Сервер будет доступен по адресу: http://localhost:8000

API документация: http://localhost:8000/docs

Frontend Setup (React)¶

1. Установка Node.js¶

macOS (Homebrew)¶

brew install node@20

Ubuntu/Debian¶

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Windows¶

Скачать установщик: https://nodejs.org/

2. Установка зависимостей¶

cd frontend

# Установить зависимости
npm install

# Или использовать yarn
yarn install

3. Настройка переменных окружения¶

Создайте файл .env.local в директории frontend/:

# API URL
VITE_API_URL=http://localhost:8000

# Yandex Maps
VITE_YANDEX_MAPS_API_KEY=your_yandex_maps_api_key

# Avito (если нужно на фронте)
VITE_AVITO_CLIENT_ID=your_avito_client_id

# Environment
VITE_ENVIRONMENT=development

4. Запуск dev сервера¶

# Development mode (hot reload)
npm run dev

# Или
yarn dev

Frontend будет доступен по адресу: http://localhost:5173

5. Сборка для production¶

# Build
npm run build

# Preview production build
npm run preview

Получение API ключей¶

Avito API¶

Зарегистрируйтесь на https://developers.avito.ru
Создайте новое приложение
Укажите Redirect URI: http://localhost:8000/api/v1/avito/auth/callback
Получите Client ID и Client Secret

Добавьте в .env:

AVITO_CLIENT_ID=ваш_client_id
AVITO_CLIENT_SECRET=ваш_client_secret

Документация: https://developers.avito.ru/api-catalog/messenger

Yandex Maps API¶

Зарегистрируйтесь на https://developer.tech.yandex.ru/
Создайте новый проект
Подключите "JavaScript API и HTTP Геокодер"
Получите API ключ
Добавьте в .env:
```
YANDEX_MAPS_API_KEY=ваш_api_key
```

Документация: https://yandex.ru/dev/jsapi-v2-1/

Циан API¶

Зарегистрируйтесь на https://www.cian.ru/account/api/
Создайте приложение
Получите API ключ и User ID

Добавьте в .env:

CIAN_API_KEY=ваш_api_key
CIAN_USER_ID=ваш_user_id

Документация: https://api.cian.ru/

Telegram Bot (для CRM)¶

Откройте Telegram и найдите @BotFather
Отправьте команду /newbot
Следуйте инструкциям (придумайте имя и username для бота)
Получите токен бота
Добавьте бота в группу менеджеров

Получите chat_id группы:

curl https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates

Добавьте в .env:

TELEGRAM_CRM_BOT_TOKEN=ваш_bot_token
TELEGRAM_CRM_CHAT_ID=ваш_chat_id

OpenAI API¶

Зарегистрируйтесь на https://platform.openai.com/
Создайте API ключ в разделе "API keys"
Пополните баланс (минимум $5)
Добавьте в .env:
```
OPENAI_API_KEY=sk-ваш_ключ
```

Стоимость: GPT-4 Turbo ~$0.01-0.03 за 1000 токенов (зависит от модели).

Docker Setup (опционально)¶

Для упрощения развертывания можно использовать Docker Compose:

1. Установка Docker¶

macOS: https://docs.docker.com/desktop/install/mac-install/
Windows: https://docs.docker.com/desktop/install/windows-install/
Linux: https://docs.docker.com/engine/install/

2. Создание docker-compose.yml¶

version: '3.8'

services:
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: silent_meadow
      POSTGRES_USER: silent_user
      POSTGRES_PASSWORD: silent_password
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

  backend:
    build: ./backend
    command: uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
    ports:
      - "8000:8000"
    volumes:
      - ./backend:/app
    env_file:
      - ./backend/.env
    depends_on:
      - postgres
      - redis

  frontend:
    build: ./frontend
    command: npm run dev -- --host
    ports:
      - "5173:5173"
    volumes:
      - ./frontend:/app
      - /app/node_modules
    env_file:
      - ./frontend/.env.local

volumes:
  postgres_data:
  redis_data:

3. Запуск¶

# Запустить все сервисы
docker-compose up -d

# Просмотр логов
docker-compose logs -f

# Остановить
docker-compose down

Проверка установки¶

Backend¶

# Проверка healthcheck
curl http://localhost:8000/health

# Ожидаемый ответ:
# {
#   "status": "ok",
#   "database": "connected",
#   "redis": "connected"
# }

# Проверка документации API
open http://localhost:8000/docs

Frontend¶

# Открыть в браузере
open http://localhost:5173

# Проверить консоль браузера на ошибки

Начальные данные (seed)¶

1. Создать администратора¶

cd backend
python -m app.scripts.create_admin \
  --email admin@silent-meadow.ru \
  --password your_secure_password \
  --name "Admin User"

2. Импортировать участки¶

# Парсинг с сайта t-lug.ru
python -m app.scripts.import_properties --source tlug

# Или из CSV
python -m app.scripts.import_properties --source csv --file data/properties.csv

3. Добавить типовые дома¶

# Импорт из JSON
python -m app.scripts.import_houses --file data/houses.json

# Или создать вручную через API
curl -X POST http://localhost:8000/v1/houses \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Шале",
    "type": "shale",
    "area_sqm": 60,
    "price_economy": 2500000,
    "price_comfort": 3200000,
    "description": "Современный дом в стиле Шале"
  }'

Настройка интеграции с Leadgen Platform¶

1. Настроить webhook в Leadgen Platform¶

В настройках Leadgen Platform укажите webhook URL:

https://silent-meadow.example.com/api/v1/webhooks/leadgen

2. Настроить фильтры лидов¶

В Leadgen Platform создайте проект "МДК Недвижимость" с параметрами: - Минимальный score: 7.0 - Keywords: участок, земля, дом, купить, Подмосковье, МО, соток - Webhook: включен

3. Тестирование интеграции¶

# Проверить webhook endpoint
curl -X POST http://localhost:8000/v1/webhooks/leadgen \
  -H "Content-Type: application/json" \
  -d '{
    "lead_id": "test-123",
    "name": "Тест",
    "telegram_username": "@test",
    "message": "Ищу участок",
    "score": 8.5
  }'

# Проверить, что лид создан
curl http://localhost:8000/v1/leads

Проверка всех компонентов¶

Чеклист успешной установки:

[ ] PostgreSQL запущен и доступен
[ ] Redis запущен и доступен
[ ] Backend запущен на http://localhost:8000
[ ] Frontend запущен на http://localhost:5173
[ ] API документация доступна http://localhost:8000/docs
[ ] Создан администратор
[ ] Импортированы участки (436 шт.)
[ ] Добавлены типовые дома (9 шт.)
[ ] Настроена интеграция с Leadgen Platform (webhook)
[ ] Telegram CRM бот создан и добавлен в группу
[ ] Получены API ключи (Avito, Циан, Yandex Maps, OpenAI)

Troubleshooting¶

Проблема: База данных не подключается¶

# Проверить запущен ли PostgreSQL
pg_isready

# Проверить порт
lsof -i :5432

# Проверить логи
tail -f /usr/local/var/log/postgresql@15.log  # macOS
sudo journalctl -u postgresql  # Linux

Проблема: Redis не подключается¶

# Проверить запущен ли Redis
redis-cli ping
# Ожидается: PONG

# Проверить порт
lsof -i :6379

Проблема: Ошибка миграций Alembic¶

# Откатить миграции
alembic downgrade -1

# Удалить alembic_version и пересоздать
psql silent_meadow -c "DROP TABLE alembic_version;"
alembic upgrade head

Проблема: Frontend не подключается к Backend¶

Проверьте CORS настройки в backend/app/main.py:

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:5173"],  # Добавить ваш frontend URL
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

Следующие шаги¶

После успешной установки:

Прочитайте docs/development.md - гайд по разработке
Изучите docs/architecture.md - архитектура проекта
Начните реализацию согласно docs/plan.md

Нужна помощь? Создайте issue в репозитории проекта.

Инструкции по установке Silent Meadow¶

Системные требования¶

Минимальные требования¶

Рекомендуемые требования¶

Создание нового проекта¶

Backend Setup (FastAPI)¶

1. Установка зависимостей¶

2. Установка PostgreSQL¶

macOS (Homebrew)¶

Ubuntu/Debian¶

Windows¶

3. Установка Redis¶

macOS (Homebrew)¶

Ubuntu/Debian¶

Windows¶

4. Настройка переменных окружения¶

5. Запуск миграций базы данных¶

6. Импорт данных участков¶

7. Запуск backend сервера¶

Frontend Setup (React)¶

1. Установка Node.js¶

macOS (Homebrew)¶

Ubuntu/Debian¶

Windows¶

2. Установка зависимостей¶

3. Настройка переменных окружения¶

4. Запуск dev сервера¶

5. Сборка для production¶

Получение API ключей¶

Avito API¶

Yandex Maps API¶

Циан API¶

Telegram Bot (для CRM)¶

OpenAI API¶

Docker Setup (опционально)¶

1. Установка Docker¶

2. Создание docker-compose.yml¶

3. Запуск¶

Проверка установки¶

Backend¶

Frontend¶

Начальные данные (seed)¶

1. Создать администратора¶

2. Импортировать участки¶

3. Добавить типовые дома¶

Настройка интеграции с Leadgen Platform¶

1. Настроить webhook в Leadgen Platform¶

2. Настроить фильтры лидов¶

3. Тестирование интеграции¶

Проверка всех компонентов¶

Troubleshooting¶

Проблема: База данных не подключается¶

Проблема: Redis не подключается¶

Проблема: Ошибка миграций Alembic¶

Проблема: Frontend не подключается к Backend¶

Следующие шаги¶