335 lines
33 KiB
Markdown
335 lines
33 KiB
Markdown
# Профилирование фронта и бэка — план исполнения
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** Воспроизводимый стенд в `perf/` и отчёт `perf/REPORT.md` с доказанными проблемными местами по скроллу, модалкам, памяти и бэку (issue #202).
|
||
|
||
**Architecture:**
|
||
- Postgres 16 в docker (с `pg_stat_statements`), бэк — `uvicorn` из `api/` в одном процессе.
|
||
- Prod-сборка фронта собирается из `web/` собственным конфигом `perf/web/rsbuild.perf.config.ts` в `perf/.build/` и раздаётся `rsbuild preview` на :8080 с прокси `/api` (включая WS) на :8000.
|
||
- Python-пакет `perf/perfkit` генерирует данные через HTTP-API, гоняет бота-соавтора и замеры бэка; Playwright-проект `perf/e2e` снимает метрики фронта через CDP.
|
||
- Все сценарии пишут записи единого формата в `perf/results/<run_id>/`, агрегатор сводит их в `summary.json` и markdown-таблицы для отчёта.
|
||
|
||
**Tech Stack:** Python 3.12 (httpx, asyncpg, websockets, argon2-cffi, pytest), Node 24 + `@playwright/test` (Chromium), docker compose, Postgres 16, Rsbuild (из `web/node_modules`).
|
||
|
||
**Spec:** `openspec/changes/perf-profiling/design.md` (+ `proposal.md`)
|
||
|
||
## Global Constraints
|
||
|
||
- Не менять `api/src`, `api/alembic`, `web/src`, `web/rsbuild.config.ts`, `web/package.json`, `api/requirements*.txt`, `api/web`. Всё новое — только в `perf/` и строки в корневом `.gitignore`.
|
||
- Не исправлять код приложения, даже очевидные баги: находка идёт в отчёт.
|
||
- Фронт мерить только на prod-сборке (`rsbuild build`), режимы CPU — `[1, 4, 6]` через `Emulation.setCPUThrottlingRate`.
|
||
- Бэк и Postgres — без лимитов CPU и памяти. В отчёте пометка: «быстрое железо, прод ≈ 1 vCPU / 4 GB».
|
||
- Postgres 16, схема `v3`, миграции — `cd api && alembic upgrade head`, бэк с `DEBUG=true`, `DATABASE_URL=postgresql+asyncpg://perf:perf@localhost:55432/perf`.
|
||
- Порты: Postgres 55432, API 8000, фронт 8080.
|
||
- Основная роль замеров — EXECUTOR_RF (role_id 3) с открытым окном этапа на правку. Контрольная — ADMIN (1), только скролл на масштабе 1.
|
||
- Масштабы данных: `1` (базовый) и `2` (удвоенный).
|
||
- Long task — задача длиннее 50 мс (`PerformanceObserver` типа `longtask`). Тяжёлый кадр — интервал между `requestAnimationFrame` больше 50 мс.
|
||
- Сырые артефакты (`*.json` trace, `*.heapsnapshot`, `perf/results/**`, `perf/.build/`, `perf/.venv/`, `perf/e2e/node_modules/`) — в `.gitignore`. Коммитятся код стенда, `perf/README.md`, `perf/REPORT.md` и `perf/report-data/<run_id>/summary.json`.
|
||
- Отчёт и README — на русском.
|
||
- Каждая цифра отчёта получается командой из `perf/README.md`.
|
||
|
||
## Review Focus
|
||
|
||
- Prod-сборка с прокси: WS `/api/v1/ws/...` через :8080 должен работать; иначе таблица не загрузится, а сценарии «зелёные» на пустой странице. Проверяется smoke в Task 1 и ассертом «в таблице ≥ N видимых строк» перед каждым замером в Task 5.
|
||
- Окно этапа закрыто на дату замера: EXECUTOR_RF видит лист read-only, и замер идёт не на той конфигурации. Генератор ставит окна `opens_at = now - 1 day`, `closes_at = now + 30 days`; verify в Task 3 проверяет это.
|
||
- Скролл не дошёл до конца (виртуализация или ленивая подгрузка): сценарий обязан проверить, что `scrollTop + clientHeight ≥ scrollHeight - 2` в конце, иначе запись получает `"incomplete": true`. Тест в Task 5.
|
||
- Перекрёстное влияние прогонов (кэш браузера, открытые WS, накопленная память): каждый замер скролла и модалок — в новом browser context. Проверяется в Task 4 тестом изоляции контекста.
|
||
- Неверный токен в WS-боте: бот молча не шлёт правки, и сценарий 1a измеряет «без соавтора». Бот обязан дождаться эха `cell_updated` хотя бы на первую правку, иначе падает. Тест в Task 6.
|
||
|
||
---
|
||
|
||
### Task 1: Стенд — Postgres, миграции, админ, бэк, prod-сборка фронта с прокси
|
||
|
||
**Модель:** sonnet
|
||
|
||
**Files:**
|
||
- Create: `perf/docker-compose.yml` — сервис `pg` из `postgres:16`, порт `55432:5432`, `POSTGRES_USER/PASSWORD/DB=perf`, `command: postgres -c shared_preload_libraries=pg_stat_statements -c pg_stat_statements.track=all`, volume `perf-pg`.
|
||
- Create: `perf/stand.sh` — подкоманды `up | migrate | bootstrap | api | web-build | web | smoke | down | all`.
|
||
- Create: `perf/stand/bootstrap.py` — `CREATE EXTENSION IF NOT EXISTS pg_stat_statements`; админ `admin`/`admin` (`admin@perf.local`, role_id 1, argon2-хеш); идемпотентно.
|
||
- Create: `perf/stand/smoke.py`.
|
||
- Create: `perf/web/rsbuild.perf.config.ts` — `mergeRsbuildConfig` поверх `web/rsbuild.config.ts`: `output.distPath.root` = `perf/.build/prod` или `perf/.build/profiling` при `PERF_PROFILING=1`; при `PERF_PROFILING=1` alias `react-dom$` → `react-dom/profiling`; `server.port 8080`, `server.proxy` `/api` → `http://localhost:8000` с `ws: true`.
|
||
- Create: `perf/requirements.txt` — httpx, asyncpg, websockets, argon2-cffi, pytest.
|
||
- Create: `perf/README.md` — раздел «Стенд».
|
||
- Modify: `.gitignore` — строки из Global Constraints.
|
||
|
||
**Interfaces:**
|
||
- Produces:
|
||
- `perf/stand.sh all` — поднимает всё, бэк и фронт в фоне, PID в `perf/.run/*.pid`, логи в `perf/.run/*.log`.
|
||
- venv `perf/.venv` (зависимости `api/requirements-dev.txt` + `perf/requirements.txt`).
|
||
- Переменные `PERF_API=http://localhost:8000`, `PERF_WEB=http://localhost:8080`, `PERF_DB_DSN=postgresql://perf:perf@localhost:55432/perf`.
|
||
- Админ `admin`/`admin`.
|
||
|
||
- [ ] **Step 1: Написать `perf/stand/smoke.py`, который проверяет:**
|
||
- `GET $PERF_API/healthz` → 200;
|
||
- `POST $PERF_API/api/v1/auth/login {"username":"admin","password":"admin"}` → 200 и `access_token`;
|
||
- `GET $PERF_WEB/` → 200, HTML содержит `<script`;
|
||
- `GET $PERF_WEB/api/v1/users/me` с Bearer → 200 (прокси);
|
||
- WS `ws://localhost:8080/api/v1/ws/export` открывается (прокси WS).
|
||
|
||
Печатает `SMOKE OK` или первую ошибку и выходит с кодом 1.
|
||
- [ ] **Step 2: Прогнать `perf/stand.sh smoke` до создания стенда**
|
||
Expected: FAIL (соединение отклонено).
|
||
- [ ] **Step 3: Реализовать compose, `stand.sh`, `bootstrap.py`, `rsbuild.perf.config.ts`**
|
||
- `web-build`: `cd web && npm ci && npx rsbuild build -c ../perf/web/rsbuild.perf.config.ts`, затем то же с `PERF_PROFILING=1`.
|
||
- `web`: `npx rsbuild preview -c ../perf/web/rsbuild.perf.config.ts`.
|
||
- `api`: `cd api && DATABASE_URL=… DEBUG=true ../perf/.venv/bin/python run_server.py`.
|
||
- [ ] **Step 4: Прогнать `perf/stand.sh all && perf/stand.sh smoke`**
|
||
Expected: `SMOKE OK`. `git status` не показывает изменений вне `perf/` и `.gitignore`.
|
||
- [ ] **Step 5: Commit** — `perf: стенд для профилирования (postgres, api, prod-сборка фронта)`.
|
||
|
||
### Task 2: perfkit — формат манифеста и результатов, агрегатор
|
||
|
||
**Модель:** sonnet
|
||
|
||
**Files:**
|
||
- Create: `perf/perfkit/__init__.py`, `perf/perfkit/manifest.py`, `perf/perfkit/results.py`, `perf/perfkit/aggregate.py`.
|
||
- Test: `perf/tests/test_manifest.py`, `perf/tests/test_aggregate.py`, `perf/pytest.ini` (`pythonpath = .`).
|
||
|
||
**Interfaces:**
|
||
- Produces:
|
||
- `perfkit.manifest`: dataclasses `Sheet(form_id:int, form_type:str, sheet:str, direction:str|None, year:int, url:str, rows:int)`, `ProjectReport(project_id:int, year:int, report_type:str, url:str, rows:int)`, `Page(name:str, url:str)`, `User(username:str, password:str, role_id:int)`, `Manifest(scale:int, users:dict[str,User], sheets:list[Sheet], project_reports:list[ProjectReport], svods:list[Page], modal_pages:list[Page])`; `load(path) -> Manifest`, `dump(m, path)`. Путь: `perf/results/manifest-s{scale}.json`. Ключи `users`: `"admin"`, `"rf"`, `"rf_coauthor"`, `"dfip"`.
|
||
URL листа — `/table/form/{form_id}/form-type/{form_type}/{sheet}/{direction or "null"}/{year}`. Реальное значение сегмента для «нет direction» исполнитель берёт из `web/src` и фиксирует в коде.
|
||
- `perfkit.results`: запись результата (одна JSON-строка) — `{"run_id","scenario","target","role","scale","cpu_rate","repeat","metrics":{…},"artifacts":[…],"incomplete":bool,"ts"}`. Функция `append(run_dir, record)` пишет в `perf/results/<run_id>/<scenario>.jsonl`. Node-сторона (Task 4) пишет тот же формат.
|
||
- `perfkit.aggregate`: `summarize(run_dir) -> dict` группирует по `(scenario, target, role, scale, cpu_rate)` и считает для каждой числовой метрики `median`, `p95`, `min`, `max`, `n`. CLI: `python -m perfkit.aggregate <run_dir>` пишет `summary.json` и `summary.md` в `perf/report-data/<run_id>/`.
|
||
|
||
- [ ] **Step 1: Тесты**
|
||
- `test_manifest_roundtrip` — dump и load дают равный объект.
|
||
- `test_summarize_median_p95`: метрика `long_task_ms` со значениями `[10,20,30,40,100]` → `median == 30`, `p95 == 100` (nearest-rank), `n == 5`.
|
||
- `test_summarize_groups_by_cpu_rate` — записи с `cpu_rate` 1 и 6 дают две группы.
|
||
- `test_incomplete_records_counted_separately` — `incomplete:true` не попадает в статистику; в группе есть `incomplete_n`.
|
||
- [ ] **Step 2:** `cd perf && .venv/bin/pytest tests -q` → FAIL (нет модулей).
|
||
- [ ] **Step 3:** Реализовать модули по интерфейсам.
|
||
- [ ] **Step 4:** `cd perf && .venv/bin/pytest tests -q` → PASS.
|
||
- [ ] **Step 5: Commit** — `perf: формат манифеста и результатов, агрегатор`.
|
||
|
||
### Task 3: Генератор данных через HTTP-API
|
||
|
||
**Модель:** sonnet
|
||
|
||
**Files:**
|
||
- Create: `perf/perfkit/gen/__init__.py`, `perf/perfkit/gen/plan.py`, `perf/perfkit/gen/run.py` (CLI `python -m perfkit.gen.run --scale N`), `perf/perfkit/gen/verify.py` (CLI `python -m perfkit.gen.verify --scale N`).
|
||
- Test: `perf/tests/test_gen_plan.py`.
|
||
|
||
**Interfaces:**
|
||
- Consumes: стенд (Task 1), `perfkit.manifest` (Task 2).
|
||
- Produces:
|
||
- `plan_for_scale(scale:int) -> GenPlan` (dataclass с полями `org_units_ssp:int`, `org_units_rf:int`, `vsp_per_rf:int`, `extra_lines_per_sheet:int`, `projects_per_rf:int`, `fill_ratio:float`).
|
||
- Манифест `perf/results/manifest-s{scale}.json`.
|
||
|
||
Генератор всё создаёт через API под `admin`, в таком порядке:
|
||
1. оргединицы (`POST /api/v1/org-unit/`);
|
||
2. пользователи `rf`, `rf_coauthor` (role 3, оба на одну РФ) и `dfip` (role 2) с паролем `perf` (`POST /api/v1/users/`, `PUT /users/dfip-many-ssp/`);
|
||
3. ВСП (`POST /api/v1/dict/info`);
|
||
4. формы FORM_1, FORM_2, FORM_4 за 2026 год по оргединицам (`POST /api/v1/form/`) — строки из шаблона создаёт сама БД;
|
||
5. дополнительные строки (`POST /form/{id}/sheet/{sheet}/line`);
|
||
6. заполнение ячеек долей `fill_ratio` (`PATCH .../cells` пачками);
|
||
7. этапы с окнами `opens_at = now - 1 day`, `closes_at = now + 30 days` для ролей EXECUTOR_RF и EXECUTOR_DFIP на всех листах (`POST /api/v1/stages/form/{id}`);
|
||
8. проекты РФ с годами и отчётами (FORM_3) и этапы проектов.
|
||
|
||
Значения `plan_for_scale(1)` исполнитель выбирает так, чтобы самый большой лист у `rf` имел ≥ 1000 строк, а своды были заполнены по всем оргединицам. Обоснование — комментарием в `plan.py`, оно попадёт в отчёт.
|
||
|
||
- [ ] **Step 1: Тесты**
|
||
- `test_plan_scale2_doubles_volume`: у `plan_for_scale(2)` поля `org_units_rf`, `vsp_per_rf`, `extra_lines_per_sheet`, `projects_per_rf` равны удвоенным значениям из `plan_for_scale(1)`, `fill_ratio` тот же.
|
||
- `test_plan_rejects_zero_scale` — `ValueError`.
|
||
- [ ] **Step 2:** pytest → FAIL.
|
||
- [ ] **Step 3:** Реализовать `plan.py` и `run.py`. Повторный запуск на непустой БД падает с понятным сообщением «сначала perf/stand.sh reset». Для этого в Task 1 нужна подкоманда `reset`: drop volume + up + migrate + bootstrap; добавить её в этом таске.
|
||
- [ ] **Step 4:** Реализовать `verify.py`. Он проверяет в БД (asyncpg, `PERF_DB_DSN`):
|
||
- число форм, строк и проектов соответствует плану;
|
||
- у `rf` самый большой лист ≥ 1000 строк;
|
||
- на каждом листе из манифеста есть этап с `opens_at < now() < closes_at` для роли EXECUTOR_RF;
|
||
- каждый URL манифеста отвечает 200 через `$PERF_WEB`.
|
||
|
||
Печатает `VERIFY OK`.
|
||
- [ ] **Step 5:** `perf/stand.sh reset && .venv/bin/python -m perfkit.gen.run --scale 1 && .venv/bin/python -m perfkit.gen.verify --scale 1` → `VERIFY OK`; pytest → PASS.
|
||
- [ ] **Step 6: Commit** — `perf: генератор данных через API`.
|
||
|
||
### Task 4: Каркас замеров фронта (Playwright + CDP)
|
||
|
||
**Модель:** sonnet
|
||
|
||
**Files:**
|
||
- Create: `perf/e2e/package.json` (`@playwright/test`, точная версия), `perf/e2e/playwright.config.ts` (Chromium, `workers: 1`, `fullyParallel: false`, без ретраев, timeout 10 мин).
|
||
- Create: `perf/e2e/lib/manifest.ts` — чтение манифеста Task 2.
|
||
- Create: `perf/e2e/lib/auth.ts` — `loginAs(context, user)`: токен через API, затем в `localStorage` под ключами, которые читает `web/src/app/context/AuthProvider.jsx`; ключи исполнитель берёт оттуда.
|
||
- Create: `perf/e2e/lib/cdp.ts` — `throttle(page, rate)`, `startTrace(page)`, `stopTrace(page, path)`, `gc(page)`, `domCounters(page)`, `heapUsed(page)`, `heapSnapshot(page, path)`.
|
||
- Create: `perf/e2e/lib/probe.ts` — init-script, встраиваемый в страницу: `PerformanceObserver('longtask')` и счётчик кадров через `requestAnimationFrame`; `window.__perf.start()` / `window.__perf.stop()` возвращают `{long_task_n, long_task_ms, frame_n, heavy_frame_n, frame_p50_ms, frame_p95_ms, duration_ms}`.
|
||
- Create: `perf/e2e/lib/results.ts` — `append(record)` в формате Task 2. `run_id` из `PERF_RUN_ID`, по умолчанию `YYYYMMDD-HHMM`.
|
||
- Create: `perf/e2e/fixtures/busy.html` — страница, которая по кнопке крутит синхронный цикл 120 мс.
|
||
- Test: `perf/e2e/tests/harness.spec.ts`.
|
||
|
||
**Interfaces:**
|
||
- Produces: перечисленные функции с этими именами. Каждая следующая e2e-задача импортирует их из `../lib/*`.
|
||
|
||
- [ ] **Step 1: Тесты в `harness.spec.ts`**
|
||
- `probe detects long task`: на `busy.html` нажатие кнопки между `start` и `stop` даёт `long_task_n >= 1` и `long_task_ms >= 100`.
|
||
- `throttle slows script`: время того же цикла при `throttle(page, 4)` ≥ 2× времени при `throttle(page, 1)`.
|
||
- `fresh context isolation`: `localStorage`, выставленный в одном контексте, не виден в новом.
|
||
- `results format`: `append` пишет строку, которую `perfkit.results` из Task 2 читает (проверка через `python -m perfkit.aggregate` на временном каталоге даёт `n == 1`).
|
||
- [ ] **Step 2:** `cd perf/e2e && npx playwright test tests/harness.spec.ts` → FAIL.
|
||
- [ ] **Step 3:** Реализовать `lib/*`.
|
||
- [ ] **Step 4:** Тот же прогон → PASS.
|
||
- [ ] **Step 5: Commit** — `perf: каркас замеров фронта`.
|
||
|
||
### Task 5: Сценарии скролла — листы форм, отчёты проектов, своды
|
||
|
||
**Модель:** sonnet
|
||
|
||
**Files:**
|
||
- Create: `perf/e2e/lib/scroll.ts` — `scrollThrough(page, containerSelector, axis: 'y'|'x', stepPx=200) -> {complete: boolean, steps: number}`: колесо мыши шагами по 200 px, после каждого шага ждать `requestAnimationFrame`, вниз до конца и обратно. `complete` — правило из Review Focus.
|
||
- Create: `perf/e2e/scenarios/scroll.spec.ts`.
|
||
- Test: `perf/e2e/tests/scroll-lib.spec.ts` на `perf/e2e/fixtures/long-list.html` (div 20 000 px).
|
||
|
||
**Interfaces:**
|
||
- Consumes: Task 4 lib, манифест (`sheets`, `project_reports`, `svods`).
|
||
- Produces: записи `scenario: "scroll"`, `target` — `"{form_type}/{sheet}/{direction}"`, `"project/{report_type}"` или `"svod/{name}"`; метрики probe плюс `axis`, `rows_visible_before`, `json_bytes_sheet` (размер ответа загрузки листа из сетевого лога). Trace на каждый первый повтор — в `artifacts`.
|
||
|
||
Матрица:
|
||
- роль `rf` × все листы и отчёты проектов × оси y и x × CPU `[1,4,6]` × 3 повтора;
|
||
- роль `admin` × листы × ось y × CPU `[1,4,6]` × 1 повтор, только масштаб 1;
|
||
- своды (свод 1 по каждому `sheet`, свод 2 GO и RF, `/projects/summaries`) под `admin` и `dfip` × ось y × CPU `[1,4,6]` × 3 повтора, плюс одна смена фильтра на CPU 6 с замером probe от клика до стабилизации (2 кадра без long task).
|
||
|
||
Перед замером: дождаться ≥ 20 видимых строк таблицы, иначе тест падает (Review Focus). Селектор контейнера скролла исполнитель берёт из DOM `material-react-table`.
|
||
|
||
- [ ] **Step 1: Тесты `scroll-lib.spec.ts`:** на `long-list.html` `scrollThrough` даёт `complete === true`; на странице, где контейнер обрезан до 5000 px при `maxSteps = 10`, — `complete === false`.
|
||
- [ ] **Step 2:** Прогон → FAIL.
|
||
- [ ] **Step 3:** Реализовать `scroll.ts` и `scroll.spec.ts`. Сценарий параметризуется `PERF_SCALE` и фильтром `PERF_TARGETS` (glob по `target`) для быстрых прогонов.
|
||
- [ ] **Step 4:** `npx playwright test tests/scroll-lib.spec.ts` → PASS. `PERF_SCALE=1 PERF_TARGETS='FORM_1/*' npx playwright test scenarios/scroll.spec.ts` → записи без `incomplete`; `python -m perfkit.aggregate` строит таблицу.
|
||
- [ ] **Step 5: Commit** — `perf: сценарии скролла`.
|
||
|
||
### Task 6: Бот-соавтор и сценарий «скролл при соавторе»
|
||
|
||
**Модель:** sonnet
|
||
|
||
**Files:**
|
||
- Create: `perf/perfkit/coauthor.py` — CLI `python -m perfkit.coauthor --form-id N --sheet S [--direction D] --rate 1|5 --duration SEC`.
|
||
- Create: `perf/e2e/scenarios/scroll-coauthor.spec.ts`.
|
||
- Test: `perf/tests/test_coauthor.py` (интеграционный, помечен `@pytest.mark.stand`; в `pytest.ini` — `markers = stand: нужен поднятый стенд`).
|
||
|
||
**Interfaces:**
|
||
- Consumes: манифест (`users.rf_coauthor`, `sheets`), Task 4/5 lib.
|
||
- Produces: записи `scenario: "scroll_coauthor"`, `metrics` + `coauthor_rate`, `coauthor_sent`, `coauthor_echoed`.
|
||
|
||
Протокол — `api/src/api/v1/websocket.py`:
|
||
- подключение `ws://localhost:8000/api/v1/ws/form/{id}/sheet/{sheet}?direction=`;
|
||
- первое сообщение `{"event":"user_login","data":{"token":…}}`;
|
||
- правка — событие `cell_updated` (формат `data` взять из обработчика `__update_cell` и из того, что шлёт фронт в `web/src/components/RealtimeTable/hooks/useWebSocket.js`).
|
||
|
||
Бот правит случайные редактируемые ячейки листа в колонках, открытых этапом для EXECUTOR_RF. Перед правкой шлёт `cell_edit_start`, после — `cell_edit_end`.
|
||
|
||
- [ ] **Step 1: Тест `test_coauthor_first_edit_echoed`:** бот с `--rate 1 --duration 3` на первом листе FORM_1 получает эхо `cell_updated` своей первой правки и завершается кодом 0. С неверным токеном завершается кодом ≠ 0 за ≤ 5 с (Review Focus).
|
||
- [ ] **Step 2:** `.venv/bin/pytest -m stand tests/test_coauthor.py` → FAIL.
|
||
- [ ] **Step 3:** Реализовать бота и сценарий:
|
||
- бот стартует как дочерний процесс на время скролла;
|
||
- роль `rf`, масштаб 1, CPU 6, rate 1 и 5, 3 повтора;
|
||
- цели — самый большой лист каждой формы.
|
||
- [ ] **Step 4:** Тест → PASS. Сценарий на FORM_1 даёт записи с `coauthor_echoed > 0`.
|
||
- [ ] **Step 5: Commit** — `perf: бот-соавтор и скролл при соавторе`.
|
||
|
||
### Task 7: Модалки — перечень, время открытия, что перерисовывается
|
||
|
||
**Модель:** sonnet
|
||
|
||
**Files:**
|
||
- Create: `perf/e2e/modals.json` — перечень модалок: `{id, page: "sheet"|"task"|"project"|"projects"|"admin_*"|"svod", source: "web/src/...:line", open: {selector, action}, priority: 1|2}`. Источник — поиск по `web/src` (`Dialog`, `Modal`, `common/Modal`) по страницам форм, задачи и проекта (priority 1) и админки (priority 2). Для модалки без воспроизводимого пути открытия ставится `"skip_reason"`.
|
||
- Create: `perf/e2e/lib/modal.ts` — `measureOpen(page, opener) -> {click_to_visible_ms, long_task_n, long_task_ms}`: отметка `performance.now()` в обработчике `pointerdown` (capture); `MutationObserver` ловит появление видимого `[role=dialog]`; конец — следующий `requestAnimationFrame` после появления.
|
||
- Create: `perf/e2e/lib/reactProfile.ts` — для profiling-сборки: через `__REACT_DEVTOOLS_GLOBAL_HOOK__` (init-script с минимальным хуком `onCommitFiberRoot`) считает число зафиксированных fiber-рендеров по `displayName` за окно замера. Возвращает топ-20 `{component, renders, self_ms}`.
|
||
- Create: `perf/e2e/scenarios/modals.spec.ts`.
|
||
- Test: `perf/e2e/tests/modal-lib.spec.ts` на `fixtures/modal.html`: кнопка открывает `role=dialog` через `setTimeout(150)`.
|
||
|
||
**Interfaces:**
|
||
- Consumes: Task 4 lib, манифест (`modal_pages`, `sheets`).
|
||
- Produces: записи `scenario: "modal"`, `target: modal.id`, метрики `measureOpen`; для profiling-прогона — `scenario: "modal_renders"`, `metrics.renders_top` (массив). Кроме того, сводная таблица `perf/report-data/<run_id>/modals-inventory.md` (id, source, priority, skip_reason).
|
||
|
||
Матрица:
|
||
- priority 1 × роль `rf` (`admin`, если модалка доступна только ему) × CPU `[1,4,6]` × 5 повторов;
|
||
- модалки страницы листа — дополнительно при открытом самом большом листе;
|
||
- priority 2 — CPU 6 × 3 повтора;
|
||
- profiling-сборка (сервер на `PERF_WEB_PROFILING`, `perf/stand.sh web-profiling` на :8081) — каждая модалка priority 1 × CPU 1 × 1 повтор.
|
||
|
||
- [ ] **Step 1: Тест:** `measureOpen` на `modal.html` даёт `click_to_visible_ms` в диапазоне `[150, 400]`; на кнопке без модалки падает по таймауту 5 с с сообщением, где есть id модалки.
|
||
- [ ] **Step 2:** Прогон → FAIL.
|
||
- [ ] **Step 3:** Составить `modals.json`. Реализовать lib, сценарий и подкоманду `web-profiling` в `stand.sh`.
|
||
- [ ] **Step 4:** Тест → PASS. Сценарий на priority 1 при CPU 6 даёт записи для всех модалок без `skip_reason`.
|
||
- [ ] **Step 5: Commit** — `perf: замеры открытия модалок`.
|
||
|
||
### Task 8: Память при длительной работе
|
||
|
||
**Модель:** sonnet
|
||
|
||
**Files:**
|
||
- Create: `perf/e2e/scenarios/memory.spec.ts`.
|
||
- Create: `perf/perfkit/memtrend.py` — `slope_per_cycle(values: list[float]) -> float` (наклон МНК); CLI печатает наклон по `heap_used_mb`, `nodes`, `js_event_listeners` из записей `memory`.
|
||
- Test: `perf/tests/test_memtrend.py`.
|
||
|
||
**Interfaces:**
|
||
- Consumes: Task 4 lib, манифест. Правки — через UI (двойной клик по ячейке и ввод числа), чтобы шли через фронтовый WS.
|
||
- Produces: записи `scenario: "memory"`, по одной на цикл: `metrics: {cycle, heap_used_mb, documents, nodes, js_event_listeners, ws_open}`. `ws_open` — счётчик открытых WebSocket, его ведёт init-script с обёрткой над `window.WebSocket`. Heap snapshots на циклах 0, 10, 20 — в `artifacts`.
|
||
|
||
Один цикл:
|
||
1. открыть самый большой лист FORM_1;
|
||
2. проскроллить вниз;
|
||
3. отредактировать 3 ячейки через UI;
|
||
4. перейти на `/tasks`;
|
||
5. открыть самый большой лист FORM_2;
|
||
6. проскроллить;
|
||
7. вернуться на `/tasks`;
|
||
8. `gc`, затем снять метрики.
|
||
|
||
Всего 20 циклов, роль `rf`, CPU 1 (память от троттлинга не зависит), масштаб 1, одна SPA-сессия без перезагрузки страницы.
|
||
|
||
- [ ] **Step 1: Тесты:** `slope_per_cycle([10,11,12,13]) == 1.0`; `slope_per_cycle([5,5,5]) == 0.0`; меньше двух точек → `ValueError`.
|
||
- [ ] **Step 2:** pytest → FAIL.
|
||
- [ ] **Step 3:** Реализовать `memtrend.py` и сценарий.
|
||
- [ ] **Step 4:** pytest → PASS. Сценарий даёт 21 запись (цикл 0 — базовая точка) и 3 heap snapshot. `python -m perfkit.memtrend <run_dir>` печатает три наклона.
|
||
- [ ] **Step 5: Commit** — `perf: сценарий памяти`.
|
||
|
||
### Task 9: Замеры бэка — запросы сценариев, pg_stat_statements, EXPLAIN
|
||
|
||
**Модель:** sonnet
|
||
|
||
**Files:**
|
||
- Modify: `perf/e2e/lib/results.ts` — сохранять сетевой лог (`page.on('requestfinished')`: метод, путь, статус, `timing`, размер тела) в `perf/results/<run_id>/network.jsonl` во всех сценариях Task 5–8 (через общую фикстуру).
|
||
- Create: `perf/perfkit/bench.py` — CLI `python -m perfkit.bench <run_dir> --repeats 20`: берёт уникальные `GET` и `PATCH`/`POST` (только идемпотентные PATCH ячеек с тем же значением) из `network.jsonl`, повторяет их через httpx под той же ролью. Пишет записи `scenario: "api"`, `target: "<METHOD> <path-template>"`, метрики `ms` и `bytes`. Шаблон пути — числа заменены на `{id}`.
|
||
- Create: `perf/perfkit/sqlstats.py` — `reset()` и `dump(run_dir, top=15)`: топ по `total_exec_time` и `mean_exec_time` из `pg_stat_statements` в `sql_top.json`. Для топ-5 по `total_exec_time`, где текст — вызов `v3.*`-функции или SELECT, выполняется `EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON)` с параметрами из сетевого лога, результат в `explain/<n>.json`. DML не EXPLAIN'ится.
|
||
- Test: `perf/tests/test_bench.py`.
|
||
|
||
**Interfaces:**
|
||
- Consumes: сетевой лог, манифест (пользователи), `PERF_DB_DSN`.
|
||
- Produces: `api`-записи, `sql_top.json`, `explain/*.json` в каталоге прогона.
|
||
|
||
- [ ] **Step 1: Тесты:**
|
||
- `test_path_template`: `"/api/v1/form/123/sheet/AHR/cells"` → `"/api/v1/form/{id}/sheet/AHR/cells"`;
|
||
- `test_select_requests_skips_non_idempotent`: `POST .../line` не попадает в набор повторов.
|
||
- [ ] **Step 2:** pytest → FAIL.
|
||
- [ ] **Step 3:** Реализовать. `sqlstats.reset()` вызывается в `globalSetup` Playwright, `dump` — в `globalTeardown`.
|
||
- [ ] **Step 4:** pytest → PASS. После прогона сценария скролла по FORM_1 есть `network.jsonl`, `sql_top.json` и ≥ 1 `explain/*.json`; `bench` пишет `api`-записи.
|
||
- [ ] **Step 5: Commit** — `perf: замеры бэка`.
|
||
|
||
### Task 10: Полные прогоны, статический разбор, отчёт
|
||
|
||
**Модель:** opus
|
||
|
||
**Files:**
|
||
- Create: `perf/run-all.sh` — масштаб 1: reset + gen + все сценарии + bench + memtrend + aggregate; то же для масштаба 2 (без admin-контроля и profiling-прогона).
|
||
- Create: `perf/REPORT.md`, `perf/report-data/<run_id>/summary.json`, `summary.md`, `modals-inventory.md`.
|
||
- Modify: `perf/README.md` — полный порядок: стенд, данные, прогоны, где результаты.
|
||
|
||
**Interfaces:**
|
||
- Consumes: всё выше.
|
||
|
||
- [ ] **Step 1:** `perf/run-all.sh` проходит целиком на масштабах 1 и 2. Записей с `incomplete` нет, а если есть — в отчёте раздел «не проверено» с причиной.
|
||
- [ ] **Step 2:** Разбор:
|
||
- traces первых повторов: топ функций по self time в long tasks при скролле;
|
||
- render counts модалок;
|
||
- retainers растущих объектов в heap snapshots (циклы 10 и 20);
|
||
- `sql_top` и EXPLAIN;
|
||
- сравнение масштабов 1 и 2;
|
||
- для эндпоинтов, где медиана `api.ms` больше суммарного времени их SQL из `sql_top.json` в 2 и более раза, — профиль `py-spy record` бэка на повторе `bench` по этому эндпоинту (`py-spy` ставится в `perf/.venv`).
|
||
|
||
Каждую горячую точку свести к `file:line` в `web/src` или `api/`.
|
||
- [ ] **Step 3:** Статический разбор кода по найденным точкам: нестабильные значения контекстов, пересоздание колонок и конфигов на рендер, слушатели, таймеры и WS без очистки, `console.log` в горячих обработчиках. Пометка «подтверждено замером: да/нет».
|
||
- [ ] **Step 4:** Написать `perf/REPORT.md` по структуре дизайна (резюме и топ-5, методика и окружение, включая версию Chromium и оговорки про Яндекс.Браузер и прод-ресурсы, обоснование масштаба из `plan.py`, таблица мест, подробности, не проверено). Каждая цифра — со ссылкой на файл в `perf/report-data/<run_id>/`.
|
||
- [ ] **Step 5:** Проверка: каждая строка таблицы мест имеет `file:line`, доказательство и приоритет; `git status` чист вне `perf/` и `.gitignore`; в `api/src`, `web/src`, `api/alembic` нет изменений (`git diff origin/test --stat -- api/src web/src api/alembic` пуст).
|
||
- [ ] **Step 6: Commit** — `perf: отчёт о проблемах производительности`.
|