passport: ссылки на план по названиям шагов, а не по номерам

план — живой документ, его нумерация поедет при вставке или закрытии шага; паспорт меняться от этого не должен
This commit is contained in:
av
2026-08-01 21:49:43 +03:00
parent d097c43084
commit d6e8b32466
+15 -13
View File
@@ -40,54 +40,56 @@
## Типовые сценарии
Восемь ситуаций, ради которых всё написано. Номера шагов — по
[plan.md](plan.md).
Ситуации, ради которых всё написано. В скобках — шаги [plan.md](plan.md),
которыми сценарий закрывается; названы, а не пронумерованы, потому что план
живой и нумерация в нём поедет.
**1. Молчаливый приём** (шаги 23). Телефон каждые 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-интерфейсом — второй взгляд на тот же контракт | Тянет за собой дашборд и визуализацию, то есть нашу границу «хранилище, а не аналитика» не держит |
### Слои, свёртка и род агрегации (шаги 45)
### Слои, свёртка и род агрегации
Здесь чужого опыта больше всего, и он старше нашей задачи на двадцать лет.