Журнал ревизије и серије са могућношћу поништавања
Свака мутација коју покреће корисник у 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
Две структурне чињенице покрећу све што следи:
- Слој контролера је једино место које зна актера. Репозиторијуми никад не виде
AuthenticatedUser; само контролери поседујуau. Сви контролери сваког модула већ пролазе крозBaseController.actionWrapper, па се ревизија укључује управо ту, без промена потписа репозиторијума. - Једна табела служи свим модулима. Редови ревизије за давања, присуство, садржај и остало се уписују у табелу
auditLogsу бази membership прекоRepoManager.getRepos("membership"), чак и из контролера који нису у membership-у. Упит „све што је Јане променила данас" остаје један упит.
Шта се бележи
Ревизија је подразумевано укључена за сваки глагол мењања на свакој рути. 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 } (чиме постаје способна за серије и по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 је ухвати). Ревизија је саветодавна и никад не сме да сруши корисников захтев. У режиму серије је строга (види испод).
- 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):
- Серија мора постојати, бити
openи припадатиau.churchId. Иначе је одговор 403. - Рута мора бити способна за серије (
{ dbModule, table }у регистру). Иначе је одговор 400. - Пре извршавања радње, слике пре за све захваћене ID-јеве учитавају се у једном упиту
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(ажурирај или уметни, ако се ред са тим ID-јем поново појавио).
- Свако поништавање се и само бележи као ревизија (
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