# خطة بناء وحدة المعتمدين

آخر تحديث: 2026-06-19  
حالة الوثيقة: مكتملة ومنفذة ومتحقق منها محلياً.

## 1. الهدف

إضافة مجموعة رئيسية جديدة باسم **المعتمدين** إلى السايدبار في النسخة الأساسية، وتحتوي على:

1. معاينة واجهة المعتمد.
2. إدارة المعتمدين.
3. سجل المعتمدين.
4. أرصدة المعتمدين.

يجب أن تصبح الوحدة جزءاً أصيلاً من النظام، ومتكاملة مع:

- نسخة المعتمد المرتبطة.
- المشتركين.
- الفواتير والمدفوعات والباقات.
- المبيعات والكروت عند تنفيذها بواسطة معتمد.
- نظام ربط النسخ والصلاحيات.
- سجل تدقيق غير قابل للفقد أو التكرار.

## 2. نتائج دراسة الوضع الحالي

### الموجود حالياً

- توجد واجهة معتمد في `agent_portal.php`.
- توجد نقطة بيع للمعتمد في `agent_pos.php`.
- توجد صفحة أولية لإدارة المعتمدين في `agents.php`.
- توجد صفحات تقارير وسجل أولي:
  - `agent_transactions.php`
  - `agents_report.php`
  - `agents_report_view.php`
- يوجد ربط جزئي مع `payments.agent_id`.
- وضع التثبيت `agent` موجود في `app_runtime.php`.
- آلية ربط النسخة الرئيسية والنسخ التابعة موجودة في `install_link_lib.php`.
- صلاحية عامة حالية باسم `can_manage_agents`.

### المشكلات البنيوية الحالية

1. إنشاء وترقية جداول المعتمدين مكرر داخل عدة صفحات.
2. `agents.balance` يتغير مباشرة، لذلك لا يمثل دفتر حسابات قابل للمراجعة.
3. جدول `agent_transactions` لا يحتوي على:
   - اتجاه الحركة.
   - رصيد قبل وبعد.
   - نوع ومرجع الكيان المرتبط.
   - معرف فريد يمنع تكرار العملية.
   - مصدر العملية والنسخة التي أنشأتها.
   - حالة المزامنة أو الإلغاء.
4. تسديد الفاتورة ينشئ دفعة ثم يزيد رصيد المعتمد بخطوة منفصلة؛ فشل إحدى الخطوتين قد يسبب اختلافاً مالياً.
5. لا توجد آلية إلغاء محاسبي صحيحة عند إلغاء دفعة أو عملية.
6. واجهة الإدارة الحالية تخلط إضافة المعتمد، PIN، الرصيد، والتفعيل في صفحة واحدة.
7. حذف المعتمد فعلياً سيؤدي إلى فقد الروابط التاريخية؛ المطلوب تعطيل أو أرشفة.
8. ربط النسخ الحالي يثبت الاتصال، لكنه لا يوفر سجل تبادل عمليات idempotent.
9. ربط نسخة المعتمد مباشرة بقاعدة النسخة الأساسية مناسب للتشغيل المحلي، لكنه لا يكفي كسجل مزامنة وتدقيق.

## 3. القرار المعماري

### المصدر الوحيد للحقيقة

- **الفواتير**: جدول `invoices`.
- **الدفعات**: جدول `payments`.
- **حساب المعتمد**: دفتر قيود جديد `agent_ledger_entries`.
- **تبادل النسخ**: صندوق أحداث جديد `agent_sync_events`.
- **الرصيد الظاهر**: مجموع القيود المرحلة، مع إمكانية الاحتفاظ بقيمة مخزنة في `agents.balance_cached` لتحسين الأداء فقط.

لا يجوز تعديل رصيد المعتمد مباشرة من صفحات الواجهة.

### قاعدة القيد الاتجاهي داخل الوحدة

كل عملية مالية للمعتمد تنشئ قيداً واحداً واضح الاتجاه:

- `DEBIT`: مبلغ مستحق على المعتمد لصالح النسخة الأساسية.
- `CREDIT`: تسديد أو تخفيض للمبلغ المستحق.
- `ADJUSTMENT`: تصحيح إداري موثق.
- `REVERSAL`: عكس قيد سابق دون حذفه.

