Comestare — مواصفات متطلبات البرمجيات (SRS)

مبنية على البنية المعمارية المنشورة فعليًا. الجمهور: المهندسون والمستثمرون التقنيون/الاستراتيجيون الذين يجرون فحصًا تقنيًا نافيًا للجهالة. المرجع المصاحب: PRD.

1. المقدمة

1.1 الغرض

تحديد المتطلبات الوظيفية وغير الوظيفية والبنية المعمارية لمنصة Comestare.

1.2 النطاق

منصة ويب ثنائية اللغة تضم تطبيقًا موجهًا للعملاء، ومنصة إدارة، وبوابة API، ومخازن بيانات داعمة، تقدم توليد استراتيجيات التسويق المعتمدة على الذكاء الاصطناعي بالإضافة إلى تحقيق الدخل بأسلوبي الخدمة الذاتية والخدمة المُنجَزة بالنيابة عن العميل.

1.3 التعريفات

الكون / الاستراتيجية — استراتيجية التسويق المُولَّدة (خريطة + خارطة طريق).
البوابة / الطبقة الوسطية — حافة API التي تتصدر الواجهات الخلفية.
سجل المسارات — إعداد مملوك للإدارة يُرشد البوابة إلى كيفية التوجيه/الوكالة.

2. البنية المعمارية للنظام (كما هي مبنية)

                    ┌──────────────────────────┐
   Customers ──────▶│  Frontend (Next.js 15)    │  comestare.com  (Cloudflare)
                    │  EN/AR, RTL, PLG funnel    │
                    └─────────────┬──────────────┘
                                  │ HTTPS (JSON)
                    ┌─────────────▼──────────────┐
                    │  Middleware / API Gateway   │  (NestJS + Fastify)
                    │  auth, JWT, rate-limit,     │  + Redis (sessions,
                    │  caching, proxy, route reg, │    rate-limit, registry)
                    │  Google ID-token verify     │
                    └───────┬───────────┬─────────┘
                            │           │ internal (X-Internal-Token)
              ┌─────────────▼──┐   ┌────▼───────────────┐
              │ Customer-backend│   │  Admin-backend      │
              │ NestJS+Fastify  │   │  NestJS+Fastify     │
              │ users/sessions/ │   │  routes/pricing/    │
              │ OTP/auth        │   │  finance/audit/admins│
              │ Prisma          │   │  Prisma (schema=admin)│
              └────────┬────────┘   └─────────┬───────────┘
                       │                      │
                       └──────────┬───────────┘
                          ┌───────▼────────┐      ┌──────────────┐
                          │  PostgreSQL     │      │  Admin Panel  │
                          │ (public + admin │◀─────│  Next.js      │
                          │  schemas)       │ direct│ (cookie auth)│
                          └─────────────────┘      └──────────────┘

المكونات:

الواجهة الأمامية (Frontend) — Next.js 15 (App Router)، Tailwind، React Query، Zustand، نظام i18n مخصص (EN/AR + RTL)، Google Identity Services؛ منشورة على Cloudflare.
الطبقة الوسطية (البوابة) — NestJS/Fastify؛ رموز JWT للوصول/التحديث، تحديد المعدل، تخزين مؤقت في الذاكرة من المستوى L1 + Redis، وكالة مدفوعة بسجل المسارات، التحقق من Google ID-token (JWKS)، CORS، Helmet.
الواجهة الخلفية للعملاء (Customer-backend) — NestJS/Fastify + Prisma/Postgres؛ المستخدمون، الجلسات، OTP، المصادقة بكلمة المرور + Google، سجلات رموز التحديث؛ تُتيح نقاط نهاية داخلية للبوابة (X-Internal-Token).
الواجهة الخلفية للإدارة (Admin-backend) — NestJS/Fastify + Prisma/Postgres (مخطط admin)؛ المسؤولون (owner/admin/viewer)، سجل المسارات (/internal/routes)، التسعير (نقطة نهاية تسعير عامة)، المالية/المحافظ، التدقيق؛ رمز JWT للإدارة (HS256) عبر ملف تعريف ارتباط HttpOnly.
لوحة الإدارة (Admin panel) — Next.js؛ تتواصل مباشرةً مع الواجهة الخلفية للإدارة بجلسة ملف تعريف ارتباط.
البيانات — PostgreSQL (نسخة مشتركة، مخططات منفصلة)؛ Redis (الجلسات، التدوير، تحديد المعدل، ذاكرة سجل المسارات المؤقتة).

3. المتطلبات الوظيفية (للنظام)

3.1 المصادقة والجلسات

