┌─────────────────────────────────────────────────────────────┐
│                                                             │
│  ИЗМЕРЕНИЕ 1: УРОВЕНЬ ПЛАТФОРМЫ (L0-L6)                     │
│  ────────────────────────────────────                        │
│  Где живёт код в экосистеме                                 │
│                                                             │
│  L0-L2  architect/      ← Методология                       │
│  L3     system/         ← Движок платформы                  │
│  L4     library/        ← Универсальные компоненты          │
│  L5     components/     ← Готовые решения (БУДЕТ)           │
│  L6     projects/       ← Конкретные проекты                │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ИЗМЕРЕНИЕ 2: ТИП СУЩНОСТИ (роль в системе)                │
│  ─────────────────────────────────────────                  │
│  Что делает класс/модуль                                    │
│                                                             │
│  Primitive → Function → Connector → Adapter → Service       │
│  (данные)   (атом)      (транспорт) (маппинг)  (логика)    │
│                                                             │
│  + Model, Repository, Parser, Factory, Config...            │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ИЗМЕРЕНИЕ 3: СЛОЙ TOGAF (внутри приложения)               │
│  ──────────────────────────────────────────                 │
│  Архитектурный слой                                         │
│                                                             │
│  MOTIVATION → BUSINESS → DATA → APPLICATION → TECHNOLOGY    │
│     (зачем)     (как)    (что)     (код)        (где)      │
│                                                             │
└─────────────────────────────────────────────────────────────┘

class ProductService:
    """
    УРОВЕНЬ: L6 (projects/pirotehnika/app/pim/)
    ТИП: Service
    СЛОЙ: APPLICATION
    """

L6  projects/pirotehnika/app/pim/
     ↓ использует
L4  library/connectors/api/ozon/
     ↓ использует
L3  system/core/executor/
     ↓ использует
L2  architect/standards/
     ↓ основаны на
L1  architect/concept/
     ↓ основаны на
L0  architect/theory/

# ✅ ПРАВИЛЬНО
# L6 → L4
from library.connectors.api.ozon import OzonConnector

# ❌ НЕПРАВИЛЬНО
# L4 → L6 (обратная зависимость!)
from projects.pirotehnika.app.pim import ProductService

┌──────────────────────────────────────────────────────────────┐
│  L2: PRIMITIVES (атомы данных)                               │
├──────────────────────────────────────────────────────────────┤
│  Type          │ Dataclass, Pydantic модель, TypedDict       │
│  Enum          │ Перечисление (IntEnum, StrEnum)             │
│  Constant      │ CONST = value                                │
│  Exception     │ class MyError(Exception)                     │
└──────────────────────────────────────────────────────────────┘
         ↓ используются в
┌──────────────────────────────────────────────────────────────┐
│  L3: FUNCTIONS (атомы логики)                                │
├──────────────────────────────────────────────────────────────┤
│  Validator     │ def validate_inn(inn: str) -> bool          │
│  Formatter     │ def format_money(amount: int) -> str        │
│  Normalizer    │ def normalize_phone(phone: str) -> str      │
│  Calculator    │ def calculate_price(base, margin) -> Decimal│
│  Generator     │ def generate_uuid() -> str                  │
│  Transformer   │ def transform_to_dict(obj) -> dict          │
└──────────────────────────────────────────────────────────────┘
         ↓ используются в
┌──────────────────────────────────────────────────────────────┐
│  L4: COMPONENTS (молекулы)                                   │
├──────────────────────────────────────────────────────────────┤
│  Connector     │ Связь с внешним API/системой                │
│  Parser        │ Чтение структурированных данных             │
│  Adapter       │ Преобразование формата A → B                │
│  Mapper        │ Маппинг полей между сущностями              │
│  Repository    │ Доступ к хранилищу данных                   │
│  Cache         │ Кеширование                                 │
│  Queue         │ Очереди задач                               │
│  Factory       │ Создание объектов                           │
└──────────────────────────────────────────────────────────────┘
         ↓ используются в
┌──────────────────────────────────────────────────────────────┐
│  L5: SERVICES (оркестрация)                                  │
├──────────────────────────────────────────────────────────────┤
│  Service       │ Бизнес-логика (ProductService)              │
│  SyncService   │ Синхронизация данных между системами        │
│  Worker        │ Фоновые задачи (Celery task)                │
│  Handler       │ Обработчик событий                          │
│  UseCase       │ Сценарий использования (CQRS)               │
└──────────────────────────────────────────────────────────────┘
         ↓ используются в
