# 02 — مواصفات الداشبورد (الأوردرات · الفواتير · المدفوعات · القالب)

> المرجع البصري: القسم 4 في `../index.html` (الأربع تابات) — الإطار هناك بتوكنز الموقع، **ينفّذ على ثيم الداشبورد الحالي (Amber Apothecary)** بنفس التركيبة.  
> كل إعداد مذكور له تعريف كامل في `invoice-template-config.json` (النوع، الافتراضي، الحدود، الصلاحية). **الهدف: ولا قيمة ثابتة في الكود.**
> الصلاحيات الحالية: `OrderManager` < `Admin` < `SuperAdmin`.

## 1. الشاشات

### 1.1 الأوردرات والفواتير (قايمة)
- أعمدة: ☐ · رقم الأوردر · العميلة (+تليفون مقنّع) · القناة (ويب/موبايل/سيلز) · طريقة الدفع · **حالة الدفع** · حالة الأوردر · الإجمالي · **الفاتورة**.
- فلاتر (chips + عدّاد): الكل · مدفوع · كاش عند الاستلام · مستني الدفع · **محتاج مراجعة** · فشل/ملغي · استرداد. + بحث (رقم أوردر/موبايل/كود دفع/رقم فاتورة) + مدى تاريخ.
- عمود الفاتورة: 👁 عرض · ⬇ تحميل · ↩ إشعار الدائن (لو فيه). الأوردرات اللي مفيهاش فاتورة: `—` ، و«محتاج مراجعة» بتظهر `متأجلة`.
- **تحديد متعدد** ⇒ شريط أسود: «تحميل الفواتير (ZIP)» و«إرسال بالواتساب». الأوردرات من غير فاتورة بتتجاهل تلقائي (والشريط يقول كده). حد أقصى 200 مستند، والـ ZIP job في الخلفية بإشعار عند الجاهزية.
- ألوان الحالة (ثابتة، من التوكنز): أخضر=مدفوع · برتقالي=مستني/COD · أحمر=فشل · ليلك=استرداد/مراجعة · رمادي=ملغي.

### 1.2 تفاصيل الأوردر
أربع حالات لازم تتغطي (موجودة كلها في البروتوتايب):

| الحالة | اللي بيظهر | الأزرار |
|---|---|---|
| **مدفوع بعد محاولة فاشلة** | Timeline المحاولات: محاولة 1 فشلت (كارت •••• + كود البنك) → محاولة 2 نجحت (Ref + 3DS) → اتصدرت الفاتورة → اتبعتت واتساب ✓✓/إيميل | تحميل · عرض · إرسال واتساب · إرسال إيميل · إعادة إصدار* · إشعار دائن* |
| **كاش عند الاستلام** | اختارت COD → اتأكد بالتليفون (باسم الموظفة) → فاتورة مستحقة → بانتظار التحصيل | تحميل · عرض · إرسال · **«تم التحصيل → فاتورة مدفوعة»** |
| **اتخصم ومحتاج مراجعة** | Banner بنفسجي «محتاج قرار» + timeline (timeout GW-504 → غير معروفة → مراجعة تلقائية بعد 30 د) + الفاتورة **متأجلة** | **راجع مع البوابة** · علّم كمدفوع · ابدأ استرداد |
| **فيه مرتجع** | الفاتورة + إشعار الدائن (225 ج.م) + سطر الاسترداد في الرحلة | تحميل الفاتورة · تحميل الإشعار · إرسال |

\* «إعادة إصدار» و«إشعار دائن» و«علّم كمدفوع» و«ابدأ استرداد»: **تفتح modal تأكيد فيه سبب إجباري** (نص حر + قايمة أسباب)، وبتتسجل في الـ audit. صلاحية `Admin` فما فوق؛ `OrderManager` يشوف ويحمّل ويبعت بس.
- كارت الفاتورة بيعرض: الرقم، النوع/الحالة، اللغات المتاحة (AR+EN)، **آخر تحميل (مين/من فين/إمتى)**.
- «ملخص»: العميلة · حالة الدفع · حالة الأوردر · الإجمالي.

### 1.3 المدفوعات الفاشلة والمعلّقة (Inbox)
- KPIs (آخر 24 ساعة): محاولات فاشلة · نسبة نجاح الدفع · **مبالغ ممكن تضيع** (مجموع سلات فشلت وما اتحوّلتش لأوردر) · **محتاج مراجعة يدوية** (card برتقالي).
- الجدول: الوقت · الأوردر/السلة · العميلة · القناة · الدفع · **السبب** (chip) · الكود · المبلغ · إجراء.
- الأسباب (نفس مفاتيح `payment-result-states.json`): رفض البنك · رصيد · 3DS · العميلة لغت · انتهى وقت المحفظة/الجلسة · مشكلة تقنية · انتهى حجز InstaPay · منتج خلص · **محتاج مراجعة**.
- الإجراء: زرار **واتساب** (يفتح محادثة برسالة جاهزة قابلة للتعديل ورابط الشنطة) — وللمراجعة: زرار **راجع** يفتح تفاصيل الأوردر.
- Banner: «رسالة تذكير بتتبعت تلقائي بعد ساعة» (قابلة للإيقاف من الإعدادات).
- حالة فاضية + حالة خطأ تحميل.

