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

9.6 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 быть готовым вложением этого чата. Одинаковый 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