architect/arh/design/UNIFIED_MVP.md

Unified Commerce Platform — MVP

Версия: 1.0.0
Дата: 2025-12-19
Статус: draft

ЦЕЛЬ MVP

Единая платформа для:
- Управления товарами и ценами (PIM)
- Обработки заказов с маркетплейсов (OZON, WB)
- Дропшипинг (закупка у поставщиков под заказ)
- Базовая CRM (клиенты, заказы)

Срок: 2-3 недели до рабочего прототипа

АРХИТЕКТУРА MVP

┌─────────────────────────────────────────┐
│            WEB UI (FastAPI + Jinja2)    │
│         http://localhost:8500           │
├─────────────────────────────────────────┤
│                  API                    │
│            /api/v1/...                  │
├────────┬────────┬────────┬─────────────┤
│  auth  │  pim   │ orders │ marketplace │
├────────┴────────┴────────┴─────────────┤
│              NocoDB API                 │
│         http://localhost:8080           │
├─────────────────────────────────────────┤
│              PostgreSQL                 │
│        (существующая БД NocoDB)         │
└─────────────────────────────────────────┘

МОДУЛИ MVP

1. AUTH (аутентификация)

Минимум для MVP:
- Логин/пароль (1 админ)
- JWT токен в cookie
- Защита всех роутов

Таблицы: используем существующую Users

# Роуты
POST /auth/login      # Вход
POST /auth/logout     # Выход
GET  /auth/me         # Текущий пользователь

2. PIM (товары и цены)

Функционал MVP:
- Список товаров с фильтрами
- Карточка товара (просмотр/редактирование)
- Импорт прайсов поставщиков
- Расчёт цен (закупка → продажа)

Таблицы NocoDB:
- pim_products — товары (5623)
- Prices_History — цены поставщиков (4126)
- v_product_prices — VIEW с расчётными ценами

# Роуты
GET  /pim/products              # Список
GET  /pim/products/{id}         # Карточка
PUT  /pim/products/{id}         # Редактирование
POST /pim/prices/import         # Импорт прайса
GET  /pim/prices/history        # История цен

UI страницы:
- /products — таблица товаров
- /products/{id} — карточка товара
- /prices — управление ценами

3. ORDERS (заказы)

Функционал MVP:
- Список заказов со всех каналов
- Детали заказа
- Смена статуса
- Печать этикеток

Таблицы NocoDB:
- OZON_Orders — заказы OZON
- OZON_OrderItems — позиции
- Order — унифицированные заказы

# Роуты
GET  /orders                    # Список
GET  /orders/{id}               # Детали
PUT  /orders/{id}/status        # Смена статуса
GET  /orders/{id}/label         # Этикетка
POST /orders/sync               # Синхронизация с МП

UI страницы:
- /orders — список заказов
- /orders/{id} — детали заказа
- /orders/new — ожидающие обработки

4. MARKETPLACE (интеграции)

Функционал MVP:
- Синхронизация заказов OZON
- Обновление статусов
- Получение этикеток

Используем: существующий код из @ozon.api

# Роуты
POST /marketplace/ozon/sync/orders     # Синхр. заказов
POST /marketplace/ozon/sync/products   # Синхр. товаров
GET  /marketplace/ozon/status          # Статус подключения

СТРУКТУРА ПРОЕКТА

projects/unified/
├── CLAUDE.md
├── app/
│   ├── main.py              # FastAPI app
│   ├── config.py            # Настройки
│   ├── dependencies.py      # DI (auth, db)
│   │
│   ├── auth/
│   │   ├── router.py
│   │   ├── service.py
│   │   └── schemas.py
│   │
│   ├── pim/
│   │   ├── router.py
│   │   ├── service.py
│   │   └── schemas.py
│   │
│   ├── orders/
│   │   ├── router.py
│   │   ├── service.py
│   │   └── schemas.py
│   │
│   ├── marketplace/
│   │   ├── router.py
│   │   ├── ozon/
│   │   │   ├── client.py    # ← из @ozon.api
│   │   │   └── sync.py
│   │   └── schemas.py
│   │
│   ├── templates/           # Jinja2 HTML
│   │   ├── base.html
│   │   ├── login.html
│   │   ├── products/
│   │   ├── orders/
│   │   └── components/
│   │
│   └── static/
│       ├── css/
│       └── js/
│
├── requirements.txt
├── .env
└── run.sh

ТЕХНОЛОГИИ

Компонент Технология
Backend FastAPI
Frontend Jinja2 + HTMX + TailwindCSS
База NocoDB (PostgreSQL)
Auth JWT + httponly cookie
Деплой Docker / systemd

ЭТАПЫ РЕАЛИЗАЦИИ

Этап 1: Каркас (2-3 дня)

Этап 2: PIM (3-4 дня)

Этап 3: Orders (3-4 дня)

Этап 4: Интеграция (2-3 дня)

МИГРАЦИЯ ДАННЫХ

Не требуется! Используем существующую NocoDB:
- База: pt7k98pv0fwi1el
- URL: http://localhost:8080
- Все таблицы уже есть

ЗАПУСК

# Разработка
cd projects/unified
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8500

# Продакшн
docker-compose up -d

ПОСЛЕ MVP

После запуска MVP добавляем:
1. CRM модуль (клиенты, воронка)
2. Dropship модуль (закупки у поставщиков)
3. WB/YM интеграции
4. AI роботы (из mcrm)
5. Мобильное приложение

Версия: 1.0.0