Генератор описаний товаров

Внутренний инструмент контент-отдела для генерации описаний товаров через несколько LLM одновременно.

• Что за проект и зачем — см. docs/description.md
• План реализации и чек-лист — см. docs/IMPLEMENTATION_PLAN.md

Стек

• Backend: Python + FastAPI
• Frontend: React + TypeScript + Tailwind CSS
• БД: PostgreSQL
• Запуск: Docker Compose (три контейнера: postgres, backend, frontend)

---

Быстрый старт (для тех, кто не работал с Docker)

1. Установить Docker Desktop

Скачать и установить с официального сайта: https://www.docker.com/products/docker-desktop/ После установки запустить Docker Desktop и дождаться, пока в трее иконка кита не станет обычной (статус «Docker Desktop is running»). Docker Desktop должен быть запущен всё время, пока работаешь с проектом.

2. Подготовить переменные окружения

В корне проекта (code/) скопировать файл-образец .env.example в .env:

cp .env.example .env

.env содержит пароль к БД и секрет для токенов авторизации. Для локальной разработки значения по умолчанию подойдут; для боевого сервера их нужно поменять на свои. Файл .env в git не коммитится (он в .gitignore).

3. Запустить всё одной командой

Из папки code/:

docker compose up

Первый запуск дольше (скачиваются образы и ставятся зависимости). Когда в логах появятся строки вида Application startup complete (бэкенд) и VITE ... ready (фронтенд) — всё готово.

4. Открыть в браузере

• Приложение (фронтенд): http://localhost:5173
• API бэкенда (при желании): http://localhost:8000/api/health → должно вернуть {"status":"ok"}

При первом входе зарегистрируй аккаунт (логин/пароль), затем пользуйся.

5. Остановить

В терминале, где запущен docker compose up, нажать Ctrl+C. Либо в отдельном терминале из папки code/:

docker compose down

docker compose down останавливает и удаляет контейнеры, но данные в БД сохраняются (лежат в отдельном docker-томе pgdata). При следующем docker compose up всё поднимется с теми же данными.

---

Повседневная работа

• Менять код можно на ходу: и бэкенд (uvicorn --reload), и фронтенд (Vite) подхватывают изменения файлов автоматически, без перезапуска контейнеров (hot reload).
• Перезапуск/пересборка нужны только если: поменялся Dockerfile, добавилась зависимость (requirements.txt / package.json) или менялся сам docker-compose.yml. Тогда:

  docker compose up --build
  

• Полный сброс с чистой БД (удаляет все данные!):

  docker compose down -v && docker compose up --build
  

  Флаг -v удаляет том с данными БД — при следующем старте схема создастся заново из db/init/001_init.sql. Используй, только когда действительно нужен чистый старт.

---

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

code/
├── docker-compose.yml     # описание трёх сервисов
├── .env / .env.example    # переменные окружения (пароли, секреты)
├── db/init/001_init.sql   # схема БД (выполняется при первом старте postgres)
├── backend/               # Python + FastAPI
│   └── app/               # auth, generation, products, history, prompts, ai/search-заглушки
├── frontend/              # React + TypeScript + Vite + Tailwind
│   └── src/               # pages, components, api, auth, generation-контекст
└── docs/                  # описание проекта и план реализации

Порты

Сервис	URL
Фронтенд	http://localhost:5173
Бэкенд (API)	http://localhost:8000
PostgreSQL	localhost:5432

Заметки по окружению

• Windows + Docker Desktop: прямое подключение к Postgres по протоколу БД с хоста (не из контейнера) через проброшенный порт может обрываться — это особенность сети Docker Desktop, не баг проекта. Внутри docker-сети (как работает бэкенд) всё в порядке. Подробнее — в docs/IMPLEMENTATION_PLAN.md.
• Внешние сервисы (поиск Tavily и «сервис ИИ») на текущем этапе — заглушки; генерация возвращает детерминированный текст-плейсхолдер. Замена на реальные сервисы — правка соответствующих адаптеров, остальной код не меняется.