Перейти до основного вмісту

Журнал аудиту та пакети з можливістю скасування

Кожна зміна даних, ініційована користувачем в Api, фіксується: хто, що, коли і з якої адреси. Це стосується всіх модулів і не потребує налаштування в кожному контролері. Поверх цього журналу працює шар пакетів: імпорт або масову дію можна позначити як пакет, а потім скасувати рядок за рядком, у стилі Planning Center. Обидва механізми зберігаються в єдиній таблиці auditLogs у базі даних членства і керуються з однієї точки, BaseController.actionWrapper. На цій сторінці описано, що саме аудитується, де зберігаються дані, компроміси щодо продуктивності, які визначають їхню структуру, і як скасування безпечно відкочує пакет без міжбазових транзакцій.

Огляд​

every mutating request (POST/PUT/PATCH/DELETE)
│
▼
BaseController.actionWrapper ──▶ derive {module, entityType, category, action}
│ from req.baseUrl + method (AUDIT_REGISTRY = overrides/opt-outs only)
│
├─ normal mode ─────────▶ run action ─▶ await AuditLogHelper.log(after-values) ──┐
│ (deletes also capture a before-image) │
│ ▼
└─ X-Batch-Id present ──▶ snapshot before-images (strict) ─▶ run action ─▶ audit rows tagged batchId
│
▼
auditLogs (membership DB, one table, all modules)
│
POST /membership/batches/:id/undo ──▶ BatchUndoHelper ──▶ walk rows reverse, per entity ┘
conflict guard → restore / delete / re-insert

Два структурні факти визначають усе, що нижче:

  1. Лише шар контролерів знає, хто виконує дію. Репозиторії ніколи не бачать AuthenticatedUser; лише контролери мають au. Усі контролери кожного модуля вже проходять через BaseController.actionWrapper, тож саме тут підключається аудит. Сигнатури репозиторіїв ніде не змінюються.
  2. Одна таблиця обслуговує всі модулі. Записи аудиту для пожертв, відвідуваності, контенту тощо потрапляють до таблиці auditLogs у базі membership через RepoManager.getRepos("membership"), навіть коли їх створює контролер іншого модуля. Запит «усе, що Jane змінила сьогодні» залишається одним запитом.

Що аудитується​

Аудит увімкнено за замовчуванням для кожного дієслова зміни на кожному маршруті. actionWrapper виводить поля аудиту із запиту без жодної конфігурації для окремих маршрутів:

ПолеПоходження
modulethis.moduleName (модуль-власник)
entityTypeоднина останнього сегмента req.baseUrl (наприклад, /membership/people → person)
categoryза замовчуванням дорівнює entityType
action${entityType}_saved для POST /, ${entityType}_deleted для DELETE /:id, інакше ${entityType}_${method}:${routePath}, тож підмаршрути, що не належать до CRUD (наприклад, task_post:/:id/move), фіксуються автоматично

BaseController.AUDIT_REGISTRY призначено лише для перевизначень і винятків. Це не список дозволених. Маршрут потрапляє туди, щоб перейменувати свою категорію або entityType, оголосити { dbModule, table } (що робить його придатним для пакетної обробки та скасування), позначити як sensitive (аудит анонімних змін) або вимкнути через optOut: true.

Список винятків (шляхи запису з великим обсягом, які затопили б журнал): відвідуваність visits / visitsessions / sessions / checkin (наплив недільної реєстрації) та повідомлення messages / connections / devices (чат і присутність). Усе інше логується.

Масові ендпоінти (people/bulk-delete, people/bulk-update, groupmembers/bulk-add, groupmembers/bulk-remove) зареєстровані в BULK_ROUTES і створюють один рядок аудиту для кожного зачепленого ідентифікатора. Тож імпорт 10 000 людей дає 10 000 рядків. Саме така деталізація за сутністю і робить пакет скасовним.

Анонімні зміни (actionWrapperAnon: анонімні пожертви, реєстрація гостей, надсилання форм) аудитуються лише для маршрутів, позначених у реєстрі як sensitive. Записи мають userId="anonymous" і IP-адресу клієнта. Пожертви очолюють список, і цей шлях має реальну історію регресій.