┌──────────────────────────────────────────────────────────────┐
│  L6: INTEGRATIONS (экосистемы)                               │
├──────────────────────────────────────────────────────────────┤
│  Integration   │ Связка систем (OZON ↔ 1C)                   │
│  Pipeline      │ Конвейер обработки данных                   │
│  Workflow      │ Многоэтапный процесс                        │
└──────────────────────────────────────────────────────────────┘

class OzonConnector:
    """OZON Seller API Connector"""

    async def _request(self, method: str, endpoint: str, **kwargs) -> Dict:
        """Базовый HTTP запрос"""

    async def get_orders(self, status: str) -> List[Dict]:
        """Получить заказы"""

library/connectors/api/ozon/
├── client.py          ← OzonConnector
├── SPEC.md            ← Спецификация API
├── QUIRKS.md          ← Особенности (!!)
└── STATUS.md          ← Статус тестирования

class ExcelParser:
    """Generic Excel parser"""

    def parse(self, file_path: str, config: ParserConfig) -> List[Dict]:
        """Parse Excel file"""

library/parsers/xlsx/
├── parser.py          ← ExcelParser
├── auto_mapper.py     ← Автоопределение колонок
└── SPEC.md

class OzonAdapter:
    """Адаптирует данные OZON к унифицированной модели Order"""

    def adapt(self, ozon_data: Dict) -> Order:
        """OZON dict → Order dataclass"""

class FieldMapper:
    """Маппинг полей 1С → PIM"""

    GUID_TO_FIELD = {
        'b86639de-...': 'brand',
        '0699197f-...': 'category'
    }

    def map_field(self, guid: str, value: Any) -> Tuple[str, Any]:
        """GUID → (field_name, normalized_value)"""

library/adapters/ozon/           ← Универсальный адаптер
projects/.../data/connectors/    ← Специфичный маппер

class ProductRepository:
    """Репозиторий товаров"""

    async def get_by_article(self, article: str) -> Optional[Product]:
        """Получить товар по артикулу"""

    async def save(self, product: Product) -> None:
        """Сохранить товар"""

    async def find_by_brand(self, brand: str) -> List[Product]:
        """Найти товары бренда"""

# Универсальный
library/storages/postgres/repository.py

# Специфичный
projects/.../app/pim/repositories/product_repo.py

class ProductService:
    """Управление товарами"""

    def __init__(
        self,
        repository: ProductRepository,
        pricing: PricingService
    ):
        self.repo = repository
        self.pricing = pricing

    async def create_product(self, data: ProductCreate) -> Product:
        """
        Создать товар:
        1. Валидация
        2. Расчёт цены
        3. Сохранение
        """
        # Validate
        if not self._validate(data):
            raise ValidationError()

        # Calculate price
        cost = await self.pricing.calculate_cost(data.base_price, data.brand)

        # Save
        product = Product(**data.dict(), cost_price=cost)
        await self.repo.save(product)

        return product

projects/.../app/pim/core/services/

class ParserFactory:
    """Фабрика парсеров"""

    def create_parser(self, supplier: str, config: Dict) -> BaseParser:
        """Создать парсер для поставщика"""

        if supplier == "jf":
            return JFPyroParser(config)
        elif supplier == "maxsem":
            return MaxsemParser(config)

from sqlalchemy import Column, String, Numeric
from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()

class PimProduct(Base):
    __tablename__ = 'pim_products'

    article = Column(String(50), primary_key=True)
    name = Column(String(500), nullable=False)
    base_price = Column(Numeric(10, 2), nullable=False)

projects/.../app/pim/models/product.py

from pydantic import BaseModel, Field
from decimal import Decimal

class Product(BaseModel):
    article: str
    name: str
    base_price: Decimal = Field(gt=0)

    def calculate_retail(self, margin: Decimal) -> Decimal:
        """Бизнес-логика расчёта цены"""
        return self.base_price * (1 + margin)

projects/.../app/pim/domain/product.py

from pydantic import BaseModel

class ProductCreate(BaseModel):
    """Схема создания товара"""
    article: str
    name: str
    base_price: Decimal

class ProductResponse(BaseModel):
    """Схема ответа API"""
    article: str
    name: str
    base_price: Decimal
    cost_price: Decimal
    retail_price: Decimal

projects/.../app/pim/schemas/product.py

