Files
mtusi2026lab4/openspec/specs/messages/spec.md
T
ricoromaandClaude Opus 5.5 116d8d3bf0 feat: add image attachments to messages
- upload, metadata and download endpoints for PNG/JPEG attachments:
  limits before reading and decompression, type by content,
  structural integrity check without decoding pixels, safe filename
- write order: pending row with object key -> PUT to S3 -> ready;
  per-step DB sessions so no pool connection is held during transfers
- attachment_ids in messages (validation, idempotency hash, history);
  whitespace-only text allowed with an attachment (teacher, 2026-10-20)
- migration: attachments and message_attachments tables, text length
  CHECK relaxed with NOT VALID
- student tests, fault checks and driver commands for attachments;
  rollout profile starts from e1161f7 and checks the commit first
- sync attachments deltas into main specs; rules, AGENTS.md, PLAN.md

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-21 01:08:56 +03:00

183 lines
9.6 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 быть готовым вложением этого чата. Одинаковый 404
`not_found` дают:
- неизвестное вложение;
- вложение другого чата, в том числе чата, где отправитель не состоит;
- вложение, загрузка которого не завершена.
Сообщение при этом MUST NOT создаваться. Сервис SHALL принимать ссылку
на вложение чата от любого его участника, а не только от владельца, и
одно вложение SHALL входить в несколько сообщений. Сообщение и его
связи с вложениями SHALL сохраняться одной транзакцией.
#### 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`