1 Загальні положення

1.1. Система призначена для польового збору даних методом очних опитувань із автоматичним контролем доброчесності інтерв'юерів: запис аудіо інтерв'ю, фіксація геолокації, автоматична перевірка голосів (діаризація), вибірковий людський аудит та розрахунок індексу доброчесності.

1.2. Система будується за обласною моделлю (СЗ-081, розд. 2) і складається з двох вебзастосунків:

• Міський вузол — кабінет інтерв'юера (PWA) та панель координатора міста; один сервер на місто;
• Обласний хаб — панель замовника: агрегація міст, діаризація на GPU, черга аудиту, індекси, нагляд за координаторами.

1.3. Технологічний стек, топологія, навантаження і процеси зафіксовані службовою запискою СЗ-081 та в цьому документі не повторюються, окрім місць, де вимога впливає на функціональність.

1.4. Терміни: інтерв'ю — одне опитування одного респондента; зміна — робочий сеанс інтерв'юера від відкриття до закриття; маніфест — пакет метаданих закритої зміни, що передається на хаб; маркер — автоматична позначка підозри; вердикт — рішення аудитора щодо інтерв'ю; індекс доброчесності — розрахунковий показник інтерв'юера (розд. 7); скринінг — запис і перевірка аудіо інтерв'ю; еталон голосу — зразок голосу інтерв'юера, з яким діаризація порівнює голоси в записах.

2 Ролі та розмежування доступу

Роль	Застосунок	Права
Інтерв'юер	PWA вузла	Свої завдання, зміни, інтерв'ю; власна історія, індекс, кількісний облік «до оплати»; подання апеляцій. Не бачить чужих даних
Координатор міста	Панель вузла	Інтерв'юери свого міста, завдання і райони, анкети, зміни, статуси інтерв'ю, керування скринінгом (Д-12), облік «до оплати», журнали міста. Не бачить інших міст
Аудитор	Панель хаба	Черга аудиту по області, картка інтерв'ю, прослуховування (з журналюванням), вердикти, апеляції. Без адміністрування
Оператор замовника	Панель хаба	Дашборди й аналітика області, індекси, звіти нагляду за координаторами, налаштування ваг і порогів, експорти
Адміністратор хаба	Панель хаба	Повний доступ: користувачі всіх ролей, реєстр вузлів, конфігурація, журнали доступу

2.1. Автентифікація всіх ролей: логін + пароль + TOTP. Сесія 30 днів із прив'язкою до пристрою. Для інтерв'юера — одна активна сесія: вхід із нового пристрою блокує попередню сесію, подія фіксується і живить сигнал «передача акаунта» (розд. 7). Зміна пристрою — лише через координатора.

2.2. Кожне прослуховування чи завантаження аудіо будь-якою роллю пишеться в журнал доступу (Додаток А, таблиці access_log).

2.3. Координаторів міських вузлів призначає хаб і керує ними централізовано: створення облікового запису, запрошення (стан «запрошення надіслано»), заміна координатора, скидання пароля і сесії, деактивація. Облікові дані передаються на вузол захищеним каналом обміну; всі дії над обліковими записами координаторів журналюються. На хабі ведеться окремий реєстр координаторів вузлів зі станом облікового запису (Додаток А, розд. 3.1).

3 Кабінет інтерв'юера (PWA міського вузла)

Клієнт — веб-PWA (Vue 3), без мобільного застосунку (рішення Д-13). Верстка адаптивна для трьох класів пристроїв: телефон (первинний), планшет, десктоп — інтерв'юер чи штаб можуть працювати з будь-якого. Екрани — Додаток Б, розд. 2.

3.1 Вхід і пристрій

• Вхід: логін + пароль + TOTP; прив'язка пристрою при першому вході; повторний вхід у межах 30 днів — без пароля (сесія);
• спроба входу при активній сесії на іншому пристрої — відмова з фіксацією події; розблокування — через координатора;
• еталон голосу: при першому вході інтерв'юер начитує контрольний фрагмент (~30 с) — без записаного еталона проведення інтерв'ю недоступне. Еталон передається на хаб, де з нього рахується голосовий відбиток; сирий запис після цього видаляється. Повторний запис еталона — лише через координатора.

