# Ревью документации от 2026-10-17 — задания к исполнению

> **Исполнитель:** агент сопровождения документации WatchBody.
> **Источник:** архитектурная проверка документации шагов 1–6 на соответствие
> канону std1 (`I:\Kit\Kit.DevAi\std1`: процесс `_process\process.md`, правила
> `_rules\d\d-db.md`, `d-dev.md`, `d-req.md`, `d-drg.md`, `_rules\glossary.md`)
> и исходной задаче (`Техническое задание.md`, `Требование.md`, документы
> «Метрики…», «Архитектура LLM…», «Форматы…»).
> **Состояние репозитория на момент проверки:** коммит `0554f17`, все ссылки
> на строки даны по нему; после правок ориентироваться по разделам, а не строкам.
> **Статусная модель заданий:** ⬜ не начато → 🔄 в работе → ✅ готово
> (утверждено владельцем). Отметки проставляются в разделе 6 по мере работы.
> **Общие правила исполнения:**
> 1. Правки вносятся новыми версиями утверждённых документов (перечень версий —
>    раздел 5). Каждая новая версия — точка утверждения **Пользователь!** (d-dev-4).
> 2. Содержание утверждённых документов меняется только в объёме заданий;
>    инварианты 🛡 не ослабляются; трассировка «Ф → БЦ → КУ → версия» (раздел 6
>    requirements) сохраняется.
> 3. Задания, зависящие от решений Р1–Р3 (раздел 1), не вносятся до выбора
>    владельцем. Остальные можно выполнять сразу.
> 4. Код (`3-app\`, `2-db\`) не трогается — задание касается только `1-docs\`
>    и корневого `readme.md`.
> 5. ~~Push не выполняется (учётные данные remote не настроены)~~ — уточнение
>    исполнителя 2026-10-17: push настроен и работает (credentials в
>    Credential Manager); коммиты пушатся после каждой волны.

## 0. Сводка ревью

Документация в целом соответствует std1 и исходной задаче: шаги 1–6 пройдены
с точками утверждения, все 9 позиций MVP ТЗ покрыты (Ф-1–Ф-9), трассировка
полная, стеки соответствуют `Требование.md`, решения LLM-дизайна и документа
метрик перенесены. Найдено: **4 существенных дефекта (P1)** — два логических
противоречия «v1-требования ↔ v1-данные», неактуальная архитектура после
изменения 1.3 и разрыв схемы синхронизации; **4 средних (P2)**; **7 мелких
(P3, гигиена)**. Позиции внедрения MVP документа метрик (п. 5) и порядок
шагов 1–3 LLM-дизайна перенесены в требования верно, кроме данных правила 1
(см. Р1).

## 1. Решения владельца (блокируют волну 2)

| Код | Вопрос | Варианты | Рекомендация ревью |
|---|---|---|---|
| **Р1** | Данные правила 1 (пульс покоя +8 два дня / самочувствие ≤ 2) отсутствуют в v1: `daily_log` v1 хранит только АД и вес; `hr_resting`, `wellbeing` помечены v2 — а Ф-12.5, БЦ-6 и КУ-7 требуют их в v1 | **А:** добавить `hr_resting`, `wellbeing` в v1-дневник (2 касания ввода) — КУ-7 закрывается целиком. **Б:** правило 1 → v2 (в v1 правила 2–6), скорректировать КУ-7. **В:** прокси — хранить предстартовый пульс сидя в `daily_log` и считать тренд по нему | **А** |
| **Р2** | Идентификация клиентских сущностей: протокол sync требует `client_guid` для каждой записи, но у `exercise`, `program_version`, `athlete_profile` его нет; ключи — серверные `serial`, телефон офлайн не может узнать server id для ссылок (`workout_set.exercise_id`, `workout.program_version_id`) | **А:** добавить `client_guid UNIQUE` в эти таблицы + расширить ответ sync маппингом `{entity, client_guid, id}`. **Б:** UUID как PK всех клиентских сущностей. **В:** натуральные ключи (имя упражнения у атлета) | **А** (минимальная правка БД, идемпотентность сохраняется) |
| **Р3** | Safety-пороги применяются на телефоне офлайн (экран допуска, Ф-13.2), но определены только в серверном `appsettings.json`; канал доставки на телефон не задан | **А:** продублировать пороги в телефонном Preferences (умолчания — документ метрик); серверные `Safety.*` — для серверных правил/`red_flags`. **Б:** синхронизируемая сущность `settings` (сервер — истина; до первой синхронизации — умолчания телефона) | **А** для v1 (один владелец; расхождение источников задокументировать, общая сущность — кандидат v2) |

Если владелец не выбрал вариант — подготовить диффы по рекомендованному и
вынести на утверждение как предложение (самовольно вариант не менять).

## 2. Задания P1 (существенные)

### З-1. Интеграция данных правила 1 в v1 ⬜ *(после Р1; по Р1-А)*

1. `1-docs\1-reqs\requirements.md`:
   - Ф-13.1 — дневник-минимум дополнить: пульс покоя (утро), самочувствие 1–5;
   - Ф-13.6 — v2-перечень сузить до «талия, сон» (пульс покоя и самочувствие
     переносятся в v1);
   - Ф-12.5 — указать источник данных правила 1 (`daily_log`, тренд 2 дня).
2. `1-docs\2-db\src\tables.md`: `src.daily_log` — `hr_resting`, `wellbeing`
   убрать из пометки «v2», описать как поля v1.
3. `1-docs\2-db\src\functions.md`: `daily_log_upsert` — параметры
   `p_hr_resting`, `p_wellbeing`.
4. `1-docs\3-tech\tech-requirements.md`: п. 2.2 (`daily_log`) — поля v1;
   чек-лист шага 7 не меняется.

### З-2. Актуализация архитектуры под Ф-13 ⬜

1. `1-docs\2-arch\architecture.md`:
   - шапка: источники — vision **v1.3**, requirements v1.1; версия документа →
     1.1 с примечанием «актуализация под Ф-13 (изменение vision 1.3)»;
   - раздел 1.2 (телефон): в `WorkoutCore` добавить ответственность «предстартовый
     допуск (пороги Safety, экран допуска) и дневник самоконтроля
     (`daily_log`)»; в `TrainingUi` — экраны «Сегодня» и «Допуск»;
   - раздел 2 (поток): шаг 0 перед «Тренировка» — допуск (пороги АД/пульса;
     блокировка/лёгкое кардио; обход блокировки логируется);
   - таблица компонентов: строка БД — добавить `daily_log` к перечню.
2. `1-docs\2-arch\hld.puml`: отразить допуск/дневник подписью в `WorkoutCore`
   (без новых компонентов и связей — гранулярность схемы не меняется);
   перерендерить `hld.svg` + `hld.png` навыком `std1\_skills\dgm-hld`
   (`python std1\_skills\dgm-hld\render.py 1-docs\2-arch\hld.puml`), рендер
   рядом с исходником (d-drg-11).
3. Утверждение — **Пользователь!**

### З-3. Синхронизация: `client_guid` и маппинг id ⬜ *(после Р2; по Р2-А)*

1. `1-docs\2-db\src\tables.md`: `src.exercise`, `src.program_version` —
   колонка `client_guid uuid NOT NULL UNIQUE` (идемпотентность sync, Ф-7.4);
   `src.athlete_profile` — upsert по `athlete_id` уже идемпотентен, решение
   (без `client_guid`) зафиксировать явно в комментарии.
2. `1-docs\3-tech\tech-requirements.md`:
   - п. 2.1 — ответ `POST /api/v1/sync`: помимо `accepted`, маппинг
     `{entity, client_guid, id}` для созданных записей (телефон хранит
     соответствие локальный id ↔ серверный);
   - п. 2.2 — `exercise`, `program_version`: поле `client_guid`.
3. `1-docs\1-reqs\requirements.md`: Ф-7.2/Ф-7.3 — дополнить маппингом id
   (одной формулировкой: «ответ содержит соответствие client_guid → серверный
   id; телефон использует его для ссылок дочерних записей»).

### З-4. Safety-пороги телефона ⬜ *(после Р3; по Р3-А)*

1. `1-docs\3-tech\tech-requirements.md`, п. 4.1 (телефон): параметры
   `Safety.BpCancelSys/Dias` (умолч. 150/90), `Safety.BpCardioSys/Dias`
   (140/90), `Safety.RestingHrSitting` (90) с валидацией — как в п. 4.2;
   примечание: умолчания из документа метрик; серверные `Safety.*` — источник
   для серверных правил (`red_flags`), совпадение значений — ответственность
   владельца конфигурации (ограничение v1 задокументировать, общая сущность —
   кандидат v2).
2. `1-docs\1-reqs\requirements.md`: раздел 3 (телефонные настройки) —
   дополнить теми же параметрами; Ф-13.5 — переформулировать: «пороги допуска
   — конфигурируемые в настройках телефона; серверные `Safety.*` применяются
   серверными правилами».

## 3. Задания P2

### З-5. `src.workout`: уникальность `fit_file_id` и `fit_workout_id` ⬜

`1-docs\2-db\src\tables.md`:
- у описания поля `fit_file_id` убрать «UNIQUE» — оставить составной
  `UNIQUE(athlete_id, fit_file_id)` (изоляция атлетов);
- колонку `fit_workout_id` удалить: факты пишутся в ту же строку
  (`facts_json`), отдельная строка «только .fit» создаётся с собственным
  `client_guid` (сервер) — ссылочная колонка не используется.

### З-6. Sync-enum: фантом и пропуск ⬜

`1-docs\3-tech\tech-requirements.md`, п. 2.1: из перечня `entity` убрать
`set_note` (сущности нет ни в БД, ни в требованиях); добавить `daily_log`.
(Совместить с З-3.2 — одна правка п. 2.1.)

### З-7. Диапазон RPE ⬜

Согласовать: Ф-13.3 и tech-requirements п. 2.2 — «0–10»; `tables.md` —
`CHECK (rpe BETWEEN 1 AND 10)`. Рекомендация: единый диапазон **1–10**
(RPE 0 в документе метрик не используется; голос «РПЭ N» — N 1–10): в
Ф-13.3 «тапом 1–10», в tech-requirements 2.2 — «int? 1–10». При выборе
владельцем 0–10 — правится CHECK в tables.md.

### З-8. Грамматика Ф-1.2: команда «РПЭ N» ⬜

`1-docs\1-reqs\requirements.md`, Ф-1.2: добавить четвёртую команду
«РПЭ **N**» → RPE последнего подхода (N 1–10, по З-7); согласовать с Ф-13.3
и решением ОВ-2 в tech-requirements (грамматика уже включает «РПЭ»).

## 4. Задания P3 (гигиена)

| Код | Задание | Где |
|---|---|---|
| З-9 | Удалить мусорную строку «io header fix»; в Ф-12 перенумеровать второй «5.» (Офлайн-режим сервера) в «6.» | requirements.md:381–384 |
| З-10 | Исправить «.gp**х**» → «.gpx» (кириллическая буква) | requirements.md:267 |
| З-11 | Шапки-источники привести к vision **v1.3**: requirements (сейчас «v1.0»), tech-requirements (сейчас «v1.2»). Для architecture — в З-2 | requirements.md:4, tech-requirements.md:4 |
| З-12 | URL репозитория: `readme.md` — `VEU/VEU.WathBody.git`, `plan.md` — `VEU/WatchBody.git`. Сверить с фактическим `git remote -v` и привести оба файла к нему (сейчас remote, вероятно, не настроен — тогда принять `VEU/WatchBody.git` и исправить опечатку «WathBody») | readme.md:3–4, plan.md:3–4 |
| З-13 | Маркер «MM» в tables.md вне словаря d-db-2 (`CRUD/SELECT/NO/CUSTOM`): оставить как есть, в комментарий строки добавить «типовой набор связи ММ — d-db-3»; о необходимости маркера «MM» сообщить владельцу std1 (вне репозитория) | src/tables.md:14 |
| З-14 | Добавить в readme БД раздел «План миграции» (требование d-db-1): создание схем `src`/`ref`, вставка значений `ref.exercise_group`, порядок применения psql-файлов из `2-db\`, версионирование миграций | 1-docs/2-db/readme.md |
| З-15 | Сообщить владельцу std1 (вне репозитория): process.md шаг 6 указывает артефакты в `1-docs\d-db\`, противореча шагу 2 того же процесса и правилу d-db-1 (`1-docs\2-db\`); проект применил верный путь | — |

## 5. Порядок исполнения и версии

**Волна 1 — errata, выполняется сразу (З-5–З-14 без Р-зависимостей:**
З-5, З-6, З-9, З-10, З-11, З-12, З-13, З-14**).** Правки представляются
владельцу одним диффом → утверждение → коммит
«Ревью документации: errata (Ф-12 нумерация, .gpx, версии источников,
fit_file_id, sync-enum)». Версии: requirements → 1.2 (errata),
tables.md → новая редакция (дата), tech-requirements → 1.2, 2-db readme →
новая редакция.

**Волна 2 — после решений Р1–Р3 (З-1, З-2, З-3, З-4, З-8).** Все правки
одним пакетом «Актуализация по ревью: Ф-13 в архитектуре, данные правила 1,
client_guid/маппинг sync, Safety телефона» → рендер hld → утверждение
владельцем (одно утверждение на пакет) → коммит. Версии: requirements → 1.3,
architecture → 1.1, tech-requirements → 1.3, tables/functions → новая
редакция (число функций не меняется — меняются параметры `daily_log_upsert`
и колонки `client_guid`).

**После каждой волны — самопроверка (раздел 7) и отметки в разделе 6.**

## 6. Чек-лист

| Задание | P | Зависит от | Статус |
|---|---|---|---|
| Р1–Р3 решения владельца | — | — | ✅ Р1-А, Р2-Б, Р3-А (2026-10-17) |
| З-1 правило 1: данные v1 | 1 | Р1 | ✅ (2026-10-17, Р1-А) |
| З-2 архитектура + hld.puml + рендер | 1 | — | ✅ (2026-10-17, architecture v1.1 утверждена, hld отрендерен) |
| З-3 client_guid + маппинг id | 1 | Р2 | ✅ (2026-10-17, Р2-Б — UUID PK; уточнено ревью №2 З-16) |
| З-4 Safety-пороги телефона | 1 | Р3 | ✅ (2026-10-17, Р3-А) |
| З-5 fit_file_id / fit_workout_id | 2 | — | ✅ (2026-10-17) |
| З-6 sync-enum (set_note/daily_log) | 2 | — | ✅ (2026-10-17) |
| З-7 диапазон RPE | 2 | — | ✅ (2026-10-17, единый 1–10) |
| З-8 грамматика «РПЭ N» | 2 | З-7 | ✅ (2026-10-17) |
| З-9 Ф-12: «io header fix», нумерация | 3 | — | ✅ (2026-10-17) |
| З-10 .gpх → .gpx | 3 | — | ✅ (2026-10-17) |
| З-11 шапки-источники → vision v1.3 | 3 | — | ✅ (2026-10-17, сразу v1.4) |
| З-12 URL репозитория | 3 | — | ✅/переоткрыт частично: readme был верен; plan.md исправлен ревью №2 (З-23) — 2026-10-17 |
| З-13 маркер «MM» + письмо std1 | 3 | — | 🔄 (комментарий добавлен; письмо std1 — вне репо) |
| З-14 план миграции в 2-db readme | 3 | — | ✅ (2026-10-17) |
| З-15 сообщение владельцу std1 о process.md | 3 | — | ⬜ |

## 7. Самопроверка после правок

1. **requirements.md:** трассировка раздела 6 не нарушена (каждая Ф имеет БЦ/КУ);
   ссылки на ОВ актуальны; нумерация Ф-12 сплошная; «РПЭ N» есть и в Ф-1.2,
   и в Ф-13.3 с одним диапазоном.
2. **architecture.md / hld.puml:** шапка ссылается на vision v1.3 и
   requirements текущей версии; Ф-13 присутствует в разделах 1.2, 2 и в таблице
   компонентов; рендер (`hld.svg`/`hld.png`) свежее `.puml`; стиль — d-drg-3,
   палитра и легенда — d-drg-4 (жёлтый — внешнее, серый — не в v1).
3. **tables.md / functions.md:** «Набор функций» в сводной таблице ↔ строки
   «Списка функций» совпадают 1:1; словарь маркеров соблюдён; составной
   `UNIQUE(athlete_id, fit_file_id)` — единственное описание уникальности;
   `daily_log_upsert` содержит все поля v1.
4. **tech-requirements.md:** enum `entity` = перечень п. 2.2 без фантомов;
   `Safety.*` есть в 4.1 и 4.2 с согласованными умолчаниями; ответ sync
   описывает маппинг id.
5. **Общее:** git-статус чистый после коммитов; в логах/доках нет секретов;
   push не выполнялся.