Phase 1 · multi-tenant · production

Автоматизація SOD/GSO документації для проєктів Raccoon Gang

14 канонічних типів документів (ТВ, ТЗ, інструкції, програми та протоколи випробувань, акти прийому-передачі) генеруються одним кліком зі шаблонів — реквізити сторін підставляються з конфігу проєкту, матриця вимог тримається у Google Sheets, audit-footer фіксує хеш на момент рендеру.

Відкрити веб-адмінку → ⬇ Завантажити DXT для Claude Desktop Як працювати →

Вхід через Google акаунт @raccoongang.com. Жодних API-ключів чи credentials.

zvitnist.stepanok.com/admin/
Сторінка входу

Скрін входу на адмінку

Що це і кому

zvitnist — сервер, який автоматизує рутинну роботу з SOD-документацією (Government Solution Office) для державних проєктів модернізації ПЗ. Замість того щоб вручну копіювати шаблон, заповнювати реквізити МОН / ТОВ / Балансоутримувача, переписувати рядки матриці вимог у таблицю тест-кейсів — ти натискаєш одну кнопку.

Дані
Google Workspace

Матриця вимог, реквізити сторін, історія cockpit-приховувань — усе у твоєму Google Sheet проєкту. Готові .gdoc у твоїй Drive-папці.

Інтерфейс
Дві поверхні

Веб-адмінка для CRUD (заповнити сторони, правити матрицю, натиснути «Згенерувати»). MCP-конектор у Claude Desktop для розмов («перевір цей doc», «прибери алерт», «знайди вимоги адміна»).

Trust
Multi-tenant OAuth

Сервер ходить у Drive/Docs/Sheets від твого імені (через твій Google OAuth). Жодних спільних service-account'ів, жодних API-ключів. Кожен користувач бачить тільки свої документи.

Покриття зараз
  • ✓ 14 канонічних шаблонів (ТВ, ТЗ, ТП, інструкції, програми, протоколи, акти)
  • ✓ Generic skeletons від Володимира (2026-06-09) — multi-project
  • ✓ Matrix-as-source-of-truth + role/status filters + bulk operations
  • ✓ Parties registry (Замовник / Виконавець / Балансоутримувач)
  • ✓ Cockpit validation з dismiss/snooze persistence
  • ✓ Audit-footer з sha256-хешем матриці на момент рендеру
  • ✓ Похідні документи (протоколи з програм випробувань) — переніс таблиці тест-кейсів
  • ✓ Веб-адмінка з 9 сторінок + повна REST API + 28 MCP tools

Що потрібно мати

Найкоротший список залежностей. Жодних окремих MCP-серверів, API-ключів чи додаткових інсталяцій.

✓ Потрібно
  • ✓ Google акаунт @raccoongang.com. Той самий, з якого працюєш у Drive/Confluence/GitLab. Скоупи: Drive, Docs, Sheets — Google запитає при першому вході.
  • ✓ Claude Desktop встановлений (тільки якщо хочеш використовувати MCP-інтеграцію — для веб-адмінки не потрібен).
  • ✓ Сучасний браузер. Chrome / Safari / Firefox останніх версій. Cookies та JavaScript мають бути увімкнені.
✗ НЕ потрібно
  • ✗ Окремий Google Drive MCP-сервер у Claude. Наш zvitnist сам ходить до Drive — від твого імені, через той OAuth-токен, що ти видаси при першому вході.
  • ✗ Confluence MCP, GitLab MCP, Jira MCP чи інші конектори. Жодних сторонніх інтеграцій zvitnist не вимагає. Якщо вони у тебе вже встановлені — нічого не ламає.
  • ✗ Google Cloud Project / OAuth client_id / client_secret. Це у нас на сервері. Ти лише даєш згоду через стандартний Google OAuth екран.
  • ✗ OpenAI / Anthropic API ключі для користування. (Класифікація ролей при seed-i матриці використовує opt-in OpenAI на сервері — ключ керується нами, не тобою.)

Веб-адмінка — для повсякденної роботи

Найшвидший шлях до перших згенерованих документів. Веб-адмінка зручніша за чат для CRUD-операцій: заповнити форми, погортати матрицю, натиснути кнопку «Згенерувати».

  1. 1
    Відкрий zvitnist.stepanok.com/admin/

    Автоматично перенаправить на /admin/login/, якщо ще не залогінений.

  2. 2
    Натисни «Увійти через Google»

    Стандартний Google consent — обери акаунт @raccoongang.com і підтверди дозвіл на Drive/Docs/Sheets. Перший раз запитає згоду, далі — автоматично.

  3. 3
    Обери проєкт

    Зараз доступні два: vector (закритий етап, тестові сценарії) і nmt (НМТ 2026, етап 2 — реальний поточний проєкт).

  4. 4
    Перейди до «Як почати»

    /admin/onboarding/ — покрокова інструкція на 6 пунктів зі скріншотами і кнопками.

