تشغيل واجهة أمامية على بياناتها التجريبية المدمجة

كيف يعمل الموقع ولوحة التحكم كلٌّ على حدة من دون API إطلاقًا، وما الذي يعمل هناك، وما معنى إشعار «بيانات تجريبية»، وما يحدث عندما تتوقف API متصلة عن الرد، وكيف تنتقل إلى API الخاصة بك أو تزيل البيانات التجريبية.

لحزمة الحزمة الكاملة

ما هو

يحمل الموقع ولوحة التحكم كلٌّ منهما إجابات API الأولية لـ Northstack، مصدَّرة منها، فيعمل كلٌّ منهما بمفرده من دون واجهة خلفية: كل شاشة في لوحة التحكم، ونموذج الاتصال في الموقع وخروج الترخيص، تعمل كما تعمل مع API. وهذا ما تعمل عليه حزمة الواجهة الأمامية الواحدة مباشرة، ويقول ذلك إشعار «بيانات تجريبية» في أسفل كل صفحة، فلا يظنها أحد واجهة خلفية متصلة.

تشغيلها وإيقافها

لا توجد راية. إعداد واحد يقرر، هو NEXT_PUBLIC_API_BASE_URL، ويُدمج عند بناء التطبيق:

.env

# empty or missing: the built-in sample data, no API needed
NEXT_PUBLIC_API_BASE_URL=

# set: your API, with the /api suffix
NEXT_PUBLIC_API_BASE_URL=http://localhost:8000/api

من دون Docker، يعمل yarn install وyarn dev في مجلد التطبيق بلا ملف .env على البيانات التجريبية. أما ملف .env المنسوخ من .env.example فيشير إلى API على http://localhost:8000/api.
مع Docker، ابنِ الصورة بالخيار --build-arg NEXT_PUBLIC_API_BASE_URL= لتعمل على البيانات التجريبية. ومن دون هذا الوسيط تُبنى الصورة لتعمل مع API على http://localhost:8000/api.
أمر docker compose up --build في الحزمة الكاملة يبني دائمًا الواجهتين الأماميتين بعنوان API.
بعد تغيير القيمة، أعد تشغيل yarn dev، أو شغّل yarn build مرة أخرى، أو ابنِ الصورة مرة أخرى.

لوحة التحكم على البيانات التجريبية

المجال	على البيانات التجريبية
تسجيل الدخول	تُدخلك أي كلمة مرور. كل من `owner@` و`admin@` و`member@` و`billing@` و`platform@` و`support@northstack.example` يفتح ذلك الحساب الأولي ودوره، والحساب المنشأ في صفحة التسجيل يدخل بصفته هو، وأي بريد آخر يفتح حساب المالك. الحقول الفارغة أو المشوّهة تُرفض كما ترفضها API.
البيانات	Forma Studio وMonogram كاملتان، بمشاريعهما ولوحاتهما وملفاتهما وفريقيهما ودعواتهما ومصفوفة الأدوار والفوترة والفواتير ومفاتيح API والنشاط والمحادثات السابقة للمساعد، ومؤسسات المنصة ومستخدميها وفريقها وأدوارها وإعداداتها. كل تاريخ يُنقل إلى الأمام، فيبقى نشاط هذا الأسبوع في هذا الأسبوع.
التغييرات	حقيقي: إنشاء مشروع، أو نقل بطاقة، أو دعوة شخص، أو تعديل مصفوفة الأدوار، أو شراء خطة عبر الدفع التجريبي، أو إيقاف مؤسسة يغيّر البيانات، ويبقى بعد إعادة التحميل، في ذلك المتصفح وحده.
الصلاحيات	تُفحص كما تفحصها API، من مصفوفة أدوار كل مساحة عمل، فيرى كل دور بالضبط ما كان سيراه مع API.
الفوترة	كما في API من دون مفاتيح Stripe: تتم الترقية عبر صفحة الدفع التجريبية المدمجة، ويُجدول التخفيض عند التجديد، والإبقاء يلغيه. تُنزَّل الفواتير بصيغة PDF.
البريد	لا يُرسل شيء. يُكتب رابط الدعوة أو إعادة تعيين كلمة المرور في وحدة تحكم المتصفح بدلًا من ذلك، ويعمل هناك.
التحديثات الحية	لا شيء: يعرض الجرس النشاط الموجود في البيانات التجريبية أصلًا.
مفاتيح API	يُنشأ المفتاح ويُبطل، ويظهر السر مرة واحدة، لكن المفتاح لا يصادق أي شيء، إذ لا توجد API.
المساعد الذكي	تظهر محادثاته السابقة وبطاقة المهام الأولية. السؤال الجديد يطلب أولًا مفتاح مزوّد، ثم يجيب بأن المساعد يحتاج إلى API؛ ولا يُستدعى أي نموذج.