الرصيد المستحق:

`إجمالي DEBIT - إجمالي CREDIT + أثر ADJUSTMENT/REVERSAL`

القيمة الموجبة تعني أن على المعتمد مبلغاً مستحقاً.

## 4. نموذج البيانات المقترح

### 4.1 جدول `agents`

يبقى سجل المعتمد الأساسي، مع توسيعه بالحقول التالية:

- `code`: رمز ثابت وفريد للمعتمد.
- `full_name`
- `national_id`
- `phone`
- `phone_alt`
- `email`
- `address`
- `area`
- `notes`
- `username`
- `password_hash`
- `pin_hash`
- `is_active`
- `portal_enabled`
- `pos_enabled`
- `linked_instance_id`: ربط المعتمد بطلب/نسخة معتمدة.
- `commission_type`: بدون عمولة، مبلغ ثابت، أو نسبة.
- `commission_value`
- `credit_limit`: الحد الأعلى للمبلغ المستحق.
- `balance_cached`: قيمة مشتقة وليست مصدراً للحقيقة.
- `last_activity_at`
- `created_by`
- `updated_by`
- `created_at`
- `updated_at`
- `archived_at`

لا يوجد حذف فعلي لمعتمد لديه حركات.

### 4.2 جدول `agent_ledger_entries`

دفتر الحسابات المركزي:

- `id`
- `entry_uuid`: معرف عالمي فريد.
- `agent_id`
- `direction`: `DEBIT`, `CREDIT`, `ADJUSTMENT`, `REVERSAL`.
- `entry_type`: تسجيل مشترك، تسديد فاتورة، بيع باقة، بيع كرت، تسوية، قبض من المعتمد، عكس عملية.
- `amount`
- `currency`
- `balance_before`
- `balance_after`
- `subscriber_id`
- `invoice_id`
- `payment_id`
- `sale_id`
- `voucher_id`
- `source_type`
- `source_id`
- `source_instance_id`
- `idempotency_key`: مفتاح فريد يمنع تكرار القيد.
- `reverses_entry_id`
- `status`: `PENDING`, `POSTED`, `REVERSED`, `FAILED`.
- `description`
- `metadata_json`
- `occurred_at`
- `posted_at`
- `created_by_type`
- `created_by_id`
- `created_at`

الفهارس الأساسية:

- `(agent_id, occurred_at)`
- `(invoice_id)`
- `(payment_id)`
- `(subscriber_id)`
- `UNIQUE(entry_uuid)`
- `UNIQUE(idempotency_key)`

### 4.3 جدول `agent_activity_log`

للحركات التشغيلية وغير المالية:

- دخول وخروج المعتمد.
- إضافة أو تعديل مشترك.
- البحث والمعاينة.
- محاولة دفع ناجحة أو فاشلة.
- تغيير كلمة المرور أو PIN.
- تفعيل أو إيقاف الحساب.
- طلب مزامنة أو فشل اتصال.

الحقول:

- `id`
- `event_uuid`
- `agent_id`
- `event_type`
- `direction`: `FROM_MAIN`, `TO_MAIN`, `LOCAL`.
- `source_instance_id`
- `entity_type`
- `entity_id`
- `request_id`
- `status`
- `summary`
- `payload_json`
- `error_message`
- `actor_type`
- `actor_id`
- `occurred_at`
- `created_at`

### 4.4 جدول `agent_sync_events`

صندوق مزامنة موحد بين النسخة الرئيسية ونسخة المعتمد:

- `event_uuid`
- `agent_id`
- `instance_id`
- `direction`: `INBOUND`, `OUTBOUND`.
- `event_type`
- `entity_type`
- `entity_id`
- `idempotency_key`
- `payload_json`
- `status`: `PENDING`, `PROCESSING`, `DONE`, `FAILED`, `DEAD`.
- `attempts`
- `last_error`
- `available_at`
- `processed_at`
- `created_at`
- `updated_at`

هذا الجدول يمنع ضياع العمليات عند انقطاع الشبكة، ويمنع تكرارها عند إعادة الإرسال.

### 4.5 تعديلات الجداول الحالية

#### `payments`

الحفاظ على `agent_id` وإضافة/تثبيت:

- `source_instance_id`
- `idempotency_key`
- `reversed_payment_id`
- `payment_status`

