заведён канон общих конвенций для личных проектов

- 13 конвенций по осям arch / lang / stack / common; репозитории берут
  оттуда копии в свой docs/conventions/ и коммитят их у себя
- conv — синхронизация копий: add / status / diff / pull / push, локальные
  регионы исключены из сравнения, поэтому расхождение не даёт шума
This commit is contained in:
av
2026-07-25 18:18:18 +03:00
commit 4a59c71737
15 changed files with 2142 additions and 0 deletions
+74
View File
@@ -0,0 +1,74 @@
---
status: рекомендуемая
---
# Время
Один формат времени на всё приложение: хранение, логи, API, обмен с
внешними системами. Разные форматы в разных слоях — источник ошибок,
которые всплывают через полгода на границе перехода на летнее время.
## Формат
- **RFC 3339, UTC, суффикс `Z`**: `2026-06-28T11:23:45Z`.
- **Ширина фиксируется на каждый носитель** и внутри него не плавает.
Лексикографическая сортировка равна хронологии только среди строк
одинаковой длины: `…00.123Z` сортируется раньше `…00.12Z`, хотя
хронологически позже. Ради этого формат и фиксируется — `ORDER BY
created_at` по текстовому полю обязан давать порядок событий.
- Разные носители могут иметь разную точность: строки БД и строки лога
между собой никогда не сравниваются. Требование — не «одна точность на
приложение», а «внутри колонки и внутри потока логов ширина одна».
- Локальное время не хранится и не передаётся **нигде** — ни в БД, ни в
логах, ни в JSON API.
## Генерирует приложение, а не хранилище
- Единая точка получения «сейчас» и единая точка форматирования и разбора —
как с идентификаторами (`arch/db-identifiers.md`). Прямые вызовы часов по
коду не разбросаны: иначе ни формат, ни зона не гарантированы.
- **Дефолты в схеме БД не используем.** Забытая вставка `created_at`
должна падать громко, а не тихо получать значение от БД — иначе
расходятся источник времени (сервер БД) и его формат.
## Длительность — не метка времени
Измерение длительности операции — отдельная величина: число (обычно
миллисекунды) в поле вида `duration_ms`, а не разность двух меток и не
время в формате выше. Засекает её тот слой, который делает вызов.
**Интервал измеряется монотонными часами процесса**, а не вычитанием
сохранённых меток: стенные часы подводит NTP, они могут шагнуть назад и
дать отрицательную длительность. Из этого следует, что источник меток
времени и источник интервалов — разные, даже если оба называются «часы».
## Зоны
Единственное место, где появляется не-UTC, — **отображение пользователю**.
Зона берётся из конфигурации (`arch/config.md`), значение по умолчанию —
`UTC`. На хранение, сортировку и логи она не влияет.
Если бизнес-логика оперирует календарными сущностями («сегодня»,
«за месяц»), зона указывается **явно** в месте вычисления — молчаливое
использование системной зоны процесса запрещено: она разная на ноутбуке и в
контейнере. По умолчанию это та же зона, что и для отображения; если
календарная логика требует другой, это записывается явно.
Конвенция описывает фиксацию **свершившихся моментов**. Планирование
будущих событий — отдельный случай (там хранят локальное время плюс имя
зоны, потому что правила зон меняются); пока такой сущности нет, правило не
формулируем.
<!-- local:механизировано -->
<!-- /local -->
<!-- local:отступления -->
<!-- /local -->
## Связано
- `arch/config.md` — где задаётся зона отображения.
- `arch/db-identifiers.md` — то же правило «генерирует приложение» для id.
<!-- local:связано -->
<!-- /local -->