# План Спринту 1: верифікація контрагентів, перша працездатна частина Тижні 3–4 (10 робочих днів). Дата складання: 10 вересня 2026. Продовжує `План-робіт-верифікація-ingest-realtime.md` (напрям A) і `ТЗ-верифікація-контрагентів.md`. --- ## 1. Мета спринту **Польська або європейська компанія за номером ПДВ отримує рівень L1 автоматично, менш ніж за 60 секунд, із доказами в сховищі та бейджем у стрічці.** Мета навмисно звужена до тих джерел, які **вже працюють без ключа і без договору**: живий зонд 10 вересня показав, що VIES, Biała lista і KRS відповідають за 454–674 мс. Український напрям упирається в договір із ДП НАІС і ключ від НСДЦ, і саме тому він винесений у Спринт 2 — інакше готовий код чекав би на папір. --- ## 2. Умови входу: що вже є | Артефакт | Стан | |---|---| | Спринт 0: БД, міграція 001, довідники, імпорт 10 773 заявок | Виконано, 25 із 25 приймальних тестів на живій БД | | `002_verification.sql` — 12 таблиць, 2 тригери, подання досьє | Написано, застосовано і перевірено, 42 із 42 тестів | | `verification.schema.json`, `openapi-verification.yaml` | Написано, 36 із 36 контрактних перевірок | | `verification_sources.json` (13), `verification_checks.json` (14) | Написано, звірено з DDL і OpenAPI | | `probe_sources.py` | Прогнано на живих джерелах | Тобто спринт починається не з проєктування, а з реалізації за готовим і машинно перевіреним контрактом. Незакритим лишається одне архітектурне питання — **хостинг бекенду**. Без нього нема куди ставити планувальник і сховище доказів, тому це рішення день 1, не пізніше. --- ## 3. Обсяг спринту ### V1. Каталоги і конфігурація — 2 д - Завантажувач каталогів джерел і перевірок при старті сервісу з файлів `seed/`, ідемпотентний `upsert`. - Сховище ключів джерел у секретах середовища, а не в коді; джерело зі станом `needs_key` без ключа стартує як `unavailable`, а не падає. - Ендпойнт `GET /verification/sources` віддає фактичний стан. **Готово, коли:** сервіс піднімається на чистій БД, каталоги збігаються з файлами байт у байт, `GET /verification/sources` показує 13 джерел із реальним станом. ### V2. Три коннектори живих джерел — 4 д | Коннектор | Що робить | Особливість | |---|---|---| | VIES | `identity.vat_active` | Без ключа, нестабільна затримка — тільки асинхронно, ніколи не блокує форму | | Biała lista | `monitor.vat_status` + знімок рахунків | Віддає перелік офіційних рахунків — основа моніторингу підміни реквізитів | | KRS | `identity.registry_match_pl` | `204` означає «не знайдено», а не помилку; `stanZDnia` пишемо в `source_as_of` | Спільний контракт коннектора: вхід — суб'єкт перевірки, вихід — `checkResult` за схемою плюс сирий відгук для доказу. Кеш за TTL із каталогу, експоненційна пауза, 3 спроби, потім `unavailable`. **Готово, коли:** офлайн-фікстури для кожного джерела зелені, прапорець `--live` робить один реальний запит, а недоступність джерела дає `unavailable` з кодом причини, а не виняток. ### V3. Машина справи — 5 д - Створення справи, черга перевірок, паралельний запуск, збірка результатів. - Правила рішення з ТЗ §5: рішучі перевірки, `blocking_unavailable`, `override_blocking` з подвійним скороченням строку і окремою подією в журналі. - Автоматичне схвалення без оператора, коли всі обов'язкові перевірки пройдено. - Перехід у `manual_review` з переліком невиконаних перевірок і причин. **Готово, коли:** компанія з чинним NIP проходить від `POST /verification/cases` до рівня L1 без участі людини, а компанія з недоступним блокуючим джерелом гарантовано в цю точку не потрапляє. ### V4. Докази і зберігання — 2 д - Об'єктне сховище з увімкненим WORM, запис сирого відгуку, SHA-256, розмір, тип. - `source_as_of` окремо від `fetched_at`. - `retention_until` = дата перевірки + 5 років; завдання прибирання за розкладом. - Тимчасові підписані посилання в `GET /verification/checks/{id}/evidence`. **Готово, коли:** доказ, записаний тиждень тому, віддається за хешем, а спроба видалити його роллю застосунку відхиляється базою (це вже перевірено тестом). ### V5. API і ролі — 3 д - 10 шляхів із `openapi-verification.yaml`, валідація запитів і відповідей проти схеми в рантаймі. - Роль оператора верифікації, окрема від адміністратора; журнал розкриття контактів подією `contact_reveal`. - Ліміт частоти на подання справ: одна активна справа на компанію вже гарантована базою, ліміт захищає від засмічення чернетками. **Готово, коли:** відповідь, що не відповідає схемі, не виходить із сервісу — вона дає 500 і запис у журнал, а не мовчазне порушення контракту. ### V6. Досьє і бейдж у SPA — 3 д (фронтенд) - Бейдж у стрічці: чотири стани, без відтінків і зірочок. - Сторінка досьє: перелік перевірок, джерело з посиланням, дата перевірки і дата стану джерела, позначка застарілого. - Екран стану власної справи для заявника. **Готово, коли:** досьє показує рівно те, що є в базі, а недоступне джерело виглядає як недоступне — тим самим способом, яким це вже роблять вкладки погоди й кордонів. ### V7. CI-гейти — 1.5 д - Додати до правила захисту гілки два обов'язкові статуси: `Контракт модуля верифікації` і `Інваріанти верифікації`. - Винести живий зонд джерел у щоденний запуск за розкладом, **не** в перевірку pull request: недоступність зовнішнього реєстру не має блокувати вливання коду. - П'ять негативних PR: `unavailable` зі знахідками; схвалення з непорожнім `blocking_unavailable`; критична зміна без призупинення; `pass` без строку дії; блокуюче джерело, позначене як суто ручне. **Готово, коли:** усі п'ять негативних PR червоні, а звичайний PR зелений. ### V8. Юридичний трек — паралельно, день 1 Не займає часу розробника, але має найдовший строк: 1. Звернення до ДП НАІС за договором на API ЄДР — 18 000 грн з ПДВ за календарний місяць. 2. Запит ключа до Державного реєстру санкцій РНБО. 3. Резервний варіант: тариф агрегатора на випадок затримки договору — від 399 грн на місяць за 400 перевірок. 4. Оцінка легітимного інтересу (LIA) і шаблон DPA з провайдером даних. **Готово, коли:** усі три звернення надіслані й мають вхідний номер. Результат до кінця спринту не очікується — очікується запущений процес. --- ## 4. Календар | День | Робота | |---|---| | 1 | Рішення про хостинг. Розгортання бекенду і сховища. Юридичний трек V8 — усі три звернення | | 2 | V1 каталоги і конфігурація | | 3–4 | V2 VIES і Biała lista | | 5 | V2 KRS, кеш і TTL | | 6–7 | V3 машина справи, правила рішення | | 8 | V3 `override_blocking`, V4 докази і WORM | | 9 | V5 API і ролі; фронтенд V6 паралельно з дня 7 | | 10 | V7 гейти, негативні PR, наскрізний прогін, демонстрація | **Ресурс:** 1 бекенд повністю, 0.5 інтеграції, 0.5 фронтенд із дня 7, 0.5 QA і CI. Юридичний трек — власник продукту. --- ## 5. Що НЕ входить у Спринт 1 Навмисно, щоб мета лишалася досяжною: - Українські джерела: ЄДР, санкції РНБО, ЄДРСР — **Спринт 2**, після ключів і договору. - Рівень L2, документи, право підпису, контрольний платіж — Спринт 2. - Планувальник дельта-моніторингу і сповіщення — **Спринт 3**. У Спринті 1 знімки реквізитів уже пишуться, тож коли планувальник з'явиться, йому буде що порівнювати. - Кабінет оператора зі складним ручним розглядом — у Спринті 1 достатньо мінімального переліку справ і кнопки рішення. - Напрям B (ingest-агент) стартує з тижня 4 окремою людиною і не конкурує за бекенд-ресурс. --- ## 6. Приймальні критерії спринту Формулювання навмисно перевірні, а не описові. 1. Компанія з чинним польським NIP отримує L1 автоматично за менш ніж 60 секунд від подання, без дотику оператора. 2. Компанія з `statusVat` не `Czynny` отримує `fail` за рішучою перевіркою і не отримує жодного рівня. 3. При недоступному блокуючому джерелі справа переходить у `manual_review`, а не схвалюється. 4. Схвалення з `override_blocking` дає рівень із удвічі коротшим строком і окремою подією в журналі. 5. Доказ кожної перевірки віддається за хешем; видалити його роллю застосунку неможливо. 6. Знімок офіційних банківських рахунків із Biała lista збережено — навіть без планувальника, бо це база для Спринту 3. 7. Бейдж у стрічці й досьє показують джерело і дві дати; жодного агрегованого балу в інтерфейсі немає. 8. `Контракт модуля верифікації` (36) і `Інваріанти верифікації` (42) — обов'язкові статуси в правилі захисту гілки, обидва зелені на `main`. 9. П'ять негативних PR блокуються CI. 10. Усі наявні перевірки Спринту 0 і контрактні перевірки репозиторію лишаються зеленими. --- ## 7. Ризики спринту і що робити | Ризик | Ознака на ранньому етапі | Дія | |---|---|---| | Рішення про хостинг затягується | День 1 закінчився без середовища | Тимчасово розгорнути на VPS із бекапами; це оборотне, на відміну від простою всього спринту | | VIES відповідає повільно або з перебоями | Затримка перевищує 2 с у прогонах | Перевірка вже асинхронна за задумом; результат `unavailable` з повтором, онбординг не блокується | | KRS повертає `204` як помилку в коннекторі | Хибні `fail` у фікстурах | Явний тест на «компанію не знайдено» в наборі фікстур із дня 1 | | Обсяг V3 недооцінено | До дня 7 машина справи не проходить наскрізь | Пожертвувати V6 (бейдж у SPA) на користь V3; демонструвати через API | | Договір із НАІС не рухається | Немає вхідного номера до дня 3 | Одразу вмикати резервний тариф агрегатора, щоб Спринт 2 не зсунувся | --- ## 8. Вартість спринту за джерелами | Джерело | Вартість у Спринті 1 | |---|---| | VIES, Biała lista, KRS | 0 — публічні, без ключа | | ДП НАІС | 0 у спринті; з моменту договору — 18 000 грн з ПДВ на місяць | | Агрегатор (резерв) | від 399 грн на місяць за 400 перевірок | | OpenSanctions | 0 у спринті; далі 0,10 EUR за запит або власне розгортання | | Об'єктне сховище доказів | Мізерна за обсягами спринту | Облік `cost_micro` у кожному результаті працює з першого дня — щоб рішення «власне розгортання чи метрована хмара» ухвалювалося за цифрами, а не за відчуттям. --- ## 9. Вихід зі спринту в Спринт 2 Спринт 2 (тижні 5–7) починається з того місця, де Спринт 1 зупинився, і додає: український напрям через отримані ключі, рівень L2 з документами і правом підпису, судовий і санкційний скринінг із ручним розглядом. Дельта-моніторинг і сповіщення — Спринт 3, тижні 7–8, паралельно з початком напряму C. --- **Примітка щодо демо-сайту Trans-Atlas.** Сторінка «Верифікація: план Спринту 1» на сайті документує цей виконавчий план (обсяг V1–V8, календар, приймальні критерії, ризики, вартість) як довідкову інформацію, а не звіт про виконану роботу: жоден із трьох коннекторів (VIES, Biała lista, KRS), машина справи, об'єктне сховище з WORM і роль оператора верифікації в цьому демо не розгорнуті. Сторінка «Верифікація контрагентів» лишається каталогом рівнів, перевірок і джерел — цей документ є наступним кроком до нього, так само як «Бекенд: Спринт 0» є наступним кроком до «Технологічного стеку».