56 lines
3.4 KiB
Markdown
56 lines
3.4 KiB
Markdown
# Commerce и МойСклад
|
||
|
||
Commerce-контур хранит нормализованные товары, внешние привязки, продажи,
|
||
возвраты, расходы, остатки и локальные изображения товаров. Источником истины
|
||
для структуры данных служат модели `backend/commerce/models/`, для HTTP API —
|
||
`backend/api/v1/commerce/`, для импорта —
|
||
`backend/commerce/services/moysklad_sync.py`.
|
||
|
||
## Импорт
|
||
|
||
Полная синхронизация запускается Celery-задачей
|
||
`commerce.sync_moysklad_run`. Для работы ручного импорта нужен Celery worker,
|
||
для расписания — также Celery Beat.
|
||
|
||
Импорт выполняет следующие этапы:
|
||
|
||
1. Загружает ассортимент страницами по 100 позиций с `expand=images`.
|
||
2. Нормализует товары, модификации, комплекты, привязки и остатки.
|
||
3. Скачивает оригиналы изображений по авторизованному `downloadHref`, проверяет
|
||
формат и лимит 25 МБ, создаёт локальную WebP-миниатюру.
|
||
4. Импортирует отгрузки и возвраты вместе с позициями.
|
||
5. Сохраняет итоговую статистику и публикует состояние через общий WebSocket.
|
||
|
||
Прогресс запуска сохраняется и отправляется frontend каждые 25 товаров или
|
||
документов. Ошибка отдельного изображения учитывается в `image_errors`, но не
|
||
отменяет импорт товарных и финансовых данных.
|
||
|
||
## Изображения
|
||
|
||
`ProductImage` хранит оригинал и миниатюру в `MEDIA_ROOT/commerce/products/`.
|
||
Временные внешние ссылки МойСклад не возвращаются клиенту и не используются как
|
||
публичные URL. Повторная синхронизация сравнивает внешний размер и время
|
||
изменения, поэтому неизменённое изображение не скачивается повторно. Удалённые
|
||
в источнике изображения удаляются локально после успешного чтения списка.
|
||
|
||
REST `ProductSerializer` возвращает `images[]` с локальными `url` и
|
||
`thumbnail_url`. Каталог использует миниатюру, карточка товара — оригинал для
|
||
полноэкранного просмотра.
|
||
|
||
## Realtime и fallback
|
||
|
||
Событие `commerce_connection_updated` содержит состояние подключения и
|
||
последнего запуска, включая `processed`, `images` и `sales`. При рабочем
|
||
WebSocket frontend не опрашивает connections endpoint. Если WebSocket
|
||
недоступен во время активного импорта, включается REST fallback раз в 30 секунд.
|
||
|
||
## Проверка
|
||
|
||
```bash
|
||
cd backend
|
||
pytest tests/commerce -q
|
||
python manage.py makemigrations --check --dry-run
|
||
python manage.py check
|
||
ruff check commerce api/v1/commerce tests/commerce
|
||
```
|