# Проект хранения данных ## Источники истины PostgreSQL является источником истины для пользователей, чатов, участников, сообщений и сессий. Redis будет использоваться как cache-aside кэш чатов, но не как источник истины. Потеря Redis не должна приводить к потере данных. ## Общие решения - Идентификаторы создаются приложением как UUID. - Время назначается PostgreSQL и хранится как `TIMESTAMPTZ`. - API возвращает время в UTC в формате RFC 3339. - Чаты и сообщения упорядочиваются по `(created_at, id)`. - Используется уровень изоляции `READ COMMITTED`. - Все SQL-запросы параметризованы и выполняются с timeout. - Snapshot между несколькими HTTP-запросами не гарантируется. ## Таблицы ### `users` ```text id UUID PRIMARY KEY username VARCHAR(32) NOT NULL UNIQUE display_name TEXT NOT NULL password_hash TEXT NOT NULL created_at TIMESTAMPTZ NOT NULL ``` Ограничения: - `username` соответствует `^[a-z0-9_]{3,32}$`; - `display_name` содержит 1–100 символов и не состоит только из пробелов; - `password_hash` содержит PHC-строку Argon2id; - исходный пароль не хранится и не записывается в логи. Уникальность `username` окончательно обеспечивает PostgreSQL. При конкурентной регистрации нарушение уникальности преобразуется в HTTP 409. ### `chats` ```text id UUID PRIMARY KEY title TEXT NOT NULL created_at TIMESTAMPTZ NOT NULL ``` Ограничения: - `title` содержит 1–100 символов; - `title` не состоит только из пробелов. Индекс порядка: ```text (created_at, id) ``` ### `chat_members` ```text chat_id UUID NOT NULL REFERENCES chats(id) user_id UUID NOT NULL REFERENCES users(id) position SMALLINT NOT NULL ``` Ограничения: ```text PRIMARY KEY (chat_id, user_id) UNIQUE (chat_id, position) CHECK (position BETWEEN 0 AND 99) ``` `position` сохраняет порядок `member_ids` и ограничивает число участников чата сотней. Индекс для поиска чатов пользователя: ```text (user_id, chat_id) ``` ### `messages` ```text id UUID PRIMARY KEY chat_id UUID NOT NULL sender_id UUID NOT NULL text TEXT NOT NULL created_at TIMESTAMPTZ NOT NULL ``` Ограничения: - `text` содержит 1–4000 символов; - `text` не состоит только из пробелов; - `(chat_id, sender_id)` ссылается на `chat_members(chat_id, user_id)`. Составной внешний ключ гарантирует, что отправитель является участником чата. Индекс истории: ```text (chat_id, created_at, id) ``` ### `sessions` ```text token_hash BYTEA PRIMARY KEY user_id UUID NOT NULL REFERENCES users(id) created_at TIMESTAMPTZ NOT NULL expires_at TIMESTAMPTZ NOT NULL ``` Ограничения: ```text CHECK (octet_length(token_hash) = 32) CHECK (expires_at > created_at) ``` Клиент получает непрозрачный токен с энтропией не менее 256 бит. В PostgreSQL хранится только его SHA-256 digest. Сессия действительна, пока строка существует и `expires_at` больше текущего времени. Logout физически удаляет строку сессии. Индекс для очистки истёкших сессий: ```text (expires_at) ``` ## Транзакционные границы ### Регистрация Хеш Argon2id вычисляется до обращения к БД. Пользователь создаётся одним `INSERT`. Уникальное ограничение защищает от конкурентной регистрации одинакового `username`. ### Создание чата Одна транзакция: 1. Проверить существование всех участников. 2. Вставить чат. 3. Вставить всех участников с позициями. 4. Выполнить COMMIT. Любая ошибка приводит к ROLLBACK всей операции. ### Отправка сообщения Проверка членства и вставка сообщения выполняются согласованно. Предпочтительно использовать один `INSERT ... SELECT ... WHERE EXISTS`. Отсутствующий и чужой чат возвращают одинаковый HTTP 404. ### Сессии При входе приложение проверяет Argon2id, создаёт случайный токен и сохраняет его digest с абсолютным `expires_at`. Аутентификация ищет digest токена и проверяет срок действия. Logout удаляет текущую сессию. После COMMIT новый запрос с этим токеном получает HTTP 401. ## Курсорная пагинация ### Сообщения Курсор содержит: ```text version, created_at, message_id, chat_id ``` SQL-граница: ```sql WHERE chat_id = $1 AND (created_at, id) > ($2, $3) ORDER BY created_at, id LIMIT $4 ``` ### Чаты Курсор содержит: ```text version, created_at, chat_id, user_id ``` SQL-граница: ```sql WHERE member.user_id = $1 AND (chat.created_at, chat.id) > ($2, $3) ORDER BY chat.created_at, chat.id LIMIT $4 ``` В обоих запросах передаётся `limit + 1`. Дополнительная строка определяет, нужно ли возвращать `next_cursor`, без отдельного `COUNT(*)`. ## Миграции Первая миграция создаёт таблицы в порядке: 1. `users`; 2. `chats`; 3. `chat_members`; 4. `messages`; 5. `sessions`. Откат удаляет таблицы в обратном порядке. Применённые миграции учитываются в отдельной таблице версий. Повторный запуск не должен повторно создавать схему, дублировать или удалять данные. Для применения используется `golang-migrate` версии `v4.20.1` как отдельный Compose-сервис. Миграции не запускаются автоматически каждой API-репликой. Инструмент хранит текущую версию и состояние применения в служебной таблице `schema_migrations`. Неуспешная миграция останавливает запуск API и требует явного разбора причины, а не автоматического `force`.