Files
mtusi2026lab6/openspec/specs/messages/spec.md
T
ricoromaandClaude Opus 5.5 9cc6c0c7a6 chore: port lab 5 solution into the lab 6 skeleton
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>
2026-11-11 04:46:56 +03:00

212 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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`