200 lines
15 KiB
Markdown
200 lines
15 KiB
Markdown
# Рекомендации агенту — этап 7 (итоги архитектурного ревью 2026-10-18)
|
||
|
||
> **Получатель:** кодирующий агент, выполняющий этап 7 «Итерационная
|
||
> разработка» (текущий модуль — m05-progression-rules; далее m06+ по
|
||
> [plan.md](plan.md)). **Источник:** архитектурная сверка артифактов
|
||
> этапа 7 с документацией (requirements 1.4, architecture 1.2,
|
||
> tech-requirements 1.4, 2-db, module_reqs/api_specs m01–m05), 2026-10-18.
|
||
> Базовые файлы стандарта `std1\` и библиотека `Kit.Helpers` не править —
|
||
> все исправления только в проектных файлах этого репозитория.
|
||
> **Статусная модель заданий:** ⬜ не начато → 🔄 в работе → ✅ готово
|
||
> (утверждено владельцем). Нумерация З-35+ продолжает З-34
|
||
> (ревью №3, [review-2026-10-17-3.md](review-2026-10-17-3.md)).
|
||
|
||
## 0. Итог сверки (что подтверждено — не перепроверять)
|
||
|
||
- Сборка решения — 0 ошибок / 0 предупреждений; тесты: Core.Tests
|
||
**55/55**, Web.Tests **80/80** (Integration 13 + Unit 12 + ProgramStore
|
||
19 + MetricsEngine 17 + ProgressionRules 19), psql-проверок **122** —
|
||
все числа в readme модулей и plan.md совпадают с фактом.
|
||
- Структура DAL — 13 репозиториев в 8 файлах, 7 фильтров; доступ к БД —
|
||
только хранимые функции через Kit.Helpers.
|
||
- 38 psql-функций ↔ 38 тестов ↔ 38 спецификаций, статусы `DONE`.
|
||
- 🛡-инварианты серверного кода соблюдены: изоляция `p_athlete_id`
|
||
(включая явные проверки в `workout_insert`, `program_version_update`,
|
||
`workout_metrics_upsert`), идемпотентность по `p_id`, статусные
|
||
переходы `draft → active → archived` со сдвигом прежней `active`,
|
||
логическое `exercise_delete`, отказ `break.source=auto` из sync,
|
||
атомарность пакета `TransactionScope` (чтения — до транзакции),
|
||
сбой метрик/правил не ломает sync, ProgramStore — 7 методов,
|
||
авторы `user/admin/rules` (llm отклоняется), авто-смены активной
|
||
версии нет.
|
||
- Sync-валидация полного состава: пакет ≤ 50, `op=upsert`, диапазоны
|
||
`rpe` 1–10 / `wellbeing` 1–5 / `knee_pain` 0–10, 409 по spec 03 m02.
|
||
- Правила m05: 1–5 по порядку, делоад ×0.6/−1 подход, формула возврата
|
||
по таблице (1.0/0.9/0.85/0.75/ReturnMinFactor), правило 17 → `test`,
|
||
дедупликация rules-черновиков.
|
||
|
||
## 1. Задание P1
|
||
|
||
### З-35. Довести З-31 (`src.program.external_id`) до артефактов БД и DAL ⬜
|
||
|
||
Решение О-4-Б утверждено и внесено в документацию
|
||
(`2-db\src\tables.md:83` — колонка `external_id`; `2-db\src\functions.md`,
|
||
`program_insert` — параметр `p_external_id`), но в коде отсутствует
|
||
полностью (grep по `2-db\` и `3-app\` — 0 вхождений): миграция 002,
|
||
`program_insert.psql`, `func_specs\program_insert.md`,
|
||
`ProgramRepository.Insert`. Контракт импорта пакета программы (Ф-8.3,
|
||
tech-req ОВ-11) на текущей схеме нереализуем — блокер m06.
|
||
|
||
1. `2-db\migrations\003_program_external_id.sql` — новая миграция
|
||
(001–002 уже применены на `watchbody-pg`, журнал не трогать):
|
||
`ALTER TABLE src.program ADD COLUMN IF NOT EXISTS external_id text;`
|
||
+ `CREATE UNIQUE INDEX IF NOT EXISTS uq_program_external_id ON
|
||
src.program (external_id);` (идемпотентно; NULL не ограничивается —
|
||
программа из sync создаётся без пакета).
|
||
2. `2-db\src\functions\program_insert.psql` — параметр
|
||
`p_external_id text DEFAULT NULL`, включить в INSERT.
|
||
3. `1-docs\2-db\src\func_specs\program_insert.md` — синхронизировать
|
||
(параметр + тест-кейс «повтор того же `external_id` → исключение
|
||
UNIQUE»; новая версия при повторе пакета — путь импорта, m06).
|
||
4. `Server.WatchBody.Core`: `Program.ExternalId` (string?) в домен,
|
||
`ProgramRepository.Insert` — параметр `p_external_id`
|
||
(`AddParameterNullable`); `SyncService.CreateProgram` не меняется
|
||
(NULL по умолчанию).
|
||
5. Тесты: psql `test_program_insert` — кейс UNIQUE-повтора; Core.Tests
|
||
`ProgramRepositoryTests` — кейс вставки с `external_id`; прогон на
|
||
docker `watchbody-pg`.
|
||
6. `readme.md` m01 — errata-примечание (практика модуля): «З-31 не был
|
||
доведён до SQL/DAL-артефактов, вскрыто ревью этапа 7 (2026-10-18),
|
||
исправлено по З-35»; числа тестов в readme m01 и plan.md (строка m01)
|
||
актуализировать после добавления кейсов.
|
||
|
||
## 2. Задания P2
|
||
|
||
### З-36. Режим `--mode migrate` — реализовать либо оформить перенос ⬜ (решение владельца)
|
||
|
||
`requirements` 2.3 и `module_reqs` m01 (разд. 1, критерий приёмки 1)
|
||
требуют CLI `--mode serve|import|fetch|migrate`; `plan.md` (строка m01)
|
||
включает его в закрытый модуль. Фактически `Program.cs` аргументы не
|
||
разбирает; `2-db\readme.md` ссылается на несуществующий `build.ps1`.
|
||
|
||
- **Рекомендация (реализовать):** разбор `--mode`/`--config` в
|
||
`Program.cs`; для `migrate` — применение файлов `2-db\migrations\`
|
||
по возрастанию, журнал через `MigrationRepository` (уже готов),
|
||
транзакция на файл, откат при сбое, коды возврата 0/1 (как import);
|
||
путь миграций — новый ключ конфига `Db.MigrationsDir` (умолчание —
|
||
`migrations` рядом с исполняемым файлом). Внесение ключа — правка
|
||
tech-req 4.2 → шлюз «**Пользователь!**».
|
||
- **Альтернатива (перенести в m06):** в `plan.md` (строки m01/m06),
|
||
`module_reqs` m01 и `2-db\readme.md` зафиксировать «`--mode migrate`
|
||
входит в `Server.WatchBody.Import` (m06)»; m01 в plan.md — примечание.
|
||
|
||
### З-37. Конфигурация `Safety.*`/`Progression.*` ↔ tech-req 4.2 ⬜ (правка утверждённого документа — шлюз)
|
||
|
||
Расхождения (код — `MetricsConfig.cs`, `ProgressionConfig.cs`,
|
||
`appsettings.json`):
|
||
|
||
1. `bpElevatedSys/Dias` (умолчание 140/**95**) против tech-req
|
||
`BpCardioSys/Dias` (140/90, «≤ BpCancel») — с умолчаниями документа
|
||
невыполнимо; отказ от проверки задокументирован в m04. Рекомендация:
|
||
tech-req 4.2 переименовать в `BpElevated*`, умолчание Dias 95,
|
||
примечание «проверка ≤ BpCancel не применяется (коридоры АД
|
||
перекрываются, spec 01 m04)».
|
||
2. В tech-req 4.2 отсутствуют фактические параметры сервера:
|
||
`hrRestingDays`, `wellbeingDays`, `lightDayCount`, `kneePainMin`,
|
||
`kneeRepeatSessions`, `hrBaselineDays`, `hrBaselineMin`,
|
||
`missDaysForBreak`, `returnMinFactor/MaxFactor` — дополнить таблицу.
|
||
3. `RestingHrSitting`, `HrStrengthMax`, `LightWeekHrRise` в серверной
|
||
конфигурации не читаются (пороги допуска — телефон по Р3-А; Ф-13.7).
|
||
Рекомендация: в tech-req 4.2 пометить «потребление — телефон (m09);
|
||
сервер в v1 не читает» — без мёртвых ключей в appsettings.
|
||
4. Диапазоны валидации сузить в коде до утверждённых:
|
||
`backoffPercent` → 1–20 (`ProgressionConfig.cs:44`), `deloadMaxWeeks`
|
||
→ 3–12 (`ProgressionConfig.cs:45`) — это правка кода без шлюза.
|
||
5. Регистр имён в tech-req 4.2 привести к фактическим camelCase.
|
||
|
||
### З-38. Шлюзы и статусы m05 ⬜ (шлюз — владелец, остальное — агент)
|
||
|
||
По [m05 readme](../4-modules/m05-progression-rules/readme.md) шаг 1.3
|
||
(«**Пользователь!**» — утверждение списка единиц) — ⬜ при выполненных
|
||
шагах 2/2.4/3; в [plan.md](plan.md) m05 — ⬜. Проект решения гейта —
|
||
`module_reqs` разд. 2.4. Порядок: владелец утверждает 1.3 → агент
|
||
проставляет 1.3 ✅ и m05 🔄 в plan.md → шлюз 3.4 (утверждение
|
||
реализации) → шаг 4 (закрытие модуля), plan.md m05 ✅.
|
||
|
||
## 3. Задания P3
|
||
|
||
### З-39. Трассировка Ф-14.3: «болезнь с температурой» vs `kind=illness` ⬜ (шлюз)
|
||
|
||
Spec 04 m05 (утверждён) применяет коэффициент перезапуска 0.6 к любому
|
||
`kind=illness` («любой длительности»), requirements Ф-14.3 — только к
|
||
«болезни с температурой». Признака «с температурой» в данных `breaks`
|
||
нет, поэтому рекомендуется примечание в requirements Ф-14.2/Ф-14.3:
|
||
«в v1 любой break `kind=illness` трактуется как перезапуск (spec 04
|
||
m05); различение „с температурой“ — кандидат v2». Утверждение —
|
||
владелец.
|
||
|
||
### З-40. Косметика и примечания ⬜ (сразу, без шлюза)
|
||
|
||
1. `2-db\src\functions\exercise_delete.psql:1` — заголовок
|
||
«is_active = 0» → «is_active = false» (терминология З-34).
|
||
2. `m02 api_specs\04-workouts-get.md` — примечание «пагинация в памяти
|
||
(выборка атлета целиком) — известное ограничение v1».
|
||
3. `tech-requirements` разд. 3 — примечание «в sync-контуре v1
|
||
используется `ILogger<SyncService>`; `Log.Logger` — файловые логи
|
||
последующих модулей (errata m04 №4)».
|
||
4. `m05 api_specs\02-micro-adjust.md` — примечание: «та же группа»
|
||
пары-замены гарантируется `exercise_replacement_insert` (проверка
|
||
на вставке пары); runtime-проверка в `ApplyExclusion` не дублируется.
|
||
|
||
## 4. Порядок исполнения
|
||
|
||
1. **Сразу агентом:** З-35 (код + БД + тесты, прогон на docker
|
||
`watchbody-pg`), З-40; в З-37 — п. 4 (диапазоны кода).
|
||
2. **Пакет на утверждение владельцу (один дифф):** З-36 (выбранный
|
||
вариант), З-37 (пп. 1–3, 5 — правки tech-req 4.2), З-39.
|
||
3. **После утверждения:** З-38 — закрытие шлюзов m05, синхронизация
|
||
статусов (readme m05, plan.md); далее продолжение этапа 7 — закрытие
|
||
m05 (3.4 → 4) и m06 по plan.md.
|
||
4. Коммит и push — после утверждения волны владельцем; эксплуатационные
|
||
файлы (`program-trenirovok.*`, `program-import.json`,
|
||
`presentation-trenirovok.html`) в коммит не включать.
|
||
|
||
## 5. Чек-лист
|
||
|
||
| Задание | P | Шлюз | Статус |
|
||
|---|---|---|---|
|
||
| З-35 external_id: миграция 003 + функция + spec + DAL + тесты | 1 | — | ✅ |
|
||
| З-36 `--mode migrate`: реализация или перенос (по выбору) | 2 | **Пользователь!** | ✅ (реализовано) |
|
||
| З-37 Safety/Progression ↔ tech-req 4.2 (пп. 1–3, 5) | 2 | **Пользователь!** | ✅ |
|
||
| З-37 п. 4 — диапазоны валидации в коде | 2 | — | ✅ |
|
||
| З-38 шлюзы/статусы m05 (1.3 → 🔄 → 3.4 → 4) | 2 | **Пользователь!** | ✅ (m05 закрыт) |
|
||
| З-39 примечание Ф-14.3 (illness → перезапуск) | 3 | **Пользователь!** | ✅ |
|
||
| З-40 косметика (4 пункта) | 3 | — | ✅ |
|
||
| Коммит и push волны | — | утверждение | ⬜ (у владельца) |
|
||
|
||
## 6. Как продолжать работу после заданий
|
||
|
||
- Точка входа — первый незакрытый шаг/шлюз в readme текущего модуля;
|
||
шлюзы «**Пользователь!**» (d-dev-4) без явного утверждения не
|
||
переходить.
|
||
- Новые сущности, функции БД, эндпоинты и параметры конфига не вводить
|
||
без правки `module_reqs.md` модуля (состав зафиксирован шагами d-dev).
|
||
- Прогон тестов — PostgreSQL 17 в docker `watchbody-pg` (порт 5433,
|
||
БД `watchbody`); изменения чисел тестов актуализировать в readme
|
||
модуля и `plan.md` той же правкой.
|
||
- Errata интеграций фиксировать в readme модуля-обнаружителя
|
||
(практика m01/m02/m04 — сохранить).
|
||
|
||
## 7. Самопроверка после З-35
|
||
|
||
1. `\i 2-db\migrations\003_program_external_id.sql` дважды — без ошибок
|
||
(идемпотентность); `src.program` содержит колонку и уникальный индекс.
|
||
2. `SELECT src.program_insert(1, 'Т', 'pkg_1')` дважды — второй вызов —
|
||
исключение UNIQUE; psql-тест `test_program_insert` — PASS.
|
||
3. Core.Tests и Web.Tests — зелёные; новые числа внесены в readme m01
|
||
и plan.md.
|
||
4. grep `external_id` по `2-db\` и `Server.WatchBody.Core` — вхождения
|
||
в миграции, функции, спецификации, домене и репозитории.
|