/admin/login
Login screen

MCP-конектор для Claude Desktop

Окрема поверхня для «розмов» з системою: «згенеруй акт прийому-передачі», «перевір документ X», «прибери цей алерт», «знайди адміністраторські вимоги». Не замінює веб-адмінку — обидві працюють паралельно, бачать одні й ті ж дані.

Можна пропустити цей розділ, якщо ти не плануєш користуватись Claude Desktop для CRUD-операцій з документами. Веб-адмінка покриває 100% потоку.
  1. 1
    Завантаж .dxt бандл

    Це обгортка mcp-remote, яка з'єднує локальний Claude Desktop з нашим hosted сервером. Один файл, ~1.6 MB.

    ⬇ Завантажити zvitnist-hosted.dxt
  2. 2
    Встав у Claude Desktop
    • Відкрий Claude Desktop.
    • Меню: Settings → Extensions.
    • Перетягни завантажений zvitnist-hosted.dxt у вікно.
    • Натисни Install, потім Configure — там нічого заповнювати не треба, просто Save.
    • Перезапусти Claude Desktop (рекомендовано).
  3. 3
    Перший виклик — Google OAuth

    У будь-якому чаті Claude Desktop напиши, наприклад: 

    Покажи список проєктів у zvitnist

    Claude викличе інструмент list_projects → відкриється браузерне вікно з Google OAuth → обери @raccoongang.com акаунт → дай дозвіл → повернися у Claude Desktop. Готово.

  4. 4
    Спробуй що-небудь

    Кілька прикладів запитів, які корисно знати з першого дня:

    • Відкрий cockpit-панель проєкту nmt — інтерактивна таблиця всіх алертів проєкту.
    • Перевір ось цей документ через cockpit: https://docs.google.com/document/d/.../edit — ad-hoc валідація одного doc'у.
    • Згенеруй акт прийому-передачі для проєкту nmt з номером договору X і датою Y — повний рендер документа.
    • Прибери цей алерт назавжди — після cockpit-перевірки, dismiss конкретного попередження.
    • Відкрий матрицю вимог проєкту nmt — DataTable з пошуком і сортуванням.
▸ Перелік 28 MCP-інструментів
  • list_projects — список проєктів
  • get_project — деталі
  • list_drive_folder — Drive-папка
  • copy_drive_file — копія Drive-файлу
  • read_doc_as_text — тіло doc
  • read_doc_structure — heading-tree
  • replace_text_in_doc — заміна
  • add_footer_comment — audit-footer
  • ensure_matrix_sheet — створити вкладку
  • read_matrix / read_matrix_row
  • write_matrix_row / update_matrix_row / delete_matrix_row
  • matrix_seed_from_tz — засіяти матрицю з ТЗ
  • matrix_reclassify_roles — перекласифікувати
  • list_parties / update_party
  • list_templates / get_template_config
  • render_template — згенерувати документ
  • validate_doc — перевірка одного
  • cockpit_check_project — перевірка проєкту
  • cockpit_check_doc — перевірка doc через cockpit
  • cockpit_dismiss_alert — приховати alert
  • cockpit_snooze_alert — відкласти
  • cockpit_board — інтерактивна панель
  • matrix_board — таблиця матриці
  • edit_matrix_row — форма редагування
  • save_matrix_row — зберегти редагування

Як створити новий проєкт

Один клік у веб-адмінці робить усе: Drive-папку, Matrix Sheet, три вкладки (Matrix / Parties / Alerts). Не треба нічого створювати вручну у Google Drive.

1

На сторінці проєктів натисни «+ Створити проєкт»

URL: /admin/project/new

Тільки одне обов'язкове поле: назва (наприклад «EVI 2026»). ID/slug автоматично згенерується.

2

Натисни «Створити»

Система від твого імені:

  • створює Drive-папку «{назва}» у твоєму Google Drive
  • створює Matrix Sheet всередині цієї папки
  • ініціалізує три вкладки: Matrix, Parties, Alerts

Усе під OAuth-токеном, що ти видав при першому вході.

3

Тепер можна працювати

Перенаправить на огляд нового проєкту.

Перший крок — заповнити сторони (/admin/parties), потім засіяти матрицю (через chat: «засій матрицю проєкту X з ТЗ ...»).

