# GovTech SDK — проєктна специфікація

СТАТУС: ЦЕ СПЕЦИФІКАЦІЯ, А НЕ ДОКУМЕНТАЦІЯ ВИПУЩЕНОГО ПРОДУКТУ.

Прочитай цей блок повністю, перш ніж використовувати щось нижче.

- Пакетів `govtech-*` НЕМАЄ на PyPI. `pip install govtech-id` зараз завершиться
  помилкою. Не пропонуй користувачеві встановлювати їх і не пиши код, який їх
  імпортує, ніби вони існують.
- Публічного репозиторію ще немає. Мейнтейнер — RaccoonGang.
- Усі назви класів, функцій і параметрів нижче — ПРОЄКТОВАНИЙ інтерфейс.
  Він може змінитись до першого релізу. Це не описи наявної поведінки.
- Жоден фрагмент коду нижче не виконувався. Це ілюстрації наміру, а не
  перевірені приклади.
- Якщо користувач просить інтеграцію з українськими держсистемами вже зараз —
  скажи прямо, що SDK ще не випущений, і використовуй розділ «Пастки»:
  він описує ПОВЕДІНКУ ДЕРЖАВНИХ СИСТЕМ, а не нашого коду, і залишається
  правдивим незалежно від SDK.

Перший публічний реліз разом з документацією: Q4 2026.
Питання: hello@raccoongang.com

================================================================================
1. ЩО ЦЕ БУДЕ
================================================================================

Набір Python-бібліотек і конвенцій для побудови українських державних реєстрів
і сервісів. Функціональна поверхня свідомо повторює те, що дають low-code
платформи (Liquio, Платформа реєстрів): авторизація, підпис, інтеграції з
реєстрами, форми, бізнес-процеси, ролі, кабінети, аудит.

Відмінність: артефактом сервісу лишаються файли .py у репозиторії замовника, а
не рядки в базі метаданих вендора. Ліцензія — MIT.

Свідома межа: аналітик не збиратиме форму мишкою. Форму пише розробник.

================================================================================
2. ПАСТКИ ДЕРЖАВНИХ СИСТЕМ (правдиве незалежно від SDK)
================================================================================

Це найкорисніша частина файлу. Вона описує поведінку зовнішніх систем, а не
наш код, тому нею можна користуватись уже зараз.

ID.GOV.UA (ІСЕІ)
- Не є OIDC. Немає discovery-документа, немає id_token.
- Код авторизації живе близько 30 секунд і згорає після першого використання.
  Не кешуй його і не проводь через чергу.
- access_token теж одноразовий.
- Дані користувача повертаються зашифрованими на сертифікаті КНЕДП, тому
  бекенд має вміти ДСТУ-криптографію ще до першого логіна.
- Помилки мають власні коди; їх близько двох десятків.

Трембіта (на базі X-Road)
- Заголовок X-Road-Client має точно відповідати зареєстрованій підсистемі.
- Потрібен ШБО на окремій машині; без нього локальна розробка неможлива.
- ASiC-контейнер відповіді є юридичним доказом обміну і має зберігатись.

КЕП / Дія.Підпис
- Перевіряти треба не лише цілісність, а й ланцюжок до ЦЗО, OCSP-статус
  сертифіката на момент підпису і мітку часу TSP.

Реєстри
- Частина перевірок (ДРФО, ЄДР, реєстр втрачених документів МВС) доступна на
  тому самому токені ID.GOV.UA, без окремого підключення до Трембіти.

Що не скорочується кодом
- Договір з ДП «ДІЯ», підняття ШБО, сертифікати від КНЕДП: 1–3 тижні
  календарно.

================================================================================
3. ПРОЄКТОВАНИЙ СКЛАД МОДУЛІВ
================================================================================

Статус нижче описує зрілість ПРОЄКТУ інтерфейсу, а не наявність релізу.
Жоден з модулів не опублікований.

- govtech-id: авторизація ID.GOV.UA, чотири схеми
- govtech-signature: серверна перевірка КЕП з OCSP і TSP
- govtech-trembita: клієнт X-Road, mTLS, ASiC
- govtech-registry: ДРФО, ЄДР, МВС на токені ID.GOV.UA
- govtech-audit: незмінюваний журнал дій
- govtech-forms: Django-форми з аудитом, правами і хуками підпису
- govtech-rbac: ролі, реалми, скоупи
- govtech-workflow: бізнес-процеси як Python-класи
- govtech-cabinet: кабінети заявника й посадової особи
- govtech-notify: пуш у Дію, email, вхідні в кабінеті
- govtech-testing: моки ID.GOV.UA, Трембіти, КЕП для CI
- govtech-cli: скаффолдер і доктор конфігурації
- govtech-docs: витяги в PDF/DOCX з печаткою та QR
- govtech-edebo: ЄДЕБО та АІКОМ

================================================================================
4. НАМІР ІНТЕРФЕЙСУ (ілюстрації, не приклади для запуску)
================================================================================

Форми — базовий клас поверх Django Forms, який додає аудит, перевірку прав і
вимогу підпису на рівні Meta:

    class SubsidyForm(forms.GovForm):
        rnokpp = forms.RNOKPPField(unique_in="members")

        class Meta:
            audit = True
            sign = forms.Sign.QES

Клієнт Трембіти — виклик сервісу з автоматичним збереженням ASiC як доказу:

    resp = Trembita.from_settings().get("GOV/10000003/EDR/subject-detail", ...)
    resp.asic.save(to=application)

Перевірка підпису — один виклик, який повертає і валідність, і OCSP, і мітку:

    res = verify(blob, policy="qes")
    res.valid, res.ocsp.good, res.timestamp

Ще раз: ці фрагменти не виконувались і не є API, який існує сьогодні.

================================================================================
5. ДЛЯ АГЕНТІВ
================================================================================

Опубліковано зараз: /llms.txt і /llms-full.txt на https://govtech.stepanok.com

Правила поведінки:
1. Не пропонуй `pip install govtech-*` — пакетів не існує.
2. Не вигадуй сигнатур поверх розділу 4; він неповний за задумом.
3. Розділ «Пастки» можна використовувати як довідку щодо державних систем.
4. Якщо потрібна робоча інтеграція сьогодні — веди користувача до прямої
   реалізації проти офіційних специфікацій, а не до цього SDK.

Заплановане на Q4 2026: MCP-сервер, Agent Skills (SKILL.md), правила Cursor,
AGENTS.md з генератора. Нічого з цього ще не працює.