krona-staff/tests/e2e/NOTES-FOR-EXECUTORS.md

Заметки для исполнителей (Codex / Antigravity)

Автор: Grok (стенд тестов и независимая приёмка). Я не меняю src/, apps/, migrations/, deploy/; всё, что требует изменения продукта, описано здесь.

Как запускать:

# bootstrap-админ PostgreSQL 17 (только создаёт роли и БД; сервер и миграции под ним не работают)
export E2E_PG_ADMIN_URL=postgres://<admin>:<pass>@127.0.0.1:55433/postgres
node scripts/test/run-e2e.mjs                    # храповик known-defects (как в CI)
node scripts/test/run-e2e.mjs --no-known-defects # строгий режим: все дефекты красные
E2E_MIGRATIONS=roundtrip node scripts/test/run-e2e.mjs  # + откат всех миграций перед запуском
./scripts/test/ci-local.sh                       # локальный эквивалент verify/format/e2e

Правило храповика. Исправили дефект → его сценарий позеленел → run-e2e.mjs падает с «дефект исправлен, обновите known-defects.json» — удалите ID из tests/e2e/known-defects.json в том же коммите. Новый красный сценарий, которого нет в списке, — регрессия.

1. Предполагаемый контракт для решений владельца (OWN-01..11) — Codex, этап 4

API пока нет, поэтому сценарии tests/e2e/30-owner-decisions.e2e.ts написаны против наиболее вероятного контракта. Если выбираете другой — поменяйте тесты и этот раздел в том же PR, смысл проверок (кто что может и когда) менять нельзя. Все пути относительно /api/v1/staff.

C1. Роли точки/бухгалтера/директора (standalone-аналог Core RBAC)

• POST /access-grants (только главный менеджер, staff:employee:write) тело { "role": "point_manager" | "accountant" | "director", "org_unit_ids": ["<ULID>"], "display_name": "..." } → 201 { "id", "role", "org_unit_ids", "access_token" }. Токен показывается один раз, хранится как хеш (как ключи сотрудников), используется как Authorization: Bearer.
• point_manager видит/считает только свои org_unit_ids; чужая точка → 403 (и для нового POST /payroll/batches, и для старого POST /payroll/calculate).
• В platform-режиме те же роли приходят из Core (User ≠ Employee, AGENTS.md).

C2. Пакет зарплаты точки и согласование

Метод и путь	Кто	Результат
POST /payroll/batches {org_unit_id, from, to}	accountant; point_manager своей точки	201 {id, status:"draft", org_unit_id, lines:[{work_session_id, employee_id, org_unit_id, amount_minor}]}
POST /payroll/batches/:id/submit	только accountant	200 {status:"submitted"}; point_manager → 403; повтор после подписи → 409
GET /notifications	любой пользователь	200 {notifications:[{type:"payroll.batch.submitted", subject_id:<batchId>}]}; каждому директору ровно одно уведомление на отправку
POST /payroll/batches/:id/sign	только director	200 {status:"signed"}; accountant → 403; если смена пакета изменилась после отправки → 409, пакет получает status:"returned"
POST /payroll/batches/:id/return {comment}	director	200 {status:"returned", return_comment}
GET /payroll/batches/:id	accountant, director	200 {status, return_comment, lines:[...]}

Инварианты, которые проверяют тесты:

• до подписи в staff_payroll_ledger для сотрудников пакета нет ни accrual, ни payout (OWN-05);
• подпись атомарно пишет accrual и payout; после подписи PATCH /work-sessions/:id для смен пакета → 409, пакет не отправляется повторно (OWN-06);
• строка пакета принадлежит точке, где отработана смена (staff_work_sessions.org_unit_id), а не основной точке сотрудника (OWN-09).

C3. Согласие на биометрию

• PUT /employees/:id/biometric-consent { "status": "granted" | "revoked", "document_ref": "..." } (главный менеджер) → 200.
• GET /terminal/employees/:id/enrollment (терминальный токен) → 200 { "employee_id", "registration_allowed": boolean, "reason": "consent_missing" | "consent_revoked" | null }. Без записи о согласии — false/consent_missing (OWN-10); после отзыва — false/consent_revoked (OWN-11).
• Шаблоны отпечатков на сервер не передаются (docs/TERMINAL-API-REQUIREMENTS.md); сервер хранит только факт согласия. Тот же флаг стоит отдать в /sync/pull (employee payload).

Сейчас все OWN красные с 404 Route ... not found (C1–C3 не реализованы); OWN-03..09 дополнительно упрутся в K3/N2 (подтверждение смены падает 500).

ID в названиях тестов — двойные «владелец/мой» ([K3/N2], [D6/OWN-01], [K17/OWN-10], [K19/OWN-07]), по таблице TASK-GROK-2 §2 и AUDIT.md.

C4. Проверочный пересчёт подписанной ведомости (K8/D1)

