Files
mtusi2026lab2/openspec/specs/pagination/spec.md
T
ricoromaandClaude Opus 5.5 7b775a29a9 chore: carry over lab 1 solution into lab 2 skeleton
Copy the committed lab 1 sources as-is: src/, student-tests/, bench/,
Dockerfile, docker-compose.yml, pyproject.toml, uv.lock,
.python-version, config_example.toml, AGENTS.md, CLAUDE.md, .claude/,
openspec/, .graphifyignore and KNOWN_ISSUES.md. Lab 1 evidence stays
in the lab 1 repository.

Merge the new skeleton files with own sections: Makefile (lab 2
targets plus own run, docker, bench and common targets), .gitignore,
.dockerignore and .env.example. Rename the image to
mtusi-messenger:lab2 and point AGENTS.md at lab 2.

The application is still the in-memory lab 1 implementation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 22:11:46 +03:00

3.5 KiB

pagination Specification

Purpose

Общие правила постраничных списков (чаты пользователя и история чата): параметр limit, непрозрачный keyset-курсор и next_cursor. Обход списка по курсору не теряет и не повторяет элементы.

Requirements

Requirement: Параметр limit

limit SHALL быть целым числом от 1 до 100, по умолчанию 50. Другие значения SHALL давать 400 invalid_request.

Scenario: Ноль

  • WHEN клиент запрашивает список с limit=0
  • THEN ответ 400

Scenario: Больше максимума и не число

  • WHEN limit=101 или limit=abc
  • THEN ответ 400

Scenario: По умолчанию

  • WHEN limit не передан и в списке 60 элементов
  • THEN страница содержит 50 элементов

Requirement: Форма страницы и next_cursor

Ответ списка SHALL иметь вид {"items": [...], "next_cursor": ...}. next_cursor SHALL быть непустой строкой, если на момент чтения после последнего элемента страницы есть ещё элементы, и null — если нет, в том числе когда страница содержит ровно limit элементов и больше ничего нет.

Scenario: Последняя полная страница

  • WHEN в списке ровно 2 элемента и клиент запрашивает limit=2
  • THEN страница содержит оба элемента и next_cursor null

Requirement: Порядок и продолжение по курсору

Элементы SHALL упорядочиваться по (created_at, id) по возрастанию, где id сравнивается как значение UUID. Запрос с cursor SHALL возвращать элементы строго после последнего элемента предыдущей страницы. При обходе неизменного списка элементы MUST NOT теряться и повторяться. limit SHALL разрешено менять между страницами.

Scenario: Полный обход

  • WHEN клиент обходит список из 7 элементов страницами по 3, затем по 2
  • THEN объединение страниц содержит все 7 элементов ровно по одному разу в правильном порядке

Requirement: Курсор непрозрачен и привязан к списку

Курсор SHALL быть непрозрачной для клиента строкой. Курсор, полученный для другого чата, для списка чатов вместо истории или наоборот, либо повреждённая строка SHALL давать 400 invalid_request.

Scenario: Курсор другого чата

  • WHEN участник двух чатов передаёт в историю чата B курсор, полученный в чате A
  • THEN ответ 400

Scenario: Повреждённый курсор

  • WHEN cursor равен произвольной строке garbage
  • THEN ответ 400