CLAUDE.md

library/connectors/
├── api/       ← API-коннекторы (ozon, telegram, 1c, pochta)
├── data/      ← Data-коннекторы (postgres, nocodb, redis)
└── device/    ← Device-коннекторы (printer, scanner)

СТАРАЯ СТРУКТУРА (для справки)

system/connectors/  ← DEPRECATED
│
├── CLAUDE.md              ← Этот файл
│
├── nocodb/                ← NocoDB REST API ✅
│   ├── client.py
│   ├── QUIRKS.md
│   └── STATUS.md
│
├── marketplaces/          ← МАРКЕТПЛЕЙСЫ
│   ├── ozon/              ← OZON Seller API ✅
│   │   ├── client.py
│   │   ├── SPEC.md
│   │   ├── QUIRKS.md
│   │   ├── STATUS.md
│   │   └── tests/
│   │
│   ├── wildberries/       ← Wildberries API (draft)
│   └── yandex_market/     ← Яндекс.Маркет API (draft)
│
├── delivery/              ← СЛУЖБЫ ДОСТАВКИ
│   ├── pochta_russia/     ← Почта России API ✅
│   │   ├── client.py
│   │   ├── QUIRKS.md
│   │   └── STATUS.md
│   │
│   ├── cdek/              ← СДЭК API (draft)
│   └── boxberry/          ← Boxberry API (draft)
│
├── erp/                   ← УЧЁТНЫЕ СИСТЕМЫ
│   ├── 1c_odata/          ← 1C через OData ✅
│   │   ├── client.py
│   │   ├── QUIRKS.md
│   │   └── STATUS.md
│   │
│   └── moysklad/          ← МойСклад API (draft)
│
├── messaging/             ← КАНАЛЫ СВЯЗИ
│   ├── telegram/          ← Telegram Bot API (draft)
│   └── email/             ← SMTP/IMAP (draft)
│
└── payment/               ← ПЛАТЕЖИ
    └── yookassa/          ← ЮKassa API (draft)

ОБЯЗАТЕЛЬНЫЕ ФАЙЛЫ КОННЕКТОРА

QUIRKS — КРИТИЧЕСКИЙ ФАЙЛ

Файл	Назначение	Обязательно
`client.py`	Код коннектора	✅ Да
`SPEC.md`	Спецификация API (endpoints, форматы)	✅ Да
`QUIRKS.md`	Особенности API (критично!)	✅ Да
`STATUS.md`	Статус тестирования	✅ Да
`tests/`	Тесты	Рекомендуется

Содержит особенности внешнего API, обнаруженные при реальной работе:
- Недокументированное поведение
- Ошибки в официальной документации
- Workaround-ы для проблем

Формат QUIRK

## QUIRK-001: Краткое описание

**Severity:** HIGH | MEDIUM | LOW | INFO
**Дата обнаружения:** YYYY-MM-DD

### Проблема
[Описание проблемы]

### Симптомы
[Как проявляется]

### Решение
[Как обойти/исправить]

### Ссылки
[Где в коде]

СТАТУСЫ КОННЕКТОРОВ

РЕЕСТР КОННЕКТОРОВ

API-сервисы

Маркетплейсы

Доставка

ERP

Messaging

ИСПОЛЬЗОВАНИЕ

Импорт коннектора

Статус	Маркер	Описание
draft	⚠️	Написано, не тестировалось
tested	✅	Протестировано на реальных данных
broken	❌	Известные ошибки, не использовать
deprecated	🚫	Устарело, есть замена

Коннектор	Путь	Статус	Quirks
NocoDB	nocodb/	✅ tested	docker_exec, table_ids

Коннектор	Путь	Статус	Quirks
OZON	marketplaces/ozon/	✅ tested	phone_only_in_get, translit_default_true
Wildberries	marketplaces/wildberries/	⚠️ draft	—

Коннектор	Путь	Статус	Quirks
Почта России	delivery/pochta_russia/	✅ tested	double_auth, kopeks
СДЭК	delivery/cdek/	⚠️ draft	—

Коннектор	Путь	Статус	Quirks
1C OData	erp/1c_odata/	✅ tested	guid_format, cyrillic_url
МойСклад	erp/moysklad/	⚠️ draft	—

Коннектор	Путь	Статус	Quirks
Telegram	messaging/telegram/	⚠️ draft	—

from system.connectors.marketplaces.ozon.client import (
    OzonConnector,
    OzonCredentials,
    extract_order_data,
)

# Создание коннектора
creds = OzonCredentials(
    client_id="123456",
    api_key="your-api-key",
    name="Main Account",
)
connector = OzonConnector(creds)

# Получение заказов с телефонами (QUIRK-001 обработан автоматически)
orders = await connector.get_orders_with_details("awaiting_packaging")

# Извлечение нормализованных данных
for order in orders:
    data = extract_order_data(order)
    print(f"Phone: {data['customer_phone']}")

ПРАВИЛА

1. Один коннектор = один внешний сервис

✅ Правильно: connectors/marketplaces/ozon/
❌ Неправильно: connectors/marketplaces_all/

2. QUIRKS документируются сразу

При обнаружении особенности:
1. Добавить в QUIRKS.md
2. Исправить код
3. Добавить тест
4. Обновить STATUS.md

3. Без бизнес-логики

Коннектор только работает с API:
- ✅ Получить данные
- ✅ Отправить данные
- ✅ Обработать ошибки API
- ❌ Бизнес-расчёты
- ❌ Трансформации под конкретный проект

4. credentials снаружи

Коннектор получает credentials через конструктор, не хранит их.

Ресурс	Новый путь	Назначение
Data connectors	`library/connectors/data/`	Доступ к БД (PostgreSQL, NocoDB)
Device connectors	`library/connectors/device/`	Работа с устройствами
Parsers	`library/functions/parsers/`	Форматы данных (xlsx, pdf)

Connectors — ПЕРЕМЕЩЕНО

⚠️ ВНИМАНИЕ: ПЕРЕМЕЩЕНО