RESOURCES.md

Принцип зеркальности: Структура папок идентична, различается только содержимое.

ПРАВИЛО РАЗМЕЩЕНИЯ

ПРИНЦИП: НЕТ ШАРИНГА В ПРОЕКТАХ

В WORKSPACE	В DATASPACE
`.py`, `.sh`, `.js`, `.go`	`.xlsx`, `.csv`, `.json` (данные)
`.md`, `.rst` (документы)	`.jpg`, `.png`, `.pdf`
`.yaml`, `.toml` (конфиги)	`.zip`, `.tar.gz` (архивы)
Шаблоны, примеры	Бэкапы, дампы

❌ НЕПРАВИЛЬНО:
projects/
├── pirotehnika/
│   └── shared_lib/          ← Общий код в проекте
└── lideravto/
    └── → ../pirotehnika/shared_lib/  ← Симлинк на чужой код

✅ ПРАВИЛЬНО:
system/
└── connectors/              ← Общий код в платформе
    └── ozon/

projects/
├── pirotehnika/
│   └── config/ozon.yaml     ← Только конфигурация
└── lideravto/
    └── config/ozon.yaml     ← Своя конфигурация

Принцип: Общий код = платформенный код. Проект содержит только свою конфигурацию.

КЛАССИФИКАЦИЯ РЕСУРСОВ

По природе

АКТИВНЫЕ (имеют логику)          ПАССИВНЫЕ (только данные)
├── API сервисов                 ├── Файлы форматов
├── Базы данных                  ├── Статические данные
├── Очереди сообщений            └── Архивы
└── Устройства

По владению

ВНЕШНИЕ (не контролируем)        ВНУТРЕННИЕ (контролируем)
├── OZON API                     ├── PostgreSQL
├── Telegram API                 ├── NocoDB
├── 1С                           ├── S3 хранилище
└── Почта России                 └── Локальные файлы

По уровню абстракции

L1 СЕРВИСЫ     Бизнес-логика      OZON, Telegram, 1С
      ↓
L2 ПРОТОКОЛЫ   Способ общения     HTTP, FTP, SQL, WebSocket
      ↓
L3 ФОРМАТЫ     Структура данных   JSON, XML, XLSX, CSV
      ↓
L4 ТРАНСПОРТ   Передача байтов    TCP, файл, память

ИЕРАРХИЯ ПОНЯТИЙ

┌─────────────────────────────────────────────────────────────────────────┐
│                           ПЛАТФОРМА (system/)                            │
│                         Переиспользуемый код                             │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  CONNECTOR          DRIVER            ADAPTER           STORE           │
│  Внешний сервис     Устройство        Формат данных     Хранилище       │
│  ─────────────      ──────────        ─────────────     ─────────       │
│  ozon               printer           xlsx              postgres        │
│  telegram           scanner           pdf               redis           │
│  1c                 pos               csv               s3              │
│  cdek               barcode           xml               clickhouse      │
│  sberbank           label_printer     json              mongodb         │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                           ПРОЕКТ (projects/)                             │
│                        Бизнес-специфичный код                            │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  CONFIG             CLIENT            INTEGRATION       SERVICE         │
│  Настройки          Экземпляр         Бизнес-процесс    Приложение      │
│  ────────           ─────────         ──────────────    ──────────      │
│  ozon.yaml          OzonClient()      ozon-1c-sync      @ozon.api       │
│  db.yaml            PostgresClient()  auto-delivery     @pim.service    │
│  telegram.yaml      TelegramClient()  price-update      @bot.app        │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                           ДАННЫЕ ($DATASPACE)                            │
│                      Файлы, экспорты, бэкапы                             │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  prices/            images/           exports/          backups/        │
│  Прайсы xlsx        Фото товаров      JSON выгрузки     Архивы          │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

ТЕРМИНЫ: ПЛАТФОРМА

Структура платформы

Термин	Уровень	Назначение	Примеры
Connector	Платформа	Доступ к внешнему API/сервису	ozon, telegram, 1c, cdek
Driver	Платформа	Работа с физическим устройством	printer, scanner, pos, barcode
Adapter	Платформа	Чтение/запись формата данных	xlsx, pdf, csv, xml, json
Store	Платформа	Доступ к хранилищу данных	postgres, redis, s3, clickhouse

