Журнал аудиту та пакети з можливістю скасування
Кожна зміна даних, ініційована користувачем в 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
Два структурні факти визначають усе, що нижче:
- Лише шар контролерів знає, хто виконує дію. Репозиторії ніколи не бачать
AuthenticatedUser; лише контролери маютьau. Усі контролери кожного модуля вже проходять черезBaseController.actionWrapper, тож саме тут підключається аудит. Сигнатури репозиторіїв ніде не змінюються. - Одна таблиця обслуговує всі модулі. Записи аудиту для пожертв, відвідуваності, контенту тощо потрапляють до таблиці
auditLogsу базі membership черезRepoManager.getRepos("membership"), навіть коли їх створює контролер іншого модуля. Запит «усе, що Jane змінила сьогодні» залишається одним запитом.
Що аудитується
Аудит увімкнено за замовчуванням для кожного дієслова зміни на кожному маршруті. actionWrapper виводить поля аудиту із запиту без жодної конфігурації для окремих маршрутів:
| Поле | Походження |
|---|---|
module | this.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 її підхоплює). Аудит є довідковим і ніколи не повинен провалювати запит користувача. У пакетному режимі вона строга (див. нижче).
- Тригери 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):
- Пакет має існувати, мати статус
openі належатиau.churchId. Інакше відповідь 403. - Маршрут має підтримувати пакети (
{ dbModule, table }у реєстрі). Інакше відповідь 400. - Перед виконанням дії зображення до змін для всіх зачеплених ідентифікаторів завантажуються одним запитом
WHERE id IN (...) AND churchId = ?. Якщо читання знімка не вдається, запит завершується з 500, і дія не виконується. Пакетний режим ніколи не повинен мовчки створити журнал, який неможливо скасувати. (У звичайному режимі, навпаки, це найкраще зусилля, і помилки знімків ковтаються.) - Після успішного виконання дії для кожної сутності записується один рядок аудиту з
batchId,details.beforeіdetails.after, а також явний маркер створення для рядків, які пакет створив.
Скасування
POST /membership/batches/:id/undo (дозвіл: творець пакету або Permissions.server.admin). Запит відхиляється, якщо пакет не має статусу completed або старший за 30-денне вікно скасування. Далі BatchUndoHelper.undo():
- Завантажує рядки аудиту пакета і групує їх за
(module, entityType, entityId). Сутність, яку пакет змінив кілька разів, скасовується один раз, до її справжнього стану перед пакетом: це найраніше зображення до змін або видалення, якщо пакет її створив. Саме тому скасування не відтворює кожен рядок підряд. Відновлення проміжного знімка посеред пакета було б помилковим. - Для кожної сутності спершу виконується перевірка конфліктів:
auditLog.hasLaterModification()перевіряє, чи існує будь-який пізніший запис аудиту для тих самих(module, entityType, entityId)поза цим пакетом. Якщо так, сутність редагували після імпорту. Її пропускають і повідомляють, але ніколи не перезаписують. Тут сам журнал аудиту слугує детектором змін, тож жодні колонкиmodifiedAtу таблицях не потрібні. - Скасовує відповідно до записаної операції, визначаючи
{ dbModule, table }з реєстру і використовуючи узагальнені записи Kysely:- created: жорстко видалити рядок.
- updated: записати
details.beforeназад. - deleted: повторно вставити
details.before(оновити або вставити, якщо рядок з цим ідентифікатором знову з'явився).
- Саме скасування теж аудитується (
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