215 lines
20 KiB
Markdown
215 lines
20 KiB
Markdown
# Ревью документации от 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 правило 1: данные v1 | 1 | Р1 | ⬜ |
|
||
| З-2 архитектура + hld.puml + рендер | 1 | — (текст), рендер после правок | 🔄 (2026-10-17: Ф-13, Ф-14 и волна 2 внесены; черновик v1.1 — на утверждении) |
|
||
| З-3 client_guid + маппинг id | 1 | Р2 | ⬜ |
|
||
| З-4 Safety-пороги телефона | 1 | Р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 | — | ⬜ |
|
||
| З-8 грамматика «РПЭ N» | 2 | З-7 | ⬜ |
|
||
| З-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 | — | ✅ (2026-10-17, remote = VEU/VEU.WathBody.git, оба файла выверены) |
|
||
| З-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 не выполнялся.
|