Паттерн: DATA-FIRST

ДАННЫЕ → CLI → ВЕБ → [PRO]
   ↑       ↑      ↑
 Мастер  Отладка Продукт

┌─────────────────────────────────────────────────────────────────────┐
│                                                                     │
│   ДАННЫЕ — единственный источник правды                            │
│                                                                     │
│   • Сначала структура данных (схема)                               │
│   • Потом наполнение (импорт из Excel/CSV/API)                     │
│   • Потом манипуляции (CRUD)                                        │
│   • Потом отображение (интерфейс)                                   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│                                                                     │
│   CLI — лаборатория                                                 │
│                                                                     │
│   • Каждая операция сначала работает в CLI                         │
│   • Видим ввод, вывод, ошибки                                       │
│   • Легко тестировать и отлаживать                                  │
│   • Результат: проверенная библиотека функций                      │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│                                                                     │
│   ВЕБ — не переписывание, а обёртка                                │
│                                                                     │
│   • Кнопка = вызов функции из библиотеки                           │
│   • Таблица = SELECT из БД                                          │
│   • Форма = INSERT/UPDATE в БД                                      │
│   • Никакой бизнес-логики в вебе — только UI                       │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│                           ИНТЕРФЕЙСЫ                                │
│                                                                     │
│    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐           │
│    │    CLI      │    │     ВЕБ     │    │    PRO      │           │
│    │  (отладка)  │    │  (продукт)  │    │   (SaaS)    │           │
│    └──────┬──────┘    └──────┬──────┘    └──────┬──────┘           │
│           │                  │                  │                   │
│           └──────────────────┼──────────────────┘                   │
│                              │                                      │
├──────────────────────────────┼──────────────────────────────────────┤
│                         БИБЛИОТЕКА                                  │
│                              │                                      │
│                    ┌─────────┴─────────┐                           │
│                    │    {project}_lib  │                           │
│                    │    ────────────   │                           │
│                    │    db.py          │  ← Доступ к данным        │
│                    │    models.py      │  ← Модели                 │
│                    │    clients/       │  ← Внешние API            │
│                    │    processes/     │  ← Бизнес-процессы        │
│                    └─────────┬─────────┘                           │
│                              │                                      │
├──────────────────────────────┼──────────────────────────────────────┤
│                           ДАННЫЕ                                    │
│                              │                                      │
│              ┌───────────────┼───────────────┐                     │
│              │               │               │                     │
│              ↓               ↓               ↓                     │
│       ┌───────────┐   ┌───────────┐   ┌───────────┐               │
│       │  КОНФИГ   │   │    БД     │   │   ЛОГИ    │               │
│       │ config.json│   │ PostgreSQL│   │ sync_log  │               │
│       └───────────┘   └───────────┘   └───────────┘               │
│                                                                     │
├─────────────────────────────────────────────────────────────────────┤
│                      ВНЕШНИЕ СЕРВИСЫ                                │
│                                                                     │
│      ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐       │
│      │Маркетплейс│  │ Доставка │  │   ERP    │  │Мессенджер│       │
│      └──────────┘  └──────────┘  └──────────┘  └──────────┘       │
└─────────────────────────────────────────────────────────────────────┘

{project}/
├── MASTER.md                 # Главный документ проекта
├── config.json               # Единый конфиг (аккаунты, службы, лимиты)
│
├── {project}_lib/            # БИБЛИОТЕКА (Python package)
│   ├── __init__.py
│   ├── config.py             # Загрузка конфига
│   ├── db.py                 # Единый доступ к БД
│   ├── models.py             # Модели данных (dataclass/pydantic)
│   │
│   ├── clients/              # API клиенты (внешние сервисы)
│   │   ├── __init__.py
│   │   ├── ozon.py           # OZON API
│   │   ├── pochta.py         # Почта России API
│   │   └── ...
│   │
│   └── processes/            # Бизнес-процессы (атомарные операции)
│       ├── __init__.py
│       ├── p0_import.py      # Импорт данных
│       ├── p1_create.py      # Создание сущностей
│       ├── p2_update.py      # Обновление
│       └── p3_sync.py        # Синхронизация
│
├── cli/                      # CLI ИНТЕРФЕЙС
│   ├── __init__.py
│   ├── main.py               # Точка входа: python -m cli
│   └── commands/             # Команды
│       ├── import_.py        # cli import
│       ├── sync.py           # cli sync
│       └── status.py         # cli status
│
├── web/                      # ВЕБ ИНТЕРФЕЙС (или ссылка на @service)
│   └── → services/@{name}.service/
│
└── docs/                     # Документация
    ├── PROCESSES.md          # Описание процессов
    ├── API.md                # API endpoints
    └── CHANGELOG.md          # История изменений

