реализован уровень 3

This commit is contained in:
2026-10-15 15:15:35 +03:00
parent 10b5842be3
commit 158fed100c
39 changed files with 3868 additions and 183 deletions
+233
View File
@@ -0,0 +1,233 @@
# Проект хранения данных
## Источники истины
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`.