Files

T

раскладка av-dev повышена с канона 12 до версии 5

- три плагина слились в один `av-dev`: служебные `docs/.docs.json` и
  `tasks/.tasks.json` заменены на `.av-dev.toml` в корне, в гейте переехали пути
  трёх скриптов, вызовы скиллов переименованы по всему репозиторию
- тип задачи `goal` и `ROADMAP.md` упразднены: семь целей закрыты с причинами,
  теги сняты, объявлена стадия `support`
- метка `small`/`medium`/`large` снята из процесса — вместо «Триггеров метки» в
  review.md подраздел «Когда звать глубокое ревью»; следом разобран урожай
  doc-consistency: девять фактов сведены к одному дому

2026-09-02 09:55:28 +03:00

4.2 KiB

Raw Blame History

Конвенция: база данных и идентификаторы

Как мы устраиваем таблицы и ключи в SQLite. Актуальная схема — ../database.md; обоснование выбора ULID — архивный design.md change'а ulid-identity.

Механизировано: AUTOINCREMENT и DEFAULT (datetime('now')) в новых миграциях (internal/archrules), время мимо store.Now() (forbidigo).

Первичные ключи — ULID, не автоинкремент

PK сущности — TEXT ULID (26 символов Crockford base32), генерируется приложением в момент создания записи.
Почему ULID: сортируем по времени создания (ORDER BY id = хронология), компактен и удобен в URL/логах (без дефисов — grep и двойной клик берут id целиком), глобально уникален across таблиц — поиск по голому id находит все записи сущности в логах.
Единственная точка генерации и разбора — internal/ident: ident.NewID() при создании (в Create-методах store), ident.Parse() на входных границах. Никаких самодельных генераторов.

Канонический вид — lowercase

Генерим и храним id в нижнем регистре. Сравнение строк в SQLite побайтовое, поэтому любой внешний id (URL, форма, callback-data) ОБЯЗАТЕЛЬНО проходит ident.Parse до запроса к БД — он валидирует формат и нормализует регистр (base32 ULID case-insensitive при декодировании).
Синтаксически невалидный id трактуем как несуществующую сущность (404), без похода в БД.

Естественные и составные ключи — для деталей

У таблиц-деталей/связей допустим естественный или составной ключ вместо ULID, когда он есть по природе данных: download_infohash — PK (infohash, download_id), override — UNIQUE(download_id, field). Отдельный ULID там — мёртвый вес.
Прочие генерируемые идентификаторы (например, apply_batch_id) — тоже через ident.NewID(): единый формат, сортируемость, корреляция в логах.

Прочее

Enum-поля — обычный TEXT/INTEGER без CHECK; допустимые значения держит код (internal/store). Какие именно поля — ../database.md → «Индексы и ограничения».
Временные метки пишет приложение: store.Now() + store.FormatTime/ ParseTime (аналогично ident.NewID для id), а не дефолт в схеме — так забытая вставка падает громко. Формат и точность хранения — ../database.md; фиксированная ширина там выбрана затем, чтобы лексикографическая сортировка TEXT совпадала с хронологией. Измерение длительности — не метка времени: у внешних вызовов его засекает logging.StartCall. Таймзона отображения в UI — конфиг [general].timezone.
Миграции — goose (internal/store/migrations): SQL-файлы для DDL; Go-миграции (goose.AddMigrationContext) — когда нужен код (генерация id, backfill). При изменении структуры обновляем ER-схему ../database.md в том же change.

4.2 KiB Raw Blame History Unescape Escape