VEU.WathBody/1-docs/4-modules/m02-rest-api/readme.md

Модуль m02-rest-api — план разработки

План по алгоритму d-dev (std1\_rules\d\d-dev.md), адаптация к REST-модулю: вместо psql-функций — эндпоинты и обработчики; статусная модель шагов та же (⬜ → 🔄 → ✅), шлюзы «Пользователь!» — d-dev-4. Требования — module_reqs.md.

Шаг d-dev	Состав	Статус
0. Персистентная подготовка	module_reqs.md, readme.md, SKILL.md	✅
1. Список единиц к реализации	эндпоинты + компоненты (middleware, sync-обработчик, DTO) со статусами в разд. «Список единиц» ниже	✅
1.3. Утверждение списка	—	Пользователь! ✅ (2026-10-17)
2. Спецификации единиц	api_specs\ модуля — контракт каждой единицы (запрос/ответ/ошибки/тесты) — 6 файлов (DTO; конфиг; middleware; sync; чтение workouts; programs/active)	✅
2.4. Утверждение спецификаций	—	Пользователь! ✅ (2026-10-17)
3. Код и тесты	3-app\2-cli\Server.WatchBody.Web + Server.WatchBody.Web.Tests (интеграционные, docker watchbody-pg): тесты 25/25 PASS (Core 55/55 на момент закрытия модуля; после З-35 — 56/56, после З-41 — Web 81/81), сборка 0 ошибок	✅
3.4. Утверждение реализации	—	Пользователь! ✅ (2026-10-18, с переводом маршрутов на fluent Kit.Helpers.Routes)
4. Завершение	сборка и тесты зелёные; критерии приёмки module_reqs разд. 7 проверены	✅ (2026-10-18: сборка 0 ошибок, тесты Web 25/25 + Core 55/55 PASS; после З-35 — Core 56/56)

Модуль завершён (2026-10-18). Следующий по плану этапа 7 — m03-program-store.

Список единиц (шаг 1)

#	Единица	Тип	Статус
1	Конфигурация и стартовая валидация (Api.*, Db.* — tech-req 4.2) + сопоставление атлетов конфига с src.athlete (upsert по хэшу)	компонент	REQ
2	Middleware X-Api-Key → athlete_id (401 при отсутствии/чужом/заблокированном ключе)	компонент	REQ
3	POST /api/v1/sync — обработчик пакета (атомарность, идемпотентность, маппинг 7 сущностей, 409/400)	эндпоинт	REQ
4	GET /api/v1/workouts — список с пагинацией	эндпоинт	REQ
5	GET /api/v1/workouts/{id} — карточка	эндпоинт	REQ
6	GET /api/v1/programs/active — активная версия программы	эндпоинт	REQ
7	DTO пакета sync и ответов (конверт, accepted, ошибки)	компонент	REQ

Примечания:

• Доступ к БД — только репозитории m01 (Server.WatchBody.Core); прямой SQL в Web-проекте запрещён (module_reqs разд. 1).
• Прогон интеграционных тестов — PostgreSQL 17 в docker watchbody-pg (порт 5433, БД watchbody), как в m01.
• Регистрация маршрутов — fluent Kit.Helpers.Routes (Config\RouteConfig.cs, MVC-контроллеры в Controllers\, UseMvc с EnableEndpointRouting = false; решение владельца 2026-10-18, паттерн — Kit.Task.WebAp\Task.WebApp). Admin REST API (/api/admin/*) для консоли — в границах m08 (UI — отдельное Flutter Web-приложение, решение владельца 2026-10-17).
• Атомарность пакета sync — TransactionScope (Npgsql подключает соединения Kit.Helpers к ambient-транзакции); все чтения — до открытия транзакции (select-функции Kit открывают собственную). Вскрытая errata m01: jsonb-параметры функций приняты как text (каста в теле); program_version_insert дополнен идемпотентностью по p_id (🛡) — подробнее в readme m01.
• Интеграционные тесты запускают приложение in-process (WebAppStartup.Build, Kestrel на 127.0.0.1:0) против docker watchbody-pg; данные — фиксированные uuid/ключи (идемпотентность повторных прогонов), атлеты тестов создаются bootstrap'ом конфига.

Errata (после закрытия модуля)

• З-41(а) (2026-10-18, ревью этапа 7 волна 2): sync терял is_active у exercise — exercise_insert/exercise_update параметр не принимают (дизайн m01, З-34), Delete из sync не вызывался: серверный контур Ф-4.2 был недостижим (фильтр ограничений m05 строится на флаге). Исправлено: SyncService при is_active=false вызывает exercises.Delete (идемпотентно, GUID — в accepted); интеграционный тест Sync_ExerciseInactive_LogicalDelete (Web.Tests 81/81). Семантика — module_reqs / spec 06 / tech-req 2.2.