system/
├── connectors/           ← Внешние сервисы (API)
│   ├── marketplaces/
│   │   ├── ozon/
│   │   ├── wildberries/
│   │   └── yandex_market/
│   ├── messengers/
│   │   ├── telegram/
│   │   └── whatsapp/
│   ├── accounting/
│   │   ├── 1c/
│   │   └── moysklad/
│   └── delivery/
│       ├── cdek/
│       └── pochta/
│
├── drivers/              ← Устройства
│   ├── printers/
│   │   ├── receipt/
│   │   └── label/
│   ├── scanners/
│   │   └── barcode/
│   └── pos/
│
├── adapters/             ← Форматы данных
│   ├── spreadsheets/
│   │   ├── xlsx/
│   │   └── csv/
│   ├── documents/
│   │   └── pdf/
│   └── data/
│       ├── json/
│       └── xml/
│
└── stores/               ← Хранилища
    ├── sql/
    │   ├── postgres/
    │   └── mysql/
    ├── nosql/
    │   ├── redis/
    │   └── mongodb/
    └── object/
        └── s3/

ТЕРМИНЫ: ПРОЕКТ

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

Термин	Уровень	Назначение	Примеры
Config	Проект	Настройки для платформенного компонента	`config/ozon.yaml`
Client	Проект	Инициализированный экземпляр компонента	`OzonClient(config)`
Integration	Проект	Бизнес-процесс из нескольких компонентов	`ozon-1c-sync/`
Service	Проект	Работающее приложение	`@ozon.api/`, `@bot.app/`

projects/pirotehnika/
│
├── config/                    ← КОНФИГУРАЦИИ
│   ├── ozon.yaml              ← Настройки для Ozon connector
│   ├── telegram.yaml          ← Настройки для Telegram connector
│   ├── db.yaml                ← Настройки для PostgreSQL store
│   └── s3.yaml                ← Настройки для S3 store
│
├── integrations/              ← ИНТЕГРАЦИИ (бизнес-процессы)
│   ├── ozon-1c-sync/          ← Синхронизация Ozon ↔ 1С
│   │   ├── sync_orders.py
│   │   ├── sync_products.py
│   │   └── mapping.yaml
│   │
│   └── auto-delivery/         ← Автоотправка заказов
│       ├── create_shipment.py
│       └── rules.yaml
│
├── services/                  ← СЕРВИСЫ (приложения)
│   ├── @ozon.api/             ← API для работы с Ozon
│   ├── @pim.service/          ← PIM система
│   └── @bot.app/              ← Telegram бот
│
└── scripts/                   ← СКРИПТЫ (разовые задачи)
    ├── import_prices.py
    └── generate_report.py

СВЯЗИ МЕЖДУ УРОВНЯМИ

ПЛАТФОРМА                    ПРОЕКТ                      КОД
──────────────────────────────────────────────────────────────────────────

Connector: ozon/       →     Config: ozon.yaml     →     client = OzonClient(config)
                             (client_id, api_key)        client.get_products()

Store: postgres/       →     Config: db.yaml       →     db = PostgresClient(config)
                             (host, port, database)      db.query("SELECT ...")

Adapter: xlsx/         →     (без конфига)         →     data = XlsxAdapter.read(file)
                                                         XlsxAdapter.write(data, file)

Driver: printer/       →     Config: printer.yaml  →     printer = PrinterDriver(config)
                             (port, model)               printer.print(label)

ПРИМЕР ИСПОЛЬЗОВАНИЯ

1. Платформа предоставляет

# library/connectors/api/ozon/client.py
class OzonClient:
    def __init__(self, client_id: str, api_key: str):
        self.client_id = client_id
        self.api_key = api_key

    @classmethod
    def from_config(cls, config_path: str):
        config = yaml.load(config_path)
        return cls(**config)

    def get_products(self): ...
    def get_orders(self): ...
    def update_stocks(self): ...

2. Проект конфигурирует

