Техническое задание Модуль «SEOMA Health» — личный ассистент здоровья Версия 1.2 · 15 июля 2025 г.

0 Содержание

1 Введение и цели
2 Глоссарий
3 Персоны и сценарии использования
4 Область проекта (Scope)
5 Подробные функциональные требования
5.1 Подключение источников данных
5.2 Импорт и валидация метрик
5.3 Расчёт KPI
5.4 Генерация совета (LLM)
5.5 Панель пользователя (WordPress)
5.6 Морфинг и HUD в Unity‑клиенте
5.7 Уведомления и TTS
6 Нефункциональные требования
7 Технологический стек
8 Архитектура развертывания (контекст + последовательности)
9 Модель данных и шифрование
10 API‑спецификации (WordPress REST)
11 LLM — prompt‑дизайн и слоты
12 План тестирования
13 Календарный план и спринты
14 Смета и OPEX (подробно)
15 Риски и митигация
16 Приложения

1 Введение и цели

SEOMA Health превращает «сырые» числовые данные носимых устройств в ясный визуальный прогресс и один‑два действенных совета в день. Модуль должен:

повысить Day‑7 retention Капсулы ≥ +15 п.п.;
конвертировать ≥ 20 % активных в подписку «Econom»;
не выходить за дневной лимит 1 с обработки на пользователя.
импорт метрик Apple Health/Google Fit/Withings, расчёт KPI, ежедневный совет локальной LLM, визуальный HUD-морфинг в Unity и автоматическая оценка калорийности блюда по фотографии (точность не хуже ± 20 % для 80 % снимков, ответ ≤ 4 с).

2 Глоссарий

Термин	Определение
Observation	Строка сырых данных (тип, значение, ед., ts, источник).
SleepScore	Нормализованная оценка сна 0–100 (см. формулу 5.3).
Tip	≤ 150 символов, plain‑text, генерируется LLM ежедневно.
Morph Target	Blend‑shape, дающий визуальный эффект «‑5 кг» или «‑10 кг».
JWT‑Capsule	Токен, подписанный RS256, разрешения health:r.

3 Персоны и сценарии

Анна, 29 лет — офис‑менеджер, Apple Watch. Хочет ориентир: «нормально ли 6 ч 42 мин сна».
Олег, 35 лет — продукт‑менеджер, Google Fit и весы Withings. Цель — «минус 7 кг к отпуску».

User‑flow «утро»: 1 07:15 WP‑Cron сформировал Tip.
2 FCM push → телефон.
3 Олег открывает Капсулу: аватар озвучивает «Сон 84 %, вес −0,3 кг, отлично!».
4 Олег видит кольцо KPI + минус 0,5 см в талии на аватаре.

4 Область проекта

Включено

OAuth 2/PKCE к Apple Health, Google Fit, Withings.
Импорт сна/шагов/пульса/веса каждые 60 мин + пуш‑триггер веса.
KPI‑движок, генерация Tip локальной LLM (Mistral‑7B‑Health, int‑4).
UI — Gutenberg‑блок, нативный Push, TTS аватара, Blend‑shape морфинг.

Исключено

Медицинские диагнозы, анализы крови, нутриенты (Q4 2025).
Версии нагрузок для Garmin/Fitbit (Q4 2025).

5 Подробные функциональные требования

5.1 Подключение источников

OAuth flows — PKCE; refresh‑tokens AES‑256‑GCM.
При отзыве доступа (invalid_grant) плагин показывает баннер «Нужно переподключить».
Edge‑case: Apple Health не возвращает шаги — создаём Observation steps=0 c флагом fallback=true.

5.2 Импорт и валидация

Cron → provider API, пачки по 100 Observation.
Дедуп по (type,ts) UNIQUE.
Правило валидации: если heart < 30 или > 260 BPM → discard, log в sentry.

5.3 KPI‑формулы

SleepScore = clamp( (sleepMinutes/targetMinutes)*100 , 0 , 100 )

StepKPI = clamp( (steps/goalSteps)*100 , 0 , 100 )

WeightΔ = ((current — base) / base) * 100

targetMinutes берём из настроек (по умолчанию 420 мин), goalSteps — 8000.

5.4 Генерация совета

Prompt‑темплейт:

