perf: stabilize list queries for pilot

2026-09-07 08:02:37 +07:00
parent c45b4511b7
commit 5e27a5b066
7 changed files with 123 additions and 27 deletions
@@ -0,0 +1,38 @@
+# Бюджет запросов для альфа-пилота
+
+Дата фиксации: 7 сентября 2026 года.
+
+## Контракт списочных API
+
+Все списочные endpoint'ы принимают ограниченный `limit` и неотрицательный `offset`. Справочники ограничены 500 строками, публичные и административные журналы — 100–200 строками. Сортировка всегда имеет уникальный `id` последним ключом, поэтому соседние страницы не меняются местами при одинаковых датах или названиях. Значения перечислимых фильтров проверяет FastAPI; неподдерживаемое значение возвращает `422`.
+
+Фильтры применяются в SQL до `offset` и `limit`. Это особенно важно для `GET /api/v1/records?category=...`: фильтрация JSON-поля после пагинации могла возвращать пустую страницу при наличии подходящих записей.
+
+## Индексы
+
+Миграция `0011` добавляет составные индексы для основных путей чтения:
+
+- activity и лента точки — статус модерации, удаление, время и точка;
+- очередь модерации — источник, статус, удаление и время;
+- официальные рекорды — источник, дата и вес;
+- журнал импорта — источник, статус и время запуска;
+- staging — статус, система-источник и время последнего наблюдения;
+- rate limit — отпечаток клиента и время попытки;
+- retention аудита — время события модерации.
+
+## Измеримый бюджет
+
+На сервере альфа-пилота при объёме до 100 000 уловов и до 100 000 staging-наблюдений принимаются следующие server-side цели без учёта сети и браузерного рендера:
+
+- p95 публичных списков и activity — не более 250 мс;
+- p95 административных очередей — не более 500 мс;
+- один запрос очистки rate limit или retention-пакет — не более 2 с;
+- ни один интерактивный запрос не должен читать более 10 000 строк фактов по `Rows Removed by Filter`.
+
+Это стартовый эксплуатационный бюджет, а не результат синтетического бенчмарка. Планы на пустой bootstrap-БД не показательны: PostgreSQL обоснованно выбирает последовательное чтение маленьких таблиц.
+
+## Проверка после загрузки пилотных данных
+
+После наполнения выполнить `EXPLAIN (ANALYZE, BUFFERS)` для activity, moderation queue, records, staging queue и удаления старых submission attempts. Проверять фактическое время, `Rows Removed by Filter`, объём buffers и соответствие выбранного индекса фильтрам. Если таблица превышает 10 000 строк, а план остаётся последовательным и выходит за бюджет, сохранить план в журнал релиза и скорректировать индекс или форму запроса до открытия альфы.
+
+Bootstrap-тест отдельно проверяет, что Alembic дошёл до `0011` и все восемь составных индексов созданы на чистой PostgreSQL.