# نتيجة الدفع + الفواتير (PDF) — الصورة الكاملة

> للـ: فريق الباك إند · فريق الداشبورد · مصمم/مطوّر الموقع والتطبيق  
> المرجع البصري: افتحوا `../index.html` (كل حاجة شغالة) — والـ PDF الحقيقية في `../samples/`

## الفكرة في سطرين
العميلة بتشتري من الموقع أو التطبيق، فتشوف **شاشة نتيجة** (نجاح / مستني / فشل / مراجعة)، وتقدر **تحمّل فاتورة PDF** من الموقع والتطبيق، والإدارة تقدر تعمل نفس الحاجة من الداشبورد. **كل نص ورقم وخيار في الفاتورة والشاشات والرسايل لازم يتعدّل من الداشبورد من غير كود** (ده معنى "داينمك").

## إيه اللي في الحزمة

| الملف | بيخدم مين | فيه إيه |
|---|---|---|
| `00-OVERVIEW.md` (ده) | الكل | الصورة الكاملة + القرارات المفتوحة |
| `01-BACKEND-SPEC.md` | الباك إند | حالات الدفع، نموذج البيانات، الترقيم، الحسابات، الـ API، الـ PDF، الـ QR، الإرسال، الحالات الحدّية |
| `02-DASHBOARD-SPEC.md` | الداشبورد | الشاشات، الصلاحيات، إعدادات القالب، النصوص، المدفوعات الفاشلة، الـ audit |
| `invoice-data-contract.json` | الاتنين | JSON Schema لـ **DocumentSnapshot** (اللي الـ PDF بيتولّد منه) + مثال كامل |
| `invoice-template-config.json` | الاتنين | **46 إعداد** قابل للتعديل من الداشبورد (النوع، الافتراضي، الحدود، الصلاحية، snapshot/live) |
| `payment-result-states.json` | الاتنين | الـ **15 حالة** دفع بنصوصها الافتراضية وسلوك الفاتورة والأزرار |
| `fixtures.json` | الاتنين | 5 أوردرات تجريبية بالإجماليات المتوقعة (للـ unit tests) |
| `../samples/*.pdf` | الاتنين | 15 PDF مرجعية (مدفوعة، COD، مبدئية، إشعار دائن، طلب كبير صفحتين، عربي/إنجليزي) |
| `../assets/qr.js` | الباك إند | مولّد QR بدون dependencies، اتجرّب بقارئ فعلي، ينفع يتنقل لأي لغة |

## المستندات الأربعة (وإمتى بيتصدر كل واحد)

| المستند | الرقم | إمتى | QR | ملاحظة |
|---|---|---|---|---|
| **فاتورة مدفوعة** | `INV-yy-nnnnnn` | أول ما الدفع يتأكد من البوابة | ✅ | بتتبعت تلقائي واتساب/إيميل |
| **فاتورة كاش عند الاستلام** | نفس `INV` | وقت تأكيد الأوردر (قابل للتغيير: بعد التسليم) | ✅ | مكتوب «مستحقة عند الاستلام»، وبتبقى «مدفوعة» بعد التحصيل **بنفس الرقم** |
| **فاتورة مبدئية** | `PF-yy-nnnnnn` | InstaPay لحد ما التحويل يتأكد | ❌ | علامة مائية «غير نهائية»، وبتتلغي لو الحجز خلص |
| **إشعار دائن** | `CN-yy-nnnnnn` | عند تسجيل مرتجع/استرداد (كلي أو جزئي) | ✅ | مرتبط بالفاتورة الأصلية، بيتصدر منه أكتر من واحد لو في أكتر من مرتجع |

## القرارات اللي اتاخدت في التصميم (غيّروها لو العميل رفض)
1. **الفاتورة snapshot ثابتة**: كل بيانات الشركة والنصوص والأسعار بتتنسخ جوّه المستند وقت الإصدار. تعديل الإعدادات أو الأسعار بعد كده **ما بيغيّرش فواتير قديمة**.
2. **الدفع مش بيتفتح بـ "نجاح" من الكلاينت**: الحالة بتيجي من `payments/{n}/verify` (زي ما هو موجود دلوقتي). الكلاينت بيعرض بس.
3. **حالة "بنراجع الدفع"** موجودة عمدًا: لو البوابة عملت timeout والعملية ممكن تكون اتخصمت، العميلة **ماتدفعش تاني**، والنظام يراجع تلقائي ويبلّغها.
4. **QR فيه رابط تحقق موقّع** (HMAC) بيعرض الحالة الحالية بدون بيانات شخصية.
5. **الأرقام شاملة الضريبة 14%** والضريبة بتظهر كسطر «منها».
6. صفحة الفاتورة القديمة `/ar/invoice/<n>` (موجودة في الموقع الحالي) **بتتحوّل** لنفس الـ PDF الجديد.

## قرارات محتاجة العميل (مش هنقدر نخلّص من غيرها)
1. **البيانات القانونية**: الرقم الضريبي، اسم الشركة الرسمي، السجل التجاري — وهل المطلوب **تكامل الفاتورة الإلكترونية مع مصلحة الضرائب (ETA)**؟ لو أيوه فالـ QR الرسمي وشكل الـ UUID بيتغيّروا (المحاسب يحسم).
2. فاتورة COD: وقت التأكيد ولا بعد التسليم؟
3. اللغة: عربي بس، ولا عربي + إنجليزي؟ والعميلة تختار؟
4. واتساب فقط ولا + إيميل؟ وتذكير بعد فشل الدفع؟
5. فاتورة باسم شركة: نسمح؟ لحد كام يوم؟
6. الإشعار الدائن: تلقائي مع المرتجع ولا بموافقة الإدارة؟
7. الترقيم: تسلسل واحد للويب والموبايل؟ بداية السنة؟
8. **صيغة رقم الأوردر** اللي بتظهر: التصميم بيستخدم `TNG-24117`، والـ API الحالي بيستخدم رقم 6 خانات + `orderToken` للضيوف. نقرر صيغة العرض ونحافظ على إن الرقم لوحده **مش** مفتاح دخول.
9. **الدومين** الحقيقي لصفحة التحقق (`lotusorganics.store/v` placeholder).

## ترتيب التنفيذ المقترح
1. (باك إند) جداول المستندات + الترقيم + الحسابات + fixtures tests.
2. (باك إند) endpoint نتيجة الدفع `result` + mapping أكواد MPGS للحالات.
3. (باك إند) توليد الـ PDF + التخزين + endpoints التحميل.
4. (داشبورد) صفحة إعدادات القالب (تغذّي الخطوة 3).
5. (باك إند) الـ QR + صفحة التحقق + الإرسال واتساب/إيميل.
6. (داشبورد) قايمة الأوردرات/تفاصيل/المدفوعات الفاشلة.
7. (موقع/تطبيق) شاشات النتيجة وتحميل الفاتورة.

## تشغيل البروتوتايب
افتحوا `index.html` في المتصفح (مفيش build). `tools/make_pdfs.py` بيعيد توليد الـ PDF، و`tools/export_handoff.js` بيعيد توليد ملفات JSON من نفس مصدر الأرقام. *كل الأسماء والأرقام والرقم الضريبي بيانات تجريبية.*