Словник

  1. Електронні торгові майданчики (ЕТМ, майданчики) — приватні онлайн-платформи, інтегровані з Центральною базою даних Prozorro.Sale. Через майданчики користувачі створюють лоти, подають документи, вносять гарантійні внески, роблять біди, беруть участь в аукціонах і отримують підтримку. Майданчики є комерційними партнерами Prozorro.Sale та посередниками між користувачем і ЦБД.

Бізнес дані

ТВ

Бізнес сценарії

Бізнес мета

Метою розробки -  створення окремого сервісу з можливістю взаємодію через АРІ що повертає альтернативну покращену версію лоту на основі інформації, внесеної у систему організатором.

Обґрунтування

Через те, що інформація про лот створюється організатором, якість опису лоту, його відображення на порталі та на сайтах майданчиків, залежить від спроможності організатора такий опис створити. Як наслідок, можуть використовуватись неякісні зображення (особливо в якості титульного), може використовуватись довга назва або неструктурований опис. 

При цьому зараз лоти з довгою назвою мають значимо кращий показник успішності. 

Розробка нового рішення дозволить:

  • спростити для організатора процес публікації інформації про лот
  • спростити відображення інформації про лот в інтерфейсах порталу та майданчиків
  • можливо підвищити конверсію перегляд → участь за рахунок більш зрозумілого та структурованого опису

Техічні вимоги

Технічні вимоги до введення тексту

На формі майданчика:

  1. надати користувачу поле description у форматі <textarea>;
  2. дозволити як ручне введення з переносами рядків (Enter), так і вставку тексту з Word.

У БД:

  1. зберігати текст як звичайний текст (plain text) без змін і додаткового форматування

На фронті при відображенні:

  1. використовувати CSS-властивість white-space: pre-wrap для збереження переносів рядків;
  2. або виконувати заміну символів нового рядка \n на <br> при рендері

Загальна архітектура системи

Створюється окремий middleware-сервіс — “Система покращення опису лоту”, який працює як незалежний компонент і може бути викликаний з різних майданчиків (ЕТМ) та інших внутрішніх сервісів.

Основні кроки роботи сервісу:

  1. Отримує вхідні дані (title, description, images та інші метадані) через HTTP/API.
  2. Проганяє їх через набір правил (регулярні вирази, форматування, валідація, ML-моделі).
  3. Формує альтернативні версії полів (titleAlt, descriptionAlt, imagesEnhanced).
  4. Повертає результат як відповідь на запит системи ЕТМ.
  5. При погодженні Організатором заміни оригінального тексту альтернативним заповнюється meta поля alternativeTitle = true та alternativeDescription = true в залежності яке поле погоджено поля набуваються значення false в разі не погодження Організатором викорисання

Основні компоненти:

  1. Вхідний API сервісу покращення опису лоту (REST/HTTP).
  2. Модуль обробки текстів (форматування, правила побудови title/description).
  3. (2-й етап) Модуль обробки зображень (покращення якості, вирівнювання горизонту тощо).
  4. Інтеграція з ЕТМ (синхронна або асинхронна модель взаємодії).

Правила обробки:

  1. Робота з полями title та description
    1. Формування структурованих описів із переносами рядків і логічними блоками.
    2. Збереження змісту критично важливих даних (кадастровий номер, площа, адреса тощо).
    3. Генерація альтернативних полів: titleAlt та descriptionAlt.
    4. Контроль максимальної довжини назви та опису (з урахуванням встановленних обмежень ЦБД).
  2. Використання альтернативного тексту в інтерфейсах
    1. У шаблоні "Детальний опис" за замовчуванням відображається альтернативний текст (titleAlt, descriptionAlt), якщо він існує, з можливістю перемикання на оригінальний (title, description).
    2. Для інших шаблонів використовується значення полів title та description.
    3. Для протоколів завжди використовується значення полів title та description.
  3. Обробка фотографій (2-й етап розробки)
    1. Перевертати фотографії в правильне розташування (орієнтація).
    2. Покращувати якість фото (контраст, різкість, яскравість у межах допустимого).
    3. Вирівнювати горизонт (особливо для фото об’єктів нерухомості).
    4. Позначати зображення як оброблені (флаг enhanced = true) для уникнення повторної обробки.

Додаткові технічні аспекти:

  1. Інтеграція та безпека
    1. Аутентифікація майданчиків через API ключі / OAuth2 / mTLS.
    2. Обмеження доступу до сервісу (whitelist IP, rate limiting).
    3. Логування запитів та відповідей (без розкриття чутливих даних).
  2. Версіонування правил
    1. Введення версії ruleset (наприклад, "land_description:v1").
    2. Можливість A/B-тестування різних версій правил для різних майданчиків.
  3. Логування та аудит
    1. Збереження інформації про факт звернення до сервісу, результат, помилки.
    2. Можливість відтворити історію змін опису лоту.

UseCase

Use Case 1. Збереження чернетки з генерацією альтернативного опису лоту

Назва

