Словник

  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. Після підтвердження система ЕТМ зберігає чернетку з оновленими значеннями.

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

  1. Користувач обирає "Ні": чернетка зберігається без змін полів title/description, але з titleAlt/descriptionAlt у метаполях.
  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 вже міститься покращена версія.
  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 (показ повідомлення, можливість прийняти/відхилити альтернативу)

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


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

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

Інші вимоги


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. Аналізує логи проблемних запитів та, за потреби, передає інформацію команді розробки

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


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

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

Інші вимоги


Use Case n. Збреження чернетки аукціону з викликом "Системи покращення опису лоту"

Назва

Збереження чернетки процедури/реєстру/ІП

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

Користувачу необхідно зберегти чернетку процедури/реєстру/ІП перед публікацією в системі

Актори

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

Передумови

  1. Користувач авторизований в кабінеті акредитованого майданчика АТ "Прозорро.Продажі"

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

  1. Користувач активує елемент "Зберегти чернетку"
  2. Система майданчика відправляє запит в "Систему покращення опису лоту"
  3. Система покращення опису лоту опрацьовує поля: title, description, all images
  4. Система покращення опису лоту віддає результат опрацювання системі майданчика
  5. Система майданчика виводить повідомлення Організатору "Система згенерувала альтернативний текст в полях: title та description. Ви можете ознайомитись та прийняти його як основний, в разі не прийняття запропонований текст буде збережений як альтернативний. Ознайомитись ?"
    1. Якщо коритстувач активує елемент "Так"→ :
      1. Cистема майданчика виводить дві варіації інформації в полях: title та description
      2. Система майданчика виводить активний елемент "Замінити"
        1. Якщо користувач активує елемент "Замінити"
          1. Система майданчика замінює теста в полях процедури title та description
          2. Користувач активує елемент "Зберегти чернетку"
          3. Система майданчика зберігає чернетку процедури/реєстру/ІП
        2. Якщо користувач не активував елемент "Замінити" але активував елемент "Зберегти чернетку" 
          1. Система майданчика не вносить зміни в поля процедури/реєстру/ІП title та description
          2. Система майданчика зберігає дані в полях процедури/реєстру/ІП title та description без змін та зберігає альтернативні значення в мета полях процедури/реєстру/ІП: titleAlt та descriptionAlt
    2. Якщо користувач активує елемент "Ні" → Cистема закриває повідомлення та зберігає дані в полях процедури/реєстру/ІП title та description без змін та зберігає альтернативні значення в мета полях процедури/реєстру/ІП titleAlt та descriptionAlt

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

  1. Користувач редагує та повторно зберігає чернетку процедури та вже має альтернативно згенерований текст (Заповнені поля: title,description, titleAlt та descriptionAlt )
    1. Система майданчика повинна виділити чи були внесені зміни в полях title та description
      1. Якщо Так →Система майданчика відправляє запит в "Сервіс покращення опису лоту" і виконує дії відповідно до основного шляху користувача
      2. Якщо Ні → Система майданчика не відправляє запит в "Сервіс покращення опису лоту" та зберігає внесені зміни до полів процедури/реєстру/ІП
  2. Користувач редагує чернетку процедури та вже прийняв альтернативно згенерований текст (Заповнені поля: title,description та Незаповнені поля - titleAlt та descriptionAlt) можливо зробимо мета поле і по ньому майданчик перевіряє чи треба відправляти запит в "Систему покращення опису лота"
    1. Система майданчика не перевіряє які поля були змінені та не відправляє запит в "Систему покращення опису лота" а збегіє чернетку в виправленому варіанті

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

Зребежена чернета має альтернативні значення title та description

Інші вимоги



Use Case 2. Збреження чернетки аукціону

Назва

Збереження чернетки процедури/реєстру/ІП

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

Користувачу необхідно зберегти чернетку процедури/реєстру/ІП перед публікацією в системі

Актори

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

Передумови

  1. Користувач авторизований в кабінеті акредитованого майданчика АТ "Прозорро.Продажі"

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

  1. Користувач активує елемент "Зберегти чернетку"
  2. Система майданчика відправляє запит в "Систему покращення опису лоту"
  3. Система покращення опису лоту опрацьовує поля: title, description, all images
  4. Система покращення опису лоту віддає результат опрацювання системі майданчика
  5. Система майданчика виводить сповіщення Організатору "Система згенерувала альтернативний текст в полях: title та description. Ви можете ознайомитись та прийняти його як основний, в разі не прийняття запропонований текст буде збережений як альтернативний"
  6. Система виводить повідомлення "Дана дія є незворотньою. Підтверджуєте ?"
    1. Якщо коритстувач активує елемент "Так"→ :
      1. Cистема змінює статус користувача на inactive
    2. Якщо користувач активує елемент "Ні" → Cистема закриває повідомлення і не змінює статус користувача

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


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

Користувач деактивував Адміністратора Факторингу/Адміністратора компанії Брокера

Інші вимоги

Система зберігає історію дій