av
f8200f7f80
- секции `workouts` и `stateOfMind` покрыты разбором: тренировка лежит одной строкой вместе с маршрутом и внутренними рядами, запись — по ключу `род + id`; миграция 00007 заводит обе таблицы и возвращает в очередь `partial`-доставки с этими ключами - сущность заменяется целиком, но условно: приехавшая побеждает, если не теряет содержания сохранённой (множество ключей и длины верхнеуровневых массивов), а при равном содержании выигрывает версия из более поздней доставки ЖУРНАЛА — «побеждает приехавшая» было бы функцией порядка свёртки, и живая витрина расходилась бы с пересборкой молча - отпечаток витрины покрывает тренировки и записи и снимается одним снимком базы; отчёт `reindex` считает «было и стало» по каждой единице хранения
146 lines
16 KiB
Markdown
146 lines
16 KiB
Markdown
# Схема базы
|
||
|
||
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 │
|
||
└────────────────────────────┘
|
||
┊ ┌──────────────────────────┐ ┌──────────────────────────┐
|
||
┊ │ 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 │
|
||
└──────────────────────────┘
|
||
```
|
||
|
||
Связь `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 секции нет. Ретеншен обязан спрашивать его прежде, чем срезать тело |
|
||
| `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 ни разу не нужен.
|
||
|
||
**Идентичность точки внутри объекта** — координаты
|
||
`метрика + слой + начало + конец`, у точки-измерения конец равен началу.
|
||
`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`, раздел «Тренировки и прочие секции».
|