vidconf/docs/architecture/adr/000-template.md

Шаблон ADR

Заголовок

[Краткое название архитектурного решения]

Статус

[PROPOSED | ACCEPTED | DEPRECATED | SUPERSEDED]

Контекст

Опишите проблему, которая мотивирует это решение. Укажите значимые факты:

• Почему это решение нужно?
• Какие ограничения или требования применимы?
• Какие альтернативы рассматривались?

Решение

Сформулируйте принятое решение чётко и кратко.

Последствия

Опишите результаты и следствия этого решения:

• Плюсы: выгоды, улучшения
• Минусы: компромиссы, риски
• Нейтрально: изменения, которые не хороши и не плохи

Ссылки

• Связанные ADR (если есть)
• Внешняя документация или стандарты
• Файлы кода, реализующие это решение

---

Пример: ADR-001 Использование UUID как первичного ключа

Статус

ACCEPTED

Контекст

VidConf требует глобально уникальных идентификаторов для распределённых операций и будущего шардирования.

• Генерация UUID в PostgreSQL быстрая (через gen_random_uuid())
• Не требует центральной нумерации
• Поддерживает репликацию без координации

Решение

Все таблицы используют UUID (версия 4) как первичный ключ, генерируемый на сервере через gen_random_uuid(). Исключения: phrases и chat_messages используют BIGINT IDENTITY для высокочастотных вставок.

Последствия

• Плюс: уникальность на всех инстансах; не требует глобальной координации
• Плюс: поддерживает будущие распределённые архитектуры
• Минус: больший размер индекса (16 байт против 8 у BIGINT)
• Нейтрально: требует явной поддержки типа UUID в ORM

Ссылки

• backend/models/*.py — все модели используют Mapped[uuid.UUID]
• backend/alembic/versions/1e2e34a0cb06_initial_schema.py — миграция