6.0 KiB
Генератор описаний товаров
Внутренний инструмент контент-отдела для генерации описаний товаров через несколько 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 и «сервис ИИ») на текущем этапе — заглушки; генерация возвращает детерминированный текст-плейсхолдер. Замена на реальные сервисы — правка соответствующих адаптеров, остальной код не меняется.