تتأخر كل إجابة جزءًا من الثانية عمدًا، لتُرى حالات التحميل التي تأتي مع لوحة التحكم.

الموقع على البيانات التجريبية

الصفحة الرئيسية وكل صفحات المحتوى لا تستدعي API أبدًا، فتبدو واحدة في الحالتين. أما الجزءان اللذان يستدعيانها فيجيبان في المتصفح، وعلى الخادم للرسم الأول، من البيانات التجريبية:

المجال	على البيانات التجريبية
الدفع على الترخيص	يُفحص كما تفحصه API. تنتقل البطاقة وPayPal كلتاهما إلى صفحة الدفع التجريبية الخاصة بالموقع على `/checkout/test`: ادفع يضع الطلب في حالة مدفوع ويعرض الإيصال مفتاح الترخيص؛ وألغِ الدفع يلغيه. المبلغ هو سعر الترخيص، أيًّا كان ما يرسله المتصفح.
نموذج الاتصال	يُفحص حقلًا حقلًا كما تفحصه API، ويُجاب بنجاح. لا يُرسل شيء إلى أي مكان.
ما يرسله الزوار	تُحفظ الطلبات والرسائل في ذلك المتصفح وحده، فيظل الإيصال يعرض مفتاحه بعد إعادة التحميل.
البريد والحدود	لا يُرسل إيصال ولا رسالة بالبريد، ولا تنطبق حدود API لكل عنوان على النموذجين.

إشعار البيانات التجريبية

ما دامت البيانات التجريبية هي التي تجيب، يظهر إشعار «بيانات تجريبية» في أسفل كل صفحة، في نهايتها لا فوقها، فلا يغطي شيئًا عند التمرير إلى النهاية. إخفاء يخفيه حتى التحميل الكامل التالي للصفحة.

التطبيق	من دون ضبط API	مع ضبط API لا تجيب
لوحة التحكم (كل الصفحات، ومنها صفحة تسجيل الدخول)	«لا توجد واجهة برمجية متصلة، لذلك تعمل لوحة التحكم على بيانات تجريبية مدمجة وتبقى تغييراتك في هذا المتصفح. أي كلمة مرور تُدخلك، وكل حساب من owner@ وadmin@ وmember@ وbilling@ وplatform@ وsupport@northstack.example يفتح دوره.»	«الواجهة البرمجية على http://localhost:8000/api لا تستجيب، لذلك تعرض لوحة التحكم بيانات تجريبية مدمجة وليست بيانات مساحة عملك. تبقى التغييرات التي تجريها الآن في هذا المتصفح. شغّل الواجهة البرمجية ثم أعد تحميل هذه الصفحة.»
الموقع	«لا توجد واجهة برمجية متصلة (القيمة NEXT_PUBLIC_API_BASE_URL فارغة)، لذا يعمل الموقع على بيانات تجريبية مدمجة: يُجيب نموذج التواصل وصفحة شراء التراخيص داخل هذا المتصفح ولا يُرسلان شيئًا. اضبط NEXT_PUBLIC_API_BASE_URL في الملف .env لاستخدام واجهتك البرمجية.»	«الواجهة البرمجية على العنوان http://localhost:8000/api لا تستجيب، لذا يعرض هذا الموقع بيانات تجريبية مدمجة. تبقى الطلبات والرسائل المرسلة الآن في هذا المتصفح. شغّل الواجهة البرمجية ثم أعد تحميل هذه الصفحة.»

العنوان في العمود الثاني هو ما بُني به التطبيق. وما دامت لوحة التحكم تعمل على البيانات التجريبية يقول تذييل مساحة العمل فيها أيضًا «بيانات تجريبية للعرض.»؛ ولا يقوله أبدًا مع API الخاصة بها.

عندما تتوقف API متصلة عن الرد

مع ضبط NEXT_PUBLIC_API_BASE_URL، تحل البيانات التجريبية محلها أيضًا عندما يتعذر الوصول إلى API إطلاقًا: متوقفة، أو انتهت المهلة، أو محجوبة لأن CORS_ORIGIN فيها لا يذكر التطبيق. أما الجواب الذي أعطته API، حتى لو كان 404 أو 500، فيُعرض دائمًا كما هو.