SRS-AUTH-1 التسجيل بالبريد الإلكتروني مع التحقق عبر OTP؛ تسجيل الدخول بكلمة المرور (argon2).
SRS-AUTH-2 تسجيل الدخول عبر Google: تحصل الواجهة الأمامية على رمز هوية (ID token) من Google؛ تتحقق البوابة من التوقيع + aud (= GOOGLE_CLIENT_ID) + iss مقابل Google JWKS؛ تُمرَّر المطالبات الموثوقة إلى الواجهة الخلفية للعملاء.
SRS-AUTH-3 إصدار رموز JWT للوصول (TTL قصير) + للتحديث (متدوّرة، مع كشف السرقة المعتمد على العائلة)؛ يُخزَّن رمز التحديث بصيغة مجزّأة في الواجهة الخلفية + يُتتبَّع في Redis.
SRS-AUTH-4 ملف تعريف ارتباط التحديث بخصائص HttpOnly/Secure/SameSite؛ يُلغي تسجيل الخروج العائلة + يُدرج JTI الوصول في قائمة الحظر.
SRS-AUTH-5 مصادقة الإدارة منفصلة (ملف تعريف ارتباط HS256، أدوار).

3.2 البوابة

SRS-GW-1 توجيه الطلبات وفق سجل المسارات المملوك للإدارة (مع احتياطي مُضمَّن).
SRS-GW-2 تحديد المعدل لكل عنوان IP بنوافذ قابلة للتهيئة؛ إتاحة ترويسات الحد.
SRS-GW-3 التخزين المؤقت للاستجابات القابلة للتخزين من المصدر (L1 + Redis) مع قيم TTL.
SRS-GW-4 توحيد اللغة المحلية (بادئة URL مثل /en، /ar ← Accept-Language) قبل إعادة التوجيه.
SRS-GW-5 فرض قائمة السماح لـ CORS؛ ترويسات الأمان (Helmet).

3.3 توليد الاستراتيجية

SRS-GEN-1 قبول الفكرة/الرابط؛ استدعاء مزود الذكاء الاصطناعي؛ إعادة كون منظّم + خارطة طريق.
SRS-GEN-2 فرض حدود الاستخدام المعتمدة على الخطة والعلامة المائية.
SRS-GEN-3 حفظ الاستراتيجيات المُولَّدة في حساب المستخدم.
SRS-GEN-4 تعريب التوليد إلى EN/AR.

3.4 الفوترة وتحقيق الدخل

SRS-BILL-1 إدارة الاشتراكات (Free/Starter/Pro/Agency) عبر Stripe (+ خارطة طريق لقنوات الدفع المحلية في GCC).
SRS-BILL-2 التحكم في الميزات حسب المستوى.
SRS-BILL-3 فوترة الخدمات على أساس المراحل؛ Ad Studio بفوترة متكررة + نسبة مئوية من الإنفاق.

3.5 الإدارة

SRS-ADM-1 إدارة المستخدمين/الجلسات/التدقيق، والتسعير، والمسارات، والمالية.
SRS-ADM-2 نقطة نهاية تسعير عامة يستهلكها الموقع التسويقي.
SRS-ADM-3 دفع عمليات إبطال سجل المسارات إلى البوابة.

3.6 العملاء المحتملون والتحليلات

SRS-LEAD-1 التقاط وتخزين سجلات العملاء المحتملين + UTM/الإسناد + الأحداث السلوكية.
SRS-LEAD-2 حساب درجة العميل المحتمل ومرحلة دورة الحياة؛ توجيه العملاء المحتملين المهتمين بشدة.

4. المتطلبات غير الوظيفية

4.1 الأداء

NFR-PERF-1 زمن استجابة API عند المئين 95 (لغير التوليد) < 300 مللي ثانية من جهة الخادم.
NFR-PERF-2 توليد الاستراتيجية بأسلوب البث/التدريجي؛ هدف الإكمال المُدرَك < 30 ثانية؛ إظهار التقدم.
NFR-PERF-3 التخزين المؤقت للقراءات المتكررة (التسعير، سجل المسارات) لحماية الواجهات الخلفية.

4.2 الموثوقية والتوافر

NFR-REL-1 استهداف توافر بنسبة 99.9% لمسارات المصادقة + التوليد.
NFR-REL-2 تدهور رشيق: تستخدم البوابة المسارات الاحتياطية إذا تعذّر الوصول إلى الواجهة الخلفية للإدارة.
NFR-REL-3 عدم ظهور أخطاء 5xx في مسار المصادقة/تسجيل الدخول في ظروف التشغيل العادية (انظر الملحق A).
NFR-REL-4 نقاط نهاية للصحة/الجاهزية (/healthz، /readyz) مع فحوصات قاعدة البيانات.

4.3 الأمان والخصوصية