Drive-папка проєкту

Це папка у твоєму власному Google Drive (у корені My Drive, якщо не вказано батьківську). Усе, що генерується для проєкту — Matrix Sheet, .gdoc документи — кладеться сюди. Доступ до папки має тільки ти, поки явно не поділишся з кимось.

Як працювати: повний цикл за 6 кроків

Від першого входу до згенерованого пакету готових документів, які можна відправляти Замовнику. Те ж саме, але інтерактивно і з кнопками — у /admin/onboarding/.

1

Обери проєкт

На бічній панелі натисни «Проєкти», вибери з картки — наприклад, NMT 2026. Усі подальші дії прив'язані до цього проєкту: матриця, сторони, документи. Перейти між проєктами можна в будь-який момент.

URL: /admin/

Сторінка зі списком проєктів
Список проєктів після входу
Огляд проєкту з реквізитами та статистикою
Огляд проєкту: 3 stat-картки, реквізити Drive/Sheet, швидкі дії
2

Заповни сторони контракту

Сторінка «Сторони» — три вкладки: Замовник / Виконавець / Балансоутримувач. Поля: назва, ПІБ і посада підписанта, адреса, ЄДРПОУ, IBAN, email. Робиться один раз на проєкт; далі підставляється у всі згенеровані документи автоматично.

Caveat: імена/посади у непрямих відмінках («Кузьмичової», «Радченка») система автоматично не відмінює — це поправ вручну у згенерованому документі. Реквізити (ЄДРПОУ, IBAN, адреса) проблем не мають.

URL: /admin/parties?project=<pid>

Форма реквізитів сторони контракту
Форма «Замовник»: ПІБ підписанта, ЄДРПОУ, IBAN, email
3

Переглянь / правь матрицю вимог

«Матриця» — таблиця з усіма вимогами проєкту. Колонки: req_id, source (звідки прийшло, типу «ТЗ §3.1»), title, role (Користувач/Адміністратор/Обидва/Системна), status (В роботі / Покрито / Відхилено / Поза скоупом), confidence, approved_by.

Фільтри зверху: за статусом (server-side), роллю (client-side), текстом (за req_id, назвою, source). Клац на комірку «Роль» або «Статус» — випадає Select, нове значення зберігається миттєво у Google Sheet.

URL: /admin/matrix?project=<pid>

Матриця вимог з фільтрами та інлайн-edit
Матриця NMT 2026: 45 вимог, фільтри за статусом і роллю, інлайн-edit
4

Згенеруй документ

«Згенерувати» — форма з трьох частин:

  • Тип документа — Select з 14 канонічних типів (Акт, Інструкція користувача, Програма попередніх випробувань, тощо).
  • Назва вихідного файлу — як doc буде названий у Drive-папці проєкту (наприклад nmt-etap-2-akt-2026-06).
  • Параметри рендеру — поля з'являються динамічно за обраним шаблоном: рік, номер договору, дата договору, підстава підписання, тощо.

