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

> Список функций слоя `src`; формат — d-db-7 (`std1\_rules\d\d-db.md`),
> статусная модель — d-dev-1..3 (`std1\_rules\d\d-dev.md`).
> Таблицы — [tables.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 | проверка «применена ли миграция» |