Классы артефактов платформы

LIBRARY/     = ГОТОВЫЙ КОД (stable, tested, reusable)
PROJECTS/    = ИСПОЛЬЗОВАНИЕ + РАЗРАБОТКА (настройки, экземпляры, эксперименты)
SYSTEM/      = ЯДРО ПЛАТФОРМЫ (runtime, agents, core)
INFRA/       = ИНФРАСТРУКТУРА (серверы, хранилища)
RUNTIME      = ВЫПОЛНЕНИЕ (сессия, инстанс, процесс)

projects/my/new-connector/   →   library/connectors/api/xyz/
      (разработка)                    (готовый код)

        АТОМЫ (низкий уровень)
        ┌─────────────────────────────┐
        │ 3. Функции                  │  parsers, validators, formatters
        └─────────────┬───────────────┘
                      │ используют
                      ▼
        ┌─────────────────────────────┐
        │ 4. API-коннекторы           │  ozon, telegram, 1c
        │ 5. Data-коннекторы          │  postgres, xlsx, s3
        │ 5b. Device-коннекторы       │  printers, scanners
        │ 6. Расширения               │  cs-cart модули, drupal модули
        └─────────────┬───────────────┘
                      │ комбинируют
                      ▼
        МОЛЕКУЛЫ (средний уровень)
        ┌─────────────────────────────┐
        │ 7. Интеграции               │  ozon-1c-sync, order-to-cdek
        │ 8. Сервисы                  │  pim-api, sync-worker
        │ 9. Приложения               │  shop-engine, admin-panel
        └─────────────┬───────────────┘
                      │ настраивают
                      ▼
        ПРОДУКТЫ (высокий уровень)
        ┌─────────────────────────────┐
        │ 10. Конфигурации            │  shop-fireworks, shop-auto
        └─────────────┬───────────────┘
                      │ применяют
                      ▼
        КЛИЕНТ (проектный уровень)
        ┌─────────────────────────────┐
        │ 11. Решения                 │  pirotehnika/shop
        │ 12. Проекты                 │  pirotehnika, lideravto
        └─────────────────────────────┘

        ОТДЕЛЬНО:
        ┌─────────────────────────────┐
        │ 1. Инфра                    │  infra/
        │ 2. Данные                   │  $DATASPACE/
        └─────────────────────────────┘

КОННЕКТОР              КОННЕКТ               СЕССИЯ
(код)              →   (настройки)       →   (runtime)
library/connectors/    projects/connects/    в памяти

ИНТЕГРАЦИЯ             ИНТЕГРАЦИЯ            ДЖОБ
(код)              →   (настроенная)     →   (runtime)
library/integrations/  projects/integrations/ процесс

СЕРВИС                 СЕРВИС                ИНСТАНС
(код)              →   (настроенный)     →   (runtime)
library/services/      projects/services/    процесс

ПРИЛОЖЕНИЕ             КОНФИГУРАЦИЯ          РЕШЕНИЕ
(код)              →   (отраслевая)      →   (для клиента)
library/applications/  library/configurations/ projects/.../app/

Где:        infra/
Что:        Серверы, хранилища, сети
Примеры:    @dev-pro.server, @beget-s3.storage
В library:  НЕТ (инфра не переиспользуется как код)
В projects: НЕТ (инфра общая)