app/pim/
│
├── design/                       ← MOTIVATION (зачем)
│   ├── VISION.md                 ← Зачем PIM
│   ├── CONCEPT.md                ← Концепция
│   └── DECISIONS.md              ← ADR
│
├── processes/                    ← BUSINESS (как работать)
│   ├── import_workflow.md        ← Процесс импорта
│   └── price_sync.md             ← Синхронизация цен
│
├── standards/                    ← DATA (схема данных)
│   ├── DATABASE.md               ← Таблицы
│   ├── MAPPING_1C.md             ← Маппинг
│   └── VALIDATION.md             ← Правила
│
├── [api/, core/, models/]        ← APPLICATION (код)
│
└── deployment/                   ← TECHNOLOGY (инфра)
    └── DEPLOYMENT.md

api/              ← Внешний интерфейс (REST, GraphQL)
core/             ← Бизнес-логика
  ├── services/   ← Оркестрация
  ├── domain/     ← Domain models + правила
  └── use_cases/  ← Сценарии (опционально, CQRS)

models/           ← ORM модели (персистентность)
schemas/          ← DTO (API contracts)
repositories/     ← Доступ к данным (опционально)

external/         ← Внешние зависимости
  ├── connectors/ ← Специфичные коннекторы
  └── adapters/   ← Специфичные адаптеры

┌───────────────────────────────────────┐
│ Это универсальный принцип?            │
│ (применим к любому проекту)           │
└───────┬───────────────────────────────┘
        │
   ДА   │   НЕТ
        ▼
┌───────────────────────────────────────┐
│ architect/                            │
│ L0-L2: Методология                    │
└───────────────────────────────────────┘
        │
        │ НЕТ
        ▼
┌───────────────────────────────────────┐
│ Это часть движка платформы?           │
│ (executor, scheduler, агенты)         │
└───────┬───────────────────────────────┘
        │
   ДА   │   НЕТ
        ▼
┌───────────────────────────────────────┐
│ system/core/                          │
│ L3: Движок                            │
└───────────────────────────────────────┘
        │
        │ НЕТ
        ▼
┌───────────────────────────────────────┐
│ Можно использовать в других проектах? │
│ (OZON, Telegram, 1C, валидаторы)      │
└───────┬───────────────────────────────┘
        │
   ДА   │   НЕТ
        ▼
┌───────────────────────────────────────┐
│ library/                              │
│ L4: Универсальные компоненты          │
└───────────────────────────────────────┘
        │
        │ НЕТ
        ▼
┌───────────────────────────────────────┐
│ Это специфика конкретного проекта?    │
│ (ProductService, маппинг 1С→PIM)      │
└───────┬───────────────────────────────┘
        │
   ДА   │
        ▼
┌───────────────────────────────────────┐
│ projects/{project}/                   │
│ L6: Бизнес-приложение                 │
│                                       │
│  app/{app}/  ← Приложение             │
│  data/       ← Код про данные         │
└───────────────────────────────────────┘

library/connectors/api/ozon/
├── client.py              ← OzonConnector
├── types.py               ← OzonCredentials, OzonOrder
├── exceptions.py          ← OzonAPIError
└── constants.py           ← OZON_BASE_URL

# ❌ НЕПРАВИЛЬНО: OzonConnector в projects/
# Он универсальный, нужен многим проектам!
projects/pirotehnika/app/ozon/connector.py

# ✅ ПРАВИЛЬНО: OzonConnector в library/
library/connectors/api/ozon/client.py

# ✅ ПРАВИЛЬНО: ProductService в projects/
# Специфика PIM, не нужен другим проектам
projects/pirotehnika/app/pim/core/services/product.py

# ✅ ПРАВИЛЬНО: Маппинг 1С→PIM в projects/
# Специфика пиротехники (GUID категорий)
projects/pirotehnika/data/connectors/1c/field_mapper.py

projects/pirotehnika/
│
├── app/pim/                              ← APPLICATION
│   ├── design/                           ← MOTIVATION
│   │   └── CONCEPT.md
│   │
│   ├── processes/                        ← BUSINESS
│   │   └── import_workflow.md
│   │
│   ├── standards/                        ← DATA (схемы)
│   │   ├── DATABASE.md
│   │   └── VALIDATION.md
│   │
│   ├── api/                              ← APPLICATION: API
│   │   ├── products.py
│   │   └── pricing.py
│   │
│   ├── core/                             ← APPLICATION: Логика
│   │   ├── services/
│   │   │   ├── product_service.py        ← ProductService
│   │   │   └── pricing_service.py        ← PricingService
│   │   └── domain/
│   │       └── product.py                ← Product (domain model)
│   │
│   ├── models/                           ← DATA: ORM
│   │   ├── product.py                    ← PimProduct
│   │   └── pricing.py                    ← PimCostRule
│   │
│   ├── schemas/                          ← APPLICATION: DTO
│   │   ├── product.py                    ← ProductCreate, ProductResponse
│   │   └── pricing.py
│   │
│   ├── repositories/                     ← DATA: Репозитории (опционально)
│   │   └── product_repo.py
│   │
│   └── deployment/                       ← TECHNOLOGY
│       └── DEPLOYMENT.md
│
└── data/                                 ← КОД ПРО ДАННЫЕ
    ├── connectors/                       ← Адаптеры к источникам
    │   ├── 1c/                           ← 1С специфика проекта
    │   │   ├── field_mapper.py           ← FieldMapper
    │   │   ├── category_mapper.yaml      ← GUID → категории
    │   │   └── adapter.py                ← Использует library/1c/
    │   │
    │   └── suppliers/                    ← Парсеры прайсов
    │       ├── jf_pyro.py                ← Специфичный парсер
    │       └── maxsem.py                 ← Специфичный парсер
    │
    └── scripts/
        └── process.py                    ← Обработка входящих