3.2 Зміна і завдання

• Відкриття зміни прив'язує інтерв'юера до активного завдання (район на карті: полігон або центр+радіус, квота, анкета);
• керування зміною (відкриття/закриття) — на головному екрані PWA;
• екран зміни показує: район на карті, лічильник інтерв'ю за зміну, статус синхронізації, поточний індекс;
• закриття зміни — явна дія; формує маніфест для хаба. Незакрита зміна закривається автоматично о 24:00 локального часу.

3.3 Проведення інтерв'ю

• підготовка до інтерв'ю (precheck): старт інтерв'ю можливий лише з проміжного екрана «Підготовка до інтерв'ю» — чек-лист готовності (гео в районі, мікрофон, місце на пристрої, стан зміни, активна анкета) та квота зміни; кнопка старту активна лише після проходження всіх перевірок;
• Старт інтерв'ю: перевірка перебування в радіусі завдання (GPS-точка старту зберігається) → позначка згоди респондента (обов'язковий чекбокс) → старт запису аудіо (якщо скринінг увімкнено) з індикацією та Wake Lock;
• екран інтерв'ю бачить респондент: нейтральна шапка (лише назва «Інтерв'ю» — без логотипа, імені інтерв'юера, завдання та службової інформації), без нижньої навігації; екран починається з чекбокса згоди респондента; кнопка завершення (скасування без збереження) — з модальним підтвердженням;
• анкета: питання за версією анкети завдання (типи: один з переліку, кілька з переліку, шкала, число, дата, вільний текст), обов'язковість, логіка переходів;
• фініш: GPS-точка фінішу, зупинка запису, підсумковий екран, постановка пакета в чергу синхронізації;
• переривання (вхідний дзвінок, згортання вкладки, блокування екрана): запис зупиняється, інтерв'ю анулюється з повідомленням «почніть інтерв'ю заново»; збій фіксується у статистиці інтерв'юера;
• чернетка анкети до відправлення живе в localStorage і переживає перезавантаження вкладки; аудіо анульованого інтерв'ю не відправляється.

3.4 Офлайн-робота і синхронізація

• Черга відправлення в IndexedDB: анкета + аудіо + гео; автоматичні повтори з дозавантаженням великих файлів частинами; контроль цілісності хешем;
• анкети відправляються першими (малі), аудіо — слідом; статус кожного пакета видимий інтерв'юеру;
• ліміт офлайн-накопичення — робочий день; при переповненні сховища браузера — блокування нових інтерв'ю з поясненням.

3.5 Історія, індекс, облік

• Історія інтерв'ю зі статусами (у т.ч. вердиктами аудиту) і причинами відхилень;
• апеляція на відхилене інтерв'ю: коментар, статус розгляду;
• екран «Мій індекс»: поточне значення, динаміка, розбір «з чого склалося» без розкриття внутрішніх порогів;
• екран «До оплати»: за періодами — скільки інтерв'ю зараховано, скільки відхилено, коригування минулих періодів. Без сум і ставок;
• повідомлення про нові вердикти, маркери та рішення за апеляціями — лічильник у кабінеті при вході й синхронізації; мобільні push-сповіщення до базового обсягу не входять.

4 Панель координатора міста (міський вузол)

Адмінка на Filament + Vue-сторінки (карта завдань, конструктор анкет). Екрани — Додаток Б, розд. 3.

4.1 Інтерв'юери

• Реєстр: створення, фото профілю (єдине фото в системі, Д-5), статуси (активний / призупинений / відсторонений), скидання сесії та зміна пристрою, дозвіл на повторний запис еталона голосу;
• картка інтерв'юера: індекс із розбором, історія змін і інтерв'ю, статистика збоїв запису, події сесій (спроби паралельного входу), стан скринінгу.

