SS/AGENTS.md

AGENTS.md — SMM Panel Project

ملف تعليمات للوكيل البرمجي (AI Agent). اقرأه بالكامل قبل كتابة أي كود. الهدف: بناء موقع SMM Panel لبيع خدمات السوشال ميديا عبر API مزوّد خارجي، مع محفظة رصيد (Wallet) ونظام مستخدمين ولوحة أدمن.

⚠️ راجع أيضاً WALLET.md — فيه تفاصيل إلزامية عن نظام تسجيل الدخول وصحة المحفظة، وTASKS.md — فيه خطة تنفيذ مرحلية بالترتيب.

---

1. نظرة عامة على المشروع (Project Overview)

منصة ويب تبيع خدمات سوشال ميديا (متابعين، لايكات، مشاهدات … إلخ). المستخدم:

1. يسجّل حساب ويسجّل دخول.
2. يشحن محفظته (Wallet) برصيد.
3. يتصفّح الخدمات المتاحة.
4. ينشئ طلب (Order): يختار خدمة + يحط الرابط/الـ ID + الكمية.
5. النظام يخصم من رصيده ويرسل الطلب لمزوّد الخدمة عبر API، ثم يتابع حالته.

الموقع وسيط: يشتري من مزوّد بسعر منخفض ويبيع للمستخدم بسعر أعلى (هامش ربح يحدده الأدمن).

---

2. المصطلحات (Glossary)

• Provider / المزوّد: الجهة الخارجية اللي تملك الـ API الحقيقي وتنفّذ الخدمات.
• Service / الخدمة: عنصر قابل للبيع (مثال: "1000 متابع انستقرام")، له service_id وسعر وحد أدنى وأقصى.
• Wallet / المحفظة: رصيد المستخدم داخل الموقع.
• Order / الطلب: عملية شراء خدمة من قبل المستخدم.
• Transaction / المعاملة: أي حركة على الرصيد (شحن، خصم، استرجاع).
• Markup / الهامش: نسبة أو مبلغ يُضاف على سعر المزوّد ليصير سعر البيع.

---

3. التقنيات (Tech Stack)

⚠️ هذه افتراضات قابلة للتغيير — راجع "قرارات مفتوحة" في الأسفل.

• Backend: Node.js + Express
• Database: MySQL (أو MariaDB)
• Auth: JWT + bcrypt لتشفير كلمات المرور
• Frontend: (اختر واحد) React / EJS templates بسيطة للبداية
• HTTP client للتواصل مع المزوّد: axios
• Validation: zod أو express-validator
• Env config: dotenv

هيكل المجلدات المقترح:

/src
  /config        (اتصال قاعدة البيانات، متغيرات البيئة)
  /models        (استعلامات قاعدة البيانات)
  /services      (منطق العمل: wallet, orders, provider API)
  /controllers   (معالجة الطلبات)
  /routes        (المسارات)
  /middleware    (auth, admin-check, error handler)
  /utils
/public          (الواجهة)

---

4. مخطط قاعدة البيانات (Database Schema)

جدول users

العمود	النوع	ملاحظات
id	BIGINT PK AUTO_INCREMENT
username	VARCHAR(50) UNIQUE
email	VARCHAR(120) UNIQUE
password_hash	VARCHAR(255)	bcrypt
balance	DECIMAL(12,4) DEFAULT 0	رصيد المحفظة
role	ENUM('user','admin') DEFAULT 'user'
status	ENUM('active','banned') DEFAULT 'active'
created_at	TIMESTAMP

جدول services

العمود	النوع	ملاحظات
id	BIGINT PK
provider_service_id	VARCHAR(50)	الـ ID عند المزوّد
name	VARCHAR(255)
category	VARCHAR(100)
provider_price	DECIMAL(12,4)	سعر المزوّد لكل 1000
sell_price	DECIMAL(12,4)	سعر البيع لكل 1000 (بعد الهامش)
min	INT	أقل كمية
max	INT	أكبر كمية
is_active	BOOLEAN DEFAULT true
updated_at	TIMESTAMP

جدول orders

العمود	النوع	ملاحظات
id	BIGINT PK
user_id	BIGINT FK → users.id
service_id	BIGINT FK → services.id
link	VARCHAR(500)	الرابط/الـ ID المستهدف
quantity	INT
charge	DECIMAL(12,4)	المبلغ المخصوم من المستخدم
provider_order_id	VARCHAR(80)	رقم الطلب عند المزوّد
status	ENUM('pending','processing','in_progress','completed','partial','canceled','failed') DEFAULT 'pending'
created_at	TIMESTAMP