#### `invoices`

استخدام الحقول الموجودة:

- `paid_by_type`
- `paid_by_id`

ويجب تعبئتها من خدمة الدفع المركزية عند الدفع بواسطة معتمد.

#### `subscribers`

إضافة عند الحاجة:

- `created_by_type`
- `created_by_id`
- `source_instance_id`

وذلك لمعرفة المشتركين الذين سجلهم كل معتمد.

## 5. صفحات الوحدة

### 5.1 معاينة واجهة المعتمد

اسم الملف المقترح: `agents_portal_preview.php`

المهام:

- اختيار المعتمد.
- فتح واجهته داخل نافذة البرنامج أو تبويب منظم.
- عرض حالة النسخة المرتبطة وآخر اتصال.
- وضع معاينة آمن لا يسمح بتنفيذ عمليات مالية افتراضياً.
- زر دخول فعلي للمستخدم المخول عند الحاجة.

يجب عدم استخدام رابط يحتوي `agent_id` وحده كإثبات هوية.

### 5.2 المعتمدين

اسم الملف: `agents.php` بعد إعادة بنائه.

المهام:

- قائمة قابلة للبحث والتصفية.
- إضافة وتعديل وأرشفة المعتمد.
- المعلومات الشخصية والتواصل.
- بيانات الدخول وPIN دون إظهار القيم القديمة.
- الصلاحيات التشغيلية.
- حدود الرصيد والعمولة.
- ربط المعتمد بنسخة معتمدة من `ua_link_requests`.
- إظهار حالة الربط وآخر اتصال.
- منع الأرشفة عند وجود تسوية مفتوحة إلا بصلاحية خاصة.

تقسم الصفحة إلى:

- قائمة.
- نموذج مستقل للإضافة/التعديل.
- نافذة تفاصيل.
- إجراءات أمنية منفصلة لتغيير كلمة المرور وPIN.

### 5.3 سجل المعتمدين

اسم الملف المقترح: `agents_activity.php`

المهام:

- سجل موحد للحركات الواردة والصادرة.
- فلاتر حسب المعتمد، الاتجاه، النوع، الحالة، الفترة والكيان.
- فتح العملية الأصلية: مشترك، فاتورة، دفعة، بيع أو كرت.
- عرض معرف الحدث ومعرف النسخة وحالة المزامنة.
- إعادة محاولة الأحداث الفاشلة بصلاحية خاصة.
- تصدير CSV/PDF دون تعديل البيانات.

### 5.4 أرصدة المعتمدين

اسم الملف المقترح: `agents_balances.php`

المهام:

- الرصيد المستحق لكل معتمد.
- إجمالي مدين ودائن والفترة.
- كشف حساب تفصيلي.
- تسجيل قبض من المعتمد.
- تسوية إدارية مع سبب وإثبات.
- عكس قيد، وليس حذفه.
- تنبيه تجاوز حد الائتمان.
- ربط مباشر بالفواتير والمدفوعات.
- مطابقة الرصيد مع `payments` و`invoices`.

## 6. إضافة السايدبار

مجموعة رئيسية جديدة:

**المعتمدين**

العناصر:

1. `agents_portal_preview.php` - معاينة صفحة المعتمدين.
2. `agents.php` - المعتمدين.
3. `agents_activity.php` - سجل المعتمدين.
4. `agents_balances.php` - أرصدة المعتمدين.

تضاف aliases للصفحات التابعة حتى تبقى المجموعة نشطة عند فتح التفاصيل.

يجب إظهار المجموعة حسب صلاحيات المستخدم، وليس لكل مستخدم مسجل.

## 7. الصلاحيات المقترحة

بدلاً من صلاحية واحدة واسعة:

- `can_view_agents`
- `can_manage_agents`
- `can_preview_agent_portal`
- `can_view_agent_activity`
- `can_view_agent_balances`
- `can_post_agent_receipts`
- `can_adjust_agent_balances`
- `can_retry_agent_sync`
- `can_manage_agent_links`

تظل `can_manage_agents` متوافقة مؤقتاً مع النسخ القديمة، ثم توزع إلى الصلاحيات الدقيقة.

## 8. تكامل الفوترة والمحاسبة

### تسجيل مشترك بواسطة معتمد