4.2 Завдання і райони

• Створення району на карті: полігон або центр+радіус; прив'язка анкети (конкретної версії), періоду, квоти;
• призначення інтерв'юерів на завдання (окремо чи списком), перепризначення, дострокове закриття;
• карта міста: активні завдання, точки інтерв'ю за день, кластери (кілька інтерв'ю з однієї точки підсвічуються).

4.3 Анкети (конструктор)

• Типи питань за 3.3; обов'язковість, підказки, логіка переходів (показ питання за умовою відповіді);
• версіонування: публікація створює незмінну версію; відповіді завжди прив'язані до версії; правка активної анкети = нова версія; тестове проходження до публікації;
• черга анкет міста: у міста одночасно активна лише одна анкета; решта очікують у черзі з позиціями. Наступна анкета стартує автоматично після настання дедлайну активної або виконання її квоти;
• параметри анкети: дедлайн збору (deadline), позиція в черзі (queue_position), квота (quota_target); статусна модель анкети: чернетка → у черзі → активна → завершена → архів;
• когортні питання: прапорець is_cohort у питання (стать, вікова група тощо) — відповіді використовуються для когортних зрізів статистики; звіти зводяться по анкеті та місту за всіма показниками;
• статистика анкети (агрегати відповідей, когортні зрізи) доступна і під час збору, і після завершення — координатору вузла та хабу (по кожному місту).

4.4 Керування скринінгом (Д-12)

• Вимкнення/увімкнення запису аудіо окремому інтерв'юеру або масовою вибіркою (фільтр за індексом, стажем, кількістю перевірених інтерв'ю);
• кожна дія вимагає підстави (вибір із довідника + коментар) і зберігається в історії;
• стан скринінгу і підстави автоматично реплікуються на хаб; контрольні тимчасові увімкнення за командою хаба виконуються автоматично.

4.5 Інтерв'ю і статуси

• Реєстр інтерв'ю міста: фільтри за статусом, інтерв'юером, завданням, датою, маркерами; перегляд анкети, треку старт/фініш на карті, сигналів;
• прослуховування аудіо (в межах 3-денного вікна) — з фіксацією в журналі доступу;
• статусна модель інтерв'ю: записано → завантажено → сигнали → у маніфесті → діаризовано → маркери → вердикт (зараховано/відхилено) / анульовано; інтерв'ю з вимкненим скринінгом минають крок діаризації зі статусом без аудіо-перевірки — решта перевірок і облік працюють як звичайно.

4.6 Облік «до оплати»

• Розрахункові періоди (місяць або півмісяця): підсумок за кожним інтерв'юером — зараховано, відхилено, коригування минулих періодів, разом «до оплати» (кількість);
• закритий період незмінний; пізні вердикти творять коригувальні рядки наступного періоду; експорт CSV/XLSX. Ставок і сум у системі немає.

5 Панель замовника (обласний хаб)

Адмінка на Filament + Vue-сторінки (картка аудиту, дашборд області, звіт нагляду). Екрани — Додаток Б, розд. 4.

5.1 Дашборд області та міста

• KPI: інтерв'ю за день/тиждень, активні інтерв'юери, частка перевірених, частка відхилених, глибина черги аудиту, стан вузлів;
• розріз за містами: динаміка, порівняння, топ підозрілих інтерв'юерів за маркерами.

5.2 Реєстр вузлів (міст)

• Реєстрація міського вузла: генерація ключів WireGuard і service-токенів, версія протоколу, перевірка зв'язку;
• стан кожного вузла: онлайн/офлайн, відставання маніфестів, черга забирання аудіо, вільний диск, версія;
• керування координаторами вузлів (п. 2.3): створення облікового запису, запрошення, заміна, скидання пароля і сесії, деактивація; стан облікового запису кожного координатора видимий у реєстрі.

5.3 Черга аудиту і картка інтерв'ю