• GET /payroll/runs/:id/verify (право staff:payroll:read) → 200 { "run_id", "stored_total_minor", "recalculated_total_minor", "matches": boolean }.
• Пересчёт идёт по снимку версий правил, параметров и ставок, действовавших при подписи (и ревизиям смен), а не по текущим значениям. После смены ставки matches остаётся true.

C5. Параметры пресета в назначении оплаты (K9/D3)

• PUT /employees/:id/pay-assignment принимает params: { <key>: integer }, ключи — из param_declarations выбранного правила (например, shift_rate_minor, percent_bp, upsell_rate_minor, avg_check_target_minor, avg_check_bonus_minor у waiter_upsell); неизвестный ключ → 400. GET .../pay-assignment возвращает их в params.
• Старые поля rate_minor/percent_bp/guarantee_minor можно оставить как сокращения.

2. Дефекты продукта, найденные сценариями (все красные сейчас)

Команда и фактический вывод — tests/e2e/evidence/e2e-run.txt; таблица — tests/e2e/REPORT.md.

ID	Файл	Что исправить
K4/N1	src/portal.ts POST /employees	42P08 inconsistent types deduced for parameter $2: явные $2::varchar(26), $5::text или отдельный запрос профессии
K3/N2	src/portal.ts PATCH /work-sessions, src/domain/payroll/service.ts calculate/approve	staff_outbox.occurred_at NULL (23502): передавать occurred_at или DEFAULT now() новой миграцией
K5/N4	service.ts	после N2 проверить: пересекающийся период не должен начислять смену повторно (409 или исключение уже начисленных смен)
K12/N3	push-подписки	allowlist push-сервисов / запрет приватных адресов, redirect:'manual'; сейчас сервер подключается к 127.0.0.1
N9	push-dispatcher.ts	ON CONFLICT ... DO UPDATE SET employee_id → 409 для чужого endpoint
N10	GET /professions, /org-units	требовать право справочника; терминал сейчас получает 200
N11	импорт	валидировать kind и схему items → 400 вместо 500 (23514)
N12	PUT pay-assignment	additionalProperties:false, верхние границы сумм
N12-DATE	POST /payroll/calculate	month=2026-13 → 500 22008; проверять месяц 01–12 → 400 (диапазон 2026-02-30 уже даёт 400)
K6/D5	portal.ts PATCH /work-sessions	смена подписанной ведомости: 409, либо сторно в ledger; сейчас (на fix-live-database) 200 и начисление остаётся
K7/D2	operations.ts импорт payroll_entries	дельта по сумме всех записей дня, вставка по ключу: две точки за день → 222,00 вместо 333,00 ₽; считать дельту по ключу
K8/D1	расчёт/подпись	снимок правил и ставок в подписанной ведомости; контракт проверки C4 (ниже)
K9/D3	PUT pay-assignment	сохранять params по param_declarations правила (C5 ниже); сейчас shift_rate_minor официанта теряется
S9	миграция 0011 FK устройств	ON DELETE SET NULL на составном (tenant_id, org_unit_id) обнуляет tenant_id → 23502; SET NULL (org_unit_id) или RESTRICT
A4	обработчик ошибок	в теле 5xx нет SQLSTATE (code) и текста PostgreSQL; подробности только в лог
K1/F2	config.ts/identity.ts	standalone без токенов не должен выдавать права (процесс без токенов отдаёт 200 на /portal, /payroll, POST /professions)
K10/F3	POST/DELETE /session	в cookie — идентификатор сессии, а не сырой токен; logout отзывает сессию
K11/F4	вход	rate limit (тест ждёт 429 не позже 30 неверных попыток; идёт на отдельном процессе, чтобы лимит не мешал другим сценариям)
F7	POST /attendance/events	использовать Idempotency-Key / staff_idempotency_keys
F10	assertSameOrigin	мутации по cookie без Origin отклонять
K13/SYNC-A, K13/SYNC-B	src/domain/sync/service.ts	устройство не должно выставлять confirmed/approved (сейчас applied)
SYNC-C0	pull() bootstrap	SELECT ... status FROM staff_org_units — такого столбца нет → 500 на любой начальной загрузке
S5/SYNC-C	pull() bootstrap	при has_more=true отдаётся next_cursor=latest, остаток после 100 сущностей теряется; нужен курсор снимка
S5/SYNC-D	портал/импорт	изменения вне sync не пишутся в staff_sync_change_log → терминал не узнаёт о новых/изменённых сотрудниках
S4/SYNC-E	executeCommand	проверять status='active' сотрудника
S4/SYNC-F	executeCommand	сохранять org_unit_id в staff_attendance_events; payload не может переопределить точку устройства
S3/SYNC-G	push()	ошибки БД одной команды → rejected для неё, а не 500 и откат всего пакета
S8/SYNC-H	/sync/devices	assertCookieMutationOrigin как в портале
K1/SYNC-I	requireManagerContext	без токенов не выдавать права (как F2)
S2/SYNC-J	executeCommand	окно времени отметки как в POST /attendance/events (−180 дней … +5 мин)
SYNC-K	acknowledge()	отклонять курсор больше MAX(cursor_seq)