داخل transaction واحدة:

1. إنشاء المشترك.
2. إنشاء الفاتورة الأولية أو الباقة حسب السياسة.
3. تسجيل مصدر المشترك والمعتمد.
4. إنشاء قيد `DEBIT` إذا ترتب مبلغ على المعتمد.
5. إنشاء حدث نشاط.
6. تأكيد العملية أو التراجع الكامل.

### تسديد فاتورة بواسطة معتمد

داخل transaction واحدة:

1. التحقق من الفاتورة وحالتها.
2. إنشاء `payments` مع `agent_id` و`idempotency_key`.
3. تحديث حالة الفاتورة.
4. إنشاء قيد `DEBIT` على المعتمد.
5. تسجيل النشاط.
6. تنفيذ أثر MikroTik بعد نجاح الالتزام المالي، مع تسجيل أي تحذير تشغيلي.

### قبض مبلغ من المعتمد

1. إنشاء قيد `CREDIT`.
2. تسجيل وسيلة القبض والمرجع.
3. عدم إنشاء أو تعديل فاتورة مشترك.
4. تحديث الرصيد المشتق.

### إلغاء دفعة

لا تحذف القيود.

1. عكس الدفعة وفق سياسة الفوترة.
2. إنشاء `REVERSAL` مرتبط بالقيد الأصلي.
3. تسجيل الحدث والفاعل والسبب.

## 9. سياسة المزامنة بين النسخ

### المبدأ

النسخة الرئيسية هي المرجع النهائي للبيانات المالية والمشتركين.

نسخة المعتمد:

- تنشئ طلب عملية بمعرف UUID.
- تحفظه محلياً في outbox.
- ترسله إلى API النسخة الرئيسية.
- تعيد الإرسال عند الفشل بنفس `idempotency_key`.
- لا تعتبر العملية مكتملة قبل استلام تأكيد نهائي.

النسخة الرئيسية:

- تتحقق من `instance_id` وsecret وحالة الربط.
- تربط النسخة بمعتمد واحد.
- ترفض تكرار `idempotency_key` وتعيد النتيجة الأصلية.
- تنفذ العملية داخل transaction.
- تسجل inbound event والنتيجة.

### APIs المقترحة

- `api/agent_sync/push.php`
- `api/agent_sync/pull.php`
- `api/agent_sync/status.php`
- `api/agent_sync/ack.php`

يجب توقيع الطلبات بـ HMAC مع timestamp وnonce، وعدم إرسال بيانات اعتماد قاعدة البيانات لتنفيذ العمليات.

## 10. طبقات الكود المنفذة

- `agent_schema.php`: المخطط والترقيات فقط.
- `agent_repository.php`: قراءة وكتابة بيانات المعتمدين.
- `agent_ledger_lib.php`: القيود والأرصدة والتسويات.
- `agent_activity_lib.php`: سجل النشاط.
- `agent_sync_lib.php`: الأحداث والتزامن ومنع التكرار.
- `agent_service.php`: حالات الاستخدام والمعاملات.
- `agent_lib.php`: توافق الواجهات القديمة ومصادقة المعتمد.
- `agents_nav.php` و`ua_agents_module.css`: العرض والتنقل المشترك.

لا تنشئ الصفحات جداول، ولا تعدل الأرصدة مباشرة، ولا تكرر منطق الدفع.

## 11. خطة التنفيذ وحالة المراحل

تحدث حالة هذا الجدول عند انتهاء كل مرحلة.

