diff --git a/docs/passport.md b/docs/passport.md index d856251..40ea920 100644 --- a/docs/passport.md +++ b/docs/passport.md @@ -40,54 +40,56 @@ ## Типовые сценарии -Восемь ситуаций, ради которых всё написано. Номера шагов — по -[plan.md](plan.md). +Ситуации, ради которых всё написано. В скобках — шаги [plan.md](plan.md), +которыми сценарий закрывается; названы, а не пронумерованы, потому что план +живой и нумерация в нём поедет. -**1. Молчаливый приём** (шаги 2–3). Телефон каждые 5 минут шлёт доставку; +**1. Молчаливый приём** (приём, разбор и хранилище). Телефон каждые 5 минут шлёт доставку; сервис кладёт тело в архив, отвечает `200`, разбирает метрики в часовые объекты. Никто ничего не спрашивает и не смотрит. *Успех:* сутки работы не порождают ни одной строки лога уровня `WARN` и ни одного действия человека. -**2. Дыра закрывается сама** (шаг 3). Телефон был заблокирован ночью, +**2. Дыра закрывается сама** (разбор и хранилище). Телефон был заблокирован ночью, автоматизация не отработала, часть дня отсутствует. Средний проход (сутки) и глубокий (неделя) переприсылают окно целиком, точки доезжают. *Успех:* дыра моложе недели закрывается без вмешательства; никто о ней даже не узнаёт. -**3. Квартальный экспорт** (шаги 8–9). Раз в 2–3 месяца владелец выгружает +**3. Квартальный экспорт** (`healthlog import`, устаревание нижнего слоя). +Изредка владелец выгружает родной экспорт Apple Health и скармливает его `healthlog import`. Нижний слой за прошлое становится честным (настоящие сэмплы вместо посекундной развёртки HAE), а сырой архив получает право быть подчищенным до даты снапшота. *Успех:* экспорт разобран, покрытие периода проверено, объём архива вернулся к норме, ничего не потеряно. -**4. Агент спрашивает про здоровье** (шаги 4, 5, 7). Агент-медик по MCP +**4. Агент спрашивает про здоровье** (каталог и род агрегации, Read API, MCP). Агент-медик по MCP спрашивает каталог («что у тебя вообще есть»), затем «шаги по дням за месяц» или «пульс за вчера». Получает свёрнутый ряд с честным указанием слоя, сетки и рода агрегации. *Успех:* ответ влезает в контекст агента, число не завышено вдвое, и агенту не пришлось знать про слои, чтобы спросить правильно. -**5. Приложение берёт тренировки** (шаг 5). Разборщик тренировок запрашивает +**5. Приложение берёт тренировки** (Read API). Разборщик тренировок запрашивает заголовки за период, потом одну тренировку целиком — с маршрутом и рядом пульса. *Успех:* тренировка отдана одним пакетом в том виде, в каком её прислал Apple, без нашей интерпретации того, что в ней главное. -**6. Разбор поменялся** (шаг 3, `reindex`). Мы начали разбирать секцию, которую +**6. Разбор поменялся** (`healthlog reindex`). Мы начали разбирать секцию, которую раньше пропускали, или нашли ошибку в старом разборе. Запускается пересборка по сырому архиву: `import(экспорт) + replay(доставки по received_at)`. *Успех:* состояние пересобрано детерминированно, повтор даёт то же самое, доставки со снятым статусом `partial` подобраны. -**7. Владелец проверяет, жив ли поток** (шаг 10). Раз в сколько-то дней — +**7. Владелец проверяет, жив ли поток** (наблюдаемость). Раз в сколько-то дней — взгляд в `/stats`: когда была последняя доставка, сколько точек, есть ли тишина, какие строки не легли в словарь кодов. *Успех:* один экран отвечает «всё идёт» или «встало тогда-то», без залезания в SQLite. -**8. Приехало незнакомое** (шаг 3). HAE обновился и прислал новую метрику, +**8. Приехало незнакомое** (разбор и хранилище). HAE обновился и прислал новую метрику, новую форму точки или новую секцию. Тело сохраняется, ответ — `200`, разбор честно помечает доставку `partial` и перечисляет непокрытое. *Успех:* данные в архиве и восстановимы, факт виден в логе и `/stats`, а @@ -127,16 +129,16 @@ HAE), а сырой архив получает право быть подчищ | Проект | Что смотреть | | --- | --- | -| [dogsheep/healthkit-to-sqlite](https://github.com/dogsheep/healthkit-to-sqlite) | Прямой прототип `healthlog import` (шаг 8): разбор `export.xml` в SQLite, включая маршруты тренировок из GPX и обход того, что файл не влезает в память | +| [dogsheep/healthkit-to-sqlite](https://github.com/dogsheep/healthkit-to-sqlite) | Прямой прототип `healthlog import`: разбор `export.xml` в SQLite, включая маршруты тренировок из GPX и обход того, что файл не влезает в память | ### Отдача агентам | Проект | Что смотреть | Оговорка | | --- | --- | --- | -| [HealthyApps/health-auto-export-mcp-server](https://github.com/HealthyApps/health-auto-export-mcp-server) | Официальный MCP поверх тех же данных: набор инструментов и их именование (шаг 7) | Правило размера ответа там **не решено** — в инструкции честно написано «помните про контекст, данные может понадобиться агрегировать». Значит на шаге 5 брать готовое неоткуда | +| [HealthyApps/health-auto-export-mcp-server](https://github.com/HealthyApps/health-auto-export-mcp-server) | Официальный MCP поверх тех же данных: набор инструментов и их именование | Правило размера ответа там **не решено** — в инструкции честно написано «помните про контекст, данные может понадобиться агрегировать». Значит для Read API брать готовое неоткуда | | [meltforce/FreeReps](https://github.com/meltforce/FreeReps) | Self-hosted сервер здоровья с MCP-интерфейсом — второй взгляд на тот же контракт | Тянет за собой дашборд и визуализацию, то есть нашу границу «хранилище, а не аналитика» не держит | -### Слои, свёртка и род агрегации (шаги 4–5) +### Слои, свёртка и род агрегации Здесь чужого опыта больше всего, и он старше нашей задачи на двадцать лет.