# projects/pirotehnika/config/ozon.yaml
accounts:
  O1:
    client_id: "3318433"
    api_key: "${OZON_O1_API_KEY}"  # из .env
    warehouse_id: "123"
  O2:
    client_id: "1763357"
    api_key: "${OZON_O2_API_KEY}"

3. Интеграция использует

# projects/pirotehnika/integrations/ozon-1c-sync/sync_orders.py
from system.connectors.marketplaces.ozon import OzonClient
from system.connectors.accounting.onec import OneCClient

# Загружаем клиенты из конфигов
ozon = OzonClient.from_config("config/ozon.yaml", account="O1")
onec = OneCClient.from_config("config/1c.yaml")

# Бизнес-логика интеграции
orders = ozon.get_orders(status="awaiting")
for order in orders:
    onec.create_order(map_order(order))

ПОЛНАЯ ТЕРМИНОЛОГИЯ

КАК ПРОЕКТ ИСПОЛЬЗУЕТ ПЛАТФОРМУ

1. Конфигурация

Термин	Где	Что это	Пример
Connector API	`library/connectors/api/`	Код доступа к внешнему API	`ozon/`, `telegram/`
Connector Data	`library/connectors/data/`	Код доступа к хранилищу	`postgres/`, `nocodb/`
Connector Device	`library/connectors/device/`	Код работы с устройством	`printer/`, `scanner/`
Parser	`library/functions/parsers/`	Код чтения/записи формата	`xlsx/`, `pdf/`
Config	`projects/*/config/`	YAML с настройками	`ozon.yaml`
Client	В коде	Экземпляр с конфигом	`OzonClient()`
Integration	`projects/*/integrations/`	Бизнес-процесс	`ozon-1c-sync/`
Service	`projects/*/services/`	Приложение	`@ozon.api/`
Script	`projects/*/scripts/`	Разовая задача	`import_prices.py`

# projects/pirotehnika/config/ozon.yaml
connector: ozon
accounts:
  O1:
    client_id: 3318433
    warehouse: "..."
  O2:
    client_id: 1763357

2. Привязка (binding)

# projects/pirotehnika/services/@ozon.api/main.py
from system.connectors.ozon import OzonConnector

# Загружаем конфигурацию проекта
config = load_config("config/ozon.yaml")

# Создаём экземпляр коннектора с конфигом проекта
ozon = OzonConnector(config)

3. Данные

# Данные в DATASPACE с такой же структурой
$DATASPACE/projects/pirotehnika/services/@ozon.api/
├── exports/           ← Экспорты из OZON
├── imports/           ← Импорты в OZON
└── logs/              ← Логи операций

ДИАГРАММА

┌─────────────────────────────────────────────────────────────┐
│                      ПЛАТФОРМА (system/)                     │
├─────────────────────────────────────────────────────────────┤
│  connectors/    drivers/    adapters/    stores/            │
│  ├── ozon/      ├── printer/ ├── xlsx/   ├── postgres/      │
│  ├── telegram/  └── scanner/ ├── pdf/    ├── s3/            │
│  └── 1c/                     └── csv/    └── redis/         │
└─────────────────────────────────────────────────────────────┘
           │              │            │           │
           ▼              ▼            ▼           ▼
┌─────────────────────────────────────────────────────────────┐
│                      ПРОЕКТ (projects/)                      │
├─────────────────────────────────────────────────────────────┤
│  config/ozon.yaml    (настройки коннектора)                 │
│  config/store.yaml   (настройки хранилища)                  │
│  services/@ozon.api/ (код, использующий коннекторы)         │
└─────────────────────────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────┐
│                      ДАННЫЕ ($DATASPACE)                     │
├─────────────────────────────────────────────────────────────┤
│  projects/pirotehnika/                                       │
│  ├── inbox/              (входящие файлы)                   │
│  ├── prices/             (прайсы xlsx)                      │
│  ├── images/             (фото товаров)                     │
│  └── archive/            (старое)                           │
└─────────────────────────────────────────────────────────────┘

Концепция: Ресурсы и Доступ

КЛЮЧЕВАЯ ИДЕЯ