Пријавите се на главни садржај

Журнал ревизије и серије са могућношћу поништавања

Свака мутација коју покреће корисник у Api-ју се бележи: ко, шта, када и odakle, у свим модулима, без посебног повезивања у сваком контролеру. Изнад тог дневника налази се слој серија: увоз или масовна радња може се означити као серија и касније поништити ред по ред, по узору на Planning Center. Оба се налазе у једној табели auditLogs у бази membership и покрећу се искључиво из једне тачке, 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"), чак и из контролера који нису у membership-у. Упит „све што је Јане променила данас" остаје један упит.

Шта се бележи​

Ревизија је подразумевано укључена за сваки глагол мењања на свакој рути. 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 } (чиме постаје способна за серије и поništавање), да би се означила као sensitive (бележе се анонимне измене) или да би се искључила помоћу optOut: true.

Листа искључења (путање са великим протоком уписа које би затрпале дневник): attendance visits / visitsessions / sessions / checkin (недељни наплав пријава) и messaging messages / connections / devices (ћаскање и присуство). Све остало се бележи.

Масовне крајње тачке (people/bulk-delete, people/bulk-update, groupmembers/bulk-add, groupmembers/bulk-remove) регистроване су у BULK_ROUTES и емитују један ред ревизије по дотакнутом ID-ју, тако да увоз од 10.000 особа производи 10.000 редова. Управо та гранулација чини серију могућом за поништавање.

Анонимне измене (actionWrapperAnon: анонимна давања, регистрација гостију, слања образаца) бележе се само за руте које су у регистру означене као sensitive, и уписују се са userId="anonymous" и IP адресом клијента. Донације су на челу листе, а та путања има стварну историју регресија.

Редакција тајни и ограничења величине​

Пре него што се било који details payload сачува, AuditLogHelper.capDetails() покреће sanitizeValue() над њим:

  • Тајна поља се редигују. Свако поље чије је име у малим словима у SENSITIVE_KEYS (password, token, cvv, cardnumber, routing_number, accesstoken, clientsecret, …) замењује се са "[redacted]".
  • Велики скалари се уклањају. Сваки data: URI или стринг дужи од 4 KB (base64 фотографије, блобови) постаје "[stripped]".
  • Превелики редови се ограничавају. Ако серијализовани JSON пређе око 64 KB, цео 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, а UI реконструише стари → нови у тренутку приказа, поређењем са претходним редом ревизије ентитета. Један упит у тренутку приказа, нула трошка у тренутку писања. Поља која никад нису мењана од покретања једноставно не приказују „стару" вредност, што је прихватљиво.
  • Брисања добијају слику пре. DELETE /:id на регистрованој рути са { dbModule, table } најпре генеричко учитава ред и чува га у details.before. Брисања су ретка, а слика пре је цела форензичка вредност.
  • Режим серије је једино систематско читање пре писања, и укључује се по избору. Операција масовног или увозног уноса је већ скупа, па су N читања снимака цена поништавања.
  • Уметања ревизије се чекају. actionWrapper прикупља обећања уписа и чека await Promise.allSettled(...) пре враћања одговора. Ово је најважнији инваријант: на Lambda-и се контејнер замрзава чим се одговор врати, па се нечекано уметање тихо изгуби. „Пали и заборави" овде значи да грешке никад не руше захтев, а не да не треба чекати. Једно уметање на већ загрејаном membership пулу траје око 1–3 ms.

Серије и поништавање​

Серија групише скуп измена да би се могле заједно прегледати и поништити. Постоје два начина да се отвори:

  • Експлицитно: POST /membership/batches { label, source } враћа batchId. Клијент (B1Transfer, UI за увоз у 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. Пре извршавања радње, слике пре за све захваћене ID-јеве учитавају се у једном упиту 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 (ажурирај или уметни, ако се ред са тим ID-јем поново појавио).
  4. Свако поништавање се и само бележи као ревизија (action: "<entityType>_undone", без batchId, јер је поништавање поништавања ван оквира).

Операција се бира према експлицитном маркеру креирања, а не закључује се из одсуства слике пре. Легитимно празна слика пре или скраћени ред не смеју да се погреше за креирање.

Резултат је { restored, skippedConflicts: [...], failed: [...], status }. Серија прелази у undone (чисто) или partial. Нема трансакције преко базе. Поништавање је по најбољем настојању по реду, исто ограничење које Planning Center документује за спојене профиле.

Ентитетима са споредним ефектима треба onUndo кука

Поништавање креирања groupMember мора уједно да упише groupMemberHistory („left"), или аналитика одлива тихо пукне. То је стални инваријант радног простора. Такви ентитети региструју callback onUndo у AUDIT_REGISTRY који враћа true кад је у потпуности обрадио поништавање, заобилазећи општи пут. groupMembers је канонски случај: кључан је по ID-ју реда на експлицитној путањи, а по personId на масовним крајњим тачкама, и прати историју при сваком додавању и уклањању.

Потрошачке површине​

Обе административне површине су у изради. Намера је следећа:

ПовршинаРепозиторијумСврха
Страница Журнала ревизијеB1Admin (ManageChurch → Audit Log)Филтрирање по модулу, категорији, кориснику и ентитету, и приказ разлика стари → нови. За измене се разлика рачуна поређењем са претходним уписом ентитета, а за брисања из details.before. Подржава га GET /membership/auditlogs, заштићено дозволом Permissions.server.admin.
Страница серијаB1Admin (исто подешавањško чвориште)Списак серија са статусом и бројевима, Прикажи резултате (редови ревизије серије преко GET /membership/batches/:id/results) и дугме Поништи, које приказује извештај о прескоченим конфликтима и неуспелим радњама.
Серије увозаB1TransferОтвори серију, шаљи X-Batch-Id уз нормалне позиве за чување и заврши на крају. Увози тако постају способни за поништавање, без нових крајњих тачака за увоз. Наслеђени importKey остаје као маркер порекла само за креирања и замењен је за поништавање.

Замке које будућа измена не сме да врати​

  • Уметања ревизије морају остати чекана. Нечекано 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
Административни UI (у изради)B1Admin странице Журнала ревизије и Серија; заглавље серије увоза у B1Transfer

Повезане странице​

  • Структура модула: како контролер изван membership-а стиже до membership репозиторијума преко RepoManager
  • Давања: путање уписа донација које се бележе као sensitive, чак и кад су анонимне
  • Крајње тачке членства: REST површина која носи X-Batch-Id и излаже /auditlogs и /batches