food-market/docs/supply-inventory.md

Приёмка и инвентаризация с телефона

С версии Sprint 31 в food-market три новых способа работы с товаром: по фото накладной, сканированием штрихкодов, и мобильная инвентаризация с офлайн-каталогом. Все три видны в простом режиме, доступны ролям Администратор и Кладовщик.

1. Приёмка по фото/PDF накладной

Когда использовать: поставщик привёз накладную в бумаге или в PDF — не хочется набивать строки руками.

Как:

1. /purchases/invoices → «Снять камерой» (с телефона) или «Загрузить файл» (image/* или PDF, до 60 МБ).
2. Загрузка попадает в очередь. Статус-бейдж на карточке: В очереди → Распознаётся → На проверке | Ошибка. Страница обновляется сама каждые 3 секунды, пока есть распознающиеся.
3. Открываем карточку «На проверке» → экран проверки:
   • Шапка (редактируемая): поставщик, №, дата, итого.
   • Строки карточками. Сопоставлено по штрихкоду или по памяти прошлых накладных → зелёная плашка → Название товара. Не сопоставлено → карточка оранжевым, предупреждение сверху.
   • Общий сканер (поле «Отсканировать…»): скан → +1 к первой несопоставленной строке или новая строка. Удобно когда вы по бумажке проходитесь сканером.
   • Для каждой строки можно «Найти товар» (поиск по каталогу) или удалить. Если товара нет — ссылка «Создать товар».
   • Сумма строк сравнивается с «Итого» в накладной; если отличается больше чем на 1 — предупреждение.
4. «Сохранить правки» — обновляет документ, автоматически запоминает все ручные сопоставления. На следующей накладной того же поставщика matcher уже найдёт эти товары автоматически.
5. «Создать приёмку» → диалог: поставщик (поиск по БИН/имени, можно создать нового), склад, валюта → POST /apply создаёт нашу Supply (Draft). Проведение — обычной кнопкой в приёмке.

Как это распознаётся: локальный Claude Code в headless-режиме (claude -p --output-format json, промпт сверяет «Итого», отличает штрихкод от кода поставщика, не угадывает — пустые поля = null). Нагрузка списывается с подписки, не с API-ключа. На сервере нужен установленный claude CLI и claude login от того же пользователя, что запускает API. Можно пустить модель на отдельной машине через Invoices:ClaudeCli:RemoteHost (ssh + scp — всё внутри сервиса).

Хранение файла: uploads/invoices/{yyyy-MM}/{guid}.ext. Удаляется по истечении Invoices:KeepFilesDays (default 7). Распознанные строки остаются навсегда — по ним всегда видно, что было в накладной.

2. Приёмка сканированием

Когда: поступил товар россыпью, по бумажке лень набивать.

Как: /purchases/supplies/scan → поставщик + склад + валюта → «Сканировать камерой». Камера непрерывная, окно не закрывается между сканами. Товар за товаром:

• +1 к существующей строке, если такой уже есть; иначе — новая строка сверху;
• цена подставляется последняя закупочная (из последней Posted Supply);
• вибрация + вспышка на удачный скан; красным — если штрихкод не в каталоге;
• аппаратный сканер тоже работает (details → поле + Enter).

«Создать черновик» → наш Supply (Draft) в указанном складе; проверить и провести — на обычной странице приёмки.

Прогресс сохраняется в localStorage (fm.supply-scan.rows) — закрыли вкладку случайно, вернулись — всё на месте. Очищается после сохранения.

3. Инвентаризация с телефона

Когда: регулярный пересчёт склада или проверка одной группы.

Как: /inventory/mobile → три шага:

Setup

• Выбор склада.
• Опционально — группа (= частичная инвентаризация, непосчитанные товары НЕ обнулятся).
• «Загрузить каталог на телефон» — компактный слепок троек [barcode, productId, name] в IndexedDB. 30 тыс. штрихкодов ≈ 3 МБ. После загрузки работает без интернета.

Scan

• Камера непрерывная или аппаратный сканер; +1 за скан;
• неизвестный штрихкод — в отдельный список «Нет в каталоге» с количеством (не попадёт в документ, нужно сначала создать карточку);
• офлайн-плашка: нет сети = сканы остаются в телефоне, уйдут на сервер когда сеть появится. Прогресс сохраняется в localStorage.

Review

• При первом переходе создаётся наш InventoryDoc в Draft, bookQty каждой позиции = текущий Stock склада (без ручной «Пересчитать»).
• Отображается сводка: Излишек +XX ₸ / Недостача -YY ₸ / количество расхождений.
• Фильтр «только расхождения» (по умолчанию выключен — показываем всё).
• Drift-плашка: если учётный остаток ПОПЛЫЛ с момента создания документа (были продажи или приёмки), сверху показывается список изменившихся позиций: Молоко: 10 → 7. Это ВИДНО до нажатия «Провести», не молча.
• «Провести» → POST /post создаёт корректирующие движения InventoryAdjustment по строкам с diff ≠ 0.

Безопасность

• Все эндпоинты требуют permission SuppliesEdit или InventoryEdit (Admin + Storekeeper).
• Mutli-tenant: все запросы фильтруются по OrganizationId текущего пользователя. Фоновый InvoiceWorker работает без HTTP-контекста и использует явный IgnoreQueryFilters + Where OrgId чтобы не утечь между орг.
• Файл накладной отдаётся только владеющему org'у через /file.

Файлы

Что	Где
Домен	src/food-market.domain/Purchases/InvoiceUpload.cs
Миграция	src/food-market.infrastructure/Persistence/Migrations/20261004170000_Phase31a_InvoiceUploads.cs
Extractor + Matcher + Worker	src/food-market.api/Infrastructure/Invoices/
API накладных	src/food-market.api/Controllers/Purchases/InvoicesController.cs
API инвентаризации	src/food-market.api/Controllers/Inventory/InventoriesController.cs (mobile-catalog, add-line, book-drift)
Web — список накладных	src/food-market.web/src/pages/InvoicesPage.tsx
Web — проверка накладной	src/food-market.web/src/pages/InvoiceReviewPage.tsx
Web — scan приёмка	src/food-market.web/src/pages/SupplyScanPage.tsx
Web — mobile инвентаризация	src/food-market.web/src/pages/InventoryMobilePage.tsx
Камера	src/food-market.web/src/components/CameraScanner.tsx (@zxing/browser)
Offline-каталог	src/food-market.web/src/lib/offlineCatalog.ts (IndexedDB)
Тесты	tests/food-market.UnitTests/InvoiceMatcherTests.cs, ClaudeCliInvoiceExtractorParseTests.cs, tests/food-market.IntegrationTests/InvoicePipelineTests.cs

Конфиг

"Invoices": {
  "ClaudeCli": {
    "Executable": "claude",
    "Model": "claude-sonnet-4-6",
    "TimeoutSeconds": 180,
    "RemoteHost": null,                     // или "user@host" — модель на другой машине
    "RemoteTmpDir": "/tmp/food-market-invoices"
  },
  "KeepFilesDays": 7
}

Что НЕ сделано (откладывается до запроса)

• Создание товара прямо в экране проверки накладной — пока уходим на /products/new (future wiring в onPick из search dialog).
• PWA manifest + ServiceWorker офлайн — IndexedDB работает без них, но установка «На главный экран» потребует manifest.json. Отдельная задача, если понадобится.
• Автоподтверждение частичной vs полной инвентаризации при проведении («обнулять ли непосчитанные») — сейчас сервер не обнуляет непосчитанные в принципе (строки с diff=0 не создают движений), что совпадает с поведением частичной. Полная «обнулить все непосчитанные» требует явного шага в UI «добавить все остальные с actual=0» — пока нет.