دليل مسؤولي الخدمات

يرسل البنّاؤون طلبات الخدمات المشتركة من لوحة المنصة، وينفّذها مسؤولو الخدمات يدويًا من هذا الدليل. يمنح المسؤول (admin) دور مسؤول الخدمات. الهدف ألّا يتوقّف أي طلب على شخص واحد، فاكتب دائمًا في ملاحظة الطلب ما فعلت، ليكمل غيرك من حيث توقّفت.

قبل كل طلب

1. انقل الطلب إلى «قيد التنفيذ» حين تبدأ، كي لا يعمل عليه مسؤولان معًا.
2. تأكّد أن الطلب لمشروع حقيقي، وأن صاحبه قائده أو عضو في فريقه. إن لم يكن ذلك واضحًا، فاسأل في ملاحظة الطلب.
3. اعمل بحسابك أنت على Cloudflare وGitHub، وبالصلاحيات التي يحتاجها الطلب فقط.
4. أنهِ الطلب بإحدى حالتين: «تمّ» مع ما فعلت والروابط والخطوة التالية لصاحبه، أو «اعتُذر عنه» مع السبب وما يستطيع فعله بدلًا من ذلك.

هدفنا في التجربة الأولى للمنصة أن تُنفَّذ الطلبات خلال 3 أيام. إن لم تستطع إكمال طلب، فاكتب ما ينقصه، واطلب من مسؤول آخر أن يتسلّمه.

الأسرار لا تمرّ عبر الطلبات

لا تطلب ولا ترسل في أي طلب كلمة مرور، أو مفتاح API، أو رمز دخول، أو AUTH_SECRET، أو أسرار Google وGitHub لخدمة الدخول. إن وجدت سرًّا في طلب، فلا تستخدمه، واطلب من صاحبه في الملاحظة أن يُلغيه ويُصدر غيره فورًا.

من يحتاج سرًّا يضبطه بنفسه: npx wrangler secret put NAME للـ Workers، وnpx wrangler pages secret put NAME لـ Pages، أو في إعدادات المستودع على GitHub. اسم قاعدة البيانات ومعرّفها ليسا سرّين.

نطاق فرعي

1. تحقّق من الاسم

• حروف إنجليزية صغيرة وأرقام وشرطات، في مستوى واحد، مثل your-app.hasanat.dev. لا يقبل تسجيل الدخول المشترك غير ذلك.
• غير مستخدم في سجلات DNS لنطاق hasanat.dev. أسماء مثل auth وapps وplatform وnext مستخدمة لمواقع حسنات.
• يدلّ على المشروع نفسه.

2. اربطه بحسب مكان التطبيق

Worker في حساب حسنات: من لوحة Cloudflare: Workers & Pages ← الـ Worker ← Settings ← Domains & Routes ← Add ← Custom Domain، ثم أدخل الاسم واختر Add Custom Domain. ينشئ Cloudflare سجل DNS والشهادة. أو أضفه إلى ملف إعداد الـ Worker، ثم انشره:

{
  "routes": [{ "pattern": "your-app.hasanat.dev", "custom_domain": true }]
}

لا يقبل Cloudflare نطاقًا مخصّصًا على اسم له سجل CNAME قائم. تحقّق لمن السجل قبل أي تغيير.

مشروع Pages في حساب حسنات: Workers & Pages ← المشروع ← Custom domains ← Set up a domain، ثم أدخل الاسم. لأن النطاق في الحساب نفسه، يضيف Cloudflare سجل CNAME بعد تأكيدك.

مشروع Pages في حساب صاحب الطلب:

1. تأكّد أن صاحب الطلب أضاف الاسم في Custom domains في مشروعه أولًا. سجل CNAME وحده دون هذه الخطوة لا يكفي.
2. في سجلات DNS لنطاق hasanat.dev، أضف سجلًا من نوع CNAME، اسمه your-app، ومحتواه your-app.pages.dev.
3. انتظر حتى يظهر النطاق نشطًا في مشروعه.

استضافة أخرى، مثل Vercel أو Netlify:

1. يضيف صاحب الطلب الاسم في إعدادات استضافته، وينقل إلى الطلب السجلات التي تطلبها، وهي غالبًا CNAME، وأحيانًا TXT للتحقّق.
2. أضف السجلات كما هي تمامًا. اتبع توثيق الاستضافة في خيار التمرير عبر Cloudflare (Proxy)، فكثير منها يطلب أن يبقى السجل «DNS only».

Worker في حساب آخر على Cloudflare: لا يمكن ربطه مباشرة، لأن Cloudflare يشترط أن يكون الـ Worker في الحساب الذي يملك نطاق hasanat.dev. اعرض على صاحب الطلب أن ينشر على Pages، أو اتفق مع المسؤول على نشره في حساب حسنات قبل أن تعرض ذلك. إن لم يناسبه أي خيار، فاعتذر عن الطلب مع السبب.

3. تحقّق وأغلق الطلب

curl -sI https://your-app.hasanat.dev

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

تسجيل دخول لتطبيق خارجي

ما يوجد في خدمة الدخول اليوم:

• تسجيل الدخول المشترك يعمل فقط للمواقع التي تُعرض على *.hasanat.dev، عبر ملف الجلسة المشترك. التفاصيل في تسجيل الدخول.
• لا يوجد تدفق OAuth للتطبيقات الخارجية، ولا تسجيل لتطبيقات عميلة، ولا معرّفات أو أسرار تُصدر لها.
• في الخدمة تدفق للتطبيقات المثبّتة على الأجهزة (/native/*)، لكنه مربوط في الكود بتطبيق «دايمة» وحده. دعم تطبيق آخر يحتاج تغييرًا في كود الخدمة، وهو في مستودع خاص يملكه المسؤول.

كيف تتعامل مع الطلب:

1. اسأل صاحب الطلب: هل يمكن عرض التطبيق على نطاق فرعي من hasanat.dev؟ إن أمكن، فهذا هو الحل: نفّذه طلبَ نطاق فرعي، ودلّه على صفحة تسجيل الدخول.
2. إن لم يمكن، مثل تطبيق جوال أو نطاق لا بد منه، فاكتب الحاجة في ملاحظة الطلب، وارفعها إلى المسؤول، لأنها تحتاج تغييرًا في خدمة الدخول. لا تعِد بموعد.
3. لا تشارك أسرار خدمة الدخول مع أي تطبيق، مهما كان السبب.

قاعدة بيانات

1. تأكّد أن التطبيق سيعمل في حساب حسنات على Cloudflare. إن كان صاحب الطلب ينشر من حسابه، فالأسهل أن ينشئ قاعدته بنفسه. دلّه على قاعدة البيانات، وأغلق الطلب.

2. سجّل الدخول إلى Wrangler بحساب له صلاحية على حساب حسنات، ثم أنشئ القاعدة باسم المشروع:

   npx wrangler login
   npx wrangler d1 create your-app-db

3. اكتب في ملاحظة الطلب ما يضيفه صاحبه إلى إعداد تطبيقه، مع المعرّف الذي طبعه الأمر:

   [[d1_databases]]
   binding = "DB"
   database_name = "your-app-db"
   database_id = "<database-id>"

4. اتفق مع صاحب الطلب على من يطبّق المخطّط على القاعدة. إن لم تكن له صلاحية على حساب حسنات، فطبّقه أنت من مجلد مستودع المشروع، بعد أن تراجع ملف SQL:

   npx wrangler d1 execute your-app-db --remote --file=schema.sql
   # أو، إن كان المشروع يستخدم ملفات الترحيل:
   npx wrangler d1 migrations apply your-app-db --remote

5. لا تطبّق تغييرًا يحذف بيانات حقيقية (مثل DROP TABLE أو DELETE واسع) دون موافقة القائد. تتيح D1 استعادة القاعدة إلى نقطة زمنية سابقة بميزة Time Travel، فاعرف كيف تعمل قبل أي تغيير كبير.

قاعدة hasanat-db خاصة بـ hasanat.dev والمنصة، ولا تُستخدم لتطبيقات المشاريع. أي تغيير في مخطّطها يتمّ في مستودع hasanat أولًا.

إدراج مشروع قائم في hasanat.dev

المشاريع القائمة تدخل مشروعًا مباشرة، وصاحبها قائدها.

1. افتح رابط المشروع، وتأكّد أنه يعمل ويخدم حاجة حقيقية، وأن صاحب الطلب صاحبه أو قائده.
2. تأكّد أن للمشروع موجزًا بقالب حسنات. إن لم يوجد، فساعد صاحبه في كتابته من القالب.
3. أضف الموجز إلى مستودع المشاريع في مجلد جديد برقم المشروع التالي، في طلب سحب.
4. بعد دمجه، تُنقل نصوص الموجزات إلى hasanat.dev بالأمر bun run sync:briefs في مستودع hasanat. إن لم تكن لديك صلاحية تشغيله، فاطلبه ممن يدير hasanat.dev.
5. في صفحة المشرفين على hasanat.dev، عيّن صاحب الطلب قائدًا، واضبط المرحلة: «قيد البناء» أو «يعمل». إن لم تكن مشرفًا، فاطلب ذلك من أحد المشرفين.
6. أرسل لصاحب الطلب رابط صفحة المشروع، وذكّره بأن يفتح الأدوار التي يحتاجها.

الإدراج في apps.hasanat.dev

يعمل دليل التطبيقات على موقع حسنات السابق، وتُراجع فيه الاقتراحات قبل نشرها من صفحة مراجعة خاصة بالمسؤولين.

1. تأكّد أن المشروع «يعمل»، وأن الطلب فيه الرابط الرسمي، ومن يساعد التطبيق وكيف، ورابط ملاحظة الخصوصية.
2. انقل الطلب بهذه المعلومات إلى المسؤول، أو إلى من له صلاحية مراجعة الدليل.
3. بعد انتقال hasanat.dev إلى الموقع الجديد، تأكّد مع المسؤول من طريقة الوصول إلى صفحة المراجعة.

طلبات أخرى

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

حين يتكرّر نوع جديد من الطلبات، أضف خطواته إلى هذا الدليل في طلب سحب إلى مستودع المنصة.