• Черга з пріоритетом за маркерами + випадкова добавка для базової лінії; взяття в роботу закріплює картку за аудитором;
• картка інтерв'ю: плеєр-хвиля (стрім із вузла), маркери з поясненнями, сигнали з внесками, карта старт/фініш, анкета з відповідями, історія інтерв'юера;
• вердикт: зараховано / відхилено (причина з довідника + коментар); ескалація старшому аудитору; розгляд апеляцій;
• вікно прослуховування — 3 доби після діаризації; флаговані записи не видаляються до вердикта (Д-10).

5.4 Індекси і налаштування

• Реєстр індексів доброчесності по області з розбором; історія перерахунків;
• налаштування ваг і порогів сигналів (розд. 7) з історією змін і застосуванням «від дати» — минулі значення не переписуються.

5.5 Нагляд за координаторами (Д-12, Д-10)

• Звіт по кожному місту: скільки інтерв'юерів зі скринінгом/без, кожне вимкнення з підставою і статистичною довідкою (чи була в інтерв'юера достатня історія перевірок);
• маркери координатору: «вимкнення без статистики», «місто не встигає з чергою», «аномалія вердиктів»; статуси реагування;
• кнопка «контрольне увімкнення»: тимчасово повертає скринінг випадковій частці довірених інтерв'юерів міста.

5.6 Аналітика й експорти

• Зведення за періодами: місто/завдання/інтерв'юер; експорт результатів опитувань CSV/XLSX; вивантаження анкетних даних без персональних даних респондентів;
• статистика анкет по кожному місту: агрегати відповідей і когортні зрізи (п. 4.3) — і під час збору, і після завершення анкети; черги анкет міст видимі хабу.

6 Обласний обмін (протокол вузол ↔ хаб)

• Транспорт: REST + JSON, підписані service-токени, лише через WireGuard; жоден службовий ендпойнт не доступний з інтернету;
• ідемпотентність: усі повідомлення мають UUID; повторна доставка не створює дублікатів;
• черги і ретраї з обох боків: недоступність контрагента не втрачає даних, лише затримує;
• версія протоколу в кожному запиті; хаб приймає версії N та N−1 (пакет packages/protocol);
• інтерв'ю з вимкненим скринінгом проходять той самий цикл без кроків 02–04 (статус skipped_screening_off);
• окремими повідомленнями обміну передаються: стан скринінгу з підставами (вузол → хаб), еталонні записи голосу інтерв'юерів (вузол → хаб), апеляції та рішення за ними, команди контрольного увімкнення скринінгу (хаб → вузол), позначки hold для флагованих записів (хаб → вузол).

7 Індекс доброчесності

7.1. Склад сигналів — за СЗ-081 розд. 4.4: геолокація (старт/фініш у радіусі, час, швидкість між інтерв'ю, кластеризація), темп роботи (верхній поріг — підозра фабрикації; нижній — показник неефективності), діаризація (кількість голосів, збіг другого голосу з інтерв'юером, повторюваність «респондента» за 30 днів у розрізах інтерв'юер/місто/область), дешеві аудіо-сигнали (тиша, VAD, гучність, кліпінг, фінгерпринт-дублі), акаунт і сесії (паралельні входи, зміни пристроїв, паралельні інтерв'ю з різних точок), стабільність запису (частота переривань), вердикти аудиту.

7.2. Розрахунок: кожен сигнал → нормоване значення 0…1 → зважена сума за групами → бал інтерв'ю (0–100); індекс інтерв'юера — агрегат балів інтерв'ю за ковзний період з урахуванням вердиктів. Ваги, пороги і період — налаштовувані (5.4), з історією.

7.3. Пояснюваність: для кожного балу зберігається розбір (сигнал → значення → внесок). Розбір бачать аудитор і координатор повністю, інтерв'юер — у спрощеному вигляді без порогів.

