🎯 MP1 PROJECT-MASTER

Проект: Marketplace MVP (mp1)
Версия: 2.4.0
Дата создания: 2025-11-07
Последнее обновление: 2025-11-08
Статус: В разработке

📑 СОДЕРЖАНИЕ

1. Описание проекта
2. Бизнес-модель
3. Архитектура
4. Схемы Fulfillment
5. Склады
6. Модели БД
7. Технологии
8. Структура проекта
9. Текущее состояние
10. Ссылки

📋 ОПИСАНИЕ ПРОЕКТА {#описание-проекта}

Система управления продажами на маркетплейсах (Ozon, Wildberries, Яндекс.Маркет).

Основной функционал:
- Автоматическое подключение каналов продаж
- Управление юридическими лицами
- Управление складами и логистикой
- Обработка заказов (FBO/FBS/realFBS)
- Учёт товаров

Для кого:
- Продавцы на маркетплейсах
- Дропшипперы
- Агрегаторы товаров

🎯 БИЗНЕС-МОДЕЛЬ {#бизнес-модель}

Основная схема работы: realFBS (своя доставка)

Проект создаётся для всех случаев (FBO/FBS/realFBS поддерживаются), но приоритет на:
1. realFBS - своя доставка через СДЭК/Почту России
2. Дропшиппинг - работа с поставщиками
3. Учёт остатков - резервирование и списание

🏗️ АРХИТЕКТУРА {#архитектура}

Структура БД

User (пользователи)
  ↓
LegalEntity (юр.лица) → связь по ИНН
  ↓
Channel (каналы продаж)
  ↓
  ├─ Warehouse (склады)
  ├─ DeliveryService (службы доставки)
  └─ ChannelStatusMapping (маппинг статусов)

Order (заказы)
  ├─ OrderItem (позиции заказа)
  └─ OrderStatusHistory (история статусов)

Product (товары)
  ├─ ProductVariant (вариации)
  ├─ ProductImage (картинки)
  └─ ProductChannelMapping (связь с каналами)

Supplier (поставщики - будущее)
  └─ SupplierProduct (товары поставщика)

Return (возвраты)
StockMovement (движение остатков - будущее)
Substitution (замены товаров - будущее)

ER Диаграмма: См. docs/diagrams/database_er.png (создать)

📦 СХЕМЫ FULFILLMENT {#схемы-fulfillment}

На маркетплейсе Ozon существует 3 основные схемы обработки заказов:

1. FBO (Fulfillment by Ozon)

Суть: Товар хранится на складе Ozon, Ozon полностью берёт на себя обработку и доставку.

Товар → Склад Ozon → Заказ → Ozon упаковывает → Ozon доставляет → Покупатель

Что делает продавец:
- Поставляет товар на склад Ozon (FBO-поставки)
- Следит за остатками
- Обрабатывает возвраты (опционально)

Что делает Ozon:
- Хранит товар
- Упаковывает заказы
- Генерирует этикетки
- Доставляет покупателю
- Обрабатывает возвраты

SLA:
- Поставка на склад: минимум за 12 часов до забора
- Доставка покупателю: 1-7 дней (зависит от региона)

2. FBS (Fulfillment by Seller)

Суть: Товар хранится на складе продавца, но доставляет Ozon.

Заказ → Продавец собирает → Ozon забирает → Ozon доставляет → Покупатель

Что делает продавец:
- Хранит товар на своём складе
- Получает заказ → собирает → упаковывает
- Печатает этикетки Ozon
- Передаёт заказы курьеру Ozon

Что делает Ozon:
- Забирает заказы со склада продавца (по графику: 10:00, 15:00)
- Доставляет покупателю
- Обрабатывает возвраты (частично)

SLA:
- Время на сборку: 24 часа с момента заказа
- График забора курьером Ozon: 10:00, 15:00 (ежедневно)

Важно:
- Этикетки генерирует Ozon (не СДЭК, не Почта!)
- Трекинг ведёт Ozon
- Акт для курьера получаете через Ozon API

3. realFBS (Real FBS / DBS)

Суть: Товар хранится на складе продавца, доставляет продавец (или его служба доставки).

Заказ → Продавец собирает → Продавец доставляет → Покупатель
          ↓
    Свои этикетки (СДЭК/Почта/курьер)
    Свой трек-номер

Что делает продавец:
- Хранит товар
- Собирает и упаковывает
- Генерирует свои этикетки (через СДЭК API / Почта API / свои)
- Доставляет сам (курьером или через службу)
- Загружает свой трек-номер на Ozon

Что делает Ozon:
- Передаёт заказы продавцу
- Следит за соблюдением SLA
- Принимает трек-номера от продавца

SLA (3 типа):

Важно:
- Этикетки генерируете вы (через API СДЭК/Почты или свои)
- Трек-номер ваш (от СДЭК/Почты/своего курьера)
- Акты доставки ваши (не Ozon)

Сравнение схем

🏭 СКЛАДЫ {#склады}

Типы складов

1. По владению (warehouse_type)

2. По схеме работы (fulfillment_type)

3. По режиму работы (work_mode)

Настройки времени по маркетплейсам (2025)

OZON:
- Максимум времени на сборку: 24 часа
- Минимум для планирования поставки: 12 часов
- График по умолчанию: 09:00-18:00 пн-пт

WILDBERRIES:
- Максимум на обработку: 120 часов (5 дней)
- Рекомендуется: 24 часа
- График по умолчанию: 08:00-22:00 ежедневно
- Штраф за просрочку: 50% от стоимости (мин. 100₽)

ЯНДЕКС.МАРКЕТ:
- Минимум рабочих дней: 5
- Целевое среднее время отгрузки: 36 часов
- График по умолчанию: 09:00-20:00 пн-вс

💾 МОДЕЛИ БД {#модели-бд}

User (Пользователи)

id: int
email: str
password_hash: str
full_name: str
role: str  # owner/admin/manager/warehouse/viewer
active: bool
created_at: datetime

LegalEntity (Юридические лица)

id: int
user_id: int  # FK → User
name_full: str
name_short: str
inn: str  # 10 или 12 цифр
ogrn: str
entity_type: str  # LLC/IP/CJSC
address: str
director: str
is_default: bool
active: bool
created_at: datetime

Channel (Каналы продаж)

id: int
entity_id: int  # FK → LegalEntity
channel_name: str
channel_type: str  # marketplace/website
platform_type: str  # ozon/wildberries/yandex
client_id: str
api_key_encrypted: str
seller_id: str
status: str
active: bool
created_at: datetime
updated_at: datetime

Warehouse (Склады)

id: int
channel_id: int  # FK → Channel
external_id: str
name: str
warehouse_type: str  # own/marketplace/dropshipper/partner/virtual
fulfillment_type: str  # fbo/fbs/dbs/crossdock
work_mode: str  # 24/7/schedule/on_demand
work_schedule: str
is_active: bool
can_ship_anytime: bool
requires_appointment: bool
min_prep_time_hours: int
filter_rules: JSON
address: str
contact_person: str
phone: str

DeliveryService (Службы доставки)

id: int
channel_id: int  # FK → Channel
external_id: str
name: str
is_available: bool
delivery_time_from: int
delivery_time_to: int

Order (Заказы)

id: int
channel_id: int  # FK → Channel
entity_id: int  # FK → LegalEntity
external_order_id: str
order_date: datetime
status_external: str
status_internal: str

# Fulfillment схема
fulfillment_scheme: str  # fbo/fbs/realfbs
realfbs_type: str  # standard/comfort/express (для realfbs)

# Доставка
delivery_type: str  # kts/pvz/courier/post
delivery_service: str  # pochta/yandex/kts/cdek/boxberry

# Трекинг
tracking_number: str  # Ozon трек (для FBO/FBS)
own_tracking_number: str  # Свой трек (для realFBS)
track_uploaded: bool
shipped_at: datetime

# Клиент
customer_name: str
customer_phone: str
customer_email: str
address_json: JSON
items_json: JSON
total_amount: Decimal

created_at: datetime
updated_at: datetime

Product (Товары)

id: int
user_id: int  # FK → User
sku: str
barcode: str
article: str
name: str
description: text

# Тип товара
product_type: str  # simple/variant_group/kit/bundle
parent_id: int  # FK → Product (для вариаций)

# Категория и бренд
category: str
brand: str
ozon_category_id: int

# Цены
price: Decimal
old_price: Decimal
cost_price: Decimal
min_price: Decimal

# Габариты и вес
weight: int  # граммы
width: int  # мм
height: int  # мм
depth: int  # мм

# Остатки
stock_quantity: int
reserved_quantity: int
available_quantity: int

# Статус
is_active: bool
is_visible: bool

# Ozon
ozon_product_id: int
vat: str

created_at: datetime
updated_at: datetime

Return (Возвраты)

id: int
order_id: int  # FK → Order
channel_id: int  # FK → Channel
external_return_id: str
return_reason: str
return_type: str  # full/partial
status: str
return_date: datetime
refund_amount: Decimal
refund_date: datetime
warehouse_id: int
restocked: bool
condition: str  # new/damaged/defect
notes: text
created_at: datetime

Полный список всех моделей: См. database/models.py

🚀 ТЕХНОЛОГИИ {#технологии}

Backend:

• Python: 3.10+
• Framework: Streamlit 1.28+
• ORM: SQLAlchemy 2.0+
• Миграции: Alembic

UI/UX (v3.0.0):

• Тема: Кастомная на основе STYLE-GUIDE.md
• Модуль: core/theme.py (цвета, константы, хелперы)
• Конфиг: .streamlit/config.toml (Streamlit тема)
• CSS: Минимальный (styles/main.css - 16 строк)

Database:

• Dev: SQLite
• Prod: PostgreSQL (планируется)

API Integrations:

• Ozon Seller API: ✅ Реализовано
• СДЭК API: 🔄 В разработке
• Почта России API: 🔄 В разработке
• Wildberries API: 📋 Планируется
• Яндекс.Маркет API: 📋 Планируется

Infrastructure:

• Server: VPS (91.218.142.168)
• Domain: mp1.seller1.ru
• Web Server: Streamlit встроенный
• Reverse Proxy: Nginx (для SSL и доменов)

📁 СТРУКТУРА ПРОЕКТА {#структура-проекта}

marketplace-mvp/
├── app.py                      # Главная страница
├── requirements.txt            # Зависимости
├── alembic.ini                 # Конфиг Alembic
├── alembic/                    # Миграции БД
│   └── versions/
├── core/
│   ├── config.py               # Настройки
│   ├── database.py             # Подключение к БД
│   ├── auth.py                 # Авторизация
│   └── theme.py                # Тема v3.0.0 (цвета, шрифты, иконки)
├── database/
│   ├── models.py               # Все модели SQLAlchemy
│   └── init_db.py              # Инициализация БД
├── modules/
│   ├── api/
│   │   └── ozon.py             # Ozon API клиент
│   ├── legal_entities/
│   │   ├── crud.py             # CRUD юр.лиц
│   │   └── inn_api.py          # API ФНС
│   ├── products/
│   │   ├── crud.py             # CRUD товаров
│   │   └── queries.py          # Запросы
│   ├── orders/
│   │   └── items.py            # Обработка заказов
│   ├── negotiation/
│   │   ├── detector.py         # Детектор утряски
│   │   └── calculator.py       # Калькулятор возвратов
│   ├── status_mapping/
│   │   └── mapper.py           # Маппинг статусов
│   └── utils/
│       └── datetime_helper.py  # Работа с датами
├── pages/                      # Страницы Streamlit
│   ├── 01_🏢_Компании.py
│   ├── 02_📡_Каналы.py
│   ├── 03_🏷️_Товары.py
│   ├── 04_📋_Заказы.py
│   ├── 05_🔙_Возвраты.py
│   └── ...
├── .streamlit/                 # Конфигурация Streamlit
│   └── config.toml             # Тема v3.0.0 (настройки цветов/шрифтов)
├── utils/
│   └── styles.py               # Хелперы загрузки стилей
├── styles/                     # Минимальный CSS (16 строк)
│   └── main.css                # Скрытие UI элементов Streamlit
├── data/                       # Данные
│   └── marketplace.db
├── logs/                       # Логи
└── docs/                       # Документация
    ├── diagrams/
    └── archive/

📊 ТЕКУЩЕЕ СОСТОЯНИЕ {#текущее-состояние}

Версия: 2.4.0
Дата обновления: 2025-11-08

✅ РЕАЛИЗОВАНО:

Инфраструктура:
- ✅ Модели БД (User, LegalEntity, Channel, Warehouse, Order, Product, Return)
- ✅ Авторизация пользователей (Streamlit Authenticator)
- ✅ Миграции Alembic

Функции:
- ✅ 3-шаговый визард подключения каналов Ozon
- ✅ Автоматическое создание/обновление юр.лиц по ИНН (ФНС API)
- ✅ Загрузка справочников с Ozon (склады, службы доставки, статусы)
- ✅ Интеграция Ozon API (полная)
- ✅ Загрузка заказов (FBS/realFBS схемы)
- ✅ Система возвратов и утряски
- ✅ Библиотека работы с датами/временем (datetime_helper)

UI:
- ✅ Компактные таблицы (стиль Airtable)
- ✅ Страницы: Компании, Каналы, Товары, Заказы, Возвраты

❌ НЕ РЕАЛИЗОВАНО:

Интеграции:
- ❌ СДЭК API (в разработке)
- ❌ Почта России API (в разработке)
- ❌ Wildberries API
- ❌ Яндекс.Маркет API

Функции:
- ❌ Автоматическая обработка realFBS заказов
- ❌ Учёт остатков (StockMovement)
- ❌ Дропшиппинг (Supplier, SupplierProduct)
- ❌ Замены товаров (Substitution)
- ❌ Аналитика и отчёты
- ❌ Telegram бот уведомления
- ❌ Multi-user (роли и права доступа)

🔗 ССЫЛКИ {#ссылки}

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

• 🗺️ Roadmap и приоритеты: См. MP1-ROADMAP.md
• 🔌 API методы: См. MP1-API-GUIDE.md
• 📝 История изменений: См. MP1-CHANGELOG.md

Универсальные гайды:

• 🎨 Дизайн UI/UX: См. STYLE-GUIDE.md
• 💻 Стандарты кода: См. CODE-GUIDE.md
• ⚙️ Процессы работы: См. WORKFLOWS.md

Внешние ресурсы:

• Ozon API Docs: https://docs.ozon.ru/api/seller/
• Streamlit Docs: https://docs.streamlit.io/
• SQLAlchemy Docs: https://docs.sqlalchemy.org/

Последнее обновление: 2025-11-08
Автор: Marketplace MVP Team