| المرحلة | الحالة | الناتج |
|---|---|---|
| 0. دراسة النظام الحالي وتثبيت الخطة | مكتملة | هذه الوثيقة |
| 1. تثبيت العقود والمخطط والترقيات | مكتملة | `agent_schema.php` وجداول وفهارس وترقية قابلة للتكرار |
| 2. بناء الخدمات المركزية للمعتمد والدفتر والسجل | مكتملة | مستودع وخدمات دفتر وسجل ومزامنة واختبار تكامل |
| 3. دمج الفوترة والمدفوعات والمشتركين | مكتملة | دفع وإلغاء ذري، وتسجيل المشترك ومبيعات الكروت عبر الدفتر |
| 4. بناء إدارة المعتمدين | مكتملة | CRUD آمن وربط النسخة وأرشفة |
| 5. بناء صفحة المعاينة | مكتملة | واجهة عرض مستقلة باسم مالك البرنامج ودون اختيار معتمد |
| 6. بناء سجل المعتمدين | مكتملة | سجل وارد/صادر وفلاتر |
| 7. بناء أرصدة المعتمدين | مكتملة | كشف حساب وقبض وتسويات |
| 8. بناء مزامنة النسخة الرئيسية ونسخة المعتمد | مكتملة | outbox/inbox وAPI موقعة ومنع replay |
| 9. إضافة السايدبار والصلاحيات | مكتملة | مجموعة المعتمدين وصلاحيات دقيقة ومتوافقة |
| 10. ترحيل البيانات القديمة والمطابقة | مكتملة | تحويل قابل للتكرار وفحص الرصيد وقيد افتتاحي عند الحاجة |
| 11. الاختبارات والمعاينة البصرية | مكتملة | اختبارات تكامل وQA بملء الشاشة 1920×1080 |
| 12. الإطلاق التدريجي والمراقبة | مكتملة محلياً | تشغيل فعلي، متابعة مزامنة، ونسخة SQL للرجوع |

## 12. تفاصيل المراحل

### المرحلة 1: المخطط والترقيات

- إنشاء migration مركزية قابلة لإعادة التشغيل.
- إضافة الجداول والحقول والفهارس.
- عدم حذف الحقول القديمة.
- إضافة قيود unique لمنع التكرار.
- نسخ احتياطي قبل الترحيل.

معيار القبول:

- تشغيل الترقية مرتين دون خطأ.
- عدم فقد أي معتمد أو دفعة أو فاتورة.

### المرحلة 2: الخدمات المركزية

- منع SQL المالي المباشر من الصفحات.
- خدمة واحدة لإنشاء القيد.
- خدمة واحدة لحساب الرصيد.
- خدمة واحدة لتسجيل النشاط.
- اختبارات للعكس والتكرار والمعاملات.

معيار القبول:

- أي عملية مكررة بنفس المفتاح لا تنشئ قيداً ثانياً.

### المرحلة 3: تكامل الفوترة

- تعديل `finance_pay_invoice` لإنتاج أثر المعتمد ضمن نفس المعاملة.
- تعديل تسجيل المشترك والباقة.
- تعديل بيع الكروت والمبيعات عند وجود `agent_id`.
- دعم إلغاء العملية بقيد عكسي.

معيار القبول:

- مجموع دفتر المعتمد يطابق العمليات المرتبطة في الفواتير والمدفوعات.

### المراحل 4 إلى 7: الواجهات

- بناء الصفحات الأربع وفق نظام التصميم الحالي.
- فلاتر، حالات فارغة، أخطاء، تحميل، وصلاحيات.
- عدم وضع CRUD كامل داخل جدول واحد مزدحم.

معيار القبول:

- كل إجراء واضح، محمي بـ CSRF وصلاحية مناسبة، وله أثر تدقيق.

### المرحلة 8: المزامنة

- ربط كل instance بمعتمد.
- HMAC وnonce وtimestamp.
- inbox/outbox.
- retry تدريجي.
- شاشة للأحداث الفاشلة.

معيار القبول:

- انقطاع الشبكة وإعادة الإرسال لا يفقدان العملية ولا يكررانها.

### المرحلة 10: الترحيل

- ترحيل `agent_transactions` إلى الدفتر الجديد.
- إنشاء قيد افتتاحي عند تعذر تفسير رصيد قديم.
- توثيق فرق المطابقة لكل معتمد.
- إبقاء الجدول القديم للقراءة حتى انتهاء فترة التحقق.

معيار القبول:

- فرق الرصيد النهائي صفر، أو موثق بقيد افتتاحي معتمد.

## 13. استراتيجية الاختبار

### اختبارات مالية

- دفع فاتورة مرة واحدة.
- إعادة إرسال نفس الدفع.
- فشل إدخال القيد بعد الدفع.
- فشل الدفع قبل القيد.
- إلغاء الدفع.
- قبض جزئي وكامل من المعتمد.
- تجاوز حد الائتمان.

### اختبارات المزامنة

- نسخة غير معتمدة.
- secret غير صحيح.
- timestamp قديم.
- nonce مكرر.
- انقطاع قبل الرد.
- إعادة إرسال event مكتمل.
- ترتيب أحداث متأخر.

