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-2.md

24 KiB
Raw Blame History

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

Исполнитель: агент сопровождения документации WatchBody. Источник: вторая архитектурная проверка документации шагов 1–6 (после выполнения волн 1–2 ревью №1, коммит e674318): сверка с исходной задачей (Техническое задание.md, Требование.md), документами- рекомендациями (Метрики_тренировок_и_самоконтроля.md, Перерывы_подводные_камни_и_рекомендации.md, Форматы_тренировок_и_рекомендации.md, Архитектура_LLM_планирования_тренировок.md, program-trenirovok.md), UI/UX-рекомендациями (3-tech\ui-ux-recommendations.md) и внутренними противоречиями. Уточнение владельца (чат, 2026-10-17): якорные часы — Fenix 6X (280×280 MIP). Примечание (ревью №3, З-30): program-trenirovok.* — импортируемый пакет эксплуатации; формулировка источника в Ф-13.7 скорректирована по З-30 — не копировать прежнюю. В ТЗ указан «Fenix 6, 260×260» — считать опиской исходника, документы разработки приводятся к Fenix 6X (З-18). Состояние репозитория на момент проверки: коммит e674318, ветка main, статус чистый; ссылки на строки — по нему, после правок ориентироваться по разделам. Статусная модель заданий: ⬜ не начато → 🔄 в работе → ✅ готово (утверждено владельцем). Отметки — в разделе 6 по мере работы. Общие правила исполнения:

  1. Правки вносятся новыми версиями утверждённых документов (перечень — раздел 5). Каждая новая версия — точка утверждения Пользователь! (d-dev-4).
  2. Содержание утверждённых документов меняется только в объёме заданий; инварианты 🛡 не ослабляются; трассировка «Ф → БЦ → КУ → версия» (раздел 6 requirements) сохраняется.
  3. Задания, зависящие от решений О-1…О-3 (раздел 1), не вносятся до выбора владельцем; остальные можно выполнять сразу. Если владелец не выбрал — подготовить дифф по рекомендованному варианту и вынести на утверждение.
  4. Код (3-app\, 2-db\) не трогается — задание касается только 1-docs\ и корневых readme.md/plan.md-упоминаний.
  5. Коммиты пушатся после каждой волны (credentials настроены).
  6. Исходные документы задачи в корне (Техническое задание.md, документы- рекомендации, program-trenirovok.*) не редактируются — это вход, а не документация разработки.

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

