Victor Trushenko
f5ac179623
Some checks are pending
ci / verify (push) Waiting to run
Executors could not see the audit: Grok reported that the owner's AUDIT.md and evidence never reached it, so its scenarios could not be mapped to the audit IDs. Keeping the audit, the acceptance report and the task for each executor in the repository lets Codex, Antigravity and Grok take work and report through git. The live-check scripts are stored as .mjs.txt so the project linter, which type-checks every .mjs file, does not break for everyone; the maintained version of these checks is Grok's harness in tests/e2e. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
105 lines
20 KiB
Markdown
105 lines
20 KiB
Markdown
# Задание для Antigravity: синхронизация, уведомления, outbox
|
||
|
||
- Репозиторий: https://git.ochenstarik.ru/ochenstarik/krona-staff
|
||
- Основа: ветка `codex/bootstrap-platform-foundation`, коммит `778ba2d`. Твоя офлайн-синхронизация в неё уже влита (`3595792`); код такой же, как в проверенном коммите `5ee7517`.
|
||
- Материалы в репозитории: `docs/audit/2026-09-26/` — `AUDIT.md` и `evidence/`. Для синхронизации есть живые сценарии: `evidence/live-sync.mjs.txt`, вывод — `evidence/live-sync.txt`.
|
||
|
||
## Контекст
|
||
|
||
На живой PostgreSQL 17 подтвердилось:
|
||
|
||
- **Устройство синхронизации создаёт подтверждённые смены.** Оно отправило смену с `status: confirmed` и `worked_minutes: 2880`. Смена сохранилась подтверждённой без участия управляющего и без записи в журнале аудита. Расчёт начислил по ней 14 400 ₽. Это дефект основной ветки.
|
||
- **Отметки задним числом проходят.** Устройство сохранило отметку с датой 2020 года.
|
||
- **Точку с устройством нельзя удалить.** Удаление падает с `23502`.
|
||
- **Push-подписка даёт доступ во внутреннюю сеть.** Сотрудник подписал push на `https://127.0.0.1:…`, после чего сервер сам открыл туда соединение.
|
||
|
||
## Зона ответственности
|
||
|
||
**Твоя зона:**
|
||
|
||
- офлайн-синхронизация: `src/sync.ts`, `src/domain/sync/**`, миграция `0011`, `docs/OFFLINE-SYNC-PROTOCOL.md`;
|
||
- уведомления: `src/domain/notification/**`, маршруты `/push/*` в `src/portal.ts`, миграция `0010`, service worker и подписка в `src/portal-ui.ts`;
|
||
- диспетчер и публикатор outbox — всё, что читает `staff_outbox` и доставляет события.
|
||
|
||
**Не трогай:**
|
||
|
||
- авторизацию, сотрудников, смены, расчёт, импорт, процесс подтверждения, терминал и развёртывание — это Codex;
|
||
- `tests/e2e/**`, `tests/integration/tenant-isolation.test.ts`, CI — это Grok.
|
||
|
||
**Записывать в outbox** только через общий хелпер, который Codex делает в задаче K3. Свою вставку не пиши: сейчас именно из-за разрозненных вставок без `occurred_at` падают подтверждение и расчёт.
|
||
|
||
## Правила
|
||
|
||
- Ветки `antigravity/fix-<тема>` от основной, отдельный PR на каждую часть.
|
||
- Маленькие коммиты. **В теле каждого коммита объясни причину** (AGENTS.md).
|
||
- Перед пушем: `npm run check` и `npm run format:check` зелёные. Миграции проверены вверх и вниз на чистой PostgreSQL 17 мигратором без SUPERUSER.
|
||
- Каждое исправление — с тестом на настоящей PostgreSQL, а не только на поддельной базе.
|
||
- Пункт считается закрытым, только если соответствующий сценарий из `evidence/live-sync.mjs.txt` или `evidence/live-audit.mjs.txt` больше не воспроизводит дефект. Grok проверяет каждый пункт независимо.
|
||
|
||
## Часть 0 — немедленная мера (первым PR, сегодня)
|
||
|
||
- Сервер отклоняет от устройств команды `upsert_work_session` и `upsert_timesheet_entry`: ответ «команда не поддерживается», в базу ничего не пишется. Файл: `src/domain/sync/service.ts:784-990`.
|
||
- Отдельный маленький PR. Grok проверяет его первым.
|
||
- До закрытия S1 и S2 устройства синхронизации в пилоте не регистрировать.
|
||
|
||
**Готово, когда:** сценарий S1 из `evidence/live-sync.mjs.txt` больше не создаёт смену.
|
||
|
||
## Часть 1 — офлайн-синхронизация
|
||
|
||
| ID | Что сделать | Где | Готово, когда |
|
||
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
|
||
| S1 (P1) | Устройство отправляет только события отметок, смены и табель считает сервер (reconcile). Если правка с устройства действительно нужна: отдельный scope, только черновые статусы, запрет трогать `confirmed` и `approved`, запись в журнал аудита | `src/domain/sync/service.ts:784-990` | Команда с `status: confirmed` отклоняется; поддельная смена не попадает в расчёт |
|
||
| S2 | `occurred_at` принимать только в строгом ISO с зоной. Устройство передаёт своё текущее время, сервер считает расхождение часов и ограничивает время отметки относительно времени получения. При большом расхождении — статус `pending_review` | `service.ts:659, 723, 756` | Отметка с датой 2020 года отклоняется или уходит на проверку |
|
||
| S3 | Сначала захватить ключ идемпотентности, потом выполнять команду. `SAVEPOINT` на каждую команду. Проверка ревизии в `UPDATE`. `source_event_id = sync:{device}:{key}`. Временные отказы не кэшировать | `service.ts:672, 702, 774, 832, 936` | Две параллельные отправки с одним ключом выполняются один раз; одна плохая команда не откатывает весь пакет |
|
||
| S4 | Начальная загрузка: только точка устройства, только активные сотрудники, ограниченное окно дат, пагинация в SQL | `service.ts:~380-590, 448` | Устройство не получает уволенных и чужие точки |
|
||
| S5 | Курсор не теряет данные при `has_more`. Порядок — по фиксации транзакций, а не по `BIGSERIAL`. Изменения из портала видны устройству. Повторная начальная загрузка при устаревшем курсоре, как обещает протокол | `service.ts:343, 595-600` | — |
|
||
| S6 | Отметки через синхронизацию пишут outbox так же, как онлайн-маршрут. Проверять `status = 'active'` сотрудника. Сохранять `org_unit_id` | `service.ts:720-780` | — |
|
||
| S9 | Внешний ключ `(tenant_id, org_unit_id) ON DELETE SET NULL` обнуляет и `tenant_id`, поэтому удаление точки падает. Заменить на `SET NULL (org_unit_id)` или `RESTRICT` новой миграцией | `migrations/0011_offline_sync_backend.up.sql:21` | Точку с устройством можно удалить или получить понятный отказ |
|
||
| S7 | Очистка входящих должна получать `tenant_id`, а не идентификатор системного актора. Запускать её по расписанию | `service.ts:1056` | — |
|
||
| S8 | Проверка Origin на маршрутах управления устройствами. Белый список scope. `no-store` на ответе с токеном устройства | `src/sync.ts:74`, `service.ts:190` | — |
|
||
|
||
## Часть 2 — уведомления
|
||
|
||
| ID | Что сделать | Где | Готово, когда |
|
||
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
|
||
| K12 (N3, P1) | Разрешать только известные push-сервисы: FCM, Mozilla, Apple, WNS. После разрешения DNS запрещать приватные, loopback и link-local адреса. `redirect: 'manual'`, таймаут 5–10 с, тело ответа не сохранять | `src/domain/notification/push-dispatcher.ts:80`, `web-push.ts:226-258` | Подписка на `https://127.0.0.1:…` отклоняется; сценарий N3 не даёт входящего соединения |
|
||
| N9 | Конфликт endpoint с другим сотрудником → 409. Перепривязка — только тем же браузером | `push-dispatcher.ts:100-111` | Сценарий N9 отвечает 409 |
|
||
| N8 | В production без `VAPID_*` сервер не стартует. Публичный ключ отдавать с `no-cache` | `web-push.ts:80-87`, `src/portal.ts:121-123` | — |
|
||
| U1 | Проверять ключи подписки при регистрации. Ошибки отправки обрабатывать отдельно для каждой подписки | `web-push.ts:230`, `push-dispatcher.ts:283` | Неверная подписка не мешает остальным устройствам сотрудника |
|
||
| U2 | Не больше 5–10 подписок на сотрудника, таймаут, чтение тела ответа не больше 1 КБ, ограничение параллельности | `web-push.ts:235-258` | — |
|
||
| U3, U4 | Атомарный захват строки перед отправкой: статус `sending` плюс аренда. Повторы с backoff и учётом `Retry-After`. Отдельный статус dead letter. Срок хранения `last_error` | `push-dispatcher.ts:233-367` | При двух экземплярах сервера сообщение уходит один раз |
|
||
| U5, U6 | Scope service worker должен покрывать `/staff`. Выход из кабинета отзывает push-подписку устройства | `src/portal-ui.ts` (регистрация service worker и выход) | — |
|
||
| U7 | Составной внешний ключ с `tenant_id` в `staff_notification_deliveries` | `migrations/0010…up.sql:44` (новой миграцией) | — |
|
||
|
||
## Часть 3 — оповещения процесса подтверждения
|
||
|
||
Решение владельца: бухгалтер отправляет пакет с расчётом и выплатами на подтверждение, руководитель получает оповещение, проверяет и подписывает, после чего всё регистрируется. Процесс, подпись и события в outbox делает Codex (его этап 4). От тебя — доставка.
|
||
|
||
| Событие | Кому | Что в оповещении |
|
||
| --------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------ |
|
||
| `staff.payroll.package_submitted` | Всем с ролью «Руководитель» в арендаторе | Период, число сотрудников, итог, число предупреждений; ссылка сразу на экран подписи |
|
||
| `staff.payroll.package_returned` | Бухгалтеру, отправившему пакет | Комментарий руководителя |
|
||
| `staff.payroll.package_signed` | Бухгалтеру; сотрудникам из пакета | Сотрудникам — только «начисление за период доступно», без сумм в тексте; суммы видны лишь в приложении |
|
||
|
||
- Основной канал — push в приложении. Если push не доставлен (нет подписки или ошибка), руководителю уходит сообщение в Telegram — без персональных данных и сумм.
|
||
- Если пакет не подписан за настраиваемое время (по умолчанию 24 ч), руководителю приходит повторное напоминание.
|
||
- Адресат определяется по роли и арендатору, а не по фиксированному списку: при смене руководителя оповещения получает новый.
|
||
|
||
**Готово, когда** на живом стенде отправка пакета даёт ровно одно оповещение каждому руководителю, а перезапуск сервера его не дублирует. Сотрудник получает уведомление без сумм и только после подписи.
|
||
|
||
## Часть 4 — публикатор outbox
|
||
|
||
| ID | Что сделать | Где | Готово, когда |
|
||
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
|
||
| F6, D7 | Заменить `setImmediate` фоновым публикатором. Он повторяет строки в `pending` и `failed`, ставит `published_at`, обеспечивает идемпотентность у получателя через inbox и соблюдает политику хранения. Альтернатива — убрать из `module.json` события, которые никто не публикует | `src/portal.ts:830-842`, `push-dispatcher.ts:333-367`, `module.json` | После перезапуска сервера неотправленные события уходят; `staff_outbox` не растёт бесконечно |
|
||
|
||
## Порядок работы с остальными
|
||
|
||
1. **Сразу:** часть 0.
|
||
2. **Параллельно с этапами 1–3 у Codex:** части 1 и 2. Часть S6 делай после того, как Codex сообщит, что влит общий хелпер outbox (K3).
|
||
3. **После этапа 4 у Codex** (события пакета): часть 3.
|
||
4. **Часть 4** — в любой момент после K3.
|
||
|
||
## Отчёт после каждой части
|
||
|
||
Таблица «ID — что сделано — коммит — тест» и список того, что не удалось, с причиной.
|