بعد الفشل تُسأل API مرة أخرى كل 30 ثانية على الأكثر، ويعود التطبيق إليها فور ردها.
تعرض لوحة التحكم إشعارها كلما حلت البيانات التجريبية محل API.
يحل الموقع محلها في المتصفح فقط: الصفحة التي يرسمها خادمه لا تعرض بيانات تجريبية أبدًا. يظهر إشعاره في yarn dev، وفي بناء الإنتاج فقط إذا بُني بالقيمة NEXT_PUBLIC_SAMPLE_DATA_NOTICE=always (في .env قبل yarn build، أو --build-arg NEXT_PUBLIC_SAMPLE_DATA_NOTICE=always مع Docker).
هذا يغطي API التي توقفت، لا تطبيقًا بلا API: يواصل المتصفح محاولة العنوان ويسجّل كل طلب مرفوض في وحدة التحكم. وإن لم تكن هناك API إطلاقًا، فاترك العنوان فارغًا.

الانتقال إلى API الخاصة بك

اضبط NEXT_PUBLIC_API_BASE_URL على عنوان API مع اللاحقة /api، ثم أعد تشغيل yarn dev أو ابنِ من جديد. يجب أن تذكر API عنوان التطبيق في CORS_ORIGIN. ما غُيّر على البيانات التجريبية يبقى في ذلك المتصفح ولا يُرسل إلى API.

الطرفية

cp .env.example .env
yarn dev

ابدأ من جديد

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

وحدة تحكم المتصفح، لوحة التحكم

localStorage.removeItem("northstack_mock_db_v1"); location.reload();

وحدة تحكم المتصفح، الموقع

localStorage.removeItem("northstack_site_mock_db_v1"); location.reload();

إزالته

عندما يعمل تطبيق على API الخاصة بك بصفة دائمة، احذف البيانات التجريبية من كوده، في مجلد التطبيق:

الطرفية

yarn remove:mock

يحذف src/lib/mock/ والإشعار (src/components/SampleDataNotice/) مع رسائله، ويزيل كل كتلة موسومة بـ mock-api في الكود وفي .env.example وفي Dockerfile وفي أدلة التطبيق نفسها، وفي الحزمة الكاملة المقاطع الموسومة من QUICKSTART.md وREADME.md في الجذر، ويُبقي remove:mock ملاحظة من سطر واحد تقول إن البيانات التجريبية أُزيلت بالفعل. وفي الموقع يحذف أيضًا أسطر التوثيق الموسومة بـ {mock}. يُقرأ كل ملف كما لو لم تُضف البيانات التجريبية إليه قط.
yarn remove:mock --dry-run يسرد التغييرات من دون تنفيذها، والتشغيل الثاني لا يجد ما يفعله. ويعمل قبل yarn remove:demo أو بعده.
يحتاج التطبيق بعد ذلك إلى ضبط NEXT_PUBLIC_API_BASE_URL. شغّل yarn typecheck وyarn build بعد ذلك.
يحذف كودًا ولا يمكن التراجع عنه بدون التحكم في الإصدارات، لذلك احفظ التغييرات أولًا.

تصديرها من API مرة أخرى

البيانات التجريبية هي إجابات API الأولية نفسها، فبعد أن تغيّر ما تملؤه بها صدّرها مرة أخرى. في back-end، وAPI تعمل وفيها البيانات الأولية:

الطرفيةفي back-end

yarn export:mock

يسجّل الدخول بكل حساب أولي، ويقرأ ما يعرضه التطبيقان، ويكتب ملفات بيانات لوحة التحكم والموقع الأولية بجانبه، في ../dashboard/src/lib/mock/db/seed/ و../website/src/lib/mock/db/seed/. لا يُكتب شيء في قاعدة البيانات. --api http://host:8000 يقرأ API أخرى. المتصفح الذي يحمل نسخة أقدم يتخلص منها عند تحميله التالي.

كيف بُنيت

مُضمَّن مع مشترياتك. سجّل الدخول لقراءته، أو افتحه في ملف التنزيل.

أين تقع البيانات التجريبية في كل تطبيق، وكيف يصل إليها الطلب، وكيف تبقيها متوافقة مع API الخاصة بك.

سجّل الدخول للقراءة عرض القالب