### 1.4 قالب الفاتورة والإرسال (الإعدادات)
- **يتبني تلقائي من `invoice-template-config.json`** (حقل لكل setting بنفس النوع والحدود)، مجمّعة: بيانات الشركة · الهوية · الترقيم · الضريبة · المحتوى · اللغة · QR · الإرسال · الدفع · الدعم.
- **معاينة مباشرة** على اليسار (أو أسفل في الموبايل): A4 مصغّر بيتحدّث مع كل حرف (debounce 250ms) من `POST /ops/settings/invoice/preview`. اختيار sample: عادي · شحن مدفوع · طلب كبير (صفحتين) · COD · مبدئية · إشعار دائن · عربي/English.
- كل حقل فيه: الافتراضي (زرار «رجوع للافتراضي»)، العدّاد (max)، رسالة الخطأ، وملصق `هيتطبق على الفواتير الجديدة بس` لإعدادات الـ `snapshot`.
- **الرقم الضريبي**: required، pattern، `SuperAdmin` بس، والصدور يتوقف (بتنبيه واضح) لو فاضي.
- **الحفظ**: ينشئ `settings_versions` جديد؛ زر «السجل» بيعرض النسخ (مين/إمتى/إيه اتغيّر) مع «استرجاع نسخة».
- **تحذيرات حيّة**: تغيير الـ prefix أو الـ padding أو `verify_base_url` أو `signing_secret` ⇒ modal تحذير (الأكواد/الأرقام القديمة بتفضل شغالة؟ يعني لازم الباك يحفظ القيم القديمة).
- المفاتيح السرية (`signing_secret`) **لا تظهر** — زرار «تدوير المفتاح» بس.

### 1.5 صفحة الفاتورة داخل الأوردر (مستندات)
قايمة كل مستندات الأوردر بالحالة (issued/voided/superseded) وزرار تحميل لكل لغة. المستندات الملغاة تظهر بخط مشطوب وسبب الإلغاء.

## 2. النصوص الديناميك (app-texts)
- النصوص الافتراضية للـ 15 حالة في `payment-result-states.json` تتسجّل في محرر النصوص الحالي (`/app-texts`) تحت مجموعة «نتيجة الدفع» بمفاتيح:
  `payment.result.<state>.title` · `.body` · `.reasons.<i>` · `.cta.<key>` · وأيضًا `invoice.card.*` و`account.documents.*` و`messages.*` (رسايل واتساب/إيميل).
- المحرر لازم **يعرض الـ placeholders المسموحة** `{order_number} {amount} {eta} {last4} {payment_ref} {phone_masked}` ويرفض اللي مش معروف.
- معاينة النص داخل شاشة النتيجة (نفس مكوّن الموقع) عند التعديل.
- تغيير النص بيظهر في الموقع والتطبيق من غير نشر (cache قصير + `ETag`).

## 3. أحداث وسجل (Audit)
- كل عملية: عرض/تحميل/إرسال/إعادة إصدار/إلغاء/إشعار دائن/حل مراجعة/تعديل إعدادات ⇒ صف في `document_audit` (مين، إمتى، IP، سبب).
- تبويب «السجل» في تفاصيل الأوردر، وصفحة سجل عامة بفلاتر (المستخدم، العملية، التاريخ).
- «آخر تحميل للعميلة» يتحسب من نفس السجل.

## 4. الأخطاء والحالات الحدّية في الواجهة
- فشل إرسال واتساب ⇒ chip أحمر على المستند «فشل الإرسال» + زرار «أعيدي الإرسال»، ومعاه سبب المزوّد.
- فشل توليد PDF ⇒ «بنجهّز الفاتورة…» + retry تلقائي + زرار يدوي (الباك بيرجع `409 document_not_ready`).
- ZIP كبير ⇒ progress + إشعار + رابط صالح 10 دقايق.
- تعارض تعديل (optimistic concurrency زي صفحة الأوردرات الحالية) على أي إجراء.
- عدم وجود الرقم الضريبي ⇒ banner دائم أعلى الصفحة.
- أوردرات مرتجعة جزئيًا: عدّاد «مُسترد 225 / 801» وزرار إشعار دائن إضافي يتعطّل لما المتبقي = 0.
- RTL كامل، الأرقام اللاتينية للأرقام والأكواد (`direction:ltr` على الأرقام)، تباين ألوان WCAG AA، لوحة مفاتيح (checkbox/زراير/ESC للـ modal).
- الموبايل: الجداول تتحوّل لكروت تحت 900px.

## 5. اختبارات الواجهة (الحد الأدنى)
1. فلتر كل chip يطلع العدّاد الصح والصفوف المطابقة.
2. تحديد 3 أوردرات (واحد منها من غير فاتورة) ⇒ ZIP فيه 2 + تنبيه.
3. «إشعار دائن» من غير سبب ⇒ مرفوض.
4. تغيير الـ prefix ⇒ المعاينة تتحدّث والتحذير يظهر؛ الحفظ بـ `OrderManager` ⇒ مرفوض.
5. مسح الرقم الضريبي ⇒ الحفظ مرفوض.
6. حالة «محتاج مراجعة»: كل من الأزرار التلاتة تغيّر الحالة وتصدر/تمنع الفاتورة صح.
7. تعديل نص `payment.result.declined.body` ⇒ يظهر في الموقع خلال دقيقة.