sequenceDiagram
autonumber
actor User as Пользователь (Сканирует пачку молока)
participant APP as Мобильное приложение (Flutter)
participant API as Бэкенд-шлюз (product-registry-service)
participant REG as Национальный реестр (Честный Знак / GS1 API)
participant DB as Реляционная СУБД (PostgreSQL)
User->>APP: Сканирует штрихкод или DataMatrix на упаковке продукта
APP->>API: HTTP POST /api/v1/pantry/scan-barcode (JSON с barcode_raw_string)
activate API
note over API: Шаг 3: Декодирование JWT и верификация сессии группы
note over API: Шаг 4: Выделение GTIN-кода (Идентификатора товарной позиции)
API->>DB: Быстрый локальный кэш-запрос по индексу GTIN
alt Продукт ранее сканировался (Cache Hit)
DB-->>API: Возврат связанного element_id и БЖУ-карточки
else Первая регистрация товара (Cache Miss)
API->>REG: GET /api/v1/products/gtin/{gtin} (Запрос паспорта SKU)
activate REG
REG-->>API: HTTP 200 OK (Бренд, Имя: "Творог 5%", Спецификация веса: 200г)
deactivate REG
Note over API, DB: Старт атомарной SQL-транзакции
API->>DB: Триграммный поиск элемента таблицы + INSERT INTO product_barcodes (gtin, element_id)
activate DB
DB-->>API: Фиксация маппинга штрихкода в системе
deactivate DB
Note over API, DB: Коммит атомарной транзакции (COMMIT)
end
API-->>APP: HTTP 200 OK / 201 Created (Товар распознан, подтянут базовый изотоп таблицы)
deactivate API
note over APP: В интерфейсе отображается точный паспорт товара: Творог (Cc), Вес: 200г, БЖУ заполнено
Метод POST /api/v1/purchase/scan-barcode
Документация API: Синхронная дешифрация кодов маркировки DataMatrix/EAN-13, интеграция с национальными системами прослеживаемости и маппинг на изотопы Периодической таблицы
- PURCHSASE-2XX Backlog — Краткое Описание задачи 1.
- PURCHSASE-1XX Refinement (Уточнение) — Краткое Описание задачи 2.
1 Функциональное назначение
Метод является основным цифровым мостом для верификации упакованных фабричных товаров (молоко, сыры, мясные полуфабрикаты, консервы). Он активируется, когда пользователь в модуле Pantry или при пополнении Fridge сканирует камерой смартфона стандартный штрихкод (EAN-13) либо код криптографической маркировки DataMatrix (системы класса «Честный Знак», GS1).
Метод решает три критические задачи:
- Валидация и парсинг крипто-хвоста (DataMatrix GTIN): Шлюз очищает сырую строку сканирования, выделяя из нее уникальный международный код товара (GTIN) и серийный номер, отсекая защитный крипто-ключ (подпись).
- Интеграция с Каталогом маркированных товаров: Метод отправляет синхронный запрос в национальный реестр прослеживаемости для получения официального паспорта товара (наименование, точный ГОСТ-вес, бренд, юридический состав).
- Привязка к изотопу Периодической Системы: Полученная верифицированная номенклатура атомарно сопоставляется с базовым кодом элемента таблицы продуктов (
element_id), автоматически обогащая склад точными данными о макронутриентах.
2 Протокол взаимодействия (HTTP Контракт)
- Метод:
POST - Маршрут:
/api/v1/pantry/scan-barcode - Формат данных:
application/json
2.1 Спецификация заголовков (HTTP Headers)
| Заголовок | Обязательный | Описание | Пример значения |
|---|---|---|---|
Content-Type |
Да | Указывает на передачу строго типизированного JSON-пакета | application/json |
Authorization |
Да | Токен авторизации (Access Token). Идентифицирует home_group_id для зачисления на баланс. |
Bearer eyJhbGciOiJIUzI1Ni... |
X-Request-ID |
Да | Сквозной ID запроса для связывания логов сканирования с внешним шлюзом маркировки | req-barcode-scan-44cc |
2.2 Спецификация тела запроса (Request Body)
| Поле | Тип | Обязательный | Описание | Пример значения |
|---|---|---|---|---|
barcode_raw_string |
String | Да | Сырая строка данных со сканера (EAN-13 или полная DataMatrix последовательность) | "010460000000000021xyz123\u001d93cffa" |
2.2.1 Пример сырого JSON-запроса (Payload):
{
"barcode_raw_string": "010460123456789021ABC12345\u001d91EE06\u001d92dGVzdA=="
}