Сервіс імпорту залишків і цін (stock-import): загальний опис

1. Призначення

Сервіс stock-import інтегрує облікову систему аптечної мережі із сайтом. Він забезпечує:

• приймання даних про товарні залишки та ціни в розрізі аптек;
• валідацію отриманих даних;
• збереження даних у базі даних, яку використовує сайт;
• актуалізацію даних: виключає застарілі залишки й ціни;
• публікацію подій про зміни залишків і цін для каталогу сайту.

---

2. Вхідні дані

2.1. Залишки

Для кожної аптеки передається перелік товарів (за кодом SKU) із кількістю в наявності.

2.2. Ціни

Для кожного товару в аптеці передаються три види цін:

Додатково передається код населеного пункту аптеки за класифікатором КОАТУУ. Він використовується для регіонального розподілу цін.

2.3. Режими вивантаження

Типовий сценарій: одне повне вивантаження на добу та інкрементальні оновлення протягом дня.

---

3. Архітектура

3.1. Компоненти

Сервіс складається з двох незалежно розгорнутих модулів:

Взаємодія модулів відбувається асинхронно, через брокер повідомлень.

3.2. Схема взаємодії

flowchart LR
    A["Облікова система"] -- "API (HTTPS)" --> B["Модуль приймання<br/>(import)"]
    B --> C[["Брокер повідомлень<br/>(RabbitMQ)"]]
    C --> D["Модуль обробки<br/>(uploader)"]
    D --> E[("База даних<br/>(PostgreSQL)")]
    E --> F["Сайт"]
    D -- "події змін" --> G[["Черга подій<br/>каталогу сайту"]]
    H["Довідник активних аптек"] --> D

3.3. Порядок обробки даних

1. Приймання. Облікова система передає дані через API. Модуль приймання перевіряє облікові дані (логін і пароль) та структуру запиту: наявність кодів аптек і товарів, правильні типи значень. Якщо перевірка пройшла, він повертає статус «Accepted» і розміщує дані в черзі.
2. Буферизація. Дані зберігаються в черзі брокера повідомлень до обробки. Облікова система не чекає на завершення запису в базу, а дані не втрачаються під час пікових навантажень.
3. Обробка. Модуль обробки послідовно отримує повідомлення з черги та пакетно записує дані в базу. Якщо запис не вдався, повідомлення повертається в чергу для повторної обробки.

Примітка. Статус «Accepted» підтверджує лише те, що дані прийнято до обробки. Він не означає, що дані вже збережено в базі. Звичайний час обробки — від кількох секунд до кількох хвилин, залежно від навантаження.

3.4. Масштабування

Модуль обробки допускає запуск кількох екземплярів для паралельної обробки. Також можна налаштувати окремі екземпляри для обробки лише залишків або лише цін.

---

4. Бізнес-правила

4.1. Фільтрація за переліком активних аптек

Модуль обробки отримує перелік діючих аптек із зовнішнього довідника мережі та оновлює його кожні 4 години. Дані аптек, яких немає в переліку, не обробляються.

Окрема регламентна процедура видаляє з бази дані аптек, виключених із переліку активних.

Наслідок: щоб дані нової аптеки з'явилися на сайті, її треба внести до довідника активних аптек.

4.2. Термін актуальності даних — одна доба

Щоденно виконуються регламентні процедури очищення.

Якщо від аптеки не надійшли актуальні дані до моменту очищення, її позиції на сайті втрачають залишок або ціну і стають недоступними для замовлення. Записи позицій при цьому не видаляються. Після надходження нових даних позиції знову стають доступними.

4.3. Обробка повного вивантаження

Після обробки повного вивантаження аптеки всі її позиції, які не ввійшли до вивантаження і не оновлювалися протягом поточної доби, вважаються відсутніми: їхні залишок або ціни скидаються.

4.4. Обробка некоректних записів

Записи з некоректним кодом аптеки або товару пропускаються. Решта даних повідомлення обробляється в звичайному порядку.

4.5. Публікація подій для каталогу сайту

Модуль обробки публікує події:

• оновлення залишків;
• скидання залишків;
• оновлення цін;
• скидання цін.

Поточний статус: функція працює в пілотному режимі лише для аптеки з кодом 217. Для інших аптек події не публікуються.

Копії опублікованих подій зберігаються протягом 4 днів для аудиту.

---

5. Технологічний стек