projects/org/pirotehnika/app/pim/CLAUDE.md

PIM — Product Information Management

Версия: 3.0.0
Дата: 2025-12-26
Тип: Приложение
Проект: pirotehnika
Агент: system/agents/specialists/pim.ai.md

⚠️ ВАЖНО: Главный документ архитектуры → ARCHITECTURE.md

ЧТО ЭТО

Централизованный каталог товаров. Собирает данные из разных источников (1С, прайсы поставщиков) в единую базу и раздаёт на выходы (OZON, сайт, отчёты).

АРХИТЕКТУРА v3.0 (2025-12-26):
- Товары (pim_products) = ТОЛЬКО характеристики
- Цены (price_supplier_cost) = цены от КАЖДОГО поставщика отдельно
- Остатки (stocks + warehouses) = количество на КАЖДОМ складе
- История цен, без дубликатов

Полное описание: ARCHITECTURE.md

ВХОДЫ:                          ЯДРО:                      ВЫХОДЫ:
┌──────────────┐               ┌─────────────┐            ┌──────────┐
│ 1С (JSON)    │──────────────►│             │───────────►│ OZON API │
└──────────────┘               │ pim_products│            └──────────┘
                               │             │            ┌──────────┐
┌──────────────┐  Staging      │ (единая     │───────────►│ OpenCart │
│ Прайсы xlsx  │──────────────►│  база)      │            └──────────┘
└──────────────┘               │             │            ┌──────────┐
                               └─────────────┘───────────►│ Отчёты   │
                                                          └──────────┘

БЫСТРЫЙ СТАРТ

cd /opt/claude-workspace/projects/org/pirotehnika/app/pim

# Запуск API
uvicorn pim.main:app --reload --port 8000

# Синхронизация с 1С
python -m pim.sync_1c

# Импорт прайса
python -m pim.import_price /path/to/price.xlsx --supplier maxsem

Подробнее: QUICKSTART.md

Ценообразование: PRICING_FINAL_CONCEPT.md ✅

АРХИТЕКТУРА ДАННЫХ

5 слоёв таблиц

Слой Таблицы Назначение
1. Источники 1c_products Товары из 1С (источник правды)
2. Staging pim_price_file_uploads, pim_staging_products, pim_validation_log Временное хранение при импорте
3. Каталог pim_products, pim_product_images Обогащённые товары (главная таблица)
4. Цены price_cost_rules, price_sale_rules, price_supplier_cost, price_history Скидки, наценки, закупки, история
5. Approval pim_function_proposals, pim_approved_functions Одобрение AI-функций

Ключевые поля pim_products

article, name, brand, category, description
base_price, fixed_price, tier
specifications (JSON), is_active

Цены вычисляются функциями:
- calculate_cost_price(article) — себестоимость
- calculate_retail_price(article) — розничная цена

ПРОЦЕССЫ

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

1С JSON → 1c_products → pim_products

Подробнее: ALGORITHM_1C_SYNC.md

2. Импорт прайса

xlsx → pim_price_file_uploads → pim_staging_products
     → валидация → pim_products

Статусы загрузки: pending → processing → validated → imported

Подробнее: IMPORT_1C_GUIDE.md

3. Расчёт цен

Себестоимость:

cost_price = base_price × (1 - discount/100)  -- если есть скидка поставщика
cost_price = fixed_price                      -- если нет скидки

Розничная цена:

-- По иерархии правил: product → category → brand → global
retail_price = base_value × (1 + markup/100)

-- Fallback (нет правил):
retail_price = MAX(base_price × 1.2, cost_price × 2)

Подробнее: PRICING_FINAL_CONCEPT.md

4. Одобрение AI-функций

AI предлагает → pim_function_proposals → review → approve/reject

Подробнее: SECURITY_APPROVAL_SYSTEM.md

API

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 Правила скидок

Подробнее: API_DOCUMENTATION.md

Концепция архитектуры: docs/CONCEPT.md

СТРУКТУРА КОДА

pim/
├── api/              ← REST endpoints (FastAPI)
│   ├── products.py
│   ├── prices.py
│   └── rules.py
├── core/             ← Бизнес-логика
│   ├── products.py   ← ProductService
│   ├── pricing.py    ← PricingService
│   └── import_service.py
├── models/           ← SQLAlchemy модели
│   ├── product.py    ← Product, PimProduct
│   ├── staging.py    ← Staging таблицы
│   ├── pricing.py    ← PimCostRule
│   └── approval.py   ← Agent Approval
├── schemas/          ← Pydantic schemas
├── mappers/          ← Маппинг полей
└── tests/

ДОКУМЕНТАЦИЯ

Основные

Документ Описание
README.md Обзор проекта (точка входа)
QUICKSTART.md Быстрый старт
API_DOCUMENTATION.md API endpoints
DEPLOYMENT.md Деплой

Стандарты PIM (standards/)

Стандарт Описание
standards/README.md Навигатор по стандартам
standards/DATABASE.md Структура БД (таблицы, поля, индексы)
standards/MAPPING_1C.md Маппинг полей из 1С
standards/NAMING.md Шаблоны названий товаров
standards/VALIDATION.md Правила валидации данных

Рабочие документы

Документ Описание
IMPORT_1C_GUIDE.md Импорт из 1С
1C_PIM_MASTER_MAPPING.md Маппинг реквизитов 1С (GUID)
BRAND_IMPORT_README.md Импорт брендов
SECURITY_APPROVAL_SYSTEM.md Система одобрения AI
DATA_FLOW_STRATEGY.md Стратегия потоков данных

Данные

Документ Описание
../../data/PRODUCT_DATA_STANDARD.md Стандарт хранения файлов

Архив

Папка Описание
archive/2025-12-23/ Старые отчёты, анализы, версии стандартов

СВЯЗИ

ТРИГГЕРЫ

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

ПРАВИЛО ТЕРМИНОВ

По умолчанию все термины = PIM (без префикса)

Контекст Как называть Пример
PIM (по умолчанию) без префикса категория, товар, артикул
1С добавить 1с_ 1с_категория, 1с_группа
OZON добавить ozon_ ozon_категория, ozon_type_id
OpenCart добавить ос_ ос_категория
Сайт добавить сайт_ сайт_категория

Есть сомнения → переспросить:
- "Категория — это PIM или 1С?"
- "Какой источник?"

Маппинг терминов

1С PIM OZON
1с_категория (КатегорияНоменклатуры) категория ozon_type_id
1с_группа (Parent_Key) подкатегория -
1с_наименование (Description) название name
1с_артикул (Артикул) артикул / sku offer_id
1с_код (Code) - -

Версия: 1.0.0