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>
93 lines
5.0 KiB
Markdown
93 lines
5.0 KiB
Markdown
# 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`.
|
||
|
||
Курсор, изменённый клиентом, SHALL давать 400 `invalid_request`, даже
|
||
если он по-прежнему разбирается: ключ элемента другого типа или не в той
|
||
записи, в которой его выдал сервер, версия другого значения или типа.
|
||
Такой курсор MUST NOT давать 500 или страницу списка. Поля, которых
|
||
сервер не знает, SHALL игнорироваться: новое необязательное поле не
|
||
делает курсор недействительным для реплик прежней версии.
|
||
|
||
#### Scenario: Курсор другого чата
|
||
|
||
- **WHEN** участник двух чатов передаёт в историю чата B курсор,
|
||
полученный в чате A
|
||
- **THEN** ответ 400
|
||
|
||
#### Scenario: Повреждённый курсор
|
||
|
||
- **WHEN** `cursor` равен произвольной строке `garbage`
|
||
- **THEN** ответ 400
|
||
|
||
#### Scenario: Изменённый курсор
|
||
|
||
- **WHEN** клиент раскодирует курсор, выданный историей чата или
|
||
списком чатов, и меняет в нём только одно: ключ последнего элемента —
|
||
на `[]`, `{}`, `123`, `false` или на тот же id без дефисов или в
|
||
верхнем регистре, либо версию — на `true`; затем кодирует обратно и
|
||
передаёт в тот же список
|
||
- **THEN** ответ 400 с `code` `invalid_request`, а тот же курсор,
|
||
раскодированный и закодированный обратно без изменений или с
|
||
добавленным незнакомым полем, даёт 200 и ту же страницу
|