добавлены документация проекта и каркас разработки

- README, CLAUDE.md, docs: назначение и границы, архитектура, конвенции, план - docs/local-research.md — 36 находок по формату Health Auto Export, снятых на живых данных; документация приложения местами расходится с тем, что оно шлёт - Taskfile, .golangci.yml, самодокументируемый config.example.toml
2026-08-01 12:37:03 +03:00
commit 5e2385ba6e
12 changed files with 2318 additions and 0 deletions
@@ -0,0 +1,93 @@
+# healthlog
+
+Коллектор данных Apple Health. Принимает выгрузки из
+[Health Auto Export](https://www.healthyapps.dev/apps/health-auto-export/),
+складывает их в единое хранилище и отдаёт другим моим проектам через HTTP API.
+
+## Зачем
+
+Данные о здоровье и тренировках нужны сразу нескольким приложениям: анализ
+здоровья, разбор тренировок, мотиватор по активности. Интегрировать каждое
+из них с Health Auto Export по отдельности — значит в каждом писать приём,
+дедупликацию и хранение заново.
+
+healthlog делает это один раз. Телефон шлёт данные в него, все остальные
+проекты берут данные из него.
+
+## Границы
+
+Это **хранилище**, а не аналитика. healthlog принимает, дедуплицирует,
+хранит и отдаёт. Он не считает агрегаты, не переименовывает поля Apple и не
+интерпретирует значения — этим занимается тот, кто данные читает.
+
+Единственный источник — Health Auto Export (куплен, пожизненный премиум).
+Другие источники не поддерживаем.
+
+## Как устроено
+
+```
+iPhone ──HTTPS POST──► healthlog ──► сырой архив (файлы, .json.gz)
+                            │              │
+                            │              └── источник истины, не трогаем
+                            ▼
+                       SQLite-витрина ──► HTTP read API ──► мои приложения
+                       (пересобирается из архива)
+```
+
+Приём сначала кладёт тело запроса на диск как есть и только потом разбирает.
+Значит, ошибка в нашем разборе не может привести к потере данных: витрина
+пересобирается из архива командой `healthlog reindex`.
+
+Подробности — [docs/architecture.md](docs/architecture.md).
+
+## Состояние
+
+В разработке. Готовы шаги 1–2 из 8: сервис принимает пакеты и складывает их в
+сырой архив. Разбора, витрины и read API ещё нет — план в
+[docs/plan.md](docs/plan.md).
+
+## Команды
+
+```
+healthlog serve        приём + read API
+healthlog import       заливка файлов в архив и витрину   (шаг 6)
+healthlog reindex      пересборка витрины из сырого архива (шаг 3)
+healthlog healthcheck  проверка живости для docker HEALTHCHECK
+```
+
+## Локальный запуск
+
+Конфиг необязателен — без него берутся умолчания (`:8080`, `./healthlog.db`,
+`./raw`). Для своих значений скопируй `config.example.toml` в `config.toml`.
+
+```
+task run
+```
+
+Проверка:
+
+```
+curl localhost:8080/healthz
+curl -X POST localhost:8080/api/v1/ingest -d '{"data":{"metrics":[]}}'
+```
+
+### Подключение телефона по локальной сети
+
+Сервис слушает все интерфейсы (`addr = ":8080"`), так что телефон в той же
+сети достучится по IP машины. В Health Auto Export заводится одна
+автоматизация: **REST API**, формат **JSON**, минимальная гранулярность
+(«Summarize Data» выключен), URL вида `http://<ip-машины>:8080/api/v1/ingest`.
+
+Если `auth.write_tokens` пуст, проверка токена выключена — для доверенной
+локальной сети этого достаточно, сервис пишет об этом `write auth disabled`
+на старте. Для доступа снаружи понадобится и токен, и TLS (шаг 8).
+
+
+## Документация
+
+- [docs/architecture.md](docs/architecture.md) — устройство, схема данных, API, принятые решения
+- [docs/conventions.md](docs/conventions.md) — как пишем код
+- [docs/plan.md](docs/plan.md) — шаги и отложенное
+- [docs/local-research.md](docs/local-research.md) — что показал реальный поток
+  Health Auto Export; источник истины по формату, документация приложения
+  местами расходится с тем, что оно шлёт