جدول transactions

العمود	النوع	ملاحظات
id	BIGINT PK
user_id	BIGINT FK
type	ENUM('deposit','order','refund')
amount	DECIMAL(12,4)	موجب = إضافة، سالب = خصم
balance_after	DECIMAL(12,4)	الرصيد بعد العملية (للتدقيق)
reference	VARCHAR(120)	مرجع (رقم الطلب / رقم الإيداع)
note	VARCHAR(255)
created_at	TIMESTAMP

جدول deposits (طلبات الشحن اليدوي)

العمود	النوع	ملاحظات
id	BIGINT PK
user_id	BIGINT FK
amount	DECIMAL(12,4)
method	VARCHAR(50)	usdt / manual …
tx_ref	VARCHAR(200)	إثبات التحويل (hash / رقم عملية)
status	ENUM('pending','approved','rejected') DEFAULT 'pending'
reviewed_by	BIGINT NULL	id الأدمن
created_at	TIMESTAMP

---

5. تكامل API المزوّد (Provider Integration)

معظم مزوّدي SMM يتبعون نفس المعيار (Perfect Panel standard). كل الطلبات عبارة عن POST إلى نقطة نهاية واحدة مع key و action.

متغيرات البيئة المطلوبة:

PROVIDER_API_URL=https://provider.example/api/v2
PROVIDER_API_KEY=xxxxxxxx

العمليات:

# جلب كل الخدمات
POST { key, action: "services" }

# إنشاء طلب
POST { key, action: "add", service, link, quantity }
→ يرجّع { order: <provider_order_id> }

# متابعة حالة طلب
POST { key, action: "status", order: <provider_order_id> }
→ يرجّع { charge, start_count, status, remains }

# رصيدك أنت عند المزوّد
POST { key, action: "balance" }

⚠️ تحقّق من توثيق المزوّد الفعلي: بعض الحقول قد تختلف بالتسمية. اجعل طبقة provider.service.js قابلة للتعديل من مكان واحد.

---

6. المنطق الحرج: المحفظة والطلبات (Critical Logic)

التفاصيل الكاملة (race conditions، idempotency، تسوية دورية) موجودة في WALLET.md. هذا ملخص سريع فقط.

قاعدة ذهبية: كل عملية على الرصيد داخل Transaction من قاعدة البيانات (atomic)

لا تسمح أبداً بخصم الرصيد وإرسال الطلب في خطوات منفصلة غير محمية.

تدفق إنشاء الطلب (order flow):

1. تحقّق أن المستخدم مسجّل دخول ونشِط.
2. تحقّق أن الخدمة موجودة و is_active.
3. تحقّق quantity ضمن [min, max].
4. احسب charge = (sell_price / 1000) * quantity.
5. ابدأ DB Transaction:
   a. اقفل صف المستخدم (SELECT ... FOR UPDATE).
   b. تحقّق balance >= charge، وإلا ارفض (رصيد غير كافٍ).
   c. اخصم: balance -= charge.
   d. أنشئ صف order بحالة pending.
   e. أنشئ صف transaction (type=order, amount=-charge).
   f. Commit.
6. أرسل الطلب لـ API المزوّد.
7. إذا نجح: خزّن provider_order_id وحدّث status=processing.
8. إذا فشل الإرسال: أعِد الرصيد (refund) وحدّث status=failed.

تدفق الشحن اليدوي:

1. المستخدم يقدّم طلب إيداع (amount + tx_ref) → deposits(status=pending).
2. الأدمن يراجع ويوافق.
3. عند الموافقة (داخل DB Transaction):
   - balance += amount
   - transaction (type=deposit)
   - deposit.status = approved

متابعة الحالات (cron/job): مهمة دورية تمرّ على الطلبات غير المكتملة وتستعلم عن حالتها من المزوّد وتحدّثها.

---

7. المسارات (API Routes)

عامة / مصادقة

POST /auth/register
POST /auth/login
POST /auth/logout
POST /auth/forgot-password

المستخدم (يتطلب تسجيل دخول)

