Source: mtusi2026lab5-safronov, solution/bvt2301-safronov, 046ec9e. Contracts, public tests and evidence of lab 5 are not carried over. The compose project, image and CI prefix are renamed to lab6; the first broker start defect is recorded in KNOWN_ISSUES.md; PLAN.md outlines the OpenSpec changes of lab 6. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
212 lines
12 KiB
Markdown
212 lines
12 KiB
Markdown
# messages Specification
|
||
|
||
## Purpose
|
||
|
||
Текстовые сообщения в чате: отправка от имени текущего пользователя и
|
||
чтение истории чата его участниками в порядке `(created_at, id)`.
|
||
|
||
## Requirements
|
||
|
||
### Requirement: Отправка сообщения
|
||
|
||
`POST /api/v1/chats/{chat_id}/messages` SHALL принимать тело
|
||
`{"text": ..., "attachment_ids": [...]}` с заголовком `Idempotency-Key`.
|
||
`attachment_ids` необязателен, по умолчанию `[]`. При успехе ответ SHALL
|
||
быть 201 с объектом `Message`: `id`, `chat_id`, `sender_id`, `text`,
|
||
`created_at`, `attachment_ids`, без других полей.
|
||
- `sender_id` SHALL быть текущим пользователем;
|
||
- `text` SHALL совпадать с отправленным;
|
||
- `attachment_ids` SHALL совпадать с отправленными, в том же порядке,
|
||
без поля в запросе — `[]`.
|
||
|
||
Формат ключа, повтор и конфликт описаны в capability `idempotency`,
|
||
проверка вложений — в требовании «Вложения в сообщении».
|
||
|
||
#### Scenario: Участник отправляет сообщение
|
||
|
||
- **WHEN** Алиса отправляет `"Привет, мир 👋"` в свой чат с новым
|
||
`Idempotency-Key`
|
||
- **THEN** ответ 201, `sender_id` — Алиса, `chat_id` — этот чат, `text`
|
||
равен `"Привет, мир 👋"`, `attachment_ids` — `[]`
|
||
|
||
#### Scenario: Сообщение с вложениями
|
||
|
||
- **WHEN** Алиса загрузила в чат вложения A и B и отправляет текст с
|
||
`attachment_ids` `[B, A]`
|
||
- **THEN** ответ 201, `attachment_ids` — `[B, A]`
|
||
|
||
### Requirement: Валидация текста
|
||
|
||
`text` SHALL содержать не больше 4000 Unicode code points. Пустой
|
||
текст — пустая строка или строка из одних пробельных символов — SHALL
|
||
допускаться только вместе с хотя бы одним вложением, без вложений он MUST
|
||
NOT приниматься (согласовано с преподавателем 2026-10-20, AGENTS.md,
|
||
«Согласования с преподавателем»). Текст SHALL сохраняться и
|
||
возвращаться как прислан, без обрезки и нормализации. Поле `sender_id`
|
||
в теле MUST NOT приниматься. Нарушения SHALL давать 400
|
||
`invalid_request`.
|
||
|
||
#### Scenario: Пустой текст
|
||
|
||
- **WHEN** участник отправляет `{"text": ""}`
|
||
- **THEN** ответ 400
|
||
|
||
#### Scenario: Граница длины
|
||
|
||
- **WHEN** текст из 4000 code points, затем из 4001
|
||
- **THEN** первый запрос даёт 201, второй — 400
|
||
|
||
#### Scenario: Попытка подменить отправителя
|
||
|
||
- **WHEN** тело содержит `sender_id` другого пользователя
|
||
- **THEN** ответ 400, сообщение не создаётся
|
||
|
||
#### Scenario: Пустой текст с вложением
|
||
|
||
- **WHEN** участник отправляет `{"text": "", "attachment_ids": [A]}` с
|
||
готовым вложением A своего чата
|
||
- **THEN** ответ 201, `text` — пустая строка, `attachment_ids` — `[A]`
|
||
|
||
#### Scenario: Пробелы с вложением
|
||
|
||
- **WHEN** участник отправляет `{"text": " ", "attachment_ids": [A]}`
|
||
с готовым вложением A своего чата, а затем `{"text": " "}` без
|
||
вложений
|
||
- **THEN** первый ответ 201, `text` — те же три пробела,
|
||
`attachment_ids` — `[A]`; второй — 400 `invalid_request`, и это
|
||
сообщение не создаётся
|
||
|
||
### Requirement: Писать и читать могут только участники
|
||
|
||
Отправка и чтение истории SHALL быть доступны только участникам чата.
|
||
Посторонний и запрос к несуществующему чату SHALL получать одинаковый
|
||
404 `not_found`; сообщение при этом MUST NOT создаваться.
|
||
|
||
#### Scenario: Посторонний пишет
|
||
|
||
- **WHEN** Ева отправляет сообщение в чат Алисы и Боба
|
||
- **THEN** ответ 404, в истории чата новых сообщений нет
|
||
|
||
#### Scenario: Посторонний читает
|
||
|
||
- **WHEN** Ева запрашивает историю чата Алисы и Боба
|
||
- **THEN** ответ 404
|
||
|
||
### Requirement: История чата
|
||
|
||
`GET /api/v1/chats/{chat_id}/messages` SHALL возвращать сообщения чата
|
||
в порядке `(created_at, id)` по возрастанию, с постраничным выводом по
|
||
capability `pagination`. Любой участник SHALL видеть все сообщения
|
||
чата, в том числе чужие. Каждое сообщение SHALL содержать
|
||
`attachment_ids` в порядке отправки.
|
||
|
||
#### Scenario: Два участника, две страницы
|
||
|
||
- **WHEN** Алиса и Боб отправили по сообщению, и Боб читает историю с
|
||
`limit=1`, а затем продолжает по курсору
|
||
- **THEN** первая страница содержит одно сообщение и непустой
|
||
`next_cursor`, вторая — второе сообщение и `next_cursor` null, а
|
||
порядок совпадает с `(created_at, id)`
|
||
|
||
#### Scenario: Вложения в истории
|
||
|
||
- **WHEN** Алиса отправила сообщение с `attachment_ids` `[B, A]`, а Боб
|
||
— текстовое сообщение
|
||
- **THEN** в истории у первого `attachment_ids` — `[B, A]`, у второго —
|
||
`[]`
|
||
|
||
### Requirement: Подтверждённое сообщение сразу видно
|
||
|
||
Сообщение, на которое сервис ответил 201, SHALL присутствовать в
|
||
любом следующем чтении истории этого чата.
|
||
|
||
#### Scenario: Чтение после записи
|
||
|
||
- **WHEN** участник получил 201 на отправку и сразу читает историю
|
||
- **THEN** сообщение есть в истории
|
||
|
||
### Requirement: Вложения в сообщении
|
||
|
||
`attachment_ids` SHALL содержать от 0 до 10 уникальных идентификаторов
|
||
в записи UUID (`api-conventions`, «UUID на входе»). Повтор
|
||
идентификатора, в том числе в другом регистре букв, больше 10
|
||
элементов, элемент не UUID и не массив — 400 `invalid_request`.
|
||
|
||
Каждое вложение SHALL быть принятым вложением этого чата в состоянии
|
||
`queued`, `processing` или `ready`. Одинаковый 404 `not_found` дают:
|
||
- неизвестное вложение;
|
||
- вложение другого чата, в том числе чата, где отправитель не состоит;
|
||
- вложение, загрузка которого не завершена.
|
||
|
||
Вложение `failed` этого чата SHALL давать 409 `conflict`: прикрепить его
|
||
нельзя. Если в списке есть и такое, и вложение из перечня выше, ответ — 404.
|
||
Повтор уже отправленного сообщения с тем же ключом SHALL проходить, даже если
|
||
его вложение стало `failed` после отправки (`idempotency`, «Повтор возвращает
|
||
исходный результат»).
|
||
|
||
Сообщение при этом MUST NOT создаваться. Сервис SHALL принимать ссылку
|
||
на вложение чата от любого его участника, а не только от владельца, и
|
||
одно вложение SHALL входить в несколько сообщений. Сообщение и его
|
||
связи с вложениями SHALL сохраняться одной транзакцией. Вложение, которое стало
|
||
`failed` после отправки, остаётся в `attachment_ids` сообщения.
|
||
|
||
#### Scenario: Вложение другого участника
|
||
|
||
- **WHEN** Алиса загрузила вложение в чат с Бобом, и Боб отправляет
|
||
сообщение с этим вложением
|
||
- **THEN** ответ 201
|
||
|
||
#### Scenario: Вложение другого чата
|
||
|
||
- **WHEN** Алиса состоит в чатах X и Y, загрузила вложение в Y и
|
||
отправляет в X сообщение с ним
|
||
- **THEN** ответ 404 `not_found`, в истории X нового сообщения нет
|
||
|
||
#### Scenario: Чужое вложение
|
||
|
||
- **WHEN** Ева загрузила вложение в свой чат, а Алиса отправляет в свой
|
||
чат сообщение с ним
|
||
- **THEN** ответ 404 `not_found`, сообщение не создано
|
||
|
||
#### Scenario: Неизвестное вложение
|
||
|
||
- **WHEN** участник отправляет сообщение со случайным UUID в
|
||
`attachment_ids`
|
||
- **THEN** ответ 404 `not_found`, сообщение не создано
|
||
|
||
#### Scenario: Неверный список вложений
|
||
|
||
- **WHEN** участник отправляет `attachment_ids` с повтором одного
|
||
вложения, с тем же вложением в верхнем регистре, из 11 элементов,
|
||
строкой вместо массива и с элементом `123`
|
||
- **THEN** каждый ответ 400 `invalid_request`, сообщений не создано
|
||
|
||
#### Scenario: Одно вложение в двух сообщениях
|
||
|
||
- **WHEN** участник дважды отправляет сообщение с одним и тем же
|
||
вложением
|
||
- **THEN** оба ответа 201, у обоих сообщений это вложение в
|
||
`attachment_ids`
|
||
|
||
#### Scenario: Вложение в обработке
|
||
|
||
- **WHEN** worker остановлен, участник загрузил файл и сразу отправляет
|
||
сообщение с этим вложением
|
||
- **THEN** ответ 201, `attachment_ids` содержит вложение, его метаданные —
|
||
`queued`, а история отдаёт это сообщение
|
||
|
||
#### Scenario: Вложение failed
|
||
|
||
- **WHEN** вложение чата стало `failed`, и участник отправляет сообщение с ним,
|
||
а затем с ним и случайным UUID
|
||
- **THEN** первый ответ 409 `conflict`, второй — 404 `not_found`, сообщений не
|
||
создано, а ключ идемпотентности свободен: новая отправка с этим ключом без
|
||
вложения — 201
|
||
|
||
#### Scenario: Вложение стало failed после отправки
|
||
|
||
- **WHEN** участник отправил сообщение с вложением в `queued`, а затем вложение
|
||
стало `failed`
|
||
- **THEN** история отдаёт сообщение с его `attachment_ids`, а метаданные вложения —
|
||
`failed` с `error_code`
|