233 lines
22 KiB
Markdown
233 lines
22 KiB
Markdown
# Технические требования: WatchBody («Феникс 6X») v1
|
||
|
||
> Шаг 5 процесса разработки (`std1\_process\process.md`).
|
||
> Источники: [vision.md](../1-reqs/vision.md) v1.5,
|
||
> [requirements.md](../1-reqs/requirements.md) (утверждён, раздел 7 —
|
||
> открытые вопросы), [architecture.md](../2-arch/architecture.md)
|
||
> (утверждена), дизайн LLM-планирования, документ форматов,
|
||
> UI/UX-рекомендации ([ui-ux-recommendations.md](ui-ux-recommendations.md)).
|
||
> Версия 1.1 — **УТВЕРЖДЕНО** (2026-10-17; интеграция документа метрик —
|
||
> Ф-13, Safety-пороги, daily_log — утверждена вместе с документом).
|
||
> Версия 1.2 — черновик (2026-10-17): errata ревью (З-6, З-11) +
|
||
> интеграция документа перерывов (Ф-14: сущность `break`,
|
||
> `session_kind`).
|
||
> Версия 1.3 — черновик (2026-10-17): волна 2 — Р1-А (daily_log v1
|
||
> поля), Р2-Б (UUID PK клиентских сущностей, маппинг id не нужен),
|
||
> Р3-А (Safety на телефоне), З-7 (RPE 1–10); UI/UX-стандарт
|
||
> (`ui-ux-recommendations.md`). Утверждение — Пользователь!
|
||
> Версия 1.4 — **УТВЕРЖДЕНО** (2026-10-17): ревью №2
|
||
> (`0-mng\review-2026-10-17-2.md`) — сущность `break` согласована с
|
||
> `src.breaks` (З-17), ОВ-7 — таргет `fenix6x` 280×280 (З-18),
|
||
> ОВ-10 закрыт (З-19, О-1-А), `Safety.HrStrengthMax` (З-20),
|
||
> интервал fetch 15 минут (З-21), грамматика «…с половиной» (З-26,
|
||
> О-2-Б), `Progression.IsoStepKg` (З-27, О-3-А). Ревью №3: решение
|
||
> ОВ-11 — импорт пакета программы (З-31, О-4-Б).
|
||
|
||
## 1. Решения открытых вопросов (закрытие раздела 7 requirements)
|
||
|
||
| # ОВ | Решение | Обоснование |
|
||
|---|---|---|
|
||
| 1. Максимальная ЧСС | Формула Танаки: `HRmax = 208 − 0,7 × возраст`; ручной ввод `Hr.MaxBpm` перекрывает расчёт | Точнее для 45+ (профиль пользователя); ручной ввод — окончательная истина |
|
||
| 2. Офлайн-STT | **Vosk** (малая русская модель ~50 МБ) + узкая грамматика команд (Ф-1.2: числа и слова «подход/вес/отдых/секунд/РПЭ» — «РПЭ 8» ставит RPE последнему
|
||
подходу, Ф-13.3); TTS-подтверждения — системный Android TTS | Работа без сети, малый словарь → устойчивость к шуму; sherpa-onnx — запасная кандидатура, если точность < КУ-1 на контрольной тренировке |
|
||
| 3. Канал телефон ↔ часы | **Штатная трансляция пульса часов «Broadcast Heart Rate», приём по BLE** — стандартный Heart Rate Service 0x180D (errata ОВ-3 от 2026-10-19: companion-канал Connect IQ на fenix 6X нереализуем — CIQ ≤ 4.1.7, `Communications` в полях данных только с API 5.0). Передаётся: текущий пульс (≈1 Гц), заряд часов (Battery Service, если транслируется). Канал односторонний (часы → телефон): таймер отдыха на часах автономный (настройка поля, умолчание `Rest.DefaultSec`; Ф-2.4 errata). Транспорт скрыт интерфейсом `WatchTransport` (мультичасовая инфраструктура, указание владельца 2026-10-19: любые часы со стандартной BLE-трансляцией работают без изменений кода; CIQ 5+/ANT+ — будущие реализации интерфейса). Garmin Connect Mobile не требуется; канал может не доставлять — обе стороны деградируют молча (Ф-2.4, Ф-3.2) | Проверка на устройстве владельца в m12: пульс доходит на телефон при активном экране часов |
|
||
| 4. Расписание fetch | Внешний планировщик ОС: systemd timer (Linux-сервер) / Планировщик задач (Windows) вызывает `--mode fetch`; внутри сервера планировщика нет. Интервал вызова — 15 минут (параметр планировщика ОС, в код не входит); вместе с лагом синхронизации часов с Garmin Connect укладывается в БЦ-5 (архив ≤ 30 минут после тренировки) | Проще, надёжнее, не дублирует средства ОС |
|
||
| 10. Источник .fit атлетов без учётки владельца | v1 — только папка импорта (`--mode import`); `fetch` работает под единственной учёткой владельца; собственные учётки атлетов в конфиге — кандидат v2. Уточнение владельца: атлет регистрируется на телефоне (имя), привязка — по uuid клиентского приложения | Не раздувать v1; деградация уже работает (решение владельца О-1-А, З-19) |
|
||
| 11. Импорт пакета программы | `--mode import` принимает `program-import.json` (формат — `program-import-format.md`): пакет маппится на `src.program` (`external_id` UNIQUE) и `src.program_version.body`; повторный импорт с тем же `external_id` — новая версия `program_version`; секция `profile` пакета в v1 не переносится — Safety-порогами управляет только конфиг `Safety.*` | Пакет — механизм эксплуатации (уточнение владельца); иначе путь доставки программы атлету в v1 не закрыт (ревью №3, О-4-Б) |
|
||
| 5. Формула 1ПМ | **Эпли**: `1ПМ = w × (1 + reps/30)` | Стандарт индустрии; при reps ≤ 10 различие с Бжицки < 2 % |
|
||
| 6. UI телефона | **Jetpack Compose** + Material 3 (тёмная тема по умолчанию) | Актуальный стек Kotlin; крупные зоны касания — Min touch target 48 dp (Ф-3.6) |
|
||
| 7. Модели часов v1 | Таргет v1 — `fenix6x` (280×280, MIP, кнопки). Fenix 6 (260×260) и 6S (240×240) добавляются отдельными таргетами с собственными макетами (Ф-2.8) по фактическому парку (уточнение владельца 2026-10-17, изменение vision 1.5) | Якорные часы владельца — Fenix 6X; «одно разрешение 260×260» в ТЗ — описка исходника |
|
||
| 8. Сопоставление телефон ↔ .fit | Окно ± 15 минут по времени начала (Ф-8.4); при нескольких кандидатах — ближайший по времени | ✅ закрыт в requirements |
|
||
|
||
## 2. Форматы обмена
|
||
|
||
### 2.1. Конверт синхронизации (телефон → сервер)
|
||
|
||
`POST /api/v1/sync`, JSON-массив записей (пакет ≤ 50), каждая:
|
||
|
||
```json
|
||
{
|
||
"client_guid": "uuid-v4",
|
||
"entity": "workout | workout_set | exercise | program_version | profile | daily_log | break",
|
||
"op": "upsert",
|
||
"data": { ...схема сущности... }
|
||
}
|
||
```
|
||
|
||
Ответ: `{ "accepted": ["guid1", ...] }` (все или ничего — пакет
|
||
атомарен; 409 при конфликте версии программы — перезапись на телефоне
|
||
после перечитывания). Повтор пакета безопасен: сервер отвечает тем же
|
||
`accepted` по уже принятым GUID (идемпотентность, Ф-7.4). Р2-Б: PK
|
||
клиентских сущностей — UUID (генерирует телефон; строки «только .fit» —
|
||
сервер): ссылки дочерних записей — те же UUID, маппинг id не нужен.
|
||
|
||
### 2.2. Сущности `data` (ключевые поля)
|
||
|
||
- `exercise`: `exercise_id` (uuid), `name`, `group` (push|pull|legs|core|…),
|
||
`is_base` (bool), `is_active` (bool) — повторная отправка с
|
||
`is_active=false` — логическое удаление на сервере (З-41(а));
|
||
- `workout`: `workout_id` (uuid), `started_at`/`ended_at` (UTC ISO 8601),
|
||
`status` (active|finished|cancelled), `session_kind`
|
||
(normal|return|deload|test — Ф-14.5), `program_version_id` (nullable),
|
||
`avg_hr`;
|
||
- `workout_set`: `workout_id`, `exercise_id`, `seq`, `weight_kg`, `reps`,
|
||
`done_at`, `source` (voice|watch|edit), `in_plan` (bool), `rpe` (int? 1–10, З-7),
|
||
`knee_pain` (int? 0–10, только группа «ноги»);
|
||
- `profile`: `sex`, `birth_year`, `weight_kg`, `hr_max` (nullable);
|
||
- `break`: `kind` (NULL до ответа атлета), `source` (телефон передаёт
|
||
`manual` — объявление простоя заранее; `auto` проставляет сервер по
|
||
пропускам ≥ 4 дней, Ф-14.1), `started_on`, `planned_return`, `note`;
|
||
`ended_on` проставляет сервер первой сессией после возврата
|
||
(совпадает с `src.breaks`, З-17);
|
||
- `daily_log`: `date` (YYYY-MM-DD), `bp_sys`, `bp_dias`, `weight_kg`,
|
||
`hr_resting`, `wellbeing` (1–5 — Р1-А, поля v1; v2 добавит
|
||
`waist_cm`, `sleep_h`);
|
||
- `program_version`: JSON-схема программы из дизайна LLM-планирования
|
||
(разд. 2) + `athlete_id` (выводится из ключа, в теле не передаётся).
|
||
|
||
### 2.3. Канонический JSON тренировки (сервер, из .fit)
|
||
|
||
Из `FitParser` → `workout_facts.facts_json`: `session` (тип, старт,
|
||
длительность), `laps[]` (индекс, старт, длительность), `records[]`
|
||
(`t_offset_s`, `hr`), `sets[]` (упражнение/повторы/вес — если писались),
|
||
`fit_file_id`, `device`. Схема версионная: `"schema": "workout-facts/1"`.
|
||
|
||
### 2.4. CSV-выгрузка (AdminWeb)
|
||
|
||
Разделитель — `;`, кодировка UTF-8 c BOM (Excel), заголовок первой
|
||
строкой: `athlete;date;duration_min;avg_hr;sets;exercises;adherence_pct`.
|
||
Строка — тренировка; выборка = текущий фильтр таблицы.
|
||
|
||
## 3. Спецификация потребления Kit.Helpers
|
||
|
||
Библиотека — `3-app\1-lib\Kit.Helpers` (std1, net10.0, Npgsql 10);
|
||
потребление без изменений исходников (полная спецификация —
|
||
[kit-helpers-spec.md](kit-helpers-spec.md)):
|
||
|
||
- `Kit.Helpers.SqlHelperAbstract` (`SqlHelperPostgres`, fluent
|
||
`SqlHelperFluent`) — доступ к PostgreSQL (единственный путь к БД из
|
||
кода сервера; строка подключения — `Db.ConnectionString`; З-42 —
|
||
фактическое имя компонента);
|
||
- `Log.Logger` — файловые логи сервера (`Log.Path`, уровень `Info`);
|
||
в sync-контуре v1 используется `ILogger<SyncService>` (Kit `Log.Logger`
|
||
не настроен и без папки логов бросает — errata m04 №4; файловые логи —
|
||
последующие модули);
|
||
- `JsonHelper` — в v1 не потребляется (System.Text.Json напрямую, З-42);
|
||
- остальное (Cache, Http, Session) в v1 не потребляется.
|
||
|
||
## 4. Схема конфигурации и правила валидации
|
||
|
||
### 4.1. Телефон (Preferences)
|
||
|
||
| Параметр | Тип | Валидация |
|
||
|---|---|---|
|
||
| `Server.BaseUrl` | string | абсолютный https:// URL — иначе экран настроек не даёт сохранить |
|
||
| `Server.ApiKey` | string | непустой |
|
||
| `Sync.WifiOnly` | bool | — |
|
||
| `Hr.MaxBpm` | int? | 120–240 или пусто (расчёт по Танаке) |
|
||
| `Rest.DefaultSec` | int | 30–600 |
|
||
| `Safety.BpCancelSys / BpCancelDias` | int | умолчания 150/90 (документ метрик, Р3-А) |
|
||
| `Safety.BpCardioSys / BpCardioDias` | int | умолчания 140/90; ≤ BpCancel |
|
||
| `Safety.RestingHrSitting` | int | умолчание 90 |
|
||
| `Safety.HrStrengthMax` | int | 100–180 (умолчание 120, З-20) |
|
||
| `Safety.LightWeekHrRise` | int | умолчание 8 |
|
||
|
||
🛡 Р3-А: телефонные `Safety.*` — источник экрана допуска (офлайн);
|
||
серверные `Safety.*` (п. 4.2) — для серверных правил (`red_flags`);
|
||
совпадение значений — ответственность владельца конфигурации (общая
|
||
синхронизируемая сущность — кандидат v2).
|
||
|
||
### 4.2. Сервер (`appsettings.json`)
|
||
|
||
| Параметр | Тип | Валидация (startup, `--mode *`) |
|
||
|---|---|---|
|
||
| `Api.Key` | string | непустой; уникальность среди `Api.Athletes[].apiKey` |
|
||
| `Api.Athletes` | list | `{name}` непусто, `{apiKey}` непустой; дубликаты ключей — фатально |
|
||
| `Admin.Login / Admin.PasswordHash` | string | непустые; хэш — PBKDF2 (100k итераций), префикс `pbkdf2$` |
|
||
| `Db.ConnectionString` | string | тест подключения при старте — фатально при неудаче |
|
||
| `Garmin.Login/Password` | string | обязательны для `--mode fetch` (иначе код возврата 1) |
|
||
| `Garmin.AthleteName` | string | обязателен для `--mode fetch` (m07, решение гейта 1.3): имя атлета `src.athlete`, на которого пишутся факты (изоляция 🛡); не найден → код 1 |
|
||
| `Garmin.DownloadDir` | path | умолчание `data it`; папка-кэш скачанных .fit (по activityId) |
|
||
| `Garmin.BaseUrl` | string | умолчание `https://connect.garmin.com`; замена точек входа для тестов/прокси |
|
||
| `Garmin.DownloadDir / Import.Dir / Import.ArchiveDir` | path | создание при старте; недоступность — фатально |
|
||
| `Progression.BaseStepKg` | double | 0,5–10 |
|
||
| `Progression.IsoStepKg` | double | 0,25–5 (умолчание 1,0 — коридор метрик «+0,5–1 кг», решение владельца О-3-А, З-27) |
|
||
| `Progression.BackoffPercent` | int | 1–20 |
|
||
| `Deload.MaxWeeks` | int | 3–12 |
|
||
| `Safety.BpCancelSys / BpCancelDias` | int | 120–200 / 70–130 (умолчания 150/90) |
|
||
| `Safety.BpElevatedSys / BpElevatedDias` | int | умолчания 140/95 (З-37: переименовано из `BpCardio*`, Dias 95 по факту кода; проверка «≤ BpCancel» не применяется — коридоры АД документа метрик перекрываются, spec 01 m04) |
|
||
| `Safety.HrRestingDays` | int | 1–30 (умолчание 14) — окно базового пульса покоя |
|
||
| `Safety.HrBaselineMin` | int | 1–14 (умолчание 3) — минимум значений для базового |
|
||
| `Safety.WellbeingDays` | int | 1–7 (умолчание 2) — длина серии самочувствия |
|
||
| `Safety.LightDayCount` | int | 2–7 (умолчание 3) — порог отмены/лимит серии |
|
||
| `Safety.KneePainMin` | int | 1–5 (умолчание 1) |
|
||
| `Safety.KneeRepeatSessions` | int | 2–5 (умолчание 2) |
|
||
| `Progression.MissDaysForBreak` | int | 2–14 (умолчание 4, Ф-14.1) |
|
||
| `Progression.ReturnMinFactor / ReturnMaxFactor` | double | 0.3–0.9 / (0.5; 1] (умолчания 0.6/0.9) — границы коэффициента возврата |
|
||
| `Db.MigrationsDir` | path | каталог миграций `--mode migrate` (З-36); умолчание — migrations рядом с исполняемым файлом |
|
||
| `Log.Path / Log.Level` | — | уровень: Debug/Info/Error |
|
||
|
||
Примечания (З-37 п. 3): `Safety.RestingHrSitting`, `Safety.HrStrengthMax`,
|
||
`Safety.LightWeekHrRise` (разд. 4.1) — потребление — телефон (m09);
|
||
сервер в v1 не читает (мёртвых ключей в appsettings нет, Р3-А).
|
||
Регистр ключей — camelCase по факту конфигов (З-37 п. 5).
|
||
|
||
Валидация конфигурации выполняется при старте любого режима; ошибки —
|
||
в лог и stderr, код возврата 1 (раздел 2.3 requirements).
|
||
|
||
## 5. Технические решения по компонентам
|
||
|
||
- **`FitFetcher`**: реализация логина Garmin Connect (SSO-последовательность)
|
||
на C# — по контракту семьи библиотек `garminconnect` (подписи запросов,
|
||
OAuth1-заголовок); при блокировке — решение ОВ шага 7 (fallback: папка
|
||
импорта уже работает независимо). Пометка прототипа итерации 1.
|
||
- **`FitParser`**: официальный **Garmin FIT SDK for C#**; парсинг —
|
||
потоковый, файл читается один раз; сбой одного файла не останавливает
|
||
пакет (код возврата 2).
|
||
- **`SyncQueue`**: таблица Room `sync_pending(guid, entity, payload,
|
||
created_at)`; отправка — WorkManager (сетевое ограничение учитывает
|
||
`Sync.WifiOnly`); ретрай — экспоненциально, 1 мин → 64 мин.
|
||
- **`VoiceInput`**: Vosk-API (Kaldi) как service в процессе приложения;
|
||
грамматика — JSON-словарь `[«подход», «вес», «отдых», «на», «секунд»,
|
||
«с половиной», 0–999]`; числа — постобработка («сто двадцать» → 120;
|
||
«…с половиной» → +0,5 кг — решение владельца О-2-Б, З-26).
|
||
- **`AdminWeb`** (решение владельца 2026-10-17): отдельное Flutter
|
||
Web-приложение (`3-app\3-web\admin-web`); бэкенд — admin REST API в
|
||
`Server.WatchBody.Web` (`/api/admin/*`): логин (логин/пароль →
|
||
Bearer-токен сессии), атлеты (список/создание/смена ключа/
|
||
блокировка), тренировки, программы, метрики, CSV-выгрузка
|
||
(генерация CSV — на сервере, п. 2.4). Пароль — PBKDF2 (см. 4.2);
|
||
графики — штатные средства Flutter.
|
||
- **HTTPS**: обратный прокси (nginx/Caddy) терминирует TLS; Kestrel —
|
||
только localhost — вопрос развёртывания, вне кода.
|
||
|
||
## 6. UI/UX-стандарт (обязательные правила)
|
||
|
||
Источник — [ui-ux-recommendations.md](ui-ux-recommendations.md);
|
||
проверяемые требования:
|
||
|
||
1. **Часы:** семантика кнопок неизменна на всех экранах (UP/DOWN —
|
||
выбор, START — подтвердить, BACK — отмена); ключевое действие —
|
||
≤ 3 нажатий и ≤ 5 секунд; шрифт ключевых цифр ≥ 22–26 px
|
||
(`FONT_NUMBER_*`); предупреждения Safety закрываются только явной
|
||
кнопкой (не исчезают сами); вибро-паттерны различаются
|
||
(подход/отдых/предупреждение); планирование/графики/настройки на
|
||
часах запрещены.
|
||
2. **Телефон:** шрифт ≥ 16 pt, контраст WCAG AA (≥ 4.5:1), цели
|
||
касания ≥ 44 pt (требования Ф-3.6); действия одной руки — в нижней
|
||
трети экрана; пикеры с шагом 2,5 кг, умолчание — последний вес;
|
||
RPE/боль — сегмент-контролы; уведомления — только значимые;
|
||
настройка размера шрифта.
|
||
3. **Админ-консоль:** десктоп-first; подтверждение предложений —
|
||
дифф + «Принять/Отклонить/Править»; экспорт/бэкап одной кнопкой.
|
||
4. **Приёмка:** эвристическое ревью по 11 эвристикам (MDPI 2024) на
|
||
каждый экран; SUS ≥ 80 — порог релиза; приёмка часов — только на
|
||
реальном Fenix (симулятор — для разработки).
|
||
|
||
## 7. Чек-лист шага 7 (проверки прототипами)
|
||
|
||
1. Канал часов: пульс доходит на телефон при активном экране часов (ОВ-3; errata 2026-10-19 — транспорт BLE-трансляция «Broadcast Heart Rate», таймер отдыха автономный на часах — m13; вибрация конца отдыха и метрики подхода Lap→Lap — приёмка m13) — итерация 5 (m12).
|
||
2. Логин Garmin Connect из C# (FitFetcher) — итерация 2.
|
||
3. Vosk: точность команд в шумном зале ≥ КУ-1 — итерация 2.
|
||
4. Сопоставление телефон ↔ .fit на реальной тренировке — итерация 3.
|