1 Загальні конвенції

• Первинні ключі: id BIGSERIAL; інтерв'ю та повідомлення обміну — uuid (глобальна ідемпотентність);
• грошових полів у системі немає (облік «до оплати» — лише кількість);
• таблиці з позначкою парт. партиціонуються за місяцями (created_at);
• enum-поля реалізуються як VARCHAR + CHECK-констрейнт; значення наведені в описі;
• гео-поля: geometry(Point,4326) / geometry(Polygon,4326) (PostGIS, лише вузол);
• час — timestamptz, зона вузла — локальна для міста, зона хаба — Києва.

2 База міського вузла

2.1 Користувачі та доступ

Поле	Тип	Опис
id	bigserial PK
role	varchar	interviewer | coordinator
full_name	varchar(160)	ПІБ
phone	varchar(20)	контактний, унікальний
login	varchar(60)	унікальний
password_hash	varchar	bcrypt/argon2
totp_secret	varchar, encrypted	секрет 2FA
photo_path	varchar, null	фото профілю (Д-5 — єдине фото в системі)
status	varchar	active | suspended | dismissed
voice_ref_recorded_at	timestamptz, null	еталон голосу записано і передано на хаб; null = інтерв'ю недоступні
integrity_index	numeric(5,2), null	кешоване значення індексу (джерело істини — хаб)
index_breakdown	jsonb, null	спрощений розбір для кабінету

Обліковий запис координатора міста створюється і керується хабом (ТЗ, п. 2.3): запрошення, заміна, скидання пароля і сесії, деактивація. Облікові дані передаються на вузол захищеним каналом обміну; всі дії журналюються.

Поле	Тип	Опис
id	bigserial PK
user_id	FK users
fingerprint	varchar(128)	відбиток браузера/пристрою
platform / user_agent	varchar	ОС, браузер
status	varchar	active | revoked; активний — один на інтерв'юера
first_seen_at / last_seen_at	timestamptz

Поле	Тип	Опис
id	bigserial PK
user_id / device_id	FK
token_hash	varchar
ip	inet
started_at / last_activity_at / expires_at	timestamptz	строк 30 днів
revoked_at / revoke_reason	timestamptz / varchar, null	parallel_login | coordinator | expired

Поле	Тип	Опис
id	bigserial PK
user_id	FK users
type	varchar	login | login_denied_parallel | device_change | session_revoked
device_fingerprint / ip	varchar / inet
geo	geometry(Point), null	де відбулася спроба (якщо надано)
details	jsonb

Поле	Тип	Опис
id	bigserial PK
actor_type / actor_id	varchar / bigint	node_user | hub_user (через обмін)
action	varchar	listen | download | delete
interview_uuid	uuid
ip	inet, null

2.2 Анкети

Поле	Тип	Опис
id	bigserial PK
title	varchar(200)
status	varchar	draft | queued | active | completed | archived; активна — лише одна на місто (частковий унікальний індекс)
deadline	timestamptz, null	дедлайн збору активної анкети
queue_position	int, null	позиція в черзі міста (для queued)
quota_target	int, null	квота інтерв'ю анкети
created_by	FK users

У міста одночасно активна лише одна анкета; решта очікують у черзі за queue_position. Наступна анкета стартує автоматично після настання deadline активної або виконання quota_target; перехід статусів журналюється. Статистика анкети (агрегати відповідей, когортні зрізи за is_cohort-питаннями) доступна і під час збору, і після завершення — координатору вузла та хабу.

Поле	Тип	Опис
id	bigserial PK
questionnaire_id	FK
version	int	інкремент у межах анкети
published_at	timestamptz, null	null = чернетка
published_by	FK users, null

Поле	Тип	Опис
id	bigserial PK
version_id	FK questionnaire_versions
position	int	порядок
type	varchar	single | multi | scale | number | date | text
text	text	формулювання
hint	text, null	підказка інтерв'юеру
required	bool
is_cohort	bool	когортне питання (стать, вікова група тощо) — відповіді формують когортні зрізи статистики анкети
config	jsonb	межі шкали/числа, маски
logic	jsonb, null	умови показу (залежність від відповідей)

