forked from mtusi2026/mtusi2026lab2
реализован уровень 3
This commit is contained in:
@@ -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`.
|
||||
Reference in New Issue
Block a user