pim.ai.md

Версия: 1.0.0
Дата: 2025-12-24
Тип: Специалист
Базовый протокол: /CLAUDE.md
Проект: pirotehnika/app/pim

РОЛЬ

Специалист по управлению товарной информацией — Product Information Management.
Централизованный каталог товаров с обогащением данных из множества источников.

ТРИГГЕРЫ

pim, пим, каталог товаров, товарная база, прайс, синхронизация товаров, обогащение данных

АРХИТЕКТУРА

┌─────────────────────────────────────────────────────────────────┐
│                         PIM DATA FLOW                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ИСТОЧНИКИ:                        ЦЕНТРАЛЬНЫЙ КАТАЛОГ:         │
│  ┌──────────────┐                  ┌──────────────────┐         │
│  │ 1c_products  │ ───────────────► │   pim_products   │         │
│  │ (из 1С)      │                  │ (обогащённый)    │         │
│  └──────────────┘                  └──────────────────┘         │
│                                            ▲                     │
│  ┌──────────────┐    ┌──────────┐          │                    │
│  │ Price Files  │ ─► │ Staging  │ ─► Validation ─► Merge        │
│  │ (xlsx/csv)   │    │ Products │                               │
│  └──────────────┘    └──────────┘                               │
│                                                                  │
│  ВЫХОД:                                                         │
│  ├── OZON API         ← Синхронизация маркетплейсов             │
│  ├── OpenCart         ← Сайт                                    │
│  └── Exports          ← Прайсы, отчёты                          │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

ТАБЛИЦЫ БД

Слой 1: Источники

Слой 2: Staging

Слой 3: Каталог

Слой 4: Ценообразование

Слой 5: Agent Approval

CORE СЕРВИСЫ

ProductService

Таблица	Назначение	Ключевые поля
`1c_products`	Товары из 1С (источник правды)	guid, name, article, brand, category, cost_price, stock

Таблица	Назначение
`pim_price_file_uploads`	Загруженные файлы прайсов
`pim_staging_products`	Промежуточные товары
`pim_validation_log`	Результаты валидации
`pim_import_log`	История импортов

Таблица	Назначение
`pim_products`	Обогащённый каталог товаров
`pim_product_images`	Изображения товаров

Таблица	Назначение
`pim_cost_rules`	Скидки по брендам
`pim_price_history`	История изменения цен

Таблица	Назначение
`pim_function_proposals`	Предложения функций от AI
`pim_approved_functions`	Одобренные функции
`pim_function_execution_log`	Лог выполнения
`pim_parser_registry`	Реестр парсеров

class ProductService:
    get_product(id) → Product
    list_products(filters, pagination) → List[Product]
    create_product(data) → Product
    update_product(id, data) → Product
    search_products(query) → List[Product]
    get_by_article(article) → Product
    bulk_update(updates) → int

PricingService

class PricingService:
    calculate_cost(product, quantity) → Decimal
    apply_discount(product, brand_rule) → Decimal
    get_rules_for_brand(brand) → List[PimCostRule]
    calculate_margin(cost, retail) → float
    suggest_retail_price(cost, target_margin) → Decimal

retail_price = cost_price × (1 + margin) × (1 - brand_discount)

ПРОЦЕССЫ

1. Импорт прайса поставщика

1. Загрузка файла → pim_price_file_uploads (status=pending)
2. Парсинг → pim_staging_products (raw_data + parsed fields)
3. Валидация:
   - Проверка обязательных полей
   - Матчинг с существующими товарами
   - Проверка цен (аномалии)
   → pim_validation_log
4. Review: Оператор смотрит ошибки/предупреждения
5. Import: Approved записи → обновление pim_products
6. History: Изменения цен → pim_price_history

2. Синхронизация с 1С

1. Получение данных из 1С (JSON/API)
2. Upsert в 1c_products (по guid)
3. Триггер: новые товары → создание в pim_products
4. Обновление stock, cost_price

3. Расчёт цен

1. Получить cost_price из 1c_products
2. Найти правила PimCostRule для бренда
3. Применить скидки (если quantity >= min_quantity)
4. Рассчитать retail_price с маржой
5. Записать в pim_products

4. Одобрение функций агента

1. AI предлагает функцию → pim_function_proposals
2. Оператор review код
3. Approve/Reject → статус
4. Approved → pim_approved_functions
5. Выполнение → pim_function_execution_log

API ENDPOINTS

ТИПЫ ЗАДАЧ

ИНСТРУМЕНТЫ

СТРУКТУРА ПРОЕКТА

Endpoint	Метод	Назначение
`/products`	GET	Список товаров
`/products/{id}`	GET/PUT/DELETE	CRUD товара
`/products/search`	POST	Поиск
`/prices/upload`	POST	Загрузка прайса
`/prices/uploads/{id}/validate`	POST	Запуск валидации
`/prices/uploads/{id}/import`	POST	Импорт в каталог
`/rules`	GET/POST	Управление скидками

Тип	Вопросы	Результат
Импорт прайса	Формат? Маппинг полей?	Staging → Validation
Обогащение данных	Какие поля? Источник?	Enriched products
Синхронизация	С чем? Направление?	Sync job
Ценообразование	Формула? Скидки?	Price update

Инструмент	Назначение
FastAPI	REST API
SQLAlchemy	ORM
Pydantic	Валидация
PostgreSQL	Хранилище
Pandas	Обработка прайсов

pim/
├── api/              ← REST endpoints
│   ├── products.py
│   ├── prices.py
│   └── rules.py
├── core/             ← Бизнес-логика
│   ├── products.py   ← ProductService
│   ├── pricing.py    ← PricingService
│   └── import_service.py
├── models/           ← SQLAlchemy модели
│   ├── product.py
│   ├── staging.py
│   ├── pricing.py
│   └── approval.py
├── schemas/          ← Pydantic schemas
├── mappers/          ← Маппинг полей
└── tests/

Задача	Кому
Парсинг прайса	→ workers/analyst
Новый endpoint	→ workers/coder
Миграция БД	→ workers/infra
Интеграция API	→ workers/integrator

PIM — Специалист по Product Information Management