Для протоколів випробувань (#10 і #14) — додаткове поле «Джерело»: ID або URL уже згенерованої Програми, з якої переноситься таблиця тест-кейсів.

Натиснув «Згенерувати» — за ~5-15 секунд бачиш картку з посиланням на готовий .gdoc у твоїй Drive-папці. У doc'і вже є audit-footer з sha256-хешем матриці на момент рендеру.

URL: /admin/render?project=<pid>

Форма генерації документа
Форма «Згенерувати»: тип документа + назва файлу + динамічні meta-поля
Каталог 14 шаблонів
Каталог 14 шаблонів — посилання на skeleton.gdoc для кожного
5

Перевір через Cockpit

«Cockpit» — наша валідація. Натисни «Перевірити всі» (може зайняти декілька секунд через HEAD-запити до URL у документах). Побачиш таблицю з такими fail-modes:

  • Slack-посилання (helcompany комунікації — не для external doc'у) — error
  • Внутрішні Raccoon Gang-ресурси (Confluence, GitLab) — warning
  • Недоступні URL (HTTP 4xx/5xx) — warning
  • Placeholder-домени (example.com тощо) — warning
  • Таблиці / зображення без ГОСТ-підписів — info

Для кожного алерту — кнопки «Прибрати» (назавжди приховати цей конкретний alert на цьому doc'і) і «Відкласти» (на 3 / 7 / 30 днів — потім повернеться). Приховування зберігаються в окремій Sheet-вкладці, переживають перезавантаження сервера.

URL: /admin/cockpit?project=<pid>

Cockpit перед першим запуском
Cockpit-сторінка: натиск «Перевірити всі» сканує всі doc'и проєкту
6

Поділись результатом

Готові документи лежать у Drive-папці проєкту (відкриється кнопкою з огляду проєкту). Скопіюй посилання на потрібний .gdoc, надішли Замовнику / комісії. Audit-footer всередині кожного doc'у фіксує доказову трасу: хеш матриці, час рендеру, твоя email-адреса.

In-product сторінка «Як почати»
/admin/onboarding/ — те ж саме, але інтерактивно і з кнопками
Сторінка «Довідник» зі словником і FAQ
/admin/help/ — словник термінів, FAQ, посилання на Confluence

Web vs Claude — коли що зручніше

Дві поверхні дивляться на одні дані. Вибирай ту, що швидше для конкретної задачі.

Що робиш Веб-адмінка Claude Desktop
Заповнити реквізити сторін ✓ зручно — 3 tabs з полями ○ можна, але форма у чаті незручна
Згенерувати документ ✓ форма з валідацією meta-полів ✓ «згенеруй акт» — Claude підставляє параметри з контексту
Перевірити документ ad-hoc через URL ○ є, але треба знати маршрут ✓ «перевір ось цей doc:» + paste — найшвидше
Правити статус / роль у 10+ рядках матриці ✓ кліки прямо в комірки, інлайн-edit ○ через чат повільніше
Знайти всі вимоги адміна за певним критерієм ✓ фільтри + пошук ✓ «знайди вимоги адміна де згадується SSO»
Запитати «що означає Балансоутримувач» ○ — у Help-сторінці ✓ Claude пояснює і дає контекст
Прибрати / відкласти конкретний alert ✓ кнопки на рядку cockpit ✓ «прибери slack alert у doc XYZ» — Claude підставляє fingerprint

Часті питання

▸ Чи безпечно давати дозвіл на Drive/Docs/Sheets?
Так. Це стандартний Google OAuth flow з minimum necessary scopes (drive, documents, spreadsheets, openid+email). Токен зберігається у нашому persistent volume на сервері (/root/.local/share/fastmcp), нікому не передається, ходить лише до Google API. Ти можеш відкликати дозвіл у будь-який момент через myaccount.google.com/permissions.
▸ Я хочу додати новий тип документа, якого немає у списку 14
Це developer-task. Треба: створити skeleton.gdoc із placeholder'ами (на кшталт {{customer_name}}), написати YAML config з sections-мапінгом, додати unit-test. Покрокова інструкція — tasks/templates-guide.md у репо. Скинь Івану посилання на скелетон + ім'я типу — підключимо за ~30 хв.
▸ Cockpit показує помилки, але вони не критичні
Натисни «Прибрати» — приховаєш назавжди для цього файлу. Або «Відкласти» (3 / 7 / 30 днів) — нагадає пізніше. Перелік активних приховувань видно знизу cockpit-сторінки. Кожен dismiss прив'язаний до трійки doc_id + fail_mode + location — інші документи проєкту не зачіпає.
▸ Що робити, якщо logout не спрацював?
Видали cookie zvitnist_session у DevTools (Application → Cookies → zvitnist.stepanok.com → Delete). Перезавантаж сторінку. Сесія знесена.
▸ Як перевірити, що у Sheet дійсно те, що очікую?
На сторінці «Огляд проєкту» є кнопка «Відкрити Google Sheet» — відкриє безпосередньо твій spreadsheet з трьома вкладками: Matrix (вимоги), Parties (сторони контракту), Alerts (cockpit-приховування). Можеш редагувати напряму в Sheets — наша адмінка одразу побачить зміни при наступному запиті.
▸ Логін висить кілька хвилин — що робити?
Іноді Google OAuth state не підхопиться, якщо ти зайшов через стороннє посилання. Поверни сторінку на /admin/ з адресного рядка, перезавантаж. Якщо знов висить — DevTools → Console — є помилки? — скинь скрін Івану.
▸ Render видає «Ключ meta.X відсутній»
Шаблон вимагає метаполя, яке ти не заповнив у формі. У «Параметри рендеру» розгорни блок і заповни відсутнє поле (підказка скаже точну назву). Найчастіше — year, contract_number, contract_date.
▸ Хто бачить мої документи?
Лише ти. Зmodтенерований .gdoc створюється у твоїй власній Drive-папці проєкту — від твого імені, через твій OAuth-токен. Раccoon Gang-адміни мають доступ тільки якщо ти явно поділишся файлом / папкою.