Редагування секретів і обмеження розміру​

Перш ніж будь-який payload details буде збережено, AuditLogHelper.capDetails() виконує sanitizeValue() над ним:

  • Секретні ключі редаговуються. Будь-яке поле, чия назва в нижньому регістрі міститься в SENSITIVE_KEYS (password, token, cvv, cardnumber, routing_number, accesstoken, clientsecret, …), замінюється на "[redacted]".
  • Великі скаляри видаляються. Будь-який URI data: або рядок понад 4 КБ (base64-фото, великі бінарні дані) стає "[stripped]".
  • Завеликі рядки обрізаються. Якщо серіалізований JSON перевищує приблизно 64 КБ, увесь payload замінюється на { truncated: true }. Обрізані рядки можна переглядати, але не можна скасувати, бо немає зображення до або після змін, з якого можна було б відновити дані.

Де зберігаються дані​

Єдина таблиця auditLogs у базі membership обслуговує всі модулі. Колонки: id, churchId, userId, category, action, entityType, entityId, details (MEDIUMTEXT JSON string), ipAddress, module, batchId, created. Міграція tools/migrations/membership/2026-07-04_audit_universal.ts додає module і batchId, розширює details з TEXT до MEDIUMTEXT, додає індекси ix_auditLogs_batch (batchId) та ix_auditLogs_entity (churchId, module, entityType, entityId, created) і створює таблицю batches. Колонка module існує саме для того, щоб колізії entityType між модулями (note і setting є в кількох) залишалися фільтрованими. Індекс за сутністю забезпечує і історію для окремої сутності, і перевірку конфліктів під час скасування.

Запис між модулями йде через RepoManager.getRepos("membership") зсередини обгортки. Порядок навмисний: основний запис фіксується спочатку в базі модуля, вставка аудиту другою. У звичайному режимі помилка вставки аудиту ковтається (console.error, Sentry її підхоплює). Аудит є довідковим і ніколи не повинен провалювати запит користувача. У пакетному режимі вона строга (див. нижче).