7.4. Автоматичні дії за порогами (налаштовуються): підняття пріоритету в черзі аудиту; примусове увімкнення скринінгу; тимчасове призупинення інтерв'юера — лише вручну координатором.

8 Нефункціональні вимоги

Вимога	Значення
Продуктивність вузла	До 5 000 інтерв'ю/день, 25 rps пік API; прийом аудіо ~12,5 ГБ/день без деградації інтерфейсів
Продуктивність хаба	До 20 000 інтерв'ю/день на одну GPU; черга діаризації розбирається за добу з запасом
Retention аудіо	3 доби після діаризації; флаговані — до вердикта; видалення журналюється
Retention відбитків	90 днів (Д-11), автоочищення
Доступність	Вузли автономні при недоступності хаба; PWA працює офлайн у межах робочого дня
Безпека	TOTP для всіх ролей; одна сесія інтерв'юера; WireGuard для службового трафіку; Cloudflare + Zero Trust на адмінки; журнал доступу до записів
Персональні дані	Закон України «Про захист персональних даних»: згода-позначка, мінімізація (3 доби аудіо), необоротні відбитки, журнал доступу
Бекапи	БД: WAL щогодини + повний дамп щоночі → Storage VPS (офсайт); перевірка відновлення за регламентом. Аудіо не бекапиться
Моніторинг	Черги, диски, канал, GPU, глибина черги аудиту, статуси вузлів; сповіщення в месенджер
Мови інтерфейсів	Українська (єдина)
Сумісність PWA	Телефон, планшет, десктоп. Chrome/Safari/Edge поточної та попередньої мажорної версії; робота при нестабільному 3G/4G; без горизонтального скролу на всіх ширинах

9 Етапи реалізації та приймання

Етап	Зміст	Критерій приймання
1. Фундамент	Монорепозиторій, dev-оточення, каркаси node/hub, автентифікація з TOTP і сесіями, протокол обміну v1	Зміна закривається на вузлі — маніфест видимий на хабі
2. Капчур	PWA: зміни, інтерв'ю, запис аудіо, гео старт/фініш, офлайн-черга, переривання; прийом і сигнали рівня 0 на вузлі	Інтерв'ю з вулиці з реальним аудіо і гео доходить до вузла при нестабільному звʼязку
3. Діаризація	GPU-воркер, забирання аудіо, відбитки, звірка, маркери, індекс; налаштування ваг	Пілотний пакет реальних записів UK/RU розмічається з узгодженою точністю; пороги зафіксовані
4. Аудит і панелі	Черга аудиту, картка інтерв'ю, вердикти, апеляції; панелі координатора і замовника; нагляд за координаторами; облік «до оплати»	Наскрізний цикл: інтерв'ю → маркер → вердикт → статус у кабінеті інтерв'юера → період «до оплати»
5. Пілот	Два VPS HostPro + Storage VPS, реальне місто 20–50 інтерв'юерів, калібрування, навчання ролей	2 тижні бойової роботи пілота; метрики точності та стабільності в межах узгоджених
6. Бойовий контур	Фізичний хаб із GPU, розгортання міст, міграція пілотних даних, runbook, передача	Нове місто розгортається за процедурою ≤ 1 години; приймальні навчання (світло/канал/відновлення)

Строки та вартість етапів — предмет комерційної пропозиції; у ТЗ не фіксуються.

10 Склад документації

Документ	Зміст
СЗ-081	Архітектура та оточення (затверджена) — fieldcontrol-arch (index.html / architecture.pdf)
ТЗ-081	Цей документ — fieldcontrol-docs (tz.html / .pdf)
Додаток А	Модель даних: усі таблиці та поля БД вузла і хаба — tz-dodatok-a.html / .pdf
Додаток Б	Візуальні вимоги: перелік екранів кожної панелі, склад елементів, посилання на макети — tz-dodatok-b.html / .pdf
Макети	HTML-макети панелей на fieldcontrol-demo (demo/pwa · demo/node · demo/hub; виконуються після затвердження ТЗ)