Збереження чернетки з генерацією альтернативного опису лоту
Актори

Основний: Організатор / Балансоутримувач.

Системні: ЕТМ (майданчик), Сервіс покращення опису лоту

Передумови

  1. Користувач авторизований в кабінеті акредитованого майданчика.
  2. Створюється або редагується чернетка процедури/реєстру/ІП.
  3. Заповнені поля title та/або description

Основний хід подій (дій)

  1. Користувач натискає елемент "Зберегти чернетку".
  2. Система ЕТМ формує запит до Сервісу покращення опису лоту з полями title, description, images.
  3. Сервіс покращення опису лоту обробляє дані та генерує titleAlt, descriptionAlt (та за потреби imagesEnhanced).
  4. Сервіс повертає результат у систему ЕТМ.
  5. Система ЕТМ зберігає альтернативні значення у метаполях чернетки та показує повідомлення: "Система згенерувала альтернативний текст... Ознайомитись?".
  6. Якщо користувач обирає "Так", система виводить оригінальні та альтернативні значення title/description.
  7. Користувач може натиснути "Замінити", щоб зробити альтернативний варіант основним.
  8. Після підтвердження система ЕТМ зберігає чернетку з оновленими значеннями та поля alternativeTitle = true та alternativeDescription = true

Альтернативні шляхи, помилки, крайові випадки

  1. Користувач обирає "Ні": чернетка зберігається без змін полів title/description, але з titleAlt/descriptionAlt у метаполях та поля alternativeTitle = false та alternativeDescription =false.
  2. Сервіс покращення опису лоту недоступний: система ЕТМ зберігає чернетку без альтернативних значень та показує інфо-повідомлення.
  3. Поля title/description порожні: сервіс повертає відповідь без альтернативи, ЕТМ зберігає чернетку без змін

Результат (Постумови)

  1. Чернетка збережена.
  2. Альтернативні значення titleAlt, descriptionAlt збережені (якщо були згенеровані).

Інші вимоги


Use Case 2. Публікація процедури з використанням альтернативного опису на порталі/майданчику

Назва

Публікація процедури з використанням альтернативного опису на порталі/майданчику

Обґрунтування


Актори

Основний: Організатор / Балансоутримувач.

Системні: ЕТМ (майданчик), Портал Prozorro.Sale

Передумови

  1. Існує збережена чернетка з полями title, description та, за наявності, titleAlt, descriptionAlt

Основний хід подій (дій)

  1. Користувач відкриває чернетку та ініціює публікацію процедури.
  2. Система ЕТМ визначає, які поля необхідно відправити до ЦБД/порталу (title, description).
  3. Якщо користувач раніше прийняв альтернативний текст — у полях title/description вже міститься покращена версія та поля alternativeTitle = true та alternativeDescription = true.
  4. Система ЕТМ відправляє дані до ЦБД.
  5. Портал Prozorro.Sale використовує значення title/description для відображення в загальних списках та протоколах.
  6. У шаблоні "Детальний опис" на порталі та майданчику може відображатися titleAlt/descriptionAlt (якщо передбачено інтерфейсом).

Альтернативні шляхи, помилки, крайові випадки


Результат (Постумови)

  1. Процедура успішно опублікована.
  2. Для користувачів порталу доступний як мінімум основний опис лоту, а за потреби — альтернативний детальний опис

Інші вимоги


Use Case 3. Перегляд лоту з можливістю перемикання між оригінальним та альтернативним описом

Назва

Перегляд лоту з можливістю перемикання між оригінальним та альтернативним описом

Обґрунтування


Актори

Основний: Учасник, гість порталу, Організатор.

Системні: Портал Prozorro.Sale, ЕТМ

Передумови

  1. Для лоту існують поля title/description та альтернативні titleAlt/descriptionAlt

Основний хід подій (дій)

  1. Користувач відкриває сторінку лоту в шаблоні "Детальний опис".
  2. Система перевіряє наявність titleAlt/descriptionAlt.
  3. Якщо альтернативний опис є — за замовчуванням відображається він.
  4. Користувачу доступний перемикач "Альтернативний / Оригінальний опис".
  5. При перемиканні інтерфейс оновлює відображувані поля без додаткових запитів до бекенду (якщо всі дані вже отримані)

Альтернативні шляхи, помилки, крайові випадки


Результат (Постумови)

Користувач має прозорий доступ до обох версій опису лоту

Інші вимоги


Use Case 4. Повторна генерація альтернативного опису при редагуванні чернетки

Назва

Повторна генерація альтернативного опису при редагуванні чернетки

Обґрунтування


Актори

Основний: Організатор / Балансоутримувач.

Системні: ЕТМ, Сервіс покращення опису лоту

Передумови

  1. Існує чернетка з уже згенерованими titleAlt/descriptionAlt

