تخطي إلى المحتوى الرئيسي

سجل التدقيق والدفعات القابلة للتراجع

يُسجَّل كل تعديل يبدأه المستخدم في الواجهة Api، من حيث من قام به وما الذي تغيّر ومتى ومن أين، عبر جميع الوحدات، دون الحاجة إلى ربط أي وحدة تحكم (controller) بذلك يدوياً. وفوق هذا السجل توجد طبقة الدفعات: يمكن وسم عملية استيراد أو إجراء جماعي كدفعة، ثم التراجع عنها لاحقاً صفاً بصف، على غرار 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. طبقة وحدات التحكم هي المكان الوحيد الذي يعرف الفاعل. المستودعات (repositories) لا ترى AuthenticatedUser أبداً؛ وحدها وحدات التحكم تحمل au. تمر كل وحدات التحكم في كل وحدة أصلاً عبر BaseController.actionWrapper، ولذلك يُربط التدقيق هناك، دون تغيير أي توقيع في أي مستودع.
  2. جدول واحد يخدم جميع الوحدات. تُكتب سجلات التدقيق الخاصة بالتبرعات والحضور والمحتوى وغيرها جميعاً في جدول auditLogs في قاعدة بيانات العضوية عبر 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}، بحيث تُلتقط المسارات الفرعية غير القياسية (مثل 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 آلاف شخص ينتج 10 آلاف سجل. هذه الحبيبية لكل كيان هي بالضبط ما يجعل الدفعة قابلة للتراجع.

التعديلات المجهولة (actionWrapperAnon، مثل التبرع كزائر أو تسجيل الزوار أو إرسال النماذج) تُدقَّق فقط للمسارات المعلَّمة sensitive في السجل، وتُكتب بـ userId="anonymous" مع عنوان IP للعميل. تتصدر التبرعات هذه القائمة، ولهذا المسار تاريخ فعلي من الانحدارات (regressions).

تنقية الأسرار وحدود الحجم​

قبل تخزين أي حمولة details، يشغّل AuditLogHelper.capDetails() الدالة sanitizeValue() عليها:

  • تُنقَّى مفاتيح الأسرار. أي حقل يتطابق اسمه بعد تحويله إلى أحرف صغيرة مع أحد مفاتيح SENSITIVE_KEYS (مثل password وtoken وcvv وcardnumber وrouting_number وaccesstoken وclientsecret) يُستبدل بالقيمة "[redacted]".
  • تُحذف القيم النصية الضخمة. أي سلسلة تبدأ بـ data: أو يتجاوز طولها 4 كيلوبايت (صور base64 والكائنات الثنائية) تصبح "[stripped]".
  • تُقتطع الصفوف الكبيرة. إذا تجاوز حجم JSON المتسلسل نحو 64 كيلوبايت، يُستبدل الحمل بالكامل بـ { truncated: true }. الصفوف المقتطعة ما زالت قابلة للعرض، لكنها غير قابلة للتراجع لأنه لا توجد صورة قبل أو بعد يُستعاد منها.

أين تُخزَّن البيانات​

يدعم جدول واحد auditLogs في قاعدة بيانات العضوية جميع الوحدات. الأعمدة: id وchurchId وuserId وcategory وaction وentityType وentityId وdetails (نص JSON من نوع MEDIUMTEXT) و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") من داخل الغلاف (wrapper). والترتيب مقصود: تُثبَّت الكتابة الرئيسية في قاعدة بيانات الوحدة أولاً، ثم يُدرج سجل التدقيق ثانياً. في الوضع العادي يُبتلع فشل إدراج التدقيق (مع console.error، ويلتقطه Sentry)، فالتدقيق استشاري ولا يجب أن يُفشل طلب المستخدم أبداً. أما في وضع الدفعات فهو صارم (انظر أدناه).

لماذا ليس Triggers أو CDC أو جداول لكل وحدة؟
  • لا تعرف Triggers في MySQL المستخدم الفاعل (الاتصال لا يحمل au)، وتعني الحاجة إلى صيانة مجموعات Triggers عبر كل مخطط.
  • binlog / CDC مشروع بنية تحتية كاملة يواجه مشكلة هوية الفاعل نفسها.
  • تمرير userId عبر كل مستودع سيمس مئات الملفات لنقل معلومات تملكها طبقة وحدات التحكم أصلاً.
  • جداول تدقيق لكل وحدة تعني 7 أضعاف من الربط واستعلامات التفريع لأي سؤال عبر الوحدات. جدول واحد عند نقطة تحكم وحدات التحكم هو أقل تصميم كوداً يلتقط الفاعل.

استراتيجية الأداء​

المسار الساخن رخيص عمداً، ولا تُدفع التكلفة إلا حيث تشتري شيئاً.

  • لا قراءة قبل الكتابة في التحديثات العادية. الحفظ المعتاد لا يحمّل السجل القديم. تُخزَّن القيم بعد الإرسال في details.after، وتُعاد بناء الصيغة القديم←الجديد في وقت العرض بمقارنتها بسجل التدقيق السابق للكيان. استعلام واحد وقت العرض، وتكلفة صفرية وقت الكتابة. الحقول التي لم تُمسّ منذ الإطلاق لا تُظهر قيمة "قديمة"، وهذا مقبول.
  • الحذف يحصل على صورة قبل. DELETE /:id على مسار في السجل له { dbModule, table } يحمّل الصف بشكل عام أولاً ويخزّنه في details.before. الحذف نادر، والصورة قبل هي كامل القيمة الجنائية له.
  • وضع الدفعات هو القراءة قبل الكتابة المنهجية الوحيدة، وهو اختياري: عملية الاستيراد الجماعي مكلفة أصلاً، لذا فقراءات اللقطات N هي ثمن إمكانية التراجع.
  • إدراجات التدقيق تُنتظر (awaited). يجمع actionWrapper وعود الإدراج وينتظر await Promise.allSettled(...) قبل الإرجاع. هذا أهم ثابت في النظام: على Lambda تُجمَّد الحاوية لحظة إرجاع الاستجابة، فالإدراج غير المنتظر يُفقد بصمت. و"إطلاق وانسَ" هنا يعني أن الأخطاء لا تُفشل الطلب، لا أن لا تُنتظر. إدراج واحد في مجمع اتصالات العضوية الدافئ يستغرق نحو 1 إلى 3 ملّي ثانية.

الدفعات والتراجع​

الدفعة تجمع مجموعة من التعديلات بحيث تُراجَع معاً وتُعكس معاً. هناك طريقتان لفتح دفعة:

  • صريحة: POST /membership/batches { label, source } تُرجع batchId. ثم يرسل العميل (B1Transfer، أو واجهة استيراد في B1Admin) الرأس X-Batch-Id: <id> مع كل عملية حفظ أو حذف لاحقة. وPOST /membership/batches/:id/complete يغلقها ويختم itemCount.
  • ضمنية: نقاط النهاية الجماعية الأربع تفتح دفعتها وتملؤها وتكملها بنفسها داخل الطلب الواحد، وتُرجع batchId في الاستجابة.

جدول batches (في قاعدة بيانات العضوية): 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، فالتراجع عن التراجع خارج النطاق).

