Files
mtusi2026lab5/openspec/specs/messages/spec.md
T
ricoromaandClaude Opus 5.5 ff1a83b6ff feat: process attachments asynchronously with RabbitMQ and a worker
Upload answers 202 after staging, a queued job in PostgreSQL and a broker
confirm; a separate worker publishes the original and a thumbnail with
bounded retries. Adds the job and variant tables, the broker service, the
worker S3 user, cleanup and reconcile support for staging and variants,
the failure stand with broker and worker, bench and driver updates.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 06:48:20 +03:00

12 KiB
Raw Blame History

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