Основний хід подій (дій)

  1. Користувач відкриває чернетку та змінює поля title або description.
  2. При наступному натисканні "Зберегти чернетку" система ЕТМ перевіряє, чи змінилися значення title/description у порівнянні з попереднім збереженням.
  3. Якщо змінилися — ЕТМ повторно викликає сервіс покращення опису лоту.
  4. Сервіс генерує нові titleAlt/descriptionAlt.
  5. Далі сценарій повторює UC-1 (показ повідомлення, можливість прийняти/відхилити альтернативу)

Альтернативні шляхи, помилки, крайові випадки

  1. Користувач погодився на використання альтернативного тексту в попередній раз відповіднго поля alternativeTitle = true та alternativeDescription = true
  2. Користувач змінює поля title або description
  3. При наступному натисканні "Зберегти чернетку" система ЕТМ не відправляє title/description на повторну перегенерацію

Результат (Постумови)

Альтернативний опис завжди відповідає актуальній версії оригінального тексту

Інші вимоги


Use Case 5. Завантаження та обробка фотографій лоту (2-й етап)

Назва

Завантаження та обробка фотографій лоту (2-й етап)

Обґрунтування


Актори

Основний: Організатор / Балансоутримувач.

Системні: ЕТМ, Сервіс покращення опису лоту (модуль обробки зображень).

Передумови

  1. Користувач знаходиться на формі редагування лоту та додає/змінює фотографії

Основний хід подій (дій)

  1. Користувач завантажує одне або кілька зображень.
  2. ЕТМ зберігає оригінали зображень та відправляє їх (або їхні URL) в сервіс покращення.
  3. Сервіс виконує попередньо визначені кроки обробки (орієнтація, вирівнювання горизонту, покращення якості).
  4. Сервіс повертає оброблені зображення або їхні URL.
  5. ЕТМ зберігає посилання на оброблені зображення та показує їх у інтерфейсі як титульні/додаткові фото.

Альтернативні шляхи, помилки, крайові випадки


Результат (Постумови)

До лоту прикріплені візуально покращені та правильно орієнтовані фотографії

Інші вимоги


Use Case 6. Масова генерація альтернативних описів для існуючих лотів (в разі batch-обробки)

Назва

Масова генерація альтернативних описів для існуючих лотів (batch-обробка)

Обґрунтування


Актори

Основний: Адміністратор Prozorro.Sale або відповідальний аналітик.

Системні: Внутрішній сервіс/скрипт, Сервіс покращення опису лоту

Передумови

  1. Існує масив уже опублікованих або активних лотів без альтернативного опису

Основний хід подій (дій)

  1. Адміністратор ініціює масову обробку (через внутрішній інструмент або планове завдання).
  2. Система по черзі або пакетами відправляє дані лотів до сервісу покращення опису лоту.
  3. Сервіс повертає згенеровані titleAlt/descriptionAlt.
  4. Результати зберігаються у метаполях лотів.
  5. Інтерфейси порталу/майданчиків автоматично починають використовувати альтернативні описи в "Детальному описі" (за потреби — після додаткового схвалення)

Альтернативні шляхи, помилки, крайові випадки


Результат (Постумови)

Багато існуючих лотів отримують покращені описи без ручного втручання організаторів

Інші вимоги


Use Case 7. Обробка помилок та недоступності сервісу покращення опису лоту (fallback-сценарії)

Назва

Обробка помилок та недоступності сервісу покращення опису лоту (fallback-сценарії)

Обґрунтування


Актори

Основний: Організатор / Балансоутримувач.

Системні: ЕТМ, Сервіс покращення опису лоту

Передумови

  1. Користувач намагається зберегти чернетку або виконати дію, яка передбачає виклик сервісу покращення

Основний хід подій (дій)

  1. ЕТМ надсилає запит до сервісу покращення.
  2. Сервіс повертає помилку або не відповідає в межах таймауту.
  3. ЕТМ логувати помилку та продовжує сценарій збереження без використання альтернативного опису.
  4. Користувач отримує повідомлення, що сервіс тимчасово недоступний, але чернетку збережено

Альтернативні шляхи, помилки, крайові випадки


Результат (Постумови)

Життєвий цикл лоту не блокується недоступністю сервісу покращення

Інші вимоги


Use Case 8. Моніторинг та адміністрування сервісу покращення опису лоту

Назва

Моніторинг та адміністрування сервісу покращення опису лоту

Обґрунтування


Актори

Основний: Адміністратор / DevOps / Підтримка.

Системні: Сервіс покращення опису лоту, системи моніторингу

Передумови

  1. Сервіс покращення опису лоту розгорнутий у промисловому середовищі

Основний хід подій (дій)

  1. Адміністратор переглядає дашборди стану сервісу (доступність, час відповіді, кількість помилок).
  2. За потреби вмикає/вимикає окремі версії ruleset або інтеграцію для окремих майданчиків.
  3. Аналізує логи проблемних запитів та, за потреби, передає інформацію команді розробки

Альтернативні шляхи, помилки, крайові випадки


Результат (Постумови)

Сервіс покращення опису лоту підтримується у стабільному та контрольованому стані

Інші вимоги


  • No labels