تُختار العملية من علامة الإنشاء الصريحة، وليس من غياب صورة قبل، فصورة قبل فارغة بشكل مشروع أو صف مقتطع يجب ألا يُحسَبا عملية إنشاء بالخطأ.

حمولة النتيجة هي { restored, skippedConflicts: [...], failed: [...], status }، وتنتقل الدفعة إلى undone (نظيفة) أو partial. لا توجد معاملة عابرة لقواعد البيانات: التراجع بذل جهد لكل صف، وهو القيد نفسه الذي توثّقه Planning Center للملفات الشخصية المدمجة.

الكيانات ذات الآثار الجانبية تحتاج إلى خطاف onUndo

عكس إنشاء groupMember يجب أن يكتب أيضاً groupMemberHistory ("left")، وإلا تنكسر تحليلات الفاقد (churn) بصمت، وهذا ثابت دائم في مساحة العمل. تسجّل هذه الكيانات دالة استدعاء onUndo في AUDIT_REGISTRY تُرجع true عندما تكون قد عالجت العكس بالكامل، فتتجاوز المسار العام. وgroupMembers هي الحالة الأساسية: يُفهرس بمعرّف الصف في المسار الصريح، لكنه يُفهرس بـ personId في نقاط النهاية الجماعية، ويُتتبع تاريخه عند كل إضافة وإزالة.

واجهات الاستخدام​

كلتا واجهتي الإدارة قيد التطوير؛ والمقصود منهما:

الواجهةالمستودعالغرض
صفحة سجل التدقيقB1Admin (ManageChurch ← Audit Log)التصفية حسب الوحدة أو الفئة أو المستخدم أو الكيان، وعرض فروق القديم←الجديد: للتعديلات بمقارنتها بالسجل السابق للكيان، وللحذف من details.before. تعتمد على GET /membership/auditlogs، وتُقيَّد بـ Permissions.server.admin.
صفحة الدفعاتB1Admin (في مركز الإعدادات نفسه)عرض الدفعات مع حالاتها وأعدادها، وعرض النتائج (سجلات تدقيق الدفعة عبر 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 يوماً. إذا انخفض الاحتفاظ نحو النافذة، فستُحذف سجلات التراجع من تحت الدفعات المفتوحة.
  • الصفوف المقتطعة غير قابلة للتراجع. الحمولة { 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 لسجل التدقيق والدفعات؛ ترويسة دفعة الاستيراد في B1Transfer

صفحات ذات صلة​

  • هيكل الوحدات: كيف تصل وحدة تحكم ليست تابعة للعضوية إلى مستودعات العضوية عبر RepoManager
  • التبرعات: مسارات كتابة التبرعات التي تُدقَّق كـ sensitive حتى عندما تكون مجهولة
  • نقاط نهاية العضوية: واجهة REST التي تحمل X-Batch-Id وتكشف /auditlogs و/batches