AGENTS.md — 30-services (Сервисы и модули)

Назначение уровня

Этот уровень описывает сервисные границы, контракты и соседние зависимости. По умолчанию здесь лежит target service design, а не описание уже выделенных runtime-процессов.

Содержание

30-services/
├── AGENTS.md                       # ← вы здесь
├── TEMPLATE-service-README.md      # шаблон README сервиса
│
├── catalog-core/                   # canonical products, характеристики, производители
├── ingestion/                      # оркестрация ingestion + коннекторы
│   ├── AGENTS.md
│   ├── README.md
│   └── connectors/
│       ├── AGENTS.md
│       ├── framework.md            # описание плагин-архитектуры коннекторов
│       └── etm/                    # первый коннектор
│           ├── AGENTS.md
│           ├── README.md
│           ├── spec.md
│           ├── mapping.md
│           └── rate-budget.md
│
├── normalization/
├── matching/
├── enrichment/
├── search/
├── pricing/
├── meta-search/
├── visibility/
├── public-api/
└── admin-api/

Ключевые концепции уровня

• Service boundary — логическая граница ответственности, даже если отдельный runtime пока не выделен.
• Current scaffold — то, что уже есть в backend/ и может отличаться от целевой декомпозиции.
• Connector — поставщиковый модуль в целевой ingestion-архитектуре.

Когда смотреть сюда

• Нужно разобраться, за что отвечает конкретный сервис.
• Нужно понять, в каком сервисе должна жить новая функциональность.
• Подключаете нового поставщика и ищете точку входа в документацию по коннекторам.

Когда НЕ смотреть сюда

• Нужны схемы или контракты на уровне полей → ../20-architecture/schemas/.
• Нужны бизнес-правила → ../10-business/.
• Нужно понять, что уже можно поднять локально сегодня → ../40-operations/deployment.md.

Связано

• Родитель: ../AGENTS.md
• Карта сервисов: index.md
• Стандарт: ../50-processes/documentation-standard.md

Соглашения

• В каждой папке сервиса обязательны AGENTS.md и README.md.
• README сервиса обязан начинаться со статуса документа: current vs target, наличие кода, текущие пути.
• Эта директория содержит только документацию; фактический код сервиса может отсутствовать или жить в backend/ по целевой раскладке из ../20-architecture/module-layout.md.