# Схема базы SQLite (`modernc.org/sqlite`, чистый Go), миграции — goose, файлы в `internal/store/migrations`. Время в текстовых колонках всегда **UTC RFC 3339** с секундной точностью: фиксированная ширина делает лексикографическую сортировку `TEXT` совпадающей с хронологией. **База производна.** Источник истины — сырой архив тел (`data/raw`); состояние пересобирается свёрткой `import(экспорт Apple) + replay(доставки по received_at)`. Поэтому терять базу неприятно, но не смертельно, а вот терять архив — смертельно. ``` ┌────────────────────────────┐ ┌──────────────────────────────┐ │ delivery │ │ bucket │ │ ───────────────────────── │ │ ──────────────────────────── │ │ id TEXT PK │ │ metric TEXT ┐ │ │ received_at TEXT │ │ layer TEXT ├ PK │ │ automation_name TEXT │ ┄┄┄┄┄▶ │ hour_utc TEXT ┘ │ │ automation_id TEXT │ первая │ units TEXT │ │ aggregation TEXT │ доставка │ payload BLOB │ │ period TEXT │ часа │ content_hash TEXT │ │ session_id TEXT │ │ points INTEGER │ │ bytes INTEGER │ │ first_ts TEXT │ │ sha256 TEXT │ │ last_ts TEXT │ │ raw_path TEXT │ │ first_delivery_id TEXT │ │ parse_status TEXT │ │ sealed INTEGER │ │ points INTEGER │ │ created_at TEXT │ │ headers TEXT │ │ updated_at TEXT │ │ derived_layer TEXT │ └──────────────────────────────┘ │ uncovered_sections TEXT │ │ skipped_entities INTEGER? │ └────────────────────────────┘ ┊ ┌──────────────────────────┐ ┌──────────────────────────┐ ┊ │ workout │ │ record │ ┊ доставка, │ ─────────────────────── │ │ ─────────────────────── │ └┄┄┄ чья версия ┄┄┄┄▶ │ id TEXT PK│ │ kind TEXT ┐ │ лежит сейчас │ name TEXT │ │ id TEXT ┘PK│ │ start_utc TEXT │ │ ts_utc TEXT │ │ end_utc TEXT │ │ tz_offset INTEGER│ │ tz_offset INTEGER│ │ payload BLOB │ │ duration_sec REAL? │ │ content_hash TEXT │ │ payload BLOB │ │ delivery_id TEXT │ │ content_hash TEXT │ │ delivery_received_at TEXT│ │ delivery_id TEXT │ │ created_at TEXT │ │ delivery_received_at TEXT│ │ updated_at TEXT │ │ created_at TEXT │ └──────────────────────────┘ │ updated_at TEXT │ └──────────────────────────┘ ┌────────────────────────────┐ │ category_value │ │ ───────────────────────── │ │ metric TEXT ┐ │ │ field TEXT ├PK │ │ value TEXT ┘ │ │ code TEXT │ │ first_seen_utc TEXT │ │ first_delivery_id TEXT │ └────────────────────────────┘ ``` Связь `bucket.first_delivery_id → delivery.id` **внешним ключом не объявлена** намеренно: доставки подрезаются ретеншеном до следующего проверенного экспорта, а объекты живут дольше. Ссылка — провенанс для разбора слияний, а не целостность. ## `delivery` — учёт принятых пакетов Одна строка на принятое тело. Само тело лежит в архиве по `raw_path` (относительный путь внутри `data/raw`). | Колонка | Смысл | |---|---| | `id` | ULID, он же имя файла в архиве | | `received_at` | время приёма, UTC | | `automation_name`, `automation_id` | какая автоматизация HAE прислала; `automation_id` нужен выводу слоя — по нему наследуется слой доставки без плотных метрик | | `aggregation` | заголовок `automation-aggregation`. Режима **не означает**: значение `Default` наблюдалось у посекундного, минутного и часового режимов одновременно | | `period` | заголовок периода (`Since Last Sync` и прочие) | | `bytes`, `sha256` | размер и хеш тела; хеш пока только для учёта | | `parse_status` | `pending` / `parsed` / `partial` / `failed`. Код ответа приёма от него **не зависит**: сохранили — значит приняли. `pending` означает «ЭТИМ разбором ещё не смотрели», а не «тела не касались»: миграция 00005 перевела сюда доставки, разобранные кодом, который частичного разбора не различал | | `points` | сколько точек дал разбор | | `headers` | все заголовки запроса JSON-объектом, кроме несущих секреты | | `uncovered_sections` | секции тела, которых разбор не покрыл, JSON-массивом имён; пустой список — `[]`. Ответ на вопрос «что останется потерянным, если тело удалить»: для `stateOfMind` он необратим, в экспорте Apple секции нет. Ретеншен обязан спрашивать его прежде, чем срезать тело | | `skipped_entities` | сколько сущностей с собственным `id` разбор пропустил (нет `id`, `id` длиннее предела, метка не разбирается, элемент не объект). Вторая половина ответа на «что потеряется, если тело удалить»: список непокрытых секций про пропущенную сущность молчит. **NULL означает «не измерялось»** и нулю не равен — так выглядят доставки, свёрнутые разбором, который пропусков не считал; читатель, принимающий по счётчику необратимое решение, обязан трактовать NULL как «не удалять» | | `derived_layer` | слой, выведенный для этой доставки. Нужен не отчётности, а самому выводу: доставка без плотных метрик наследует последний надёжно выведенный слой той же автоматизации, и без хранения этой памяти первая такая доставка после перезапуска осталась бы без слоя | Индексы: `delivery_received_at` (порядок журнала), `delivery_sha256` (учёт повторов), `delivery_automation_layer` (поиск последнего слоя автоматизации), `delivery_pending` (очередь свёртки). `delivery_pending` **частичный** — только строки со статусом `pending`. Таблица и есть очередь фоновой свёртки: воркер выбирает неразобранные доставки в порядке журнала чаще, чем раз в минуту. В установившемся режиме в индексе ноль-одна строка, тогда как полный индекс по `parse_status` хранил бы всю историю ради выборки из одной. ## `bucket` — часовой объект точек Единица хранения — час одной метрики в одном слое, а не отдельная точка. | Колонка | Смысл | |---|---| | `metric` | имя метрики как прислал HAE. Исключение — `sleep_analysis_summary`: под именем `sleep_analysis` приезжают две несовместимые схемы, и они разводятся на разные имена | | `layer` | `sample` / `raw` / `minute` / `hour` / `day`. Выводится из выравнивания меток | | `hour_utc` | начало часа, UTC. Час берётся **по началу точки** | | `units` | единицы метрики. Внутри точки их нет, они живут на уровне метрики | | `payload` | точки часа: JSON-массив исходных байтов, gzip. Точки упорядочены по началу | | `content_hash` | хеш канонической формы — **детектор изменений**, не ключ. Совпал — записи нет | | `points` | сколько точек внутри | | `first_ts`, `last_ts` | границы содержимого; каталогу разрезов, чтобы не разжимать блоб ради диапазона | | `first_delivery_id` | доставка, создавшая объект | | `sealed` | час, в который досчёт не ожидается. Правило перевода пока не определено | Таблица `WITHOUT ROWID`: обращение всегда по полному первичному ключу, и лишний уровень косвенности через rowid ни разу не нужен. Индекс `bucket_catalog` (`metric, layer, hour_utc, first_ts, last_ts, points, units`) — **покрывающий**, и это следствие той же формы таблицы: у `WITHOUT ROWID` строка целиком, вместе со сжатым `payload`, живёт в дереве первичного ключа, поэтому агрегат «какие слои есть у метрики и за какой период» без индекса тащил бы страницы содержимого — сотни мегабайт чтения на запрос каталога при 260 тысячах объектов за год. По нему же идёт поиск часов, за которые у метрики есть объекты сразу в двух слоях. Цена — около 60 байт на объект и одна вставка в дерево на запись; платит её только настоящее изменение, потому что при совпавшем хеше объект не переписывается вовсе. **Идентичность точки внутри объекта** — координаты `метрика + слой + начало + конец`, у точки-измерения конец равен началу. `source` в ключ не входит: он нестабилен и переписывается задним числом. При столкновении выигрывает более полная точка, а при равной полноте — стоящая позже в журнале (внутри одной доставки — минимум канонической формы). Провенанса у точки нет: «позже в журнале» выражено происхождением кандидата, и потому порядок свёртки обязан равняться журнальному. ## `workout` и `record` — сущности с собственным `id` Вторая единица хранения витрины. Часовой объект им не подходит: у них есть естественный ключ, они редки (за двое суток потока — две тренировки и две записи состояния разума при 44 и 52 доставленных копиях), и группировать их по часам незачем. Таблицы две, а не одна с колонкой рода: у тренировки есть заголовок, по которому идёт выборка (имя, интервал, длительность), а у записи его нет. Общая таблица либо теряла бы заголовок, либо держала колонки, пустые у пяти родов из шести. | Колонка | Смысл | |---|---| | `workout.id` | идентификатор из HealthKit. Приходит из тела и ограничен по длине разбором: уезжает и в ключ, и в записи лога | | `record.kind` + `record.id` | ключ — **пара**. Собственный `id` наблюдался живьём только у `stateOfMind`, где он UUID; форма идентификатора остальных пяти секций не наблюдалась никем, и короткий несквозной `id` в двух разных секциях затёр бы одну запись другой молча | | `kind` | верхнеуровневый ключ секции HAE **дословно** (`stateOfMind`, не `state_of_mind`): инвариант «форма Apple не транслируется» относится и к именам секций | | `start_utc` / `end_utc` / `ts_utc` | UTC RFC 3339. Конец, которого нет или который не читается, равен началу: ключ — `id`, схлопывать координаты нечем, а истина остаётся в `payload` | | `tz_offset` | смещение зоны **начала**. У `stateOfMind` всегда `0` — это значит «источник прислал UTC», а не «человек был в Гринвиче»: местной зоны у секции в потоке нет вовсе. Клиент, считающий по нему местные сутки, ошибётся | | `duration_sec` | длительность тренировки в секундах, как прислал HAE. **`NULL` означает «источник не прислал»**: ноль — законная длительность. Не вычисляется из интервала — HAE шлёт 91.746 при интервале в 91 секунду | | `payload` | сущность целиком исходными байтами, gzip: заголовок, маршрут, внутренние ряды и сводки. Маршрут — 95% веса тренировки, а такой JSON жмётся примерно в 25 раз. Внутрь SQL-функциями не заглянуть — та же плата, что у `bucket.payload` | | `content_hash` | хеш канонической формы: детектор изменений, не ключ. Тренировка переприсылается каждой доставкой, пока не доедет маршрут (44 копии дают три различных содержимых) | | `delivery_id`, `delivery_received_at` | провенанс: доставка, **чья версия лежит сейчас**, и её метка приёма. Не отчётность: по паре разрешается тай-брейк между версиями равной полноты | Индексы: `workout_start_utc` («заголовки тренировок за период» — основной запрос трекера), `record_kind_ts` («записи такого-то рода за период» — единственная форма запроса к таблице). **Ряд пульса внутри тренировки лежит в её `payload`, а не в объектах метрики `heart_rate`.** Пульс приезжает дважды — в общем потоке и внутри тренировки; это разные таблицы, и смешение задвоило бы ряд. **Замена версии условна.** Приехавшая побеждает, если не теряет содержания сохранённой (множество ключей с непустым значением плюс длины верхнеуровневых массивов); при равных наборах выигрывает версия из более поздней доставки журнала, а не свёрнутая последней. Подробности и обоснование — в `architecture.md`, раздел «Тренировки и прочие секции». ## `category_value` — реестр категориальных значений Какие перечислимые строки поток приносил и какой у них стабильный код HealthKit. HAE отдаёт фазу сна как «БДГ», контекст пульса как «Сидячий образ жизни», тип тренировки как «В помещении Ходьба» — строками локали телефона, а родной экспорт Apple говорит кодами; без словаря источники не сходятся (находка 37). Словарь фаз сна выведен сопоставлением потока с экспортом за тот же период (находка 43). | Колонка | Смысл | |---|---| | `metric` | имя метрики или секции, **то же**, которым адресуется единица хранения (`sleep_analysis_summary` после разделения схем, `workouts` у тренировок). Второе имя для того же понятия развело бы наблюдение и объект по разным ключам | | `field` | имя поля внутри точки или сущности дословно как у HAE: `value`, `context`, `name` | | `value` | строка **дословно**, как прислал HAE. Код приписывается рядом, а не подменяет её: инвариант «точки хранятся дословно» это и означает | | `code` | канонический код HealthKit. Пустая строка — законное состояние: «словарь этой строки не знает», и перечень таких строк есть заявка на пополнение словаря. **Это кэш**: код производен от словаря в бинаре, а не от журнала, и потому в отпечаток витрины не входит. Строка, переставшая приезжать, держит код прежнего словаря до пересборки | | `first_seen_utc`, `first_delivery_id` | провенанс **первой** встречи, минимум по журналу `(received_at, id)`. Минимум идемпотентен при повторной свёртке той же доставки; счётчик встреч не идемпотентен и потому не заводится вовсе. Отвечает на вопрос «когда сменился язык телефона», а язык доставки восстанавливается по `delivery.headers` | Ключ — тройка без локали, и это решение, а не упущение. Локаль приезжает заголовком `Accept-Language`, а заголовков в сыром архиве нет: они были заголовками запроса, а не телом. Доставка, восстановленная из осиротевшего тела, приходит без локали — ключ с локалью положил бы вторую строку на то же значение, то есть состояние стало бы функцией от того, уцелела ли учётная строка. Локаль при выводе кода сужает поиск по словарю; её отсутствие вывода не отменяет, если строка однозначна. Таблица `WITHOUT ROWID`: обращение всегда по полному первичному ключу, а строк единицы — на живом потоке различных значений по всем трём полям около одиннадцати. Индексов нет: чтение идёт целиком, в порядке ключа. Границы разбора не дают доставке положить больше 64 различных значений и значение длиннее 128 байт (измерено: ~11 значений, самое длинное 36 байт). Слишком длинное **отбрасывается со счётчиком, а не обрезается** — обрезанная строка неотличима от настоящей и стала бы самостоятельным ключом; сама точка при этом хранится целиком. Data-миграции у таблицы нет и быть не может: коды выводятся из тел, а тела лежат в архиве. Реестр рабочей витрины наполняется по мере свёртки новых доставок и целиком — пересборкой. Отсюда первое расхождение отпечатков после выкатки: оно законно, и отчёт `reindex` называет его ожидаемым классом «появилась единица хранения». ## Представление данных - **Точки часового объекта лежат сжатым BLOB** (`gzip`) в колонке `payload`. Чтение объекта распаковывает его **целиком**: частичного доступа к точке нет, и любая правка — read-modify-write всей пачки. Отсюда цена широкой доставки: 63 МиБ на одной координате держат транзакцию 5.15 с, а тело 40 МиБ давало 768 МиБ пика кучи, пока канонизация шла внутри транзакции. - Таблицы часовых объектов — `WITHOUT ROWID`: строка целиком, вместе со сжатым `payload`, живёт в дереве первичного ключа. Поэтому агрегатные запросы идут по покрывающему индексу `bucket_catalog`, а не по таблице. - Тела доставок в базе не лежат вовсе — они в сыром архиве (`/raw/ГГГГ/ММ/ДД/.json.gz`); в `delivery` только учёт. ## Настройки с числовым значением Без них замер не превращается в находку: пик памяти — аномалия только рядом со строкой «запись лежит сжатой и распаковывается целиком». | Настройка | Значение | Где задана | | --- | --- | --- | | `journal_mode` | `WAL` | `internal/store/store.go`, строка соединения | | `busy_timeout` | `5000` мс | там же; на устаревший снимок транзакции **не** действует | | `foreign_keys` | `on` | там же | | `journal_size_limit` | 64 МиБ | `internal/store/store.go`, `journalSizeLimit` | | чекпойнт WAL по таймеру | 1 мин | `cmd/healthlog/checkpoint.go`, `checkpointInterval` | | предел тела запроса | 64 МиБ (`ingest.max_body_mb`) | конфиг; **ретроактивен** — тем же пределом читаются тела из архива при пересборке | | таймаут чтения запроса | 5 мин (`server.read_timeout`) | конфиг; щедро: экспорт истории по мобильной сети | | таймаут отправки ответа | 30 с (`server.write_timeout`) | конфиг; маршрут приёма держит собственный бюджет | | бюджет остановки | 30 с | `cmd/healthlog/serve.go`, `shutdownTimeout` | | ретеншен сырого архива | до следующего проверенного экспорта (~2 ГБ за квартал) | правило, а не число; не реализован — задача `raw-archive-retention` | | предела на одну сущность | **нет** | задача `entity-size-limits` |