Где:        $DATASPACE/
Что:        Бинарные файлы (xlsx, jpg, pdf, json >1MB)
Примеры:    prices/*.xlsx, images/*.jpg
В library:  НЕТ (это не код)
В projects: $DATASPACE/projects/{name}/

Где:        library/functions/
Что:        Атомарные операции без внешних зависимостей
Типы:
  - parsers/      — чтение форматов (xlsx, csv, html)
  - formatters/   — форматирование (price, phone, date)
  - validators/   — проверка (email, inn, phone)
  - calculators/  — вычисления (price, delivery)
  - generators/   — генерация (barcode, sku, uuid)
В library:  library/functions/parsers/xlsx/
В projects: НЕТ (используется через import)
Runtime:    вызов функции

Где:        library/connectors/api/
Что:        Связь с внешним сервисом по API
Примеры:    ozon, telegram, 1c, cdek, wildberries
В library:  library/connectors/api/ozon/
В projects: projects/.../connects/ozon.yaml
Runtime:    сессия (авторизованное подключение)

Где:        library/connectors/data/
Что:        Связь с источником данных
Примеры:    postgres, mysql, redis, s3, xlsx, csv
В library:  library/connectors/data/postgres/
В projects: projects/.../connects/db.yaml
Runtime:    сессия (открытое соединение)

Где:        library/connectors/device/
Что:        Связь с физическим устройством
Примеры:    printers (чеки, этикетки), scanners (штрих-коды)
В library:  library/connectors/device/printer/
В projects: projects/.../connects/printer.yaml
Runtime:    сессия (подключение к устройству)

Где:        library/extensions/{platform}/
Что:        Модуль для чужой платформы
Примеры:    cs-cart/smart_images, drupal/commerce_sync
В library:  library/extensions/cs-cart/smart_images/
В projects: projects/.../modules.yaml (список используемых)
Runtime:    установленный модуль на платформе

Где:        library/integrations/
Что:        Бизнес-процесс из нескольких коннекторов
Примеры:    ozon-1c-sync, order-to-cdek, low-stock-alert
В library:  library/integrations/ozon-1c-sync/
В projects: projects/.../integrations/ozon-1c-sync.yaml
Runtime:    джоб (запущенный процесс синхронизации)

Где:        library/services/
Что:        Работающий процесс (API, worker, daemon)
Примеры:    pim-api, sync-worker, notification-service
В library:  library/services/pim-api/
В projects: projects/.../services/@pim.api/
Runtime:    инстанс (запущенный сервис)

Где:        library/applications/
Что:        Самостоятельная готовая программа
Примеры:    shop-engine, admin-panel, dashboard
В library:  library/applications/shop-engine/
В projects: НЕТ (используется через конфигурацию)
Runtime:    НЕТ (это шаблон)

Где:        library/configurations/
Что:        Отраслевая настройка приложения
Примеры:    shop-fireworks, shop-auto, shop-clothes
В library:  library/configurations/shop-fireworks/
В projects: НЕТ (используется через решение)
Runtime:    НЕТ (это настройки)

Где:        projects/.../app/
Что:        Применение конфигурации к конкретному клиенту
Примеры:    pirotehnika/app/shop, lideravto/app/shop
В library:  НЕТ
В projects: projects/org/pirotehnika/app/shop/
Runtime:    работающее приложение

Где:        projects/{owner}/{name}/
Что:        Бизнес или клиент целиком
Примеры:    org/pirotehnika, org/lideravto, my/experiments
В library:  НЕТ
В projects: projects/org/pirotehnika/
Runtime:    весь бизнес

$WORKSPACE/
│
├── architect/                        ← МЕТА (методология)
│
├── infra/                            ← 1. ИНФРА
│   ├── @dev-pro.server/
│   └── @beget-s3.storage/
│
├── library/                          ← БИБЛИОТЕКА (классы 3-10)
│   │
│   ├── functions/                    ← 3. ФУНКЦИИ
│   │   ├── parsers/
│   │   │   ├── xlsx/
│   │   │   ├── csv/
│   │   │   └── html/
│   │   ├── formatters/
│   │   │   ├── price/
│   │   │   └── phone/
│   │   ├── validators/
│   │   │   ├── email/
│   │   │   └── inn/
│   │   ├── calculators/
│   │   └── generators/
│   │
│   ├── connectors/                   ← 4-5. КОННЕКТОРЫ
│   │   ├── api/                      ← 4. API-коннекторы
│   │   │   ├── ozon/
│   │   │   ├── telegram/
│   │   │   ├── 1c/
│   │   │   └── cdek/
│   │   ├── data/                     ← 5. Data-коннекторы
│   │   │   ├── postgres/
│   │   │   ├── xlsx/
│   │   │   ├── s3/
│   │   │   └── redis/
│   │   └── device/                   ← 5b. Device-коннекторы
│   │       ├── printer/
│   │       └── scanner/
│   │
│   ├── extensions/                   ← 6. РАСШИРЕНИЯ
│   │   ├── cs-cart/
│   │   │   ├── smart_images/
│   │   │   └── lider_import/
│   │   ├── drupal/
│   │   └── opencart/
│   │
│   ├── integrations/                 ← 7. ИНТЕГРАЦИИ
│   │   ├── ozon-1c-sync/
│   │   ├── order-to-cdek/
│   │   └── low-stock-alert/
│   │
│   ├── services/                     ← 8. СЕРВИСЫ
│   │   ├── pim-api/
│   │   └── sync-worker/
│   │
│   ├── applications/                 ← 9. ПРИЛОЖЕНИЯ
│   │   ├── shop-engine/
│   │   └── admin-panel/
│   │
│   └── configurations/               ← 10. КОНФИГУРАЦИИ
│       ├── shop-fireworks/
│       └── shop-auto/
│
├── system/                           ← ЯДРО ПЛАТФОРМЫ (не library!)
│   ├── agents/                       ← AI-агенты
│   │   ├── dispatcher.ai.md
│   │   ├── projector.ai.md
│   │   ├── specialists/
│   │   └── workers/
│   ├── core/                         ← Движок
│   ├── config/                       ← Системная конфигурация
│   ├── monitor/                      ← Мониторинг
│   ├── scheduler/                    ← Планировщик
│   └── scripts/                      ← Утилиты
│
└── projects/                         ← ПРОЕКТЫ (классы 11-12)
    ├── my/                           ← Личные
    └── org/                          ← Организации
        └── pirotehnika/              ← 12. ПРОЕКТ
            ├── connects/             ← Коннекты (настройки подключений)
            │   ├── ozon.yaml
            │   ├── telegram.yaml
            │   └── db.yaml
            ├── modules.yaml          ← Какие расширения используем
            ├── integrations/         ← Интеграции (настроенные)
            │   └── ozon-1c-sync.yaml
            ├── services/             ← Сервисы (настроенные)
            │   └── @pim.api/
            └── app/                  ← 11. РЕШЕНИЯ
                └── shop/
                    extends: library/configurations/shop-fireworks

$DATASPACE/
└── projects/                         ← 2. ДАННЫЕ
    └── pirotehnika/
        ├── prices/
        ├── images/
        └── exports/

library/
├── functions/        ← Атомарные функции (parsers, formatters)
├── connectors/       ← Подключения (api, data, device)
├── extensions/       ← Расширения платформ (cs-cart, drupal)
├── integrations/     ← Бизнес-процессы
├── services/         ← Сервисы (API, workers)
├── applications/     ← Приложения-шаблоны
└── configurations/   ← Отраслевые конфигурации

system/
├── agents/           ← AI-агенты (НЕ в library!)
├── core/             ← Движок платформы
├── config/           ← Системная конфигурация
├── monitor/          ← Мониторинг
├── scheduler/        ← Планировщик задач
└── scripts/          ← Системные утилиты

infra/
├── @dev-pro.server       ← Серверы
├── @beget-s3.storage     ← Хранилища
└── @backup.service       ← Инфра-сервисы