VEU.WathBody/1-docs/2-db/src/functions.md

Слой src — список функций

Список функций слоя src; формат — d-db-7 (std1\_rules\d\d-db.md), статусная модель — d-dev-1..3 (std1\_rules\d\d-dev.md). Таблицы — tables.md (утверждены 2026-10-17). 🛡 Во всех функциях p_athlete_id обязателен (кроме athlete_* — они для сервисов владельца): изоляция атлетов. Статусы: PLAN — только в списке (спецификаций и кода нет). УТВЕРЖДЕНО (2026-10-17) — список функций к реализации утверждён. Новая редакция (2026-10-17): + breaks (break_insert/update/select), session_kind в workout_insert/update — интеграция документа перерывов (Ф-14, изменение vision 1.4). Ревью №2 (2026-10-17): возвраты insert-функций uuid-сущностей — uuid, FK-параметры — uuid (З-16); break_insert/break_update — p_planned_return, break_update принимает ответ атлета (З-17);

• migration_insert/migration_select (З-25). УТВЕРЖДЕНО (2026-10-17). Ревью №3: p_external_id в program_insert/program_version_insert, комментарий workout_insert (З-31, З-34) — УТВЕРЖДЕНО (2026-10-17).

Список функций

Сущность	Функция	Статус	Параметры	Возвращает	Функция	Репозиторий	Комментарий
athlete	athlete_insert	DONE	p_name, p_api_key_hash	int — id атлета	DONE	CODE	AdminWeb; дубликаты hash — исключение UNIQUE
athlete	athlete_update	DONE	p_id, p_name, p_api_key_hash, p_is_blocked	int — число строк	DONE	CODE	NULL-семантики нет (db-m-8)
athlete	athlete_select	DONE	p_api_key_hash, p_is_blocked	TABLE — строки athlete	DONE	CODE	фильтры: NULL = без фильтра; для middleware и AdminWeb
athlete	athlete_get	DONE	p_id	TABLE — одна строка	DONE	CODE	—
athlete_profile	athlete_profile_upsert	DONE	p_athlete_id, p_sex, p_birth_year, p_weight_kg, p_hr_max	int — id	DONE	CODE	1:1 — ON CONFLICT (athlete_id) DO UPDATE
athlete_profile	athlete_profile_get	DONE	p_athlete_id	TABLE — одна строка	DONE	CODE	—
exercise	exercise_insert	DONE	p_athlete_id, p_id (uuid), p_name, p_group_id, p_is_base	uuid — id упражнения	DONE	CODE	дубликат имени у атлета — исключение UNIQUE
exercise	exercise_update	DONE	p_athlete_id, p_id, p_name, p_group_id, p_is_base	int — число строк	DONE	CODE	exercise_id не меняется (Ф-4.3, 🛡)
exercise	exercise_delete	DONE	p_athlete_id, p_id	int — число строк	DONE	CODE	логическое: is_active=false (Ф-4.2)
exercise	exercise_select	DONE	p_athlete_id, p_name, p_group_id, p_is_base, p_is_active	TABLE — строки + пары замен (MM)	DONE	CODE	по умолчанию только is_active; замены — денормализация (d-db-3)
exercise	exercise_get	DONE	p_athlete_id, p_id	TABLE — одна строка + замены	DONE	CODE	—
exercise_replacement	exercise_replacement_insert	DONE	p_athlete_id, p_exercise_id, p_replacement_id	int — число строк	DONE	CODE	оба упражнения — атлета, группа равна (проверка в функции)
exercise_replacement	exercise_replacement_delete	DONE	p_athlete_id, p_exercise_id, p_replacement_id	int — число строк	DONE	CODE	—
program	program_insert	DONE	p_athlete_id, p_title, p_external_id	int — id программы	DONE	CODE	вторая программа атлета — исключение UNIQUE; p_external_id — идентификатор пакета (program-import.json, З-31)
program	program_select	DONE	p_athlete_id	TABLE — строки + активная версия	DONE	CODE	денормализация активной версии (d-db-3)
program	program_get	DONE	p_athlete_id, p_program_id	TABLE — одна строка	DONE	CODE	—
program_version	program_version_insert	DONE	p_athlete_id, p_id (uuid), p_program_id, p_based_on_version, p_author, p_body, p_rationale	uuid — id версии	DONE	CODE	импорт пакета: повтор p_external_id → новая версия; version = max+1; status='draft'; body — jsonb (параметр text, errata m02); 🛡 идемпотентность по p_id (errata m02)
program_version	program_version_update	DONE	p_athlete_id, p_id, p_status	int — число строк	DONE	CODE	🛡 меняется только статус; переходы draft→active→archived; активной становится ровно одна (сдвиг прежней в archived)
program_version	program_version_select	DONE	p_athlete_id, p_program_id, p_status, p_author	TABLE — строки (без body)	DONE	CODE	body — отдельным get (крупный jsonb)
program_version	program_version_get	DONE	p_athlete_id, p_id	TABLE — одна строка с body	DONE	CODE	—
workout	workout_insert	DONE	p_athlete_id, p_id (uuid), p_program_version_id, p_started_at, p_session_kind	uuid — id	DONE	CODE	повтор p_id (uuid — PK клиентской сущности, генерирует телефон) возвращает существующий id (🛡 идемпотентность)
workout	workout_update	DONE	p_athlete_id, p_id, p_ended_at, p_status, p_session_kind, p_avg_hr, p_facts_json, p_fit_file_id, p_hr_recovery_s	int — число строк	DONE	CODE	факты .fit дописывает FitParser; клиент — только ended/status/session_kind/avg_hr
workout	workout_select	DONE	p_athlete_id, p_status, p_date_from, p_date_to	TABLE — карточки + подходы (агрегат jsonb)	DONE	CODE	мультикурсор/агрегат: карточка + sets (d-db-6)
workout	workout_get	DONE	p_athlete_id, p_id	TABLE — одна строка + sets + command_log	DONE	CODE	полная карточка (Ф-9.2)
workout_set	workout_set_insert	DONE	p_athlete_id, p_id (uuid), p_workout_id, p_exercise_id, p_seq, p_weight_kg, p_reps, p_done_at, p_source, p_in_plan, p_rpe, p_knee_pain	uuid — id	DONE	CODE	идемпотентность по PK uuid (Р2-Б)
workout_set	workout_set_get	DONE	p_athlete_id, p_id	TABLE — одна строка	DONE	CODE	—
command_log	command_log_insert	DONE	p_athlete_id, p_id (uuid), p_workout_id, p_t_offset_s, p_recognized_text, p_semantics, p_accepted	uuid — id	DONE	CODE	🛡 не редактируется (Ф-1.5)
command_log	command_log_select	DONE	p_athlete_id, p_workout_id	TABLE — строки	DONE	CODE	для сопоставления с .fit
daily_log	daily_log_upsert	DONE	p_athlete_id, p_id (uuid), p_date, p_bp_sys, p_bp_dias, p_weight_kg, p_hr_resting, p_wellbeing	uuid — id	DONE	CODE	UNIQUE(athlete_id, date) — upsert; hr_resting/wellbeing — поля v1 (Р1-А)
daily_log	daily_log_select	DONE	p_athlete_id, p_date_from, p_date_to	TABLE — строки	DONE	CODE	для сводки метрик и AdminWeb
workout_metrics	workout_metrics_upsert	DONE	p_athlete_id, p_workout_id, p_adherence, p_tonnage, p_tonnage_by_group, p_e1pm_by_exercise, p_hr_metrics, p_red_flags	int — id	DONE	CODE	1:1, пересчёт MetricsEngine
workout_metrics	workout_metrics_select	DONE	p_athlete_id, p_workout_id, p_date_from, p_date_to	TABLE — строки	DONE	CODE	графики AdminWeb (Ф-9.4)
breaks	break_insert	DONE	p_athlete_id, p_id (uuid), p_kind, p_source, p_started_on, p_planned_return, p_note	uuid — id	DONE	CODE	auto — сервер по пропускам (Ф-14.1); manual — телефон, объявление простоя заранее (Ф-14.2)
breaks	break_update	DONE	p_athlete_id, p_id, p_kind, p_note, p_planned_return, p_ended_on	int — число строк	DONE	CODE	ответ атлета на вопрос о причине (Ф-14.2) + закрытие первой сессией после возврата
breaks	break_select	DONE	p_athlete_id, p_kind, p_date_from, p_date_to	TABLE — строки	DONE	CODE	журнал перерывов; CSV-выгрузка (документ перерывов разд. 4)
migration	migration_insert	DONE	p_filename	int — id	DONE	CODE	журнал миграций (d-db-1); пишет --mode migrate
migration	migration_select	DONE	p_filename	TABLE — одна строка	DONE	CODE	проверка «применена ли миграция»