# projects/.../data/connectors/1c/adapter.py

from library.connectors.data.1c import OneCConnector  # L4
from library.functions.normalize import normalize_price  # L3

class PIM1CAdapter:
    """Адаптер 1С → PIM для пиротехники"""

    def __init__(self):
        self.client = OneCConnector(...)  # Универсальный клиент

    async def fetch_products(self) -> List[Dict]:
        """Получить товары из 1С"""
        raw_data = await self.client.get_catalog()
        return [self._adapt(item) for item in raw_data]

    def _adapt(self, item: Dict) -> Dict:
        """Преобразовать 1С → PIM"""
        return {
            'article': item['Артикул'],
            'name': item['Description'],
            'base_price': normalize_price(item['Цена']),  # L3 function
            'category': self.GUID_MAPPING[item['Parent_Key']]  # Специфика
        }

# library/connectors/api/ozon/client.py  (L4)
class OzonConnector:
    """Универсальный OZON API клиент"""

    async def get_orders(self, status: str) -> List[Dict]:
        """Получить заказы (raw API response)"""
        return await self._request("POST", "/v3/posting/fbs/list", {...})

# library/adapters/ozon/order_adapter.py  (L4)
class OzonOrderAdapter:
    """Адаптер OZON order → унифицированная Order"""

    def adapt(self, ozon_data: Dict) -> Order:
        """OZON dict → Order domain model"""
        return Order(
            order_id=ozon_data['posting_number'],
            customer_name=ozon_data['customer']['name'],
            ...
        )

# projects/.../app/ozon/core/sync_service.py  (L6)
class OrderSyncService:
    """Синхронизация заказов OZON → 1C"""

    def __init__(
        self,
        ozon: OzonConnector,      # L4
        adapter: OzonOrderAdapter, # L4
        onec: OneCConnector        # L4
    ):
        self.ozon = ozon
        self.adapter = adapter
        self.onec = onec

    async def sync_new_orders(self) -> int:
        """
        Бизнес-логика синхронизации:
        1. Получить новые заказы из OZON
        2. Адаптировать к Order
        3. Отправить в 1С
        """
        # 1. Extract
        raw_orders = await self.ozon.get_orders("awaiting_packaging")

        # 2. Transform
        orders = [self.adapter.adapt(raw) for raw in raw_orders]

        # 3. Load
        for order in orders:
            await self.onec.create_order(order.to_1c_format())

        return len(orders)

# library/connectors/api/ozon/client.py
class OzonConnector:
    async def get_orders_and_create_in_1c(self):
        """❌ Коннектор не должен знать о 1С!"""
        orders = await self.get_orders()
        for order in orders:
            await self.onec.create(order)  # НЕПРАВИЛЬНО!

# library/connectors/data/1c/field_mapper.py
class FieldMapper:
    """❌ GUID категорий специфичны для пиротехники!"""
    GUID_MAPPING = {
        '0699197f-e960-11ed-919d-3cecefa69fd9': 'Батареи салютов',  # Специфика!
        ...
    }

# library/connectors/api/ozon/client.py
from projects.pirotehnika.app.pim import ProductService  # ❌ ЗАПРЕЩЕНО!

class OzonConnector:
    def __init__(self):
        self.pim = ProductService()  # L4 не может зависеть от L6!

□ Определил уровень (L0-L6)
□ Определил тип (Connector, Service, Model, etc.)
□ Определил слой TOGAF (если L6)
□ Проверил правило зависимостей (N → N-1)
□ Выбрал правильную папку
□ Использовал правильный суффикс
□ Написал docstring с назначением
□ Добавил в index.yaml (если модуль)