GET  /me                 → بيانات الحساب + الرصيد
GET  /services           → قائمة الخدمات النشطة (بسعر البيع)
POST /orders             → إنشاء طلب
GET  /orders             → طلباتي
GET  /orders/:id         → تفاصيل طلب
GET  /transactions       → كشف حساب المحفظة
POST /deposits           → طلب شحن يدوي
GET  /deposits           → طلبات الشحن الخاصة بي

الأدمن (يتطلب role=admin)

GET   /admin/users
PATCH /admin/users/:id           → حظر/رفع حظر، تعديل رصيد يدوي
GET   /admin/deposits            → طلبات الشحن المعلّقة
PATCH /admin/deposits/:id        → موافقة/رفض
GET   /admin/orders              → كل الطلبات
POST  /admin/services/sync       → سحب الخدمات من المزوّد
PATCH /admin/services/:id        → تعديل السعر/الهامش/التفعيل
GET   /admin/stats               → إحصائيات (أرباح، مبيعات)

---

8. متطلبات الأمان (Security — إلزامي)

• تشفير كلمات المرور بـ bcrypt (لا تخزّنها نصّاً أبداً).
• مفتاح API المزوّد في متغيرات البيئة فقط، لا يُرسل للواجهة إطلاقاً.
• كل حسابات المال بـ DECIMAL وليس FLOAT.
• التحقق من صحة كل المدخلات (server-side validation).
• حماية من SQL Injection عبر prepared statements / ORM.
• Rate limiting على مسارات auth و orders.
• التحقق من الصلاحيات (middleware) على كل مسار أدمن.
• السعر يُحسب دائماً في الخادم — لا تثق بأي سعر قادم من الواجهة.

---

9. متغيرات البيئة (.env)

PORT=3000
DATABASE_URL=mysql://user:pass@localhost:3306/smm
JWT_SECRET=change_me_long_random
PROVIDER_API_URL=https://provider.example/api/v2
PROVIDER_API_KEY=your_provider_key
DEFAULT_MARKUP_PERCENT=25

---

10. ترتيب البناء (Build Order / Milestones)

1. الإعداد: مشروع Node + Express + اتصال MySQL + الهجرات (migrations).
2. المصادقة: register / login / JWT / middleware.
3. المحفظة: جداول transactions + عرض الرصيد + كشف حساب.
4. الشحن اليدوي: deposits + موافقة الأدمن.
5. الخدمات: سحب من المزوّد + عرضها بسعر البيع + إدارة الأدمن.
6. الطلبات: تدفق الطلب الكامل (atomic) + الإرسال للمزوّد.
7. متابعة الحالات: مهمة دورية لتحديث حالات الطلبات.
8. لوحة الأدمن: الإحصائيات والإدارة.
9. الواجهة: ربط كل شيء بواجهة نظيفة.

سلّم كل مرحلة قابلة للتشغيل والاختبار قبل الانتقال للتالية.

📋 للتنفيذ الفعلي خطوة بخطوة، اتّبع TASKS.md.

---

11. قرارات مفتوحة (Open Decisions — املأها)

هذه القرارات محسومة للنسخة الحالية، ومفصلة في DECISIONS.md:

• طريقة الشحن: شحن يدوي عبر قنوات قابلة للإدارة، مع PayPal وشام كاش وUSDT كبداية.
• اللغة/التقنية: Node.js + Express + MySQL/MariaDB.
• الواجهة: HTML/CSS/JavaScript ثابتة داخل public/ وتخدمها Express.
• العملة المعتمدة: USD بأربع خانات عشرية.
• الهامش: هامش افتراضي من DEFAULT_MARKUP_PERCENT مع تخزين markup_percent لكل خدمة ودعم تعديل الأدمن.
• رابط ومفتاح API المزوّد الفعلي: عبر PROVIDER_API_URL وPROVIDER_API_KEY في متغيرات البيئة فقط.
• دعم متعدد اللغات: الواجهة والرسائل عربية حالياً، وتعليقات الكود والداخليات بالإنجليزية.

---

12. ملاحظات للوكيل (Agent Notes)

• اطلب توثيق المزوّد الحقيقي قبل كتابة طبقة provider.service.js.
• لا تفترض تفاصيل الدفع؛ إن كانت غير محسومة اسأل المالك.
• اكتب اختبارات لمنطق المحفظة (أهم جزء حسّاس) — راجع WALLET.md قسم 4.
• علّق الكود بالإنجليزية، والرسائل للمستخدم بالعربية (أو حسب إعداد اللغة).