VEU
/
VEU.WathBody
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
VEU.WathBody/1-docs/0-mng/review-2026-10-17.md

20 KiB
Raw Blame History

Ревью документации от 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 не выполнялся.