# БД WatchBody (PostgreSQL)

> Документация БД серверной части — шаг 6 процесса
> (`std1\_process\process.md`), правила d-db (`std1\_rules\d\d-db.md`),
> db-func (`std1\_rules\db\db-func.md`). Решение шага 6 —
> [0-mng\plan.md](../0-mng/plan.md).

## Общие сведения

- **СУБД:** PostgreSQL 17+; доступ — только через хранимые функции
  (`Kit.Helpers\Db.Postgres.SqlServerHelper`, tech-requirements разд. 3).
- **Схемы-слои:** `src` — основные данные (атлеты, тренировки,
  программы, метрики); `ref` — справочники (двигательные группы).
- **Изоляция атлетов (🛡):** каждая таблица данных несёт `athlete_id`;
  все функции слоя `src` принимают `p_athlete_id` и выбирают/пишут
  только в пределах атлета (requirements, Ф-8.5, инвариант раздела 5).
- **Идемпотентность (🛡, Р2-Б):** PK клиентских сущностей — UUID;
  телефон генерирует UUID (строки «только .fit» — сервер), повторная
  вставка с тем же UUID возвращает существующую запись; ссылки дочерних
  записей — те же UUID, маппинг серверных id не нужен.
- **JSON:** версии программ и факты .fit — `jsonb` с проверкой схемы
  на стороне приложения (не в БД).

## Состав

| Файл | Содержание |
|---|---|
| [ref\tables.md](ref/tables.md) | справочники слоя `ref` |
| [src\tables.md](src/tables.md) | таблицы слоя `src` |
| `{слой}\functions.md` | списки функций (после утверждения таблиц) |

## План миграции (d-db-1)

1. Схемы: `CREATE SCHEMA IF NOT EXISTS src; CREATE SCHEMA IF NOT EXISTS ref;`
2. Справочники: `ref\exercise_group.psql` — таблица + вставка 5 значений
   (идемпотентно, `ON CONFLICT (code) DO NOTHING`).
3. Таблицы `src`: порядок — `athlete` → `athlete_profile` → `exercise` →
   `exercise_replacement` → `program` → `program_version` → `workout` →
   `workout_set` → `command_log` → `daily_log` → `workout_metrics` →
   `breaks` (FK-зависимости).
4. Функции: файлы `{слой}\функции.psql` по сущностям в том же порядке
   (`CREATE OR REPLACE` — перезапуск безопасен).
5. Версионирование: каталог `2-db\migrations\` — `NNN_описание.sql`
   по возрастанию; каждая миграция идемпотентна (IF NOT EXISTS /
   OR REPLACE); факт применения — одна запись на файл в
   `src.migration` (id, filename, applied_at).
6. Сборка: скрипт `2-db\build.ps1` применяет миграции по номеру
   (утилита `Server.WatchBody.Import --mode migrate`).

## Таблица `llm_calls` (v2)

Журнал вызовов LLM-планировщика (дизайн LLM-планирования, разд. 8)
создаётся в v2 вместе с `LlmPlanner` — в v1 не проектируется.