3. deploy/ (K1/PILOT-1, K2/PILOT-2) — Codex

• PILOT-1: все подстановки в deploy/pilot/compose.yaml → ${VAR:?VAR is required} (сейчас 14 без :?: пустой STANDALONE_MANAGER_TOKEN молча превращает pilot в F2).
• PILOT-2: NODE_ENV: development в app. Конфликт: config.ts запрещает STAFF_RUNTIME_MODE=standalone при NODE_ENV=production. Нужно решение: либо разрешить standalone в production при обязательных токенах и HTTPS, либо отдельный режим для pilot. Тест требует только «не development».
• N6: scripts/create-app-role.mjs не работает мигратором без SUPERUSER («Only roles with SUPERUSER may change the SUPERUSER attribute»). CI и e2e обходятся scripts/test/provision-pg.mjs (роли создаёт bootstrap-админ, как docker/postgres/init-app-role.sh). В pilot мигратор = POSTGRES_USER = суперпользователь; рекомендую схему как в provision-pg.mjs.

4. CI

• Задаче docker-build нужен раннер с меткой docker-host (Docker daemon). Без него задача ждёт в очереди; остальные задачи не блокируются.
• format красная, пока не исправлен F14 (23 файла на замер 2026-09-26, в основном src/, docs/, tests/unit/).
• format станет зелёной после влития codex/fix-format-baseline (проверено на ветке).
• Задача windows выключена, пока нет раннера с меткой windows: включается переменной репозитория KRONA_WINDOWS_RUNNER=true; для полного e2e нужен секрет WINDOWS_E2E_PG_ADMIN_URL (локальная PostgreSQL 17 на раннере).
• tests/e2e/evidence/ не хранится в git; в CI это артефакт e2e-evidence.
• Реальный Forgejo-раннер мной не запускался (нет API-токена) — не проверено.

5. N13 (гонка первого расчёта) и утечка текста ошибок БД

• scripts/test/n13-race.mjs, вывод tests/e2e/evidence/n13-race.txt: 10/25/50 параллельных первых POST /payroll/calculate × 5 попыток. Как есть — все 500 (N2), гонку не видно. В одноразовой БД с обходом N2 (DEFAULT now() только там) — 0 из 30 некорректных попыток (без смен и с подтверждённой сменой): один run_id, один расчёт в БД.
• Почему не воспроизводится (вывод из кода, не проверено отдельным экспериментом): calculatePayroll сначала вызывает ensureDefaultPayRules, а там INSERT ... ON CONFLICT DO UPDATE по одним и тем же строкам staff_pay_rules тенанта. Первая транзакция держит блокировки этих строк до коммита, остальные ждут — расчёты одного тенанта выполняются по очереди случайно. Если upsert правил вынесут из расчёта или сделают DO NOTHING, окно SELECT ... FOR UPDATE (строки нет) → INSERT ... ON CONFLICT DO NOTHING со своим runId → строки/UPDATE по несуществующему runId вернётся. Рекомендация: явный pg_advisory_xact_lock по (tenant, org_unit, period_start) или INSERT ... ON CONFLICT DO UPDATE ... RETURNING id. Скрипт стоит перезапустить после такого изменения.
• Ответы 500 содержат сырой текст ошибки PostgreSQL (например null value in column "occurred_at" of relation "staff_outbox" ...) — клиенту видна схема БД. Для 5xx отдавать нейтральное сообщение, подробности — только в лог.

6. Приёмка веток исполнителей (2026-09-26)

Подробно — tests/e2e/REPORT.md и tests/e2e/report-evidence/acceptance-*.txt.

• codex/fix-live-database (ea68e12, перепроверено на b289dd6): K3/N2 и K4/N1 зелёные на живой PostgreSQL 17. Дальше по цепочке открылись K5/N4 (196800 вместо 98400 — двойное начисление) и K6/D5 (отклонение оплаченной смены: 200, начисление осталось). A4 частично: POST /employees больше не 500, но month=2026-13 по-прежнему отдаёт code=22008 с текстом.
• codex/fix-format-baseline (fd1ec3d): prettier --check . чистый. Но коммит «style» содержит функциональное исправление Antigravity: src/domain/sync/service.ts и tests/unit/sync.test.ts после нормализации prettier совпадают с antigravity/fix-reject-device-shifts (0 строк diff) и отличаются от 331e490 на 255/139 строк. Изменение поведения стоит вынести в отдельный коммит с объяснением или влить ветку Antigravity отдельно, иначе история смешивает темы (AGENTS.md).
• antigravity/fix-reject-device-shifts (795bba0, перепроверено на 1df2019 — уже на f5ac179): K13/SYNC-A и K13/SYNC-B зелёные, остальное без изменений.
• Ни одна ветка не влита в основную (f5ac179), поэтому ID из known-defects.json не удалены.
• Суммы в тестах кратны рублю: расчёт округляет строку до rounding_unit_minor (по умолчанию 100 коп.). Если округление должно быть другим — это решение продукта, не теста.