NFR-SEC-1 جميع الحركة عبر TLS؛ الأسرار في متغيرات البيئة/مخزن الأسرار، وليست أبدًا في نظام التحكم بالإصدارات.
NFR-SEC-2 كلمات المرور بخوارزمية argon2؛ رموز JWT موقّعة؛ تدوير رموز التحديث مع كشف إعادة الاستخدام.
NFR-SEC-3 استدعاءات الخدمات الداخلية مُصادَق عليها عبر X-Internal-Token (≥32 بايت).
NFR-SEC-4 تحديد المعدل + Helmet + قائمة سماح صارمة لـ CORS.
NFR-SEC-5 الامتثال لـ PDPL (السعودية) + GDPR: التقاط الموافقة الصريحة، وحقوق صاحب البيانات، وسياسة الاحتفاظ بالبيانات، وخيار إقامة البيانات لمنطقة GCC (انظر ملخص السعودية/GCC).
NFR-SEC-6 تدقيق الوصول إلى المعلومات الشخصية القابلة للتعريف (يوجد سجل تدقيق للإدارة).

4.4 قابلية التوسع والتكلفة

NFR-SCALE-1 البوابة والواجهات الخلفية عديمة الحالة وقابلة للتوسع أفقيًا؛ الحالة في Postgres/Redis.
NFR-SCALE-2 التحكم في تكلفة استدلال الذكاء الاصطناعي عبر حدود المستوى المجاني، والتخزين المؤقت، وتدرّج النماذج.

4.5 التدويل وإمكانية الوصول

NFR-I18N-1 تكافؤ كامل بين EN/AR بما يشمل RTL، والطباعة العربية، والتنسيق المراعي للغة المحلية.
NFR-A11Y-1 استهداف معايير WCAG-AA لمسار التحويل الأساسي.

4.6 قابلية الصيانة وإمكانية المراقبة

NFR-OBS-1 تسجيل مُهيكل (pino) بمعرّفات الطلبات؛ تتبّع OpenTelemetry اختياري.
NFR-OBS-2 تحليلات مسار التحويل لكل قناة؛ مراقبة الأخطاء.

5. النشر والبيئات

الواجهة الأمامية: Cloudflare (Next.js / OpenNext).
الواجهات الخلفية والبوابة: محوّلة إلى حاويات؛ مُنسَّقة عبر Coolify (Nixpacks)؛ متغيرات البيئة تُحقَن لكل خدمة.
البيانات: PostgreSQL + Redis مُدارة.
التواصل بين الخدمات عبر شبكة خاصة باستخدام اسم الخدمة؛ الأسرار لكل بيئة.

6. القيود والافتراضات

يؤثر توافر مزود الذكاء الاصطناعي وتسعيره على التكلفة/زمن الاستجابة.
قد تتطلب إقامة البيانات في GCC نشرًا إقليميًا.
تقيّد المصادقة عبر النطاقات (نطاقات الواجهة الأمامية مقابل البوابة) استراتيجية ملفات تعريف الارتباط.

الملحق A — مشكلات الإنتاج المعروفة (قائمة أعمال الموثوقية)

اعرض هذه المشكلات بشكل استباقي في الفحص التقني النافي للجهالة؛ فهي تصلّب طبيعي لمرحلة ما قبل الإطلاق، والإصلاحات مفهومة:

الشبكات بين الطبقة الوسطية ↔ الواجهة الخلفية للعملاء — يجب أن تتمكن البوابة من تحليل خدمة الواجهة الخلفية للعملاء بشكل موثوق (لوحظ EAI_AGAIN)؛ الإصلاح = شبكة خاصة مشتركة + host:port صحيح. وإلى حين الإصلاح، تُعيد جميع عمليات المصادقة المعتمدة على الواجهة الخلفية أخطاء 5xx.
إعداد/جلسة تسجيل الدخول عبر Google — يجب ضبط GOOGLE_CLIENT_ID على البوابة (يجب أن يساوي معرّف عميل الواجهة الأمامية)؛ تحقق من نفاذ JWKS الصادر.
ملف تعريف ارتباط التحديث عبر النطاقات — الواجهة الأمامية والبوابة على نطاقات جذرية مختلفة؛ أنجز استراتيجية ملف تعريف الارتباط/الجلسة (أو وحّد النطاقات) كي تستمر الجلسات.
سلوك FedCM/ملفات تعريف الارتباط من جهات خارجية على جانب العميل — يعتمد منتقي Google على حالة FedCM/ملفات تعريف الارتباط في المتصفح؛ وثّق التكوينات المدعومة.

هذه المشكلات متتبَّعة ومفهومة جيدًا، ومُقيَّدة قبل توسيع الاكتساب المدفوع (NFR-REL-3). ولا تتطلب أيٌّ منها إعادة هيكلة معمارية.