Поле	Тип	Опис
id	bigserial PK
question_id	FK questions
position	int
label	varchar(300)
is_other	bool	варіант «інше» з вільним полем

2.3 Завдання, зміни, інтерв'ю

Поле	Тип	Опис
id	bigserial PK
name	varchar(160)
kind	varchar	polygon | radius
geom	geometry(Polygon), null	для polygon
center / radius_m	geometry(Point) / int, null	для radius
created_by	FK users

Поле	Тип	Опис
id	bigserial PK
district_id	FK districts
questionnaire_version_id	FK	конкретна версія анкети
date_from / date_to	date	період
quota	int, null	цільова кількість інтерв'ю
status	varchar	planned | active | closed
created_by	FK users

Поле	Тип	Опис
assignment_id / user_id	FK, разом PK
assigned_by / assigned_at	FK users / timestamptz
revoked_at	timestamptz, null	перепризначення

Поле	Тип	Опис
id	bigserial PK
user_id / assignment_id	FK
started_at / closed_at	timestamptz
close_type	varchar	manual | auto_midnight
interviews_count	int	кеш
manifest_uuid	uuid, null	посилання на відправлений маніфест
status	varchar	open | closed | manifested | acked

Поле	Тип	Опис
uuid	uuid PK	глобальний ідентифікатор (той самий на хабі)
shift_id / user_id / assignment_id	FK
questionnaire_version_id	FK
respondent_consent	bool	позначка згоди (обов'язкова для старту)
started_at / finished_at	timestamptz
duration_sec	int
geo_start / geo_finish	geometry(Point)	точки старту і фінішу
geo_start_acc / geo_finish_acc	int	точність, м
geo_start_in_zone / geo_finish_in_zone	bool	результат радіус-чеку
audio_uuid	uuid, null	FK media_files; null = скринінг вимкнено
status	varchar	recorded | uploaded | signals_done | manifested | diarized | skipped_screening_off | marked | accepted | rejected | annulled
abort_reason	varchar, null	call | minimized | screen_lock | manual
prelim_score / final_score	numeric(5,2), null	бал вузла / бал хаба

Поле	Тип	Опис
id	bigserial PK
interview_uuid	uuid FK
question_id	FK questions
value	jsonb	значення будь-якого типу питання (обрані опції, число, текст)
answered_at	timestamptz	для аналізу темпу заповнення

Поле	Тип	Опис
uuid	uuid PK
interview_uuid	uuid FK
path	varchar	шлях на диску вузла
size_bytes / duration_sec	bigint / int
codec	varchar	opus/webm
sha256	char(64)	контроль цілісності
uploaded_at	timestamptz
diarized_at	timestamptz, null	ack хаба; старт 3-денного відліку
hold	bool	флагований — не видаляти до вердикта (Д-10)
delete_after	date, null	diarized_at + 3 доби
deleted_at	timestamptz, null	факт видалення (журналюється)

2.4 Сигнали, скринінг, обмін, облік

Поле	Тип	Опис
id	bigserial PK
interview_uuid	uuid FK, null	null для сигналів рівня інтерв'юера (темп, сесії)
user_id	FK users
type	varchar	silence_ratio | vad_ratio | volume_low | clipping | fingerprint_dup | geo_out_start | geo_out_finish | speed_anomaly | cluster_point | tempo_high | tempo_low | parallel_session | record_abort
value_num	numeric, null	нормоване значення
details	jsonb	сирі дані розрахунку
computed_at	timestamptz

Поле	Тип	Опис
user_id	FK users, PK
audio_enabled	bool	false = довірений, аудіо не пишеться
changed_by	FK users	координатор
reason_code	varchar	trusted_by_stats | control_reenable | forced_by_hub | manual
reason_comment	text, null
stats_snapshot	jsonb	статистична довідка на момент рішення (перевірених інтерв'ю, індекс, маркери)
changed_at	timestamptz

Історія змін — таблиця screening_history з тими самими полями + id; кожна зміна стану реплікується на хаб.

Поле	Тип	Опис
uuid	uuid PK	ідемпотентність доставки
type	varchar	manifest | screening_state | appeal | voice_reference | ack
payload	jsonb
status	varchar	pending | sent | acked | failed
attempts / last_attempt_at / last_error	int / timestamptz / text	ретраї з бекофом

Поле	Тип	Опис
id	bigserial PK
interview_uuid	uuid FK
marker_type / severity	varchar / smallint	тип і вага (довідник хаба)
payload	jsonb	пояснення для координатора
received_at	timestamptz

Поле	Тип	Опис
interview_uuid	uuid PK
verdict	varchar	accepted | rejected
reason_code / comment	varchar / text, null
received_at	timestamptz	визначає період обліку коригувань

Поле	Тип	Опис
id	bigserial PK
interview_uuid / user_id	uuid FK / FK users
message	text
status	varchar	open | in_review | upheld | declined
resolved_at	timestamptz, null	рішення приходить пушем із хаба

Поле	Тип	Опис
id	bigserial PK
period_start / period_end	date
status	varchar	open | closed; закритий незмінний
closed_by / closed_at	FK users / timestamptz, null

Поле	Тип	Опис
id	bigserial PK
period_id / user_id	FK
accepted_count / rejected_count	int	за період
correction_count	int	± коригування за вердикти після закриття минулих періодів
payable_count	int	accepted + correction
details	jsonb	перелік interview_uuid коригувань

Ключі: пороги темпу, ліміти офлайн-черги, retention (3 доби), адреса хаба, версія протоколу. Аналогічна таблиця на хабі.

3 База обласного хаба

3.1 Реєстр вузлів і користувачі

Поле	Тип	Опис
id	bigserial PK
name	varchar(120)	місто
wg_address	inet	адреса у WireGuard-мережі
wg_public_key	varchar
api_token_hash	varchar	service-токен вузла, ротований
protocol_version	smallint	хаб приймає N і N−1
status	varchar	online | offline | disabled
last_seen_at / registered_at	timestamptz
health	jsonb	диск, черги, відставання (з моніторингу)

Поле	Тип	Опис
id	bigserial PK
role	varchar	admin | operator | auditor
full_name / login / password_hash / totp_secret	varchar	як у вузла
status	varchar	active | suspended

Таблиці devices, sessions, access_log хаба — ідентичні вузловим (розд. 2.1) і тут не повторюються.

Поле	Тип	Опис
id	bigserial PK
node_id	FK nodes
coordinator_ref	bigint, null	id користувача-координатора на вузлі (після активації)
full_name / phone	varchar
account_state	varchar	invited (запрошення надіслано) | active | replaced | deactivated
invited_at / activated_at / deactivated_at	timestamptz, null
managed_by	FK hub_users	хто виконав останню дію

Дії хаба над координаторами (створення облікового запису, запрошення, заміна, скидання пароля і сесії, деактивація) передаються на вузол командами обміну захищеним каналом і журналюються з обох боків.

3.2 Обмін і реєстр інтерв'ю

Поле	Тип	Опис
uuid	uuid PK	з вузла, ідемпотентність
node_id	FK nodes
shift_ref / interviewer_ref	bigint	id зміни та інтерв'юера на вузлі
interviews_count	int
payload	jsonb	метадані і сигнали вузла за кожним інтерв'ю
received_at / processed_at	timestamptz
status	varchar	received | queued | done

Поле	Тип	Опис
uuid	uuid PK	= uuid інтерв'ю на вузлі
node_id / manifest_uuid	FK
interviewer_ref	bigint	id інтерв'юера на вузлі
meta	jsonb	тривалість, гео-флаги, темп, сигнали вузла
audio_state	varchar	pending | fetching | diarized | skipped_screening_off | failed
score	numeric(5,2), null	підсумковий бал інтерв'ю
score_breakdown	jsonb, null	сигнал → значення → внесок
audit_state	varchar	none | queued | in_review | accepted | rejected

Поле	Тип	Опис
id	bigserial PK
interview_uuid	uuid FK registry
priority	smallint	вище — раніше (за сигналами вузла)
status	varchar	queued | fetching | done | failed
attempts / last_error	int / text

3.3 Діаризація і голосові відбитки

Поле	Тип	Опис
interview_uuid	uuid PK
voices_count	smallint	у проаналізованому вікні
window_sec	smallint	фактична довжина вікна (30–90)
net_second_voice_sec	numeric(5,1)	чистої речі другого голосу
second_voice_confirmed	bool, null	null = не набралося мовлення
similarity_to_interviewer	numeric(4,3), null	другий голос ≈ інтерв'юер → фейк «на два голоси»
gpu_ms	int	метрика продуктивності
details	jsonb	сегменти, впевненості

Поле	Тип	Опис
id	bigserial PK
interview_uuid	uuid FK, null	null для еталона інтерв'юера
node_id / interviewer_ref	FK / bigint
kind	varchar	respondent | interviewer_reference
embedding	vector(256)	pgvector, необоротний
expires_at	timestamptz	created_at + 90 днів; еталони — без строку

Еталон (kind = interviewer_reference) рахується з контрольного фрагмента ~30 с, який інтерв'юер начитує при першому вході в PWA (ТЗ, п. 3.1); сирий аудіозапис еталона після розрахунку відбитка видаляється. Повторний запис — через координатора (нова версія еталона замінює стару).

Поле	Тип	Опис
id	bigserial PK
voiceprint_id / matched_id	FK voiceprints	пара
similarity	numeric(4,3)	косинусна близькість
scope	varchar	same_interviewer | same_city | oblast

3.4 Скоринг, аудит, нагляд

Поле	Тип	Опис
key	varchar PK	тип сигналу (довідник розд. 2.4 + голосові)
group_name	varchar	гео / темп / голос / аудіо / сесії / стабільність / вердикти
weight	numeric(4,3)
thresholds	jsonb	нормування значення
active	bool
effective_from / updated_by	timestamptz / FK hub_users	застосування «від дати», минуле не переписується

Поле	Тип	Опис
node_id / interviewer_ref	разом PK
value	numeric(5,2)	0–100
breakdown	jsonb	групи → внески
interviews_window	int	кількість інтерв'ю у ковзному періоді
computed_at	timestamptz

Поле	Тип	Опис
id	bigserial PK
interview_uuid	uuid FK registry
reason	varchar	marker | random | appeal | control
priority	smallint
status	varchar	pending | in_review | done | expired_audio
assigned_to / taken_at	FK hub_users / timestamptz, null	закріплення за аудитором
audio_deadline	timestamptz, null	кінець 3-денного вікна прослуховування

Поле	Тип	Опис
interview_uuid	uuid PK
auditor_id	FK hub_users
verdict	varchar	accepted | rejected
reason_code / comment	varchar / text, null	довідник причин відхилення
listened_sec	int	скільки реально прослухано (контроль якості аудиту)
pushed_at	timestamptz, null	доставлено вузлу

Поле	Тип	Опис
uuid	uuid PK	з вузла
interview_uuid / node_id	FK
message	text
status	varchar	open | in_review | upheld | declined
resolved_by / resolution_comment	FK hub_users / text, null

Поле	Тип	Опис
node_id / interviewer_ref	разом PK
audio_enabled	bool
reason_code / stats_snapshot	varchar / jsonb	реплікація з вузла
assessed	varchar, null	оцінка хаба: justified | no_stats | bad_stats
changed_at / synced_at	timestamptz

Поле	Тип	Опис
id	bigserial PK
node_id / coordinator_ref	FK / bigint, null
type	varchar	screening_no_stats | screening_bad_stats | audit_queue_lag | verdict_anomaly
severity	smallint
payload	jsonb	обґрунтування, цифри
status	varchar	open | acknowledged | closed

Поле	Тип	Опис
id	bigserial PK
scope / scope_id	varchar / bigint	oblast | node | interviewer
date	date
metrics	jsonb	інтерв'ю, перевірено, відхилено, середній бал, збої, черга

4 Довідники

• Причини відхилення інтерв'ю (вердикти): немає другого голосу; голос збігається з інтерв'юером; повторюваний респондент; поза районом; фабрикація темпу; дубль запису; порушення згоди; інше (коментар обов'язковий);
• Підстави зміни скринінгу: довірений за статистикою; контрольне увімкнення; примусово хабом; вручну (коментар);
• Типи маркерів — збігаються з типами сигналів (розд. 2.4 + голосові: no_second_voice, self_dialogue, repeat_respondent_interviewer, repeat_respondent_city, repeat_respondent_oblast, second_voice_unconfirmed).