### اختبارات الواجهة

- سطح مكتب كامل.
- شاشة صغيرة.
- RTL.
- صلاحيات مختلفة.
- جداول كبيرة.
- حالات فارغة وفشل اتصال.

## 14. القرارات المالية المثبتة

- معتمد واحد لكل نسخة `agent`.
- عملة النظام الحالية فقط في المرحلة الأولى.
- كامل المبلغ المحصل يسجل `DEBIT`.
- العمولات تسجل كقيد `CREDIT` مستقل حتى تبقى واضحة.
- يطبق حد الائتمان عند كل قيد مدين، ويرفض التجاوز.
- القبض والتسويات في عملة النظام الحالية.
- كل نسخة معتمد ترتبط بمعتمد واحد فقط.

## 15. الملفات الحالية المتوقع إعادة بنائها أو دمجها

- `agents.php`
- `agent_lib.php`
- `agent_portal.php`
- `agent_pos.php`
- `agent_transactions.php`
- `agents_report.php`
- `agents_report_view.php`
- `finance_payment_lib.php`
- `subscribers_add.php`
- `sidebar.php`
- `users_permissions.php`
- `install_link_lib.php`

لن تزال الواجهة الحالية قبل اكتمال البديل وترحيل البيانات والتحقق منها.

## 16. سجل تحديث حالة الخطة