Чому не тригери, CDC чи окремі таблиці для кожного модуля?
  • Тригери MySQL не знають, який користувач діє (з'єднання не має au), і вимагали б підтримки наборів тригерів у кожній схемі.
  • binlog / CDC — це окремий інфраструктурний проєкт із тією самою проблемою ідентифікації виконавця.
  • Передача userId через кожен репозиторій торкнулася б сотень файлів заради інформації, яка вже є в шарі контролерів.
  • Окремі таблиці аудиту для кожного модуля означали б у сім разів більше інфраструктури та запитів для будь-якого міжмодульного питання. Одна таблиця в точці контролера — це найменш складне рішення, яке все ще фіксує виконавця.

Підхід до продуктивності​

Гарячий шлях навмисно дешевий. Ціна сплачується лише там, де вона щось купує.

  • Немає читання перед записом під час звичайних оновлень. Звичайне збереження не завантажує старий запис. Надіслані значення після змін зберігаються в details.after. Інтерфейс відтворює перехід від старого до нового під час перегляду, порівнюючи з попереднім записом аудиту цієї сутності. Це один запит під час перегляду і нульова вартість під час запису. Поля, яких не чіпали від запуску, просто не показують «старого» значення. Це прийнятно.
  • Видалення отримують зображення до змін. DELETE /:id на маршруті реєстру з { dbModule, table } спочатку узагальнено завантажує рядок і зберігає його в details.before. Видалення трапляються рідко, а зображення до змін є всією криміналістичною цінністю.
  • Пакетний режим є єдиним систематичним читанням перед записом, і він увімкнений за бажанням. Масова операція або імпорт і так дорогі, тож N читань знімків є ціною скасування.
  • Вставки аудиту очікуються (await). actionWrapper збирає проміси логування і викликає await Promise.allSettled(...) перед поверненням відповіді. Це найважливіший інваріант: на Lambda контейнер заморожується в той момент, коли відповідь повертається, тож невідкладена вставка тихо втрачається. «Fire and forget» тут означає, що помилки ніколи не провалюють запит, а не не чекати. Одна вставка на вже прогрітому пулі membership займає близько 1–3 мс.

Пакети та скасування​

Пакет групує набір змін, щоб їх можна було разом переглянути й скасувати. Відкрити його можна двома способами:

  • Явно: POST /membership/batches { label, source } повертає batchId. Клієнт (B1Transfer, інтерфейс імпорту B1Admin) потім надсилає X-Batch-Id: <id> з кожним наступним збереженням або видаленням. POST /membership/batches/:id/complete закриває пакет і записує itemCount.
  • Неявно: чотири масові ендпоінти відкривають, наповнюють і завершують власний пакет в межах одного запиту та повертають batchId у відповіді.

Таблиця batches (база membership): id, churchId, userId, label, source, status (open|completed|undone|partial|failed), itemCount, created, completedAt, undoneAt.

Пакетний режим строгий​

Коли присутній X-Batch-Id, actionWrapper посилює кожну перевірку (writeBatchAuditRows):

  1. Пакет має існувати, мати статус open і належати au.churchId. Інакше відповідь 403.
  2. Маршрут має підтримувати пакети ({ dbModule, table } у реєстрі). Інакше відповідь 400.
  3. Перед виконанням дії зображення до змін для всіх зачеплених ідентифікаторів завантажуються одним запитом WHERE id IN (...) AND churchId = ?. Якщо читання знімка не вдається, запит завершується з 500, і дія не виконується. Пакетний режим ніколи не повинен мовчки створити журнал, який неможливо скасувати. (У звичайному режимі, навпаки, це найкраще зусилля, і помилки знімків ковтаються.)
  4. Після успішного виконання дії для кожної сутності записується один рядок аудиту з batchId, details.before і details.after, а також явний маркер створення для рядків, які пакет створив.

Скасування​

POST /membership/batches/:id/undo (дозвіл: творець пакету або Permissions.server.admin). Запит відхиляється, якщо пакет не має статусу completed або старший за 30-денне вікно скасування. Далі BatchUndoHelper.undo():

  1. Завантажує рядки аудиту пакета і групує їх за (module, entityType, entityId). Сутність, яку пакет змінив кілька разів, скасовується один раз, до її справжнього стану перед пакетом: це найраніше зображення до змін або видалення, якщо пакет її створив. Саме тому скасування не відтворює кожен рядок підряд. Відновлення проміжного знімка посеред пакета було б помилковим.
  2. Для кожної сутності спершу виконується перевірка конфліктів: auditLog.hasLaterModification() перевіряє, чи існує будь-який пізніший запис аудиту для тих самих (module, entityType, entityId) поза цим пакетом. Якщо так, сутність редагували після імпорту. Її пропускають і повідомляють, але ніколи не перезаписують. Тут сам журнал аудиту слугує детектором змін, тож жодні колонки modifiedAt у таблицях не потрібні.
  3. Скасовує відповідно до записаної операції, визначаючи { dbModule, table } з реєстру і використовуючи узагальнені записи Kysely:
    • created: жорстко видалити рядок.
    • updated: записати details.before назад.
    • deleted: повторно вставити details.before (оновити або вставити, якщо рядок з цим ідентифікатором знову з'явився).
  4. Саме скасування теж аудитується (action: "<entityType>_undone", без batchId, бо скасування скасування виходить за межі цієї роботи).

Операція визначається за явним маркером створення, а не виводиться з відсутнього зображення до змін. Законно порожнє зображення до змін або обрізаний рядок не повинні сприйматися як створення.

Результат є payload { restored, skippedConflicts: [...], failed: [...], status }. Пакет переходить у стан undone (чисто) або partial. Міжбазової транзакції немає. Скасування виконується за принципом найкращих зусиль для кожного рядка, і це те саме обмеження, яке Planning Center документує для об'єднаних профілів.

Сутності з побічними ефектами потребують хука onUndo

Скасування створення groupMember також має записати groupMemberHistory («вийшов»), інакше аналітика плинності тихо зламається. Це постійний інваріант робочого простору. Такі сутності реєструють callback onUndo в AUDIT_REGISTRY, який повертає true, коли повністю обробив скасування, і обходить загальний шлях. groupMembers є канонічним прикладом: на явному шляху вони ключуються за ідентифікатором рядка, а на масових ендпоінтах за personId, і їхня історія відстежується при кожному додаванні та видаленні.

Споживчі поверхні​

Обидві адміністративні поверхні ще в розробці. Задум такий:

ПоверхняРепозиторійПризначення
Сторінка журналу аудитуB1Admin (ManageChurch → Audit Log)Фільтрація за модулем, категорією, користувачем або сутністю та відображення змін old→new: для редагувань через порівняння з попереднім записом сутності, для видалень із details.before. Працює через GET /membership/auditlogs, доступ за Permissions.server.admin.
Сторінка пакетівB1Admin (той самий хаб налаштувань)Список пакетів зі статусами та лічильниками, View Results (рядки аудиту пакета через GET /membership/batches/:id/results) і кнопка Undo, яка показує звіт про пропущені конфлікти та помилки.
Пакети імпортуB1TransferВідкрити пакет, надсилати X-Batch-Id у звичайних викликах збереження, завершити наприкінці. Імпорти стають скасовними без нових ендпоінтів імпорту. Застарілий importKey залишається маркером походження лише для створень і для скасування замінений.

Підводні камені, яких майбутня зміна не повинна зламати​

  • Вставки аудиту мають залишатися з await. Невідкладений AuditLogHelper.log(...) губиться через заморожування Lambda. Збирайте проміси та викликайте await Promise.allSettled перед поверненням.
  • Kysely відкидає undefined у .set() і .values(). Під час відновлення очищена колонка залишилася б недоторканою. BatchUndoHelper перетворює кожне відсутнє поле на явний null (nullify). Ніколи не обходьте це заради «швидшого» прямого запису.
  • Строк зберігання має бути значно більшим за вікно скасування. AuditLogRepo.deleteOld() працює за нічним таймером (типово 365 днів зберігання), а вікно скасування становить 30 днів. Якщо зберігання колись наблизиться до цього вікна, журнали скасування буде видалено з-під відкритих пакетів.
  • Обрізані рядки не можна скасувати. Payload { truncated: true } не має зображення до або після змін. Скасування позначає його як failed і ніколи не вгадує.
  • Порядок: спершу запис модуля, потім аудит. Ніколи не переносьте вставку аудиту перед реальним записом. Зберігайте її строгою в пакетному режимі та довідковою у звичайному.

Перелік файлів​

ОбластьФайли
Обгортка / реєстрApi/src/shared/infrastructure/BaseController.ts (AUDIT_REGISTRY, BULK_ROUTES, actionWrapper, actionWrapperAnon, знімок і запис рядків)
Рушій скасуванняApi/src/shared/infrastructure/BatchUndoHelper.ts
Помічник аудитуApi/src/modules/membership/helpers/AuditLogHelper.ts (log, capDetails/sanitizeValue, diffFields, getClientIp)
КонтролериApi/src/modules/membership/controllers/AuditLogController.ts, BatchController.ts
Моделі / репозиторіїApi/src/modules/membership/models/AuditLog.ts, Batch.ts; repositories/AuditLogRepo.ts (loadFiltered, loadForBatch, hasLaterModification, deleteOld), BatchRepo.ts
МіграціяApi/tools/migrations/membership/2026-07-04_audit_universal.ts
Інтерфейс адміністратора (у розробці)Сторінки B1Admin Audit Log і Batches; заголовок пакета імпорту в B1Transfer

Пов'язані сторінки​

  • Структура модуля: як контролер модуля, що не є membership, отримує доступ до репозиторіїв membership через RepoManager
  • Пожертви: шляхи запису пожертв, які аудитуються як sensitive, навіть коли вони анонімні
  • Ендпоінти membership: REST-інтерфейс, який передає X-Batch-Id і надає /auditlogs та /batches