1. Определить сущности (entities)
   └─ Что храним? (заказы, товары, клиенты...)

2. Спроектировать схему БД
   └─ Таблицы, поля, связи

3. Создать модели (models.py)
   └─ Python классы для данных

4. Импортировать начальные данные
   └─ Из Excel/CSV/API → БД

1. Написать клиенты для внешних API
   └─ clients/ozon.py, clients/pochta.py...

2. Написать процессы (бизнес-логика)
   └─ processes/p0_import.py...

3. Создать CLI команды
   └─ cli/commands/...

4. Тестировать в терминале
   └─ python -m cli sync --dry-run

1. Подключить библиотеку к FastAPI
   └─ from {project}_lib import ...

2. Создать endpoints
   └─ Кнопка → вызов process

3. Создать UI (таблицы, формы)
   └─ Данные из БД

4. Добавить авторизацию
   └─ OAuth/JWT

1. Мультитенант (несколько клиентов)
2. API для внешних пользователей
3. Биллинг
4. SLA

# ПРАВИЛЬНО: всё из БД
orders = db.get_orders(account="O1")

# НЕПРАВИЛЬНО: данные в файлах
orders = json.load(open("/tmp/orders.json"))

# ПРАВИЛЬНО: из конфига
accounts = config.get_accounts()  # ["O1", "O2", "O3"]

# НЕПРАВИЛЬНО: hardcode
accounts = ["O1", "O2", "O3"]

# ПРАВИЛЬНО: CLI использует библиотеку
from fulfillment.processes import p0_import
p0_import.run(account="O1")

# ПРАВИЛЬНО: Веб использует ту же библиотеку
from fulfillment.processes import p0_import
@router.post("/import")
async def import_orders():
    return p0_import.run(account="O1")

# НЕПРАВИЛЬНО: дублирование логики
# В CLI одна реализация, в вебе другая

# ПРАВИЛЬНО: один процесс — одна задача
p0_import.run()   # Только импорт
p1_create.run()   # Только создание
p2_ship.run()     # Только отгрузка

# НЕПРАВИЛЬНО: процесс делает всё
process_everything()  # Монолит

# ПРАВИЛЬНО: история в таблице
db.log_sync(process="p0", account="O1", result={"imported": 5})

# НЕПРАВИЛЬНО: логи только в консоль/файлы
print("Imported 5 orders")

fulfillment/
├── MASTER.md
├── config.json
├── fulfillment/          ← Библиотека
│   ├── db.py
│   ├── clients/
│   │   ├── ozon.py
│   │   └── pochta.py
│   └── processes/
│       ├── p0_import.py
│       ├── p1_create.py
│       ├── p2_ship.py
│       └── p3_status.py
├── cli/
│   └── main.py           ← fulfill sync
└── → @mp1.service        ← Веб-интерфейс

pim/
├── MASTER.md
├── config.json
├── pim_lib/              ← Библиотека
│   ├── db.py
│   ├── clients/
│   │   └── nocodb.py
│   └── processes/
│       ├── import_prices.py
│       ├── match_products.py
│       └── export_to_ozon.py
├── cli/
│   └── main.py           ← pim import
└── → @mp1.service        ← Веб-интерфейс