Соответствие исходной задаче и рекомендациям в целом подтверждено: все 9 позиций MVP ТЗ покрыты (Ф-1–Ф-9), стеки соответствуют Требование.md (C#/.NET 10 + PostgreSQL по std1, Kotlin, Monkey C), решения ревью №1 (Р1-А/Р2-Б/Р3-А, З-1…З-8) внесены в документы, правила книг перенесены (допуск АД/пульс, правила 1–6 в v1 / 7–10 в v2, формула возврата и правила 12–17 дословно, FIT/JSON/CSV, шаг 1 LLM-дизайна в v1, UI/UX-стандарт). Найдено: 2 существенных дефекта (P1) — Р2-Б доведён не до конца (FK-колонки и типы возврата остались int при uuid-PK) и контур break не имеет пути записи ответа атлета; 4 средних (P2); 8 мелких (P3, гигиена), включая неактуализированный чек-лист ревью №1.

1. Решения владельца (блокируют часть заданий)

Код Вопрос Варианты Рекомендация ревью
О-1 ОВ-10 requirements (источник .fit для атлетов без учётки владельца) помечен «закрыт шагом 5», но решения в tech-requirements нет А: v1 — только папка импорта --mode import для таких атлетов; собственные учётки в конфиге — кандидат v2. Б: список учётных записей Garmin в appsettings.json (по атлету) уже в v1 А (не раздувать v1; деградация уже работает)
О-2 П-2 (vision) «вес — целые числа» противоречит пикеру шага 2,5 кг (Ф-3.6): голос не введёт 22,5 кг — запишет 22 (искажение план/факт и тоннажа) А: зафиксировать ограничение: голос — целые кг, дробные — правка тапом (примечание в Ф-1.2 и П-2). Б: расширить грамматику: «…с половиной» → +0,5 кг (словарь Vosk + постобработка, tech-req §5) А для v1 (просто и предсказуемо); Б — кандидат v2
О-3 Шаг прогрессии изоляции BaseStepKg/2 = 1,25 кг (при умолчании 2,5) выходит из коридора метрик «руки +0,5–1 кг» (правило 4) А: отдельный параметр Progression.IsoStepKg (умолчание 1,0; валидация 0,25–5). Б: оставить 1,25 с примечанием «осознанное решение владельца» А (коридор метрик соблюдается без ручной подгонки)

2. Задания P1 (существенные, блокируют шаг 7)

З-16. Доведение Р2-Б: uuid-FK и типы возврата функций ⬜

  1. 1-docs\2-db\src\tables.md — колонки-ссылки на uuid-PK сменить int → uuid NOT NULL (или NULL по смыслу):
    • src.workout.program_version_id: uuid NULL → src.program_version.id;
    • src.workout_set.exercise_id: uuid NULL → src.exercise.id;
    • src.exercise_replacement.exercise_id, replacement_id: uuid → src.exercise.id.
  2. 1-docs\2-db\src\functions.md — тип возврата для uuid-сущностей «int — id» → «uuid — id»: exercise_insert, program_version_insert, workout_insert, workout_set_insert, command_log_insert, break_insert. Для exercise_replacement_insert (ММ, составной PK, id нет) — «int — число строк».
  3. Самопроверка: в tables.md не осталось ссылок int → на таблицы с uuid PK; каждой функции вставки uuid-сущности соответствует возврат uuid.

З-17. Контур break: путь записи ответа атлета ⬜

Противоречие: Ф-14.2 собирает причину и дату возврата, sync-сущность break передаёт planned_return, но в src.breaks колонки нет, source объявлен «🛡 всегда auto», а break_update принимает только p_ended_on — ответу атлета некуда и нечем записаться; правила 12–14 без kind не работают.

  1. 1-docs\2-db\src\tables.md, src.breaks:
    • добавить колонку planned_return | date NULL | предполагаемая дата возврата (Ф-14.2);
    • source — снять пометку «🛡 всегда auto», описать: auto — сервер по пропускам (Ф-14.1); manual — запланированный простой, объявленный атлетом заранее (Ф-14.2). Значение из sync — только manual; auto проставляет сервер.
  2. 1-docs\2-db\src\functions.md:
    • break_insert — параметры p_kind, p_source, p_started_on, p_planned_return, p_note; комментарий: «auto — сервер по пропускам; manual — телефон (объявление заранее)»;
    • break_update — параметры p_kind, p_note, p_planned_return, p_ended_on; комментарий: «ответ атлета на вопрос о причине (Ф-14.2) + закрытие первой сессией после возврата».
  3. 1-docs\1-reqs\requirements.md, Ф-14.1 — снять натяжку «Ручного включения break нет» против Ф-14.2: переформулировать «Break ставится автоматически по пропускам (основной путь); атлет может объявить перерыв заранее (Ф-14.2) — такой break создаётся с source=manual; произвольного ручного включения без объявления нет».
  4. 1-docs\3-tech\tech-requirements.md, п. 2.1, сущность break — привести к таблице: kind (NULL до ответа), source (телефон передаёт manual), started_on, planned_return, note; ended_on проставляет сервер первой сессией после возврата.

3. Задания P2

З-18. Якорные часы — Fenix 6X (уточнение владельца от 2026-10-17) ⬜

Заменить «Fenix 6 (260×260)» → «Fenix 6X (280×280)» и убрать ложное «одно разрешение для 6/6S/6X» (фактически: 6S — 240×240, 6 — 260×260, 6X — 280×280):

  1. 1-docs\1-reqs\vision.md: «Что уже есть» (Fenix 6, 260×260 MIP → Fenix 6X, 280×280 MIP); БР-3 («якорное устройство — Fenix 6»); З-3 п. 1.7 («якорь — Fenix 6»); п. 2.4 («якорное устройство v1 — Fenix 6 (260×260 MIP, кнопки)»). Оформить как изменение 1.5 (уточнение владельца 2026-10-17: якорь — Fenix 6X; в ТЗ указан Fenix 6/260×260 — описка исходника) → версия vision 1.5.
  2. 1-docs\1-reqs\requirements.md: раздел 2.1 («Якорное устройство — Fenix 6») + примечание об уточнении владельца; открытый вопрос 8 («Якорь — Fenix 6»).
  3. 1-docs\3-tech\tech-requirements.md, решение ОВ-7 — переписать: «Таргет v1 — fenix6x (280×280, MIP, кнопки). Fenix 6 (260×260) и 6S (240×240) добавляются отдельными таргетами с собственными макетами (Ф-2.8) по фактическому парку». Утверждение — Пользователь!
  4. Корневой readme.md («часы Garmin Fenix 6», состав системы) и 1-docs\0-mng\plan.md (строка версий, «Fenix 6 (Monkey C…)») — привести к Fenix 6X.
  5. 1-docs\3-tech\ui-ux-recommendations.md не трогать: там Fenix 6X / 280×280 указаны верно.
  6. ТЗ (..\..\Техническое задание.md) не редактировать (вход).

З-19. Закрытие ОВ-10 (после О-1; по О-1-А) ⬜

1-docs\3-tech\tech-requirements.md, раздел 1 — добавить строку ОВ-10: «Источник .fit атлетов без учётки владельца — только папка импорта (--mode import); fetch работает под единственной учёткой владельца; собственные учётки атлетов в конфиге — кандидат v2». В requirements раздел 7 (ОВ-10) — проставить финальное решение со ссылкой на tech-requirements.

З-20. Порог пульса силовой части (Safety.HrStrengthMax) ⬜

Ограничение профиля «пульс при силовой ≤ 110–120 уд/мин» (program-trenirovok.md, документ метрик п. 2.3) в требованиях не отражено; зоны 50/70/85 % дают жёлтый от ~123 и красный от ~150 (Танака, 45 лет) — для гипертоника 45+ ключевой порог не контролируется.

  1. 1-docs\1-reqs\requirements.md:
    • раздел 3, таблица телефона: Safety.HrStrengthMax — «порог пульса в силовой части (предупреждение)», умолчание 120; та же строка — в серверной таблице (для red_flags);
    • Ф-13 — новый пункт 7 (без перенумерации 4–6, на них есть ссылки): «Во время силовой части: пульс > Safety.HrStrengthMax → предупреждение на телефоне (баннер + вибро, спокойная формулировка по UI/UX-стандарту); на часы порог передаётся в объёме канала (ОВ-3). Источник — программа тренировок и документ метрик (п. 2.3)».
  2. 1-docs\3-tech\tech-requirements.md: п. 4.1 и 4.2 — строка Safety.HrStrengthMax | int | 100–180 (умолчание 120).
  3. Трассировку раздела 6 не менять (Ф-13 уже привязан к БЦ-6/КУ-7).

З-21. Период запуска fetch (проверяемость БЦ-5) ⬜

БЦ-5 требует «архив на сервере ≤ 30 минут после тренировки», решение ОВ-4 — внешний планировщик — интервал не задан нигде, критерий непроверяем.

1-docs\3-tech\tech-requirements.md, решение ОВ-4 — дополнить: «Интервал вызова — 15 минут (параметр планировщика ОС, в код не входит); вместе с лагом синхронизации часов с Garmin Connect укладывается в БЦ-5 (≤ 30 мин)».

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

Код Задание Где
З-22 Шапка-источник: «vision v1.3» → «vision v1.4»; в разделе 2.3 («--mode fetch») «открытый вопрос 5» → «открытый вопрос 4» requirements.md:4, :85
З-23 URL репозитория → https://git.mind01.ru/VEU/VEU.WathBody.git (как в readme, по фактическому remote; З-12 ревью №1 был закрыт ошибочно); в «Составе версий» указать: v1.0 включает Ф-13 (MVP-состав документа метрик) и Ф-14 (vision 2.2) plan.md:3–4, раздел «Состав версий»
З-24 Чек-лист ревью №1 актуализировать по факту: Р1-А/Р2-Б/Р3-А — решены; З-1, З-3, З-4, З-7, З-8 — ✅; З-2 — ✅ (architecture v1.1 утверждена); З-12 — частично переоткрыт (plan.md, см. З-23); З-13 🔄 и З-15 ⬜ остаются review-2026-10-17.md, раздел 6
З-25 Опечатка «2-dbuild.ps1» → «2-db\build.ps1»; режим --mode migrate добавить в таблицу режимов requirements 2.3 (семантика: применение миграций из 2-db\migrations\; коды возврата — как у import); таблицу src.migration (id serial PK, filename UNIQUE, applied_at; функции migration_insert/migration_select, CUSTOM) добавить в перечень и описания tables.md 2-db\readme.md:47–48, requirements 2.3, 2-db\src\tables.md
З-26 Дробные веса (после О-2): по А — примечание в Ф-1.2 («голос — целые кг; дробные (шаг 2,5) — правка тапом, Ф-1.6») и уточнение П-2 в vision; по Б — грамматика «…с половиной» → +0,5 кг в Ф-1.2 и словарь/постобработка в tech-req §5 (VoiceInput) requirements Ф-1.2, vision П-2, tech-req §5
З-27 Шаг прогрессии изоляции (после О-3): по А — параметр Progression.IsoStepKg (умолчание 1,0; валидация 0,25–5) в раздел 3 и п. 4.2, Ф-12.2 — «+ IsoStepKg (изоляция)»; по Б — примечание в Ф-12.2 «умолчание даёт 1,25 кг — выше коридора метрик 0,5–1 кг, решение владельца» requirements 3, Ф-12.2; tech-req 4.2
З-28 UI/UX-рекомендации → версия 1.1: §3 и §6.3 — «id-mapping» заменить на «UUID PK клиентских сущностей (Р2-Б)»; §2.2 и §6.2 — пометить «ввод RPE/боли на часах» как неприменимое к форме «поле данных» (кнопки обрабатывает Garmin, Ф-2.5–2.6; ввод RPE/боли — телефон, Ф-13.3); §2.1/§8 (Fenix 6X, 280×280) — верно, не менять 3-tech\ui-ux-recommendations.md
З-29 Перечень LocalDb в архитектуре дополнить: дневник самоконтроля (daily_log) и перерывы (breaks); версия architecture → 1.2 (мелкая правка перечня) architecture.md, раздел 1.2

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

Волна 1 — P1 + P2 (З-16, З-17, З-18, З-20, З-21 сразу; З-19 после О-1). Один пакет «Ревью №2: uuid-FK (Р2-Б доведён), контур break, якорь Fenix 6X, ОВ-10, Safety.HrStrengthMax, период fetch» → утверждение владельцем (одно утверждение на пакет) → коммит и push. Версии: vision → 1.5 (изменение 1.5), requirements → 1.4, tech-requirements → 1.4, tables/functions → новая редакция (число функций не меняется — меняются типы/параметры), 2-db readme → новая редакция.

Волна 2 — P3 errata (З-22, З-23, З-24, З-25, З-29 сразу; З-26, З-27 после О-2/О-3; З-28 сразу). Пакет «Ревью №2: errata (шапки, plan.md, чек-лист ревью №1, migrate-mode, ui-ux v1.1, LocalDb)» → утверждение → коммит и push. Версии: ui-ux-recommendations → 1.1, architecture → 1.2; остальные правки — внутри версий волны 1.

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

6. Чек-лист

Задание P Зависит от Статус
О-1…О-3 решения владельца — — ✅ О-1 — ответ владельца: атлеты саморегистрируются на телефоне (имя), привязка — по uuid клиентского приложения (для .fit применён О-1-А — папка импорта); О-2-Б; О-3-А (2026-10-17)
З-16 uuid-FK + типы возврата 1 — ✅ (2026-10-17)
З-17 контур break (planned_return, source, update) 1 — ✅ (2026-10-17)
З-18 якорь Fenix 6X (vision 1.5, requirements, tech-req, readme, plan) 2 — (уточнение владельца дано) ✅ (2026-10-17)
З-19 закрытие ОВ-10 2 О-1 ✅ (2026-10-17, О-1-А + уточнение владельца о регистрации)
З-20 Safety.HrStrengthMax 2 — ✅ (2026-10-17)
З-21 период fetch (БЦ-5) 2 — ✅ (2026-10-17, интервал 15 мин)
З-22 шапка requirements, ОВ-нумерация 3 — ✅ (2026-10-17, сразу vision v1.5)
З-23 plan.md URL + состав версий 3 — ✅ (2026-10-17)
З-24 чек-лист ревью №1 3 — ✅ (2026-10-17)
З-25 migrate-режим, src.migration, опечатка 3 — ✅ (2026-10-17; опечатка подтвердилась — байт 0x08, исправлена по З-33 ревью №3)
З-26 дробные веса 3 О-2 ✅ (2026-10-17, по О-2-Б)
З-27 шаг изоляции 3 О-3 ✅ (2026-10-17, по О-3-А)
З-28 ui-ux-recommendations v1.1 3 — ✅ (2026-10-17)
З-29 LocalDb перечень (architecture 1.2) 3 — ✅ (2026-10-17)

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

  1. tables.md / functions.md: нет ссылок int → на uuid-PK; возвраты insert-функций uuid-сущностей — uuid; у src.breaks есть planned_return, source описан как auto|manual; перечень таблиц ↔ список функций совпадают 1:1 (включая src.migration).
  2. requirements.md: Ф-14.1 согласован с Ф-14.2; Ф-13.7 ссылается на Safety.HrStrengthMax; строки раздела 3 (телефон и сервер) содержат Safety.HrStrengthMax; шапка — vision v1.4 (после волны 1 — v1.5); трассировка раздела 6 не нарушена; Ф-13.4/Ф-13.5/Ф-13.6 сохранили номера.
  3. tech-requirements.md: ОВ-7 — таргет fenix6x (280×280); ОВ-4 — интервал 15 минут; ОВ-10 присутствует и закрыт по О-1; п. 4.1/4.2 содержат Safety.HrStrengthMax с одинаковой валидацией; сущность break (п. 2.1) совпадает с src.breaks по полям.
  4. vision.md: изменение 1.5 добавлено в шапку; упоминания «Fenix 6 / 260×260» в п. 1.1, БР-3, З-3, п. 2.4 заменены на Fenix 6X / 280×280.
  5. Согласованность устройств: «Fenix 6X / 280×280» единообразно в vision, requirements, tech-requirements, architecture (если упоминается), корневом readme.md, plan.md; в ui-ux-recommendations не изменено (уже верно).
  6. Общее: git-статус чистый после коммитов; исходники задачи в корне не редактировались; в логах/доках нет секретов; push выполнен после каждой волны.