System: «Ты лаконичный фитнес‑коуч, ответ ≤ 150 символов, без эмодзи»

User: «Сон:{SleepScore} Шаги:{StepKPI} ВесΔ:{WeightΔ} Locale:{lang}»

LLM отвечает ≤ 800 мс p95, иначе fallback статический совет «Сегодня сфокусируйтесь на {weakestKpi}».
Кэш wp_cache_set(‘health_tip’,sha1(uid+date)) 24 ч чтобы избежать двойного биллинга.

5.5 Панель пользователя (WordPress)

React 18 + Chart.js 4 «sparkline 30 дней».
Lazy‑load на viewport, бюджет JS ≤ 45 KB gz.
А11y — WCAG 2.1 AA, ARIA‑labels.

5.6 Морфинг и HUD (Unity)

HealthManager MonoBehaviour подписывается на GET /health/kpi каждые 5 мин.
Tween кольца KPI: DOTween from oldVal → newVal 0.6 s, easeOutCubic.
Морфинг: текущий WeightΔ → линейная интерполяция между 0 и TargetBlend («–10 кг» ≈ –7 %).

5.7 Уведомления и TTS

Push — Web‑Push (VAPID) + FCM/APNs, TTL = 6 ч.
Unity TTS — AWS Polly neural; автодетект RU/EN/ES языка совета.

6 Нефункциональные требования

Метрика	Порог
Импорт 1 польз.	≤ 500 мс REST, 50 KB traffic
Cron Import 10 k	≤ 5 мин CPU < 70 % of 1 vCPU
Dashboard TTI	≤ 1000 мс (Moto G7, 4G)
LLM latency p95	≤ 800 мс
Uptime квартал	≥ 99 %
GDPR erase SLA	≤ 24 ч

7 Технологический стек

WordPress-плагин (основной UI):

React 18
Chart.js 4 — графики (sparkline, KPI)
Tailwind CSS — стилизация интерфейса (быстро, современно)
Gutenberg API — для кастомных блоков в WP

Unity-клиент:

Unity 2022+ (URP)
DOTween Pro — анимация морфинга и KPI-колец
Odin Inspector — ускорение UI/отладки в редакторе
UnityWebRequest — REST-интеграция
AWS Polly или Microsoft Azure TTS — генерация TTS для аватара

Мобильный клиент (если будет):

Flutter — кроссплатформа
Firebase FCM — пуш-уведомления

8 Архитектура развертывания

8.1 Контекст

[Apple Health] ←→ [WP Plugin] ← REST → [RDS MySQL]

↘ push → [FCM]

[Google Fit] ←→ ↑ Cron

[Withings] ←→ ↘ REST → [LLM Service] ← llama.cpp weights

8.2 Диаграмма последовательностей «Daily Tip»

1 00:05 Cron job fetch → observations.
2 00:15 KPI calc → cache.
3 07:00 LLM call → save Tip, send Push.
4 07:05 User opens app → GET Tip → TTS.

9 Модель данных (SQL + Crypto)

Каждому пользователю создаётся user_key — random 32 B, зашифрован master‑key KMS.
В таблице observations значение шифруется AEAD_CHACHA20_POLY1305(key=user_key).
Ключ удаляется при GDPR erase.

10 API (REST)

Detailed OpenAPI 3.1 в /docs/openapi-health.json (Прил. A).

11 LLM Prompt‑дизайн

Слоты: {sleep}, {steps}, {weightDelta}, {lang}, {today}, {goal}.
Температура 0.6, топ‑p 0.9, max_tokens 60.
Guardrail regexp — запрещённых medical terms.

12 План тестирования

Добавлено fuzz‑тест преобразования единиц (кг→фунты) и snapshot‑тест UI разных локалей.

13 Календарь (Gantt в Прил. C)

Разбит на 3‑дневные задачи, параллельные потоки BE / FE / Unity. Code‑freeze — 22 сентября 2025.

14 Смета и OPEX (USD)

75 000 $.

15 Риски и митигация

Риск	P	I	План
Rate‑limit Apple Health	M	M	Back‑off + exponential retry, cache local.
LLM latency spike	H	M	Fallback static tips, alert if >1 s p95 5 мин.
BMI‑shaming content	L	H	Prompt guard + regex blacklist.