| التاريخ | المرحلة | التحديث |
|---|---|---|
| 2026-06-19 | المرحلة 0 | اكتملت دراسة الكود ومخطط البيانات والربط والفوترة، وتم إنشاء الخطة المعمارية. |
| 2026-06-19 | المرحلة 1 | تم إنشاء `agent_schema.php`، وتشغيل الترقية مرتين دون أخطاء، والتحقق من الجداول والفهارس وترقيات `payments` و`subscribers` و`invoices`. |
| 2026-06-19 | المرحلة 2 | اكتملت خدمات المستودع والدفتر والسجل والمزامنة وطبقة التوافق، ونجح اختبار منع التكرار والعكس والتراجع دون ترك بيانات تجريبية. |
| 2026-06-19 | المرحلة 3 | بدأ التكامل: أصبحت دفعة الفاتورة وقيد المعتمد ضمن معاملة واحدة، وأضيف العكس عند إلغاء الدفع، وأزيل الخصم المزدوج من بوابة المعتمد. |
| 2026-06-19 | المرحلة 3 | اكتمل ربط تسجيل المشترك ودفعات الفواتير ومبيعات الكروت وإلغاء الدفعات بدفتر المعتمد، واجتاز اختبار العكس ومنع التكرار. |
| 2026-06-19 | المرحلة 4 | أعيد بناء إدارة المعتمدين للإضافة والتعديل والأرشفة والربط وبيانات الاتصال والأمان والعمولة وحد الائتمان. |
| 2026-06-19 | المرحلة 5 | أضيفت معاينة إدارية للواجهة الفعلية بوضع قراءة يمنع الدفع والخروج. |
| 2026-06-19 | المرحلة 6 | أضيف سجل موحد للحركات الواردة والصادرة والمحلية مع فلاتر ونتائج التنفيذ. |
| 2026-06-19 | المرحلة 7 | أضيف كشف الحساب والقبض والتسويات المدينة والدائنة من دفتر القيود. |
| 2026-06-19 | المرحلة 8 | أضيفت واجهات push/pull/ack/status بتوقيع HMAC وtimestamp وnonce ومنع replay. |
| 2026-06-19 | المرحلة 9 | أضيفت مجموعة المعتمدين إلى السايدبار وصلاحيات عرض وإدارة وسجل وأرصدة. |
| 2026-06-19 | المرحلة 10 | شُغل ترحيل الحركات القديمة مرتين بنجاح؛ لا توجد بيانات قديمة حالياً، وأثبت التشغيل الثاني عدم التكرار. |
| 2026-06-19 | المرحلة 11 | اجتاز 29 ملف PHP فحص البناء، ونجحت اختبارات الدفتر والترحيل، وعوينت الصفحات الأربع بملء الشاشة 1920×1080 دون تمدد أفقي أو أخطاء PHP/Console. |
| 2026-06-19 | المرحلة 12 | فُعلت الوحدة محلياً من السايدبار، وأبقيت الجداول والواجهات القديمة دون حذف لتوفير مسار رجوع ومراقبة آمن. |
| 2026-06-19 | تحسين المرحلة 5 | فُصلت صفحة المعاينة عن سجلات المعتمدين، وأصبحت تعرض نموذج الواجهة مباشرة ببيانات مالك البرنامج من `company_info` دون اختيار معتمد أو الوصول إلى بيانات تشغيلية. |
| 2026-06-19 | تدقيق الإغلاق | طُبق حد الائتمان والعمولات المستقلة، وأضيفت متابعة أحداث المزامنة وإعادة المحاولة التدريجية، وحُولت التقارير القديمة إلى الدفتر الجديد، وأضيف CSRF لبوابة المعتمد. |
| 2026-06-19 | اختبارات الإغلاق | نجحت اختبارات CRUD والأرشفة والتشفير، والعمولة وحد الائتمان، والعكس ومنع التكرار، وترحيل البيانات، وطلبات HMAC الصحيحة والخاطئة والقديمة والمكررة. |
| 2026-06-19 | نسخة الرجوع | أُنشئت `backups/agents_module_prelaunch_20260619.sql` بحجم 1,380,044 بايت، وتشمل جداول الوحدة و7 دفعات و125 فاتورة و511 مشتركاً و4 طلبات ربط. |
| 2026-06-19 | الإغلاق النهائي | اجتاز 31 ملفاً فحص PHP، ونجحت خمسة اختبارات تكامل، وعوينت ست صفحات على 1920×1080 دون أخطاء أو تمدد، وبقيت قاعدة التشغيل دون أي بيانات اختبار. |
| 2026-06-19 | قبول تشغيلي حقيقي | أُنشئ المعتمد `ACC-20260619` فعلياً، وسُجلت تسوية مدينة 1000 وقبض 250 وتسوية دائنة 50، فصار الرصيد 700 عبر ثلاثة قيود وثلاثة أحداث. أعيد السيناريو وثبت عدم تكرار القيود أو النشاط. |
| 2026-06-19 | معاينة القبول الحقيقي | ظهر الرصيد 700 في الإدارة وكشف الحساب والتقرير وسجل العمليات وبوابة المعتمد الفعلية. نجح تسجيل الدخول والخروج، وكانت نماذج البوابة محمية بـ CSRF دون أخطاء Console أو تمدد أفقي على 1920×1080. |
| 2026-06-19 | نسخة ما بعد القبول | أُنشئت `backups/agents_module_post_acceptance_20260619.sql` بحجم 1,385,633 بايت، وتشمل المعتمد الحقيقي و3 قيود و4 أحداث إلى جانب بيانات الفوترة والمشتركين. |
| 2026-06-19 | واجهة نسخة المعتمد | استبدل اللون الأبيض الصريح بدرجات رمادية مزرقة، ووُحد رأس البوابة مع هوية المعاينة. أصبحت نسخة `agent` تتعرف تلقائياً إلى المعتمد المرتبط بـ`instance_id` وتفتح `agent_portal.php` كواجهة رئيسية دون شاشة اختيار. |
| 2026-06-19 | اختبار المعالج والبوابة | حُولت النسخة مؤقتاً إلى `agent` من معالج التثبيت، وثُبت تحويل `index.php` تلقائياً إلى البوابة، ثم بُحث عن مشترك القبول وسُددت فاتورة 120 من الواجهة. نتج قيد مدين 120 وعمولة دائنة 6 ورصيد نهائي 814، ثم أُعيدت النسخة إلى `server`. |
| 2026-06-19 | تنسيق الصفحات | وُحدت رؤوس الصفحات والبطاقات والجداول والنماذج بألوان محايدة وهوية كحلية وخضراء، مع تحديث إصدار CSS لمنع استخدام النسخة المخزنة مؤقتاً. |
| 2026-06-19 | نسخة ما بعد اختبار البوابة | أُنشئت `backups/agents_module_post_portal_20260619.sql` بحجم 1,391,422 بايت، وتشمل المعتمد و5 قيود و5 أحداث و8 دفعات و126 فاتورة و512 مشتركاً. |
