This is the abridged developer documentation for منصة حسنات للبنّائين (Hasanat Builders Platform) # منصة حسنات للبنّائين > كل ما يحتاجه المتطوّع ليبني مشروعًا في حسنات، في مكان واحد. الأدلة علنية، يقرؤها أي شخص ويقرؤها وكلاء البرمجة. ## من أين تبدأ؟ * [كيف يعمل مشروع حسناتالمراحل من الفكرة إلى المشروع، والأدوار، والقواعد.](/start-here/how-hasanat-works/) * [أسبوعك الأولمهمة بداية صغيرة لكل دور.](/start-here/first-week/) * [ابدأ مشروعًامن المواصفات إلى النسخة الأولى، أو أدخل مشروعًا قائمًا.](/start-a-project/from-spec-to-first-version/) * [ابنِ مع وكيل برمجةرسالة البداية، وحزمة المهارات الموثّقة.](/coding-agent/starter-prompt/) * [الخدمات المشتركةتسجيل الدخول، وقاعدة البيانات، والنطاقات الفرعية، والتصميم، وطلبها من اللوحة.](/services/request-a-service/) * [التجربة والإطلاقجرّب مع مستخدمين حقيقيين، ثم أطلق المشروع.](/pilot-and-launch/run-a-pilot/) * [بنك المواردواجهات وبيانات وخطوط وأدوات، مع رخصها وتنبيهاتها.](/resources/resource-bank/) * [لمسؤولي الخدماتدليل تنفيذ طلبات الخدمات المشتركة.](/maintainers/runbook/) ## ما الذي توفّره حسنات للبنّائين؟ * **قالب بداية رسمي** على [GitHub](https://github.com/hasanat-dev/starter)، معدّ للعربية أولًا ولـ Cloudflare. انظر [ابنِ من القالب](/start-a-project/build-from-starter/). * **خمس مهارات لوكلاء البرمجة** في [حزمة موثّقة](/coding-agent/skills-pack/) تتحقّق منها قبل التثبيت. * **تسجيل دخول مشترك** عبر auth.hasanat.dev بحساب Google أو GitHub، للمواقع التي تعمل على نطاقات hasanat.dev. انظر [تسجيل الدخول](/services/sign-in/). * **نطاق فرعي** مثل `name.hasanat.dev`، و**قاعدة بيانات** Cloudflare D1، تطلبهما من [لوحة المنصة](https://platform.hasanat.dev/dashboard) بعد تسجيل الدخول. * **مجتمع** يتواصل على واتساب، و**لقاء شهري** تُختار فيه الأفكار التي تُكتب مواصفاتها. ## ما لا يوجد بعد * منتدى للبنّائين. نكتفي الآن بمجموعات واتساب. * تجهيز آلي للنطاقات وقواعد البيانات. ينفّذها مسؤولو الخدمات يدويًا من [دليل مكتوب](/maintainers/runbook/). * تسجيل دخول للتطبيقات التي لا تعمل على نطاقات hasanat.dev. اطلب الدعم من اللوحة. * أداة الملاحظات المشتركة. توقّفت، وتعود خدمةً مشتركة حين تحتاجها تجربة حقيقية. ## لوكلاء البرمجة الأدلة نفسها متاحة نصًّا لوكلاء البرمجة: [llms.txt](/llms.txt) للفهرس، و[llms-full.txt](/llms-full.txt) للنص الكامل، و[llms-small.txt](/llms-small.txt) لنسخة مختصرة. # كيف يعمل مشروع حسنات > المراحل من الفكرة إلى المشروع، والأدوار، والقواعد التي تحكم العمل في حسنات. حسنات مجتمع يحوّل حاجات حقيقية إلى مشاريع صغيرة يبنيها متطوّعون. ينتهي كل مشروع بتجربة مع مستخدمين حقيقيين، لا بإطلاق موقع فقط. ## المراحل **فكرة** ← يختارها اللقاء الشهري ← **مواصفات** ← يتقدّم شخص لقيادتها ← **مشروع** (قيد البناء ← يعمل) ### فكرة * تحتاج: حاجة حقيقية وتأييدًا. * الفعل الأساسي: اقتراح فكرة، أو التصويت لها. * تنتقل إلى المرحلة التالية حين يختارها اللقاء الشهري وتُكتب مواصفاتها. ### مواصفات * تحتاج: قائدًا. * الفعل الأساسي: «سأقود هذا المشروع». * تصبح مشروعًا حين يؤكّد مشرفٌ القائد. ### مشروع قيد البناء * يحتاج: متطوّعين للأدوار المفتوحة. * الفعل الأساسي: «أستطيع المساعدة» على دور. * يصبح «يعمل» حين يعلن القائد أن التجربة الأولى مع مستخدمين حقيقيين تمّت. ### مشروع يعمل * يحتاج: مساعدة في الميزات والنمو. * الفعل الأساسي: «أستطيع المساعدة» على دور. تجري هذه الأفعال كلها على [hasanat.dev](https://hasanat.dev). تظهر المواصفات التي تنتظر قائدًا في قائمة «تبحث عن قائد»، والمشاريع التي تحتاج متطوّعين في «أدوار مفتوحة». ## القواعد * الأفكار تجمع الحاجات والأصوات فقط. لا تعليقات عليها، ولا عروض للبناء في مرحلة الفكرة. * يستطيع أي شخص أن يكتب مسودة مواصفات بمساعدة وكيل برمجة ومن القالب، ويرسلها طلب سحب (pull request) إلى مستودع المشاريع. يعتمد اللقاء الشهري بعضها. التفاصيل في [من المواصفات إلى النسخة الأولى](/start-a-project/from-spec-to-first-version/). * القائد مسؤول عن النتيجة، لا عن الكود بالضرورة. * أمام القائد بعد تأكيده 4 أسابيع ليضيف رابط بداية: مجموعة الفريق أو المستودع. إن لم يضفه، تعود المواصفات تلقائيًا إلى «تبحث عن قائد». * طلبات المساعدة تصل إلى قائد المشروع مباشرة، لا إلى شخص مركزي. يقبلها القائد أو يعتذر عنها على الموقع. * طلبات الميزات لمشروع يعمل تذهب إلى مهامّ المشروع على GitHub، لا إلى قائمة الأفكار. * المشاريع القائمة تدخل مشروعًا مباشرة، وصاحبها قائدها. انظر [أدخل مشروعًا قائمًا](/start-a-project/existing-project/). ## الأدوار * **زائر:** يقرأ كل شيء، ويصوّت للأفكار. * **عضو:** يقترح الأفكار، ويعرض المساعدة، ويطلب القيادة. يكفي أن يسجّل الدخول عبر auth.hasanat.dev. * **متطوّع:** يعمل في دور مفتوح في مشروع، بعد أن يقبل القائد طلبه. * **قائد:** يدير مشروعًا واحدًا: يردّ على طلبات المساعدة، ويفتح الأدوار ويغلقها، ويضبط رابط البداية والمرحلة. يصبح قائدًا حين يؤكّد مشرفٌ طلب القيادة. * **مشرف:** يؤكّد القادة، ويخفي الأفكار المسيئة أو المكرّرة، ويحدّد الأفكار التي اختارها اللقاء الشهري. يمنحه المسؤول هذا الدور. * **مسؤول خدمات:** ينفّذ طلبات الخدمات المشتركة على المنصة: النطاقات الفرعية، وتسجيل الدخول، وقواعد البيانات، والإدراج. يمنحه المسؤول هذا الدور. * **المسؤول:** يمنح دوري المشرف ومسؤول الخدمات. ## أين يجري العمل | المكان | ما الذي تجده فيه | | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | [hasanat.dev](https://hasanat.dev) | الأفكار، والمواصفات التي تبحث عن قائد، والمشاريع وأدوارها المفتوحة | | platform.hasanat.dev | هذه الأدلة، و[لوحة](https://platform.hasanat.dev/dashboard) طلب الخدمات المشتركة بعد تسجيل الدخول | | [hasanat-dev/projects](https://github.com/hasanat-dev/projects) | موجزات المشاريع ومواصفاتها. المستودع خاص، والموجز يُنشر على hasanat.dev | | [hasanat-dev/starter](https://github.com/hasanat-dev/starter) | قالب البداية العام للتطبيقات الجديدة | | [apps.hasanat.dev](https://apps.hasanat.dev) | دليل التطبيقات المفيدة لمن يبحث عنها | | auth.hasanat.dev | تسجيل الدخول المشترك لمواقع hasanat.dev | | واتساب | مجموعة لكل فريق، ومجموعة للبنّائين | | GitHub | الكود ومهامّ كل مشروع | ## التواصل يتواصل كل فريق في مجموعة واتساب خاصة به. حين يقبل القائد طلبك يصلك رابط البداية، وهو مجموعة الفريق أو مستودع المشروع. لا يوجد منتدى بعد، ونبنيه حين يكثر البنّاؤون الفاعلون. رابط مجموعة البنّائين على واتساب يصلك من قائد مشروعك أو من أحد المشرفين، ولا يُنشر هنا بعد. # أسبوعك الأول حسب دورك > مهامّ بداية صغيرة لكل دور في مشاريع حسنات، تتفق عليها مع قائد المشروع. حين يقبل القائد طلبك «أستطيع المساعدة»، يصلك رابط البداية: مجموعة الفريق أو مستودع المشروع. ابدأ بمهمة صغيرة واحدة تنجزها في أسبوعك الأول. ## قبل أن تبدأ 1. اقرأ موجز المشروع على [hasanat.dev](https://hasanat.dev)، ثم مواصفاته الكاملة حين تصلك من الفريق. 2. عرّف بنفسك في مجموعة الفريق في سطرين: دورك، والوقت المتاح لك. 3. اتفق مع القائد على مهمتك الأولى وموعد المتابعة. 4. سجّل المهمة في مهامّ المشروع على GitHub إن كان الفريق يتابع عمله هناك. ## مهامّ البداية حسب الدور هذه مهامّ مقترحة لبداية كل دور. الجهد المذكور تقدير: صغير، أو متوسط، أو كبير. اختر مع القائد ما يناسب وقتك. ### التطوير * **إعداد المستودع وبيئة التطوير** (جهد صغير): وثّق خطوات التشغيل محليًا، وتأكّد من نجاح البناء. * **بناء أول مسار أساسي للمستخدم** (جهد كبير): نفّذ أصغر مسار يقدّم فائدة حقيقية للمستخدم. * **نشر نسخة قابلة للتجربة** (جهد متوسط): انشر رابطًا تجريبيًا، ودوّن طريقة التحقق منه. ابدأ من [ابنِ من القالب](/start-a-project/build-from-starter/) و[رسالة البداية](/coding-agent/starter-prompt/). ### التصميم * **رسم مسار المستخدم الأساسي** (جهد صغير): حدّد الشاشات والقرارات من الدخول حتى إنجاز الهدف. * **مراجعة تجربة الجوال والاتجاهين** (جهد متوسط): راجع العربية من اليمين إلى اليسار، والإنجليزية، على شاشات الهاتف. انظر [نظام التصميم](/services/design-system/) و[العربية والاتجاه](/services/arabic-and-rtl/). ### المحتوى * **جمع المصادر ومراجعتها** (جهد متوسط): وثّق مصادر المحتوى، وتحقّق من دقتها. * **كتابة المحتوى العربي والإنجليزي** (جهد متوسط): جهّز النصوص الأساسية بلغة واضحة في اللغتين. لا تولّد نصوص القرآن أو الحديث ولا تعيد صياغتها: انقلها من مصدر موثّق كما هي. انظر [بنك الموارد](/resources/resource-bank/). ### الترجمة * **مراجعة الترجمة والاتجاه** (جهد متوسط): راجع المعنى والمصطلحات واتجاه الواجهة في اللغتين. ### البحث * **التحقق من احتياج المستخدمين** (جهد متوسط): تحدّث مع خمسة مستخدمين محتملين، ولخّص أصعب مشكلاتهم. ### الاختبار * **إعداد خطة اختبار مختصرة** (جهد صغير): غطِّ المسار الأساسي، والجوال، وإمكانية الوصول، وحالات الخطأ. * **تجربة المنتج مع ثلاثة مستخدمين** (جهد متوسط): سجّل ما نجح، وما أربك المستخدمين، وما يجب تغييره. انظر [أدر تجربة مع مستخدمين حقيقيين](/pilot-and-launch/run-a-pilot/). ### المجتمع * **دعوة مختبرين من المجتمع** (جهد متوسط): حدّد الجمهور، وادعُ مجموعة صغيرة لتجربة النسخة الأولى. ### التسويق * **إعداد رسالة الإطلاق** (جهد صغير): اكتب إعلانًا واضحًا يشرح المشكلة والفائدة وطريقة التجربة. ### التشغيل * **تنظيم خطة الأسبوع الأول** (جهد صغير): حدّد المسؤوليات، وأول ثلاث نتائج، ومواعيد المتابعة. ### دور آخر * **تحديد مساهمة عملية** (جهد صغير): حوّل عرض المساعدة إلى مهمة واضحة يمكن إنجازها. ## في نهاية الأسبوع اكتب للفريق في سطرين: ماذا أنجزت، وما الذي أوقفك إن وُجد، وما خطوتك التالية. # من المواصفات إلى النسخة الأولى > كيف تُكتب المواصفات وتُعتمد، وكيف يصبح لها قائد، وكيف تُبنى منها النسخة الأولى. لكل مشروع في حسنات ملفان في مجلده في مستودع [hasanat-dev/projects](https://github.com/hasanat-dev/projects): * **الموجز** `brief.md`: صفحة واحدة يفهم منها أي متطوّع المشكلة ولماذا تستحق العمل. * **المواصفات** `spec.md`: التفاصيل التي يبدأ منها الفريق ووكلاء البرمجة: النسخة الأولى ومعايير قبولها، والتجربة، والأدوار، والأسئلة المفتوحة. الموجز يُنشر على hasanat.dev. المواصفات الكاملة تبقى في المستودع الخاص، ويصل إليها الفريق. ## 1. من الفكرة إلى مسودة مواصفات * تُقترح الأفكار ويُصوَّت لها على [hasanat.dev](https://hasanat.dev). الفكرة تجمع الحاجة والتأييد فقط. * يختار اللقاء الشهري بعض الأفكار لتُكتب مواصفاتها. * يستطيع أي شخص أن يكتب مسودة: انسخ [القالب](/start-a-project/spec-template/)، واكتب الموجز والمواصفات بمساعدة وكيل برمجة، ثم أرسلهما طلب سحب (pull request) إلى المستودع. * المستودع خاص. إن لم تكن لديك صلاحية الوصول إليه، اطلبها في مجموعة البنّائين. * يعتمد اللقاء الشهري بعض المسودات، فتظهر في hasanat.dev. ## 2. من المواصفات إلى قائد * تظهر المواصفات المعتمدة في قائمة «تبحث عن قائد» على hasanat.dev. * سجّل الدخول، واضغط «سأقود هذا المشروع»، واكتب لماذا تتقدّم ومتى تستطيع البدء. * يؤكّد مشرف طلبك أو يعتذر عنه. حين يؤكّده تصبح المواصفات مشروعًا قيد البناء، وأنت قائده. * القائد مسؤول عن النتيجة، لا عن الكود بالضرورة. ويكفي غالبًا متطوّع تقني واحد يبني النسخة الأولى بمساعدة وكلاء البرمجة. مهلة الأسابيع الأربعة بعد تأكيدك قائدًا، أمامك 4 أسابيع لتضيف رابط البداية: مجموعة الفريق أو مستودع المشروع. يظهر الموعد في صفحة المشروع. إن انتهت المهلة دون رابط، تعود المواصفات تلقائيًا إلى «تبحث عن قائد». ## 3. تكوين الفريق * افتح الأدوار التي يحتاجها المشروع من صفحة إدارته، كما في جدول «الأدوار المطلوبة» في الموجز. * يضغط المتطوّعون «أستطيع المساعدة» على دور مفتوح، ويصلك الطلب. ترى بريد المتطوّع، ورقم واتساب إن أضافه. * اقبل الطلب أو اعتذر عنه من صفحة إدارة المشروع. حين تقبله يصل المتطوّع رابط البداية. * وجّه كل متطوّع جديد إلى [أسبوعك الأول](/start-here/first-week/)، وأغلق الدور حين يكتمل. ## 4. بناء النسخة الأولى المواصفات هي المرجع في النطاق والقرارات: * ابدأ مما هو موجود (القسم 4): أعد استخدام الكود والبيانات والوثائق قبل أن تبني شيئًا جديدًا. * ابنِ ما في القسم 5 «النسخة الأولى» فقط، وافحص معايير قبوله. * اعتبر القسم 6 «نؤجّله لمراحل لاحقة» خارج النطاق، ومنه الإضافات «السريعة». * لا تفترض إجابة عن «الأسئلة المفتوحة» (القسم 11): اسأل القائد. إن لم يحتمل العمل الانتظار، اختر أصغر خيار يمكن التراجع عنه، واذكر افتراضك. * تبدأ المشاريع الجديدة من [قالب حسنات](/start-a-project/build-from-starter/). وتبقى المشاريع القائمة على تقنيتها ومستودعها. * اقترح أي تغيير في المواصفات طلبَ سحب إلى مستودع المشاريع، ليراجعه القائد. في القسم 12 من كل مواصفات رسالة جاهزة لوكيل البرمجة. هذه رسالة القالب: ```text اقرأ AGENTS.md في جذر المستودع، ثم brief.md وspec.md في مجلد المشروع. ابنِ «النسخة الأولى» فقط، والتزم «نؤجّله لمراحل لاحقة». لا تفترض إجابة لأي «سؤال مفتوح»: اسألني أولًا. ابدأ بخطة قصيرة، ثم بخطوة صغيرة واحدة يمكن فحصها في المتصفح. ``` ## 5. من «قيد البناء» إلى «يعمل» * الهدف تجربة مع مستخدمين حقيقيين (القسم 7)، لا موقع منشور فقط. انظر [أدر تجربة](/pilot-and-launch/run-a-pilot/). * حين تتمّ التجربة، ينقل القائد المشروع إلى «يعمل» ويضبط رابط المنتج. * بعد ذلك تذهب طلبات الميزات إلى مهامّ المشروع على GitHub. # قالب الموجز والمواصفات > الملفان اللذان يبدأ منهما كل مشروع في حسنات، وكيف تكتبهما وتولّد منهما الموجز. كل مشروع في حسنات مجلد في مستودع [hasanat-dev/projects](https://github.com/hasanat-dev/projects)، باسم يبدأ برقمه مثل `04-project-name`. في المجلد ملفان: * `brief.md`: الموجز المختصر. منه يُولَّد `brief.pdf` ونص رسالة واتساب `whatsapp.txt`. * `spec.md`: المواصفات التفصيلية: النسخة الأولى ومعايير قبولها، والتجربة، والأدوار، والأسئلة المفتوحة. لبدء مشروع جديد انسخ مجلد `_template` في المستودع، أو انسخ الملفين من هذه الصفحة. اجعل `number` في الموجز مطابقًا لرقم المجلد. ## كيف نكتب * **نبدأ بالمشكلة، لا بالتقنية.** يفهم أي متطوّع من الموجز المشكلة ولماذا تستحق العمل. * **نسخة أولى صغيرة.** أبسط نسخة تختبر الفكرة، ونؤجّل ما سواها. * **متطوّع تقني واحد يكفي غالبًا** لبناء النسخة الأولى بمساعدة وكلاء البرمجة. الأدوار الأخرى، كالمحتوى والمجتمع وتنظيم التجارب، لا يُستغنى عنها. * **كل مشروع ينتهي بتجربة حقيقية**، لا بإطلاق موقع فقط: مجموعة محدودة من المستخدمين نتعلّم منها قبل التوسّع. * لغة بسيطة وجمل قصيرة، دون مصطلحات تقنية في الموجز. * لا تخترع أرقامًا أو مصادر. إن لم تعرف شيئًا، اكتبه سؤالًا مفتوحًا. ## الموجز جدول الأدوار عمودان: الدور، وماذا ستفعل. يمكن إضافة عمود ثالث للوقت إن كان التقدير موثوقًا. يتوقّف توليد الموجز برسالة واضحة إن نقص قسم مطلوب أو تغيّر عنوانه، لتبقى كل الموجزات على القالب نفسه. لذلك لا تغيّر عناوين الأقسام. NN-slug/brief.md ```markdown --- number: 0 stage: تشكيل الفريق duration: 6 أسابيع team: 3–4 متطوّعين lead: اسم قائد المشروع join_by: 2026-10-09 updated: 2026-10-01 --- # اسم المشروع جملة واحدة تقول ماذا يفعل المشروع ولمن. ## المشكلة من يعاني من ماذا اليوم، ولماذا تستحق المشكلة العمل عليها؟ جملتان أو ثلاث بلغة بسيطة، دون مصطلحات تقنية. ## الفكرة الفكرة الأساسية للحل، كما يراها المستخدم. ## الرؤية بعيدة المدى جملة عن الاتجاه الذي نطمح إليه. ليست ضمن النسخة الأولى. ## ما الموجود اليوم - ما القائم الآن: منتج يعمل، أو موقع قديم، أو كود، أو وثائق، أو مستخدمون - أو: لا شيء بعد، نبدأ من الفكرة ## النسخة الأولى - أبسط ما يُكمل الدورة الأساسية للمستخدم - وظيفة ثانية لا تكتمل الأولى دونها - وظيفة ثالثة فقط إن كانت ضرورية ## نؤجّله لمراحل لاحقة - فكرة جيدة نؤجّلها حتى نتعلّم من التجربة - فكرة أخرى نؤجّلها ## التجربة الأولى - مع من نجرّب، وكم، وإلى متى - ماذا نراقب - متى نعدّ التجربة ناجحة ## الأدوار المطلوبة | الدور | ماذا ستفعل | | --- | --- | | تطوير | بناء النسخة الأولى بمساعدة وكلاء البرمجة. يكفي متطوّع واحد | | تنسيق التجربة | تنظيم التجربة مع المستخدمين، وجمع ملاحظاتهم | ## طريقة العمل - الوقت مرن: يتّفق كل متطوّع مع الفريق على ما يناسبه - لقاء أسبوعي قصير عبر الإنترنت - مجموعة واتساب للفريق، والمهام على GitHub ``` ## المواصفات المواصفات للفريق ولوكلاء البرمجة، وهي المرجع في النطاق والقرارات. أهم أقسامها: * **5. النسخة الأولى:** لكل وظيفة معايير قبول يمكن فحصها. * **6. نؤجّله لمراحل لاحقة:** ما لن نبنيه الآن حتى لو طُلب. * **7. التجربة الأولى:** مع من، وكيف، وماذا نقيس، ومتى تنجح. * **11. أسئلة مفتوحة:** لا يفترض أحد إجابتها؛ يُسأل القائد ثم يُسجَّل القرار. * **12. للبدء مع وكيل البرمجة:** رسالة جاهزة لبدء العمل. NN-slug/spec.md ````markdown # اسم المشروع — المواصفات > للفريق ولوكلاء البرمجة. الموجز المختصر في [brief.md](brief.md). > > الحالة: مسودة · آخر تحديث: 2026-10-01 · يعتمد التغييرات: قائد المشروع ## 1. المشكلة ولماذا تستحق العمل من يعاني من ماذا، وما الذي يفعله اليوم بدلًا من ذلك، ولماذا يستحق الأمر جهد المتطوّعين. اكتب الفرضية التي نختبرها إن وُجدت. ## 2. الفكرة الأساسية الحل في فقرة، وأدوار المستخدمين فيه. ## 3. الرؤية بعيدة المدى ليست ضمن النسخة الأولى. تساعد على فهم الاتجاه فقط. ## 4. ما الموجود اليوم ما القائم الآن: منتج يعمل، أو موقع قديم، أو كود، أو بيانات، أو وثائق، أو مستخدمون. اذكر الروابط وما يمكن إعادة استخدامه، أو اكتب أنه لا شيء بعد. ## 5. النسخة الأولى أبسط نسخة تُكمل الدورة الأساسية وتختبر الفكرة. لكل وظيفة معايير قبول يمكن فحصها: ### 5.1 اسم الوظيفة - [ ] معيار قبول يمكن فحصه - [ ] ... ## 6. نؤجّله لمراحل لاحقة ما لن نبنيه الآن حتى لو طُلب. أي إضافة تحتاج موافقة قائد المشروع أولًا. - ... ## 7. التجربة الأولى مع مستخدمين حقيقيين - **مع من:** ... - **كيف:** ... - **ماذا نقيس:** ... - **متى تنجح:** ... ## 8. الأدوار نفترض متطوّعًا تقنيًا واحدًا يبني معظم النسخة الأولى بمساعدة وكلاء البرمجة. الأدوار الأخرى، كالمحتوى والمجتمع وتنظيم التجربة، لا يُستغنى عنها. لا نحدّد ساعات ثابتة: يتّفق كل متطوّع مع الفريق على ما يناسب وقته. | الدور | المهمة | | --- | --- | | تطوير | ... | ## 9. البيانات والخصوصية ما الذي نحفظه، ومن يراه، وما الذي لا نجمعه أبدًا. ## 10. نقطة البداية التقنية الفريق يقرّر. الاقتراح الافتراضي: [قالب حسنات](https://github.com/hasanat-dev/starter) (Astro وCloudflare). ## 11. أسئلة مفتوحة لا تفترض إجابة: اسأل قائد المشروع، ثم سجّل القرار هنا. - [ ] ... ## 12. للبدء مع وكيل البرمجة ```text اقرأ AGENTS.md في جذر المستودع، ثم brief.md وspec.md في مجلد المشروع. ابنِ «النسخة الأولى» فقط، والتزم «نؤجّله لمراحل لاحقة». لا تفترض إجابة لأي «سؤال مفتوح»: اسألني أولًا. ابدأ بخطة قصيرة، ثم بخطوة صغيرة واحدة يمكن فحصها في المتصفح. ``` ```` ## توليد الموجز في جذر مستودع المشاريع: ```sh npm install npm run brief -- 04-project-name ``` يُنشئ الأمر `brief.pdf` و`whatsapp.txt` في مجلد المشروع، وتضيف `--png` صورة للمعاينة. الخط المستخدم IBM Plex Sans Arabic، برخصة OFL. ## مع وكيل البرمجة يقرأ وكيل البرمجة ملف `AGENTS.md` في جذر المستودع أولًا. يمكنك أن تبدأ برسالة مثل: ```text اقرأ AGENTS.md، ثم _template/brief.md و_template/spec.md. ساعدني في كتابة موجز ومواصفات لمشروع جديد بالقالب نفسه. اسألني عن المشكلة ومن يعاني منها قبل أن تقترح حلًّا، ولا تخترع أرقامًا أو مصادر. ``` حين تكتمل المسودة، أرسلها طلب سحب. انظر [من المواصفات إلى النسخة الأولى](/start-a-project/from-spec-to-first-version/). # ابنِ من القالب > انسخ قالب حسنات، وشغّله على جهازك، ثم أضف ما يحتاجه مشروعك. [قالب حسنات](https://github.com/hasanat-dev/starter) نقطة البداية المقترحة للتطبيقات الجديدة. هو مستودع عام برخصة MIT، ومعدّ للعربية أولًا ولـ Cloudflare. ## ما في القالب * Astro 5 مع العرض على الخادم، وReact 19 للأجزاء التفاعلية. * Tailwind CSS v4، وTypeScript بالوضع الصارم. * العربية افتراضيًا من اليمين إلى اليسار، والإنجليزية. * ربط جاهز مع [تسجيل الدخول المشترك](/services/sign-in/). * مساعدات لقاعدة بيانات [Cloudflare D1](/services/database/)، وإعداد للنشر على [Cloudflare Pages](/services/deploy-and-subdomains/). * Biome للتنسيق والفحص، وzod للتحقق من المدخلات، وlucide-react للأيقونات. * أربع مهارات لوكلاء البرمجة في `.github/skills/`. نسخها أقدم من [حزمة المهارات](/coding-agent/skills-pack/)، فاعتمد نسخ الحزمة. ## المتطلبات git، وNode.js 20 أو أحدث، وnpm. يعتمد القالب على npm وملف `package-lock.json`، فلا تغيّر مدير الحزم. ## التشغيل لأول مرة 1. أنشئ نسختك. اضغط **Use this template** في صفحة القالب على GitHub لتنشئ مستودعك، أو انسخه مباشرة: ```sh git clone --depth 1 https://github.com/hasanat-dev/starter.git my-app cd my-app ``` 2. ثبّت الاعتماديات، وانسخ ملف البيئة: ```sh npm install cp .env.example .env ``` 3. شغّل خادم التطوير: ```sh npm run dev ``` افتح الرابط الذي يطبعه Astro، وهو عادة `http://localhost:4321`. يحوّلك الجذر إلى `/ar/`. إن كان المنفذ مشغولًا فاستخدم الرابط الذي يختاره Astro، ولا توقف عملية أخرى. 4. تأكّد من البناء قبل أي تعديل: ```sh npm run check npm run build ``` نقطة النجاح الأولى صفحة حقيقية تعمل على جهازك. تسجيل الدخول وقاعدة البيانات والنشر خطوات لاحقة واختيارية. ## مشكلات معروفة في القالب جرّبنا القالب كما هو في 13 أكتوبر 2026: التثبيت والبناء وخادم التطوير تعمل، لكن أمرين يفشلان. * **`npm run check`** يعرض خطأً واحدًا: `Cannot find name 'D1Result'` في `src/lib/db.ts`. أضف هذا السطر إلى `src/env.d.ts` بجانب تعريف `D1Database`: ```ts type D1Result = import("@cloudflare/workers-types").D1Result; ``` * **`npm run lint`** يتوقّف لأن `biome.json` مكتوب لإصدار Biome 1، والقالب يثبّت Biome 2. الأمر `npx biome migrate --write` يحدّث الإعداد، لكن بعض القواعد تبقى تشتكي من ملفات Astro ومن صيغ Tailwind. اعتمد على `npm run check` و`npm run build` إلى أن يُصلَح القالب. ## ملف البيئة * في `.env.example` متغيّران فقط: `PUBLIC_SITE_URL` و`PUBLIC_APP_NAME`. تسجيل الدخول المشترك لا يحتاج أي سرّ. * في الملف سطران معلّقان `HASANAT_CLIENT_ID` و`HASANAT_CLIENT_SECRET` لتدفق OAuth للتطبيقات الخارجية. هذا التدفق غير موجود اليوم، فاتركهما كما هما. انظر [تسجيل الدخول](/services/sign-in/). * لا تضع أسرارًا في المستودع، ولا ترسلها في محادثة أو طلب. ## بنية المشروع ```text src/ ├── middleware.ts يقرأ جلسة تسجيل الدخول ├── lib/ │ ├── auth.ts روابط الدخول والخروج وحماية الصفحات │ └── db.ts مساعدات D1 ├── layouts/ │ └── Layout.astro يضبط lang وdir ├── pages/ │ ├── index.astro يحوّل إلى /ar/ │ ├── ar/ الصفحات العربية │ ├── en/ الصفحات الإنجليزية │ └── api/health.ts ├── i18n/ ar.json وen.json وutils.ts └── styles/global.css ألوان Tailwind والخطوط schema.sql مخطّط قاعدة البيانات wrangler.toml إعداد Cloudflare .env.example .github/skills/ مهارات وكلاء البرمجة AGENTS.md تعليمات وكلاء البرمجة DATA_POLICY.md سياسة البيانات للبنّائين ``` ## الأوامر | الأمر | ماذا يفعل | | -------------------------- | --------------------------------------- | | `npm run dev` | يشغّل خادم التطوير على `localhost:4321` | | `npm run build` | يبني نسخة الإنتاج | | `npm run preview` | يعاين البناء على جهازك | | `npm run lint` | يفحص الكود بـ Biome | | `npm run check` | يفحص TypeScript وAstro | | `npm run db:migrate:local` | يطبّق `schema.sql` على قاعدة D1 المحلية | | `npm run db:migrate:prod` | يطبّقه على قاعدة الإنتاج | قبل أوامر قاعدة البيانات، ضع اسم قاعدتك مكان `YOUR_DB_NAME` في `package.json`. ## اصطلاحات القالب من ملف `AGENTS.md` في القالب: * استورد بالمسار المختصر `@/`. * استخدم خصائص Tailwind المنطقية مثل `ms-*` و`pe-*` بدل `ml-*` و`pr-*`. * أضف كل نص يظهر للمستخدم إلى `ar.json` و`en.json` معًا، ولا تكتبه مباشرة في الصفحة. * Biome للتنسيق لا Prettier، وzod للتحقق من المدخلات، وlucide-react للأيقونات. * لا تضف Firebase أو مزوّد دخول آخر: استخدم auth.hasanat.dev وD1. ## بعد أن تعمل الصفحة الأولى * شكّل النسخة الأولى حول نتيجة واحدة مفيدة، كما في المواصفات إن كان المشروع من مشاريع حسنات. * حين تحتاج تسجيل الدخول أو قاعدة بيانات أو نطاقًا، اقرأ [الخدمات المشتركة](/services/request-a-service/). * يشير ملف README في القالب إلى صفحة إرسال قديمة على hasanat.dev لم تعد مسار العمل. اطلب النطاق والإدراج من [لوحة المنصة](https://platform.hasanat.dev/dashboard). # أدخل مشروعًا قائمًا > إن كان لديك تطبيق يعمل أو كود أو نموذج أولي، أدخله حسنات مشروعًا دون أن تعيد بناءه. المشاريع القائمة تدخل حسنات مشروعًا مباشرة، دون المرور بمرحلتي الفكرة والمواصفات، وصاحبها قائدها. لا تحتاج إلى تغيير تقنيتك أو نقل مستودعك. ## متى يناسبك هذا المسار * لديك تطبيق يعمل، أو كود، أو نموذج أولي، يخدم حاجة حقيقية. * تريد متطوّعين لأدوار محدّدة، أو تريد أن يجد الناس مشروعك. * أنت صاحب المشروع أو قائده. إن كان التطبيق لغيرك وتريد أن يجده الناس، فاقترحه على دليل التطبيقات. انظر [الإدراج في apps.hasanat.dev](/pilot-and-launch/apps-listing/). ## الخطوات 1. **اكتب موجزًا لمشروعك** بالقالب نفسه. نصوص صفحات المشاريع على hasanat.dev تأتي من ملفات الموجز في مستودع المشاريع. انظر [قالب الموجز والمواصفات](/start-a-project/spec-template/). 2. **اطلب الإدراج** من [لوحة المنصة](https://platform.hasanat.dev/dashboard) بعد تسجيل الدخول، واختر «إدراج مشروع قائم في hasanat.dev». اذكر في الطلب: اسم المشروع، ورابطه، ومستودعه إن وُجد، ومن يقوده، والأدوار التي يحتاجها، ونص الموجز أو رابطه. 3. **تابع الطلب** في اللوحة. يتواصل معك مسؤول الخدمات في ملاحظة الطلب حتى يظهر المشروع على hasanat.dev بقائده ومرحلته: «قيد البناء» أو «يعمل». 4. **بعد الإدراج** افتح الأدوار التي تحتاجها، وردّ على طلبات «أستطيع المساعدة». لا تضع في الطلب كلمات مرور أو مفاتيح أو أي أسرار. ## خدمات اختيارية اطلب كل خدمة في طلب مستقل من اللوحة: * **نطاق فرعي** مثل `name.hasanat.dev`، حتى لو كان التطبيق مستضافًا خارج Cloudflare. انظر [النشر والنطاقات الفرعية](/services/deploy-and-subdomains/). * **تسجيل الدخول المشترك:** يعمل حين يُعرض التطبيق على نطاق فرعي من hasanat.dev. إن بقي التطبيق على نطاق آخر، فاطلب «تسجيل دخول لتطبيق خارجي». انظر [تسجيل الدخول](/services/sign-in/). * **قاعدة بيانات** Cloudflare D1. انظر [قاعدة البيانات](/services/database/). ## إن بنيته بأداة بناء لا تحتاج أن تكتب الكود بنفسك لتبني مشروعًا. أدوات مثل [Replit](https://replit.com) و[Lovable](https://lovable.dev) و[Bolt](https://bolt.new) و[v0](https://v0.app) تبني تطبيقات من وصف نصي، وبعضها يستضيفها. 1. ابنِ تطبيقك بالأداة التي تناسبك. 2. انشره حيث تشاء: على استضافة الأداة نفسها، أو أي منصة أخرى. 3. اتبع الخطوات أعلاه لإدراجه، واطلب نطاقًا فرعيًا إن أردت. أدوات البناء مناسبة للمشاريع البسيطة. إن احتجت لاحقًا تسجيل الدخول المشترك أو قاعدة D1، فقد يكون الانتقال إلى [قالب حسنات](/start-a-project/build-from-starter/) أسهل. # رسالة البداية لوكيل البرمجة > رسالة جاهزة تلصقها في وكيل البرمجة، فيبدأ معك من فكرة صغيرة إلى صفحة تعمل على جهازك. مهارة `hasanat-builder` تعطي وكيل البرمجة مسارًا واضحًا: يصقل معك نتيجة أولى صغيرة، وينسخ القالب الرسمي، ويشغّله على جهازك، ويتحقق من الصفحة قبل أن يضيف تسجيل الدخول أو قاعدة البيانات أو النشر. تعمل الرسالة مع وكلاء البرمجة الذين يستطيعون تشغيل الأوامر وقراءة الملفات، مثل GitHub Copilot أو Claude Code أو Cursor. ## ثلاث خطوات 1. **راجع المصدر.** اقرأ [تعليمات المهارة](/skills/hasanat-builder-SKILL.md) قبل أن تمنحها للوكيل. 2. **انسخ الرسالة كما هي** والصقها في وكيل البرمجة. لا تحتاج إلى تعديل أي جزء منها. 3. **أجب عن سؤاله الأول:** سيبدأ بسؤالك عمّا تريد بناءه. ## الرسالة ```text ساعدني في بدء مشروع صغير يعمل ضمن حسنات. ابدأ بسؤالي: ما الذي أريد بناءه؟ لا تطلب مني تعديل هذه الرسالة أو إعادة كتابتها. بعد إجابتي، اسأل سؤالين قصيرين كحد أقصى، وفقط عند الحاجة، لتحديد: - لمن ستكون النسخة الأولى، وما المشكلة التي تحلها؛ - الفعل المفيد الوحيد الذي يجب أن تدعمه أول صفحة محلية. بعد ذلك لخّص المرحلة الأولى في جملة واحدة، ثم تابع دون أن تطلب مني إعداد وثيقة متطلبات. تحقق أولاً مما إذا كانت مهارات حسنات الخمس متاحة: hasanat-builder وhasanat-auth وhasanat-d1 وhasanat-design وhasanat-deploy. إن كانت أي منها غير متاحة: 1. نزّل الحزمة الكاملة الموثقة وملف البيان وأداة التحقق من https://platform.hasanat.dev/skills/ إلى مجلد مؤقت: hasanat-skills.skill وhasanat-skills.manifest.json وverify-hasanat-skills.mjs. 2. شغّل node verify-hasanat-skills.mjs hasanat-skills.skill hasanat-skills.manifest.json. لا تثبّت الحزمة إن فشل التحقق. ثم اعرض محتوياتها باستخدام unzip -l وتحقق من احتوائها على مجلد لكل مهارة من المهارات الخمس. اشرح باختصار أن المهارات تعليمات وسكربتات سيتبعها وكيل البرمجة. 3. اطلب موافقتي مرة واحدة قبل تثبيت المهارات الناقصة، ولا تستبدل أي مجلد مهارة موجود. 4. بعد الموافقة، أنشئ .agents/skills داخل المشروع الحالي وفك الحزمة هناك: mkdir -p .agents/skills unzip -n /hasanat-skills.skill -d .agents/skills ثم حمّل مهارة hasanat-builder واتبعها، وحمّل المهارات المساندة فقط عندما تصل إلى تسجيل الدخول أو قاعدة البيانات أو التصميم أو النشر. اجعل المرحلة الأولى محددة: عرّف نتيجة واحدة مفيدة للصفحة الأولى، انسخ قالب حسنات الرسمي العام عبر HTTPS إلى مجلد جديد، ثبّت الاعتماديات المقفلة، انسخ .env.example، شغّل خادم التطوير، وتحقق من الصفحة في المتصفح. لا تشترط تسجيل GitHub أو OAuth أو D1 أو النشر أو أي أسرار قبل أن أرى صفحة تعمل محليًا. بعد ذلك واصل معي تشكيل الفكرة وتنفيذها. ``` ## ماذا سيحدث * يسألك الوكيل عمّا تريد بناءه، ثم سؤالين قصيرين على الأكثر عند الحاجة. * يلخّص المرحلة الأولى في جملة واحدة. * يتحقّق من وجود المهارات الخمس. إن نقص بعضها نزّل الحزمة إلى مجلد مؤقت، وتحقّق منها، وطلب موافقتك مرة واحدة قبل التثبيت. التفاصيل في [حزمة المهارات](/coding-agent/skills-pack/). * ينسخ القالب، ويثبّت الاعتماديات، ويشغّل خادم التطوير، ويفتح الصفحة في المتصفح. ## إن كنت تعمل على مشروع له مواصفات ابدأ برسالة القسم 12 في مواصفات المشروع بدل هذه الرسالة، لأنها توجّه الوكيل إلى الموجز والمواصفات أولًا. انظر [من المواصفات إلى النسخة الأولى](/start-a-project/from-spec-to-first-version/). ## إن لم يستطع وكيلك تنزيل الملفات نزّل الحزمة وتحقّق منها بنفسك باتباع [حزمة المهارات](/coding-agent/skills-pack/)، ثم الصق الرسالة. # حزمة المهارات > خمس مهارات لوكلاء البرمجة في حزمة واحدة موثّقة. نزّلها، وتحقّق منها، ثم ثبّتها. المهارات تعليمات وسكربتات صغيرة يتبعها وكيل البرمجة. تجمع حسنات خمس مهارات في حزمة واحدة، معها بيان يحمل مجموع SHA-256 لكل ملف، وأداة تتحقّق منها قبل التثبيت. | المهارة | متى يستخدمها الوكيل | | ----------------- | ----------------------------------------------------------------------------------- | | `hasanat-builder` | المسار الأساسي: من فكرة أو مواصفات إلى صفحة تعمل على جهازك، ثم طلب الخدمات والإطلاق | | `hasanat-auth` | تسجيل الدخول المشترك عبر auth.hasanat.dev | | `hasanat-d1` | قاعدة بيانات Cloudflare D1 | | `hasanat-design` | ألوان حسنات وخطوطها، والاتجاه من اليمين إلى اليسار، وإمكانية الوصول | | `hasanat-deploy` | النشر على Cloudflare وطلب النطاق الفرعي | ## الحزمة الحالية | الإصدار | `2026.10.13.1` | | ---------------------- | ------------------------------------------------------------------------- | | المهارات | hasanat-auth, hasanat-builder, hasanat-d1, hasanat-deploy, hasanat-design | | الملفات المتحقَّق منها | 7 | | SHA-256 | `4c730633cd80c2f4ead93a7083af26071ca36a525746a00a7fadd61021f08362` | | الحجم | 35.7 KB | * [hasanat-skills.skill](/skills/hasanat-skills.skill): الحزمة الكاملة بالمهارات الخمس. * [hasanat-skills.manifest.json](/skills/hasanat-skills.manifest.json): البيان: الإصدار، والمصادر، ومجموع SHA-256 لكل ملف. * [verify-hasanat-skills.mjs](/skills/verify-hasanat-skills.mjs): أداة التحقق (تحتاج Node.js والأمر unzip). * [hasanat-skills.skill.sha256](/skills/hasanat-skills.skill.sha256): مجموع الحزمة وحده. * [hasanat-builder.skill](/skills/hasanat-builder.skill): مهارة hasanat-builder وحدها. * [hasanat-builder-SKILL.md](/skills/hasanat-builder-SKILL.md): تعليمات hasanat-builder لتقرأها قبل التثبيت. ## التنزيل والتحقق والتثبيت تحتاج Node.js والأمر `unzip`. 1. نزّل الحزمة والبيان وأداة التحقق إلى مجلد مؤقت خارج مشروعك: ```sh mkdir -p ~/Downloads/hasanat-skills && cd ~/Downloads/hasanat-skills curl -fsSLO https://platform.hasanat.dev/skills/hasanat-skills.skill curl -fsSLO https://platform.hasanat.dev/skills/hasanat-skills.manifest.json curl -fsSLO https://platform.hasanat.dev/skills/verify-hasanat-skills.mjs ``` 2. تحقّق من الحزمة. لا تثبّتها إن فشل التحقق: ```sh node verify-hasanat-skills.mjs hasanat-skills.skill hasanat-skills.manifest.json ``` تقارن الأداة مجموع الحزمة وحجمها وقائمة ملفاتها ومجموع كل ملف بما في البيان. 3. اعرض محتوى الحزمة، وتأكّد أن فيها مجلدًا لكل مهارة من الخمس: ```sh unzip -l hasanat-skills.skill ``` 4. فكّ الحزمة داخل مشروعك: ```sh mkdir -p .agents/skills unzip -n ~/Downloads/hasanat-skills/hasanat-skills.skill -d .agents/skills ``` الخيار `-n` لا يستبدل أي ملف موجود. إن كان وكيلك يقرأ المهارات من مجلد آخر، فكّها هناك بحسب توثيقه. [رسالة البداية](/coding-agent/starter-prompt/) تطلب من الوكيل هذه الخطوات نفسها، وتسألك قبل التثبيت. ## المهارات في القالب في قالب حسنات أربع من هذه المهارات في `.github/skills/`، لكنها أقدم من الحزمة. نسخة `hasanat-auth` في القالب تصف تدفق OAuth للتطبيقات الخارجية غير موجود، ونسخة `hasanat-deploy` تطلب سرًّا لا تحتاجه. اعتمد نسخ الحزمة. ## ما الذي تغيّر في هذا الإصدار * `hasanat-builder` يتبع مسار حسنات الحالي: الأفكار والمواصفات والقادة و«أستطيع المساعدة»، وطلب الخدمات من لوحة المنصة. * `hasanat-auth` يصف تسجيل الدخول كما يعمل فعلًا: لا تدفق OAuth للتطبيقات الخارجية، ولا سرّ في التطبيق، ولا تسجيل دخول على `localhost`. * `hasanat-deploy` يطلب النطاق الفرعي من اللوحة، ولا يطلب `AUTH_SECRET`. * `hasanat-d1` و`hasanat-design`: تصحيحات صغيرة، وألوان حسنات وخطّها. * أصبح لكل مهارة اسم ووصف في رأس ملفها، لتتعرّف عليها أدوات وكلاء البرمجة. # اطلب خدمة مشتركة > ما الخدمات المشتركة التي توفّرها حسنات، وكيف تطلبها من لوحة المنصة، وكيف تتابع طلبك. توفّر حسنات للمشاريع خدمات مشتركة: نطاقًا فرعيًا، وتسجيل دخول، وقاعدة بيانات، وإدراجًا في hasanat.dev. تطلبها من [لوحة المنصة](https://platform.hasanat.dev/dashboard) بعد تسجيل الدخول عبر auth.hasanat.dev. ينفّذ الطلبات **مسؤولو الخدمات** يدويًا، من [دليل مكتوب](/maintainers/runbook/)، فلا يتوقّف أي طلب على شخص واحد. هدفنا في التجربة الأولى للمنصة أن تُنفَّذ الطلبات خلال 3 أيام. ## أنواع الطلبات ### نطاق فرعي * متى تحتاجه: تريد عنوانًا مثل `name.hasanat.dev`. * ماذا تكتب في الطلب: الاسم المطلوب، وأين يعمل التطبيق (مشروع Cloudflare Pages أو Worker، أو استضافة أخرى)، ورابطه الحالي. ### تسجيل دخول لتطبيق خارجي * متى تحتاجه: تطبيقك لا يعمل على نطاق من hasanat.dev، ويحتاج حسابات حسنات. * ماذا تكتب في الطلب: رابط التطبيق، ولماذا يحتاج تسجيل الدخول، وهل يمكن أن يعمل على نطاق فرعي من hasanat.dev. ### قاعدة بيانات * متى تحتاجه: تحتاج قاعدة Cloudflare D1 في حساب حسنات. * ماذا تكتب في الطلب: اسم المشروع، والاسم المقترح للقاعدة، وأين سيعمل التطبيق. ### إدراج مشروع قائم في hasanat.dev * متى تحتاجه: لديك مشروع يعمل، وتريد أن يظهر في hasanat.dev. * ماذا تكتب في الطلب: الاسم، والرابط، والمستودع، والقائد، والأدوار المطلوبة، والموجز أو رابطه. ### غير ذلك * متى تحتاجه: أي حاجة أخرى، مثل الإدراج في [apps.hasanat.dev](/pilot-and-launch/apps-listing/). * ماذا تكتب في الطلب: ما تحتاجه، ولماذا، والروابط المفيدة. اختر لاسم النطاق الفرعي حروفًا إنجليزية صغيرة وأرقامًا وشرطات فقط، في مستوى واحد مثل `your-app.hasanat.dev`. هذا ما يقبله تسجيل الدخول المشترك. التفاصيل في [النشر والنطاقات الفرعية](/services/deploy-and-subdomains/). لا ترسل أسرارًا في أي طلب لا تكتب في الطلب كلمة مرور، أو مفتاح API، أو رمز دخول، أو أي سرّ آخر. مسؤول الخدمات لا يطلبها منك أبدًا. من يحتاج سرًّا يضبطه بنفسه مباشرة في Cloudflare أو GitHub. اسم قاعدة البيانات ومعرّفها ليسا سرّين. ## حالة الطلب يرى الطلبَ صاحبُه ومسؤولو الخدمات فقط. تتابع حالته في اللوحة: | الحالة | معناها | | ----------- | ------------------------------------------------ | | جديد | وصل الطلب ولم يبدأ تنفيذه | | قيد التنفيذ | يعمل عليه مسؤول خدمات، وقد يسألك في ملاحظة الطلب | | تمّ | نُفّذ، وفي الملاحظة ما فُعل وما خطوتك التالية | | اعتُذر عنه | لم يُنفّذ، وفي الملاحظة السبب | قد يصلك بريد حين تتغيّر حالة طلبك، والحالة تبقى ظاهرة في اللوحة دائمًا. ## ما ليس متاحًا الآن * **التجهيز الآلي** للنطاقات وقواعد البيانات: كل طلب يُنفَّذ يدويًا. * **تدفق OAuth** للتطبيقات التي لا تعمل على نطاقات hasanat.dev: اطلب «تسجيل دخول لتطبيق خارجي» ليُبحث وضعك. * **أداة الملاحظات المشتركة:** أداة الملاحظات السابقة متوقفة، ولا يضمّنها أي تطبيق يعمل اليوم. تعود خدمةً مشتركة حين تطلبها تجربة حقيقية تحتاج ملاحظات من داخل التطبيق، فاذكر ذلك في طلب «غير ذلك». * **منتدى البنّائين:** نكتفي الآن بمجموعة واتساب. # تسجيل الدخول المشترك > كيف يعمل تسجيل الدخول عبر auth.hasanat.dev، وكيف تستخدمه في تطبيقك، وما حدوده. auth.hasanat.dev خدمة تسجيل دخول مشتركة لكل المواقع التي تعمل على نطاقات hasanat.dev. يسجّل المستخدم دخوله مرة واحدة بحساب Google أو GitHub، فيعرفه كل موقع من مواقع حسنات. ## كيف يعمل * بعد تسجيل الدخول تضع الخدمة ملف تعريف الارتباط `authjs.session-token` على النطاق `.hasanat.dev`. يرسله المتصفح إلى كل موقع على `https://*.hasanat.dev`. * الملف مشفّر بسرّ لا تملكه إلا خدمة الدخول، فلا يفكّه تطبيقك. يسأل تطبيقك الخدمة بدلًا من ذلك: يرسل ترويسة `cookie` كما وصلته إلى `https://auth.hasanat.dev/api/auth/session`، فيصله بيان الجلسة، أو `null` إن لم يكن أحد مسجّلًا. * الملف `httpOnly` و`Secure` و`SameSite=Lax`، فلا تقرؤه شيفرة الصفحة. * تنتهي الجلسة بعد 30 يومًا دون استخدام، وكل فحص للجلسة يمدّدها. ## الروابط * **صفحة الدخول:** `https://auth.hasanat.dev/api/auth/signin?callbackUrl=<رابط العودة بعد ترميزه>` * **بيان الجلسة:** `https://auth.hasanat.dev/api/auth/session` * **تسجيل الخروج:** `https://auth.hasanat.dev/api/auth/signout` * **حساب المستخدم:** `https://auth.hasanat.dev/account` تقبل الخدمة رابط العودة إن كان `https://hasanat.dev`، أو نطاقًا فرعيًا من مستوى واحد مثل `https://name.hasanat.dev`، أو `http://localhost`. أي رابط آخر يعيد المستخدم إلى auth.hasanat.dev نفسها. صفحة الدخول بالإنجليزية حاليًا. ## بيان الجلسة ```json { "user": { "id": "…", "name": "…", "email": "…", "image": "…", "provider": "google", "githubUsername": null, "role": "user" }, "expires": "…" } ``` * `id` معرّف ثابت للمستخدم. اربط به بيانات تطبيقك. * `provider` هو `google` أو `github`. * `role` من سجل المستخدم في خدمة الدخول، وقيمته الافتراضية `user`، ويُقرأ عند تسجيل الدخول. ليس دورًا في مشاريع حسنات مثل القائد أو المشرف. احفظ صلاحيات تطبيقك في قاعدة بياناته. ## في قالب حسنات القالب مربوط بالخدمة مسبقًا. الملف `src/middleware.ts` يسأل خدمة الدخول عن الجلسة، ويضع المستخدم في `Astro.locals.user`، أو `null`. المسارات التي يغطيها القالب يفحص القالب الجلسة فقط في المسارات التي تبدأ بـ `/api/` أو تحتوي `/dashboard`. في غيرها يبقى `Astro.locals.user` فارغًا حتى لو كان المستخدم مسجّلًا. وسّع الشرط `needsAuth` في `src/middleware.ts` إن احتاجت صفحات أخرى أن تعرف المستخدم. ```astro --- // صفحة تحتاج تسجيل الدخول import { requireAuth } from "@/lib/auth"; const redirect = requireAuth(Astro.locals.user, Astro.url.href); if (redirect) return redirect; const user = Astro.locals.user; // { id, name, email, image, role } --- ``` ```ts // روابط الدخول والخروج، وفحص المسؤول import { getSignInUrl, getSignOutUrl, isAdmin } from "@/lib/auth"; const signIn = getSignInUrl(Astro.url.href); const signOut = getSignOutUrl(); const admin = isAdmin(Astro.locals.user); // role === "admin" ``` ```ts // مسار API محمي import type { APIRoute } from "astro"; export const GET: APIRoute = async ({ locals }) => { if (!locals.user) return new Response("Unauthorized", { status: 401 }); return Response.json({ id: locals.user.id }); }; ``` ## من المتصفح الصفحات التي تعمل على نطاق فرعي من hasanat.dev تستطيع أن تسأل عن الجلسة من المتصفح، لأن خدمة الدخول تقبل الطلبات المصحوبة بملفات الارتباط من نطاقات hasanat.dev: ```js const res = await fetch("https://auth.hasanat.dev/api/auth/session", { credentials: "include", }); const session = await res.json(); // null إن لم يكن المستخدم مسجّلًا ``` ## على جهازك لا يعمل تسجيل الدخول المشترك على `localhost`، لأن ملف الارتباط خاص بنطاقات hasanat.dev فلا يُرسل إلى جهازك. في وضع التطوير يوجّه القالب روابط الدخول إلى `http://localhost:8788`، وهي نسخة محلية من خدمة الدخول لا يشغّلها أغلب البنّائين، فمستودعها خاص. لذلك يبقى `Astro.locals.user` فارغًا على جهازك. ابنِ الصفحات العامة أولًا، وجرّب تسجيل الدخول بعد النشر على نطاق فرعي من hasanat.dev. ## التطبيقات خارج نطاقات hasanat.dev لا يوجد اليوم تدفق OAuth للتطبيقات الخارجية. الروابط `auth.hasanat.dev/oauth/authorize` و`/oauth/token` غير موجودة، ولا تُصدر معرّفات أو أسرار للعملاء. السطران المعلّقان `HASANAT_CLIENT_ID` و`HASANAT_CLIENT_SECRET` في ملف `.env.example` في القالب لا يُستخدمان. لتستخدم حسابات حسنات في تطبيق خارجي: 1. اعرضه على نطاق فرعي من hasanat.dev إن أمكن، فيعمل تسجيل الدخول المشترك. انظر [النشر والنطاقات الفرعية](/services/deploy-and-subdomains/). 2. أو اطلب «تسجيل دخول لتطبيق خارجي» من [لوحة المنصة](https://platform.hasanat.dev/dashboard)، ويبحث مسؤول الخدمات وضعك معك. ## البيانات والخصوصية يصل تطبيقك من خدمة الدخول: معرّف المستخدم، واسمه، وبريده، وصورته. تحدّد [سياسة البيانات](https://github.com/hasanat-dev/starter/blob/main/DATA_POLICY.md) في القالب ما يجوز: * استخدم المعرّف لربط بيانات المستخدم في تطبيقك، واعرض اسمه وصورته. * لا تحفظ البريد أو الصورة في قاعدتك إلا إن احتاجها التطبيق وأفصحت عن ذلك. * لا تشارك بيانات المستخدمين مع أي طرف آخر، ولا تبعها، ولا تستخدمها للإعلانات. * ضع في التطبيق ملاحظة خصوصية قصيرة يصل إليها المستخدم، ولو رابطًا في التذييل. ## ما لا تفعله * لا تطلب `AUTH_SECRET` أو تنسخه إلى تطبيقك. لا يحتاجه التطبيق، ولا يُرسل في أي طلب. * لا تحفظ كلمات مرور أو رموز دخول أو ملف الجلسة نفسه. * لا تحاول فكّ ملف الجلسة بنفسك: اسأل خدمة الدخول. * لا تضف مزوّد دخول آخر، مثل Firebase Auth أو Clerk، إلى تطبيقات القالب. # قاعدة البيانات > استخدم Cloudflare D1 قاعدةً لبيانات تطبيقك، أنشئها بنفسك أو اطلبها من المنصة. يستخدم قالب حسنات [Cloudflare D1](https://developers.cloudflare.com/d1/)، وهي قاعدة بيانات SQLite تعمل مع Cloudflare. لكل تطبيق قاعدته الخاصة. ## قاعدتك أو قاعدة من حسنات * **في حسابك على Cloudflare:** أنشئ القاعدة بنفسك بالخطوات أدناه. يناسبك هذا إن كنت تنشر التطبيق من حسابك. * **في حساب حسنات:** إن كان تطبيقك سيعمل في حساب حسنات على Cloudflare، فاطلب «قاعدة بيانات» من [لوحة المنصة](https://platform.hasanat.dev/dashboard). ينشئها مسؤول الخدمات ويرسل لك اسمها ومعرّفها في ملاحظة الطلب. الاسم والمعرّف ليسا سرّين، ولا ترسل أي سرّ في الطلب. اتفق معه في الطلب نفسه على من يطبّق تغييرات المخطّط على القاعدة. قاعدة `hasanat-db` المشتركة خاصة بـ hasanat.dev وهذه المنصة، ومخطّطها في مستودع hasanat. لا تستخدمها لتطبيق مشروعك. ## الإعداد في القالب 1. أنشئ القاعدة. يطبع الأمر معرّفها `database_id`: ```sh npx wrangler d1 create your-app-db ``` 2. أضف الربط إلى `wrangler.toml`: ```toml [[d1_databases]] binding = "DB" database_name = "your-app-db" database_id = "paste-your-database-id-here" ``` 3. عدّل `schema.sql` بما يحتاجه تطبيقك. 4. ضع اسم قاعدتك مكان `YOUR_DB_NAME` في أمري `db:migrate:local` و`db:migrate:prod` في `package.json`، ثم طبّق المخطّط على القاعدة المحلية: ```sh npm run db:migrate:local ``` الأمر `npm run db:migrate:prod` يطبّقه على قاعدة الإنتاج. لا تشغّله قبل مراجعة التغيير. ## تغييرات المخطّط بعد الإطلاق ملف `schema.sql` الواحد يكفي في البداية. حين يصبح للقاعدة بيانات حقيقية، احفظ كل تغيير في ملف ترحيل مستقل، ليبقى تاريخ التغييرات واضحًا: ```sh npx wrangler d1 migrations create your-app-db add-items npx wrangler d1 migrations apply your-app-db --local npx wrangler d1 migrations apply your-app-db --remote ``` ## الاستخدام في الكود ```ts import { getDB, queryAll, queryOne, execute } from "@/lib/db"; const db = getDB(Astro.locals); const items = await queryAll(db, "SELECT * FROM items WHERE status = ?", "active"); const item = await queryOne(db, "SELECT * FROM items WHERE id = ?", id); await execute(db, "INSERT INTO items (title_ar, created_by) VALUES (?, ?)", title, user.id); ``` يستخدم القالب Astro 5، فيقرأ الربط من `Astro.locals.runtime.env`. في Astro 6 وما بعده أُزيل `Astro.locals.runtime`، فاستورد `env` من `cloudflare:workers` واستخدم `env.DB`. ## اصطلاحات المخطّط * أعمدة ثنائية اللغة لكل نص يظهر للمستخدم: `title_ar` و`title_en`. * التواريخ نصًّا بالقيمة الافتراضية `datetime('now')`. * قيود `CHECK` لحقول الحالة. * `created_by` نصًّا، ويحمل معرّف المستخدم من [تسجيل الدخول](/services/sign-in/). * فهارس على الأعمدة التي تصفّي بها أو ترتّب بها كثيرًا. ## الأمان * استخدم الاستعلامات ذات المعاملات دائمًا، ولا تدمج مدخلات المستخدم في نص SQL. * تحقّق من المدخلات بـ zod قبل الكتابة. * تأكّد من تسجيل الدخول قبل أي كتابة، ولا تُرجع إلا البيانات التي يحق للمستخدم رؤيتها. * لا تضع في الاختبارات أو البيانات التجريبية أسماء أو أرقامًا حقيقية. ```ts // صحيح: استعلام بمعاملات await db.prepare("SELECT * FROM items WHERE id = ?").bind(id).all(); // خطأ: عرضة لحقن SQL await db.prepare(`SELECT * FROM items WHERE id = ${id}`).all(); ``` ## الحدود بحسب [توثيق Cloudflare](https://developers.cloudflare.com/d1/platform/limits/)، تتيح الخطة المجانية 5 ملايين صف مقروء و100 ألف صف مكتوب يوميًا، و5 غيغابايت تخزينًا للحساب، و500 ميغابايت للقاعدة الواحدة، و10 قواعد للحساب. راجع الصفحة الرسمية لأحدث الأرقام. # النشر والنطاقات الفرعية > انشر تطبيقك على Cloudflare أو أي استضافة، واطلب له نطاقًا فرعيًا مثل name.hasanat.dev. تنشر تطبيقك حيث يناسبك، ثم تطلب له نطاقًا فرعيًا من hasanat.dev إن أردت. يربط مسؤول الخدمات النطاق بالطريقة التي تناسب استضافتك. ## النشر من القالب يستخدم القالب Astro 5 مع Cloudflare Pages: في `wrangler.toml` السطر `pages_build_output_dir = "./dist"`. تحتاج حسابًا على Cloudflare، ثم: ```sh npx wrangler login npm run build npx wrangler pages deploy dist/ ``` * اضبط في `wrangler.toml` اسم المشروع، و`PUBLIC_SITE_URL` و`PUBLIC_APP_NAME` تحت `[vars]`. * لا يحتاج تسجيل الدخول المشترك أي سرّ. إن احتاج تطبيقك سرًّا خاصًا به، فاضبطه بالأمر `npx wrangler pages secret put NAME`، لا في المستودع. * ملف `public/_headers` في القالب يضيف ترويسات أمان أساسية لكل الصفحات. * انشر بعد نجاح `npm run check` و`npm run build` فقط. ## النشر التلقائي من GitHub يمكنك أن تنشر عند كل دمج في الفرع الرئيسي بـ GitHub Actions: .github/workflows/deploy.yml ```yaml name: Deploy on: push: branches: [main] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 22 - run: npm ci - run: npm run build - uses: cloudflare/wrangler-action@v3 with: apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }} command: pages deploy dist/ --project-name=your-app-name ``` احفظ `CLOUDFLARE_API_TOKEN` سرًّا في إعدادات المستودع على GitHub، لا في الكود. ## اطلب نطاقًا فرعيًا اطلب «نطاق فرعي» من [لوحة المنصة](https://platform.hasanat.dev/dashboard) بعد أن يعمل تطبيقك. اكتب في الطلب: * **الاسم المطلوب:** حروف إنجليزية صغيرة وأرقام وشرطات، في مستوى واحد، مثل `your-app.hasanat.dev`. لا يقبل تسجيل الدخول المشترك نطاقًا من مستويين مثل `app.your-app.hasanat.dev`. * **أين يعمل التطبيق:** مشروع Cloudflare Pages أو Worker، وفي أي حساب، أو استضافة أخرى. * **رابطه الحالي:** مثل `your-app.pages.dev`. ## كيف يُربط النطاق ### Worker في حساب حسنات * أنت: لا شيء. * مسؤول الخدمات: يضيف الاسم للـ Worker نطاقًا مخصّصًا (Custom Domain)، فينشئ Cloudflare سجل DNS والشهادة. ### مشروع Pages في حساب حسنات * أنت: لا شيء. * مسؤول الخدمات: يضيف النطاق في إعدادات المشروع، فينشئ Cloudflare سجل DNS. ### مشروع Pages في حسابك * أنت: أضف النطاق أولًا: **Workers & Pages** ← مشروعك ← **Custom domains** ← **Set up a domain**. * مسؤول الخدمات: يضيف سجل CNAME يشير إلى `your-app.pages.dev`. ### استضافة أخرى، مثل Vercel أو Netlify * أنت: أضف النطاق في إعدادات الاستضافة، وانقل إلى الطلب السجلات التي تطلبها. * مسؤول الخدمات: يضيف سجلات DNS كما طلبتها الاستضافة. ### Worker في حسابك على Cloudflare لا يمكن ربطه مباشرة، لأن Cloudflare يشترط أن يكون الـ Worker في الحساب الذي يملك نطاق hasanat.dev. اتفقا في الطلب على النشر على Pages، أو في حساب حسنات. بعد الربط افتح `https://name.hasanat.dev` وتأكّد أن الصفحة تعمل بشهادة صحيحة. إن كان تطبيقك يستخدم تسجيل الدخول المشترك، فجرّبه الآن: لا يعمل على `localhost` ولا على `*.pages.dev` أو `*.workers.dev`. ## الاستضافة خارج Cloudflare لست مضطرًا لاستخدام Cloudflare. انشر تطبيقك على أي منصة، واطلب نطاقًا فرعيًا يشير إليه. يعمل تسجيل الدخول المشترك حين يُعرض التطبيق على النطاق الفرعي من hasanat.dev، إن كان خادم تطبيقك يسأل خدمة الدخول عن الجلسة كما في [تسجيل الدخول](/services/sign-in/). # نظام التصميم > ألوان حسنات وخطّها، وكيف تطبّقها في قالب البداية، ومبادئ التصميم في مشاريعها. هوية حسنات البصرية هادئة وواضحة: زمرّدي على خلفية ورقية دافئة، مع لمسة ذهبية صغيرة، وخط عربي واحد. تستخدمها hasanat.dev وموجزات المشاريع وهذه المنصة. ## الألوان الأساسية | اللون | القيمة | الاستخدام | | --------------- | --------- | -------------------------------- | | الزمرّدي | `#047857` | الأزرار والروابط والحالات النشطة | | الزمرّدي الداكن | `#064e3b` | تمييز قوي للنص، وحالة الضغط | | الذهبي | `#b8860b` | لمسات زخرفية صغيرة فقط، لا للنص | | الورقي | `#f7f5ee` | خلفية الصفحة | | الحبر | `#16271d` | النص الأساسي | تباين الزمرّدي مع الخلفية الورقية نحو 5:1، والنص الأبيض على الزمرّدي نحو 5.5:1، فهما مناسبان للنص. أما الذهبي على الخلفية الورقية فتباينه نحو 3:1 فقط، فلا تكتب به نصًّا. ## ألوان مساندة من ملف تنسيق الموجزات: | اللون | القيمة | الاستخدام | | ------------ | --------- | ---------------------------- | | سطح مرتفع | `#fffefb` | البطاقات والأسطح فوق الخلفية | | نعناعي | `#eef4ec` | خلفيات هادئة للأقسام | | حبر ثانوي | `#3a5446` | النص الثانوي | | خافت | `#526b5e` | الملاحظات والتسميات | | ذهبي فاتح | `#f1d58a` | خلفية تمييز ذهبية | | خط فاصل | `#dde5da` | الفواصل | | خط فاصل أوضح | `#c3d1c5` | الحدود الأوضح | ## الوضع الداكن تستخدم هذه المنصة في الوضع الداكن ألوان الوضع الداكن في موقع حسنات السابق: | اللون | القيمة | الاستخدام | | ------------ | --------- | ---------------------- | | الخلفية | `#08110d` | خلفية الصفحة | | سطح مرتفع | `#0f1d18` | الشريط العلوي والجانبي | | النص الأساسي | `#e8f2ec` | العناوين | | النص | `#a7c6b6` | النص الجاري | | الزمرّدي | `#10b981` | العناصر النشطة | | زمرّدي فاتح | `#8ee0b7` | الروابط | | الذهبي | `#e3b341` | اللمسات الزخرفية | ## الخط الخط **IBM Plex Sans Arabic**، برخصة SIL Open Font License، ويغطي الحروف العربية واللاتينية معًا. تستخدم هذه المنصة الأوزان 400 و600 و700. * استضف الخط مع تطبيقك، مثلًا بالحزمة `@fontsource/ibm-plex-sans-arabic`، بدل تحميله من خدمة خارجية. * اجعل ارتفاع السطر في النص العربي واسعًا: 1.8 في الموجزات، و1.85 في هذه المنصة. * لا تضف تباعدًا بين الحروف في النص العربي، فهو يقطع اتصال الحروف. * لا تستخدم المائل في العربية. الخط لا يحتوي أشكالًا مائلة. ## تطبيقها في قالب البداية ما زال القالب يستخدم لوحة ألوان أقدم (`#0f766e`)، وخطّي Inter وNoto Sans Arabic من Google Fonts. لتطبيق هوية حسنات: 1. ثبّت الخط: ```sh npm install @fontsource/ibm-plex-sans-arabic ``` 2. في أعلى `src/styles/global.css`، استبدل سطر Google Fonts وقيم `@theme`: ```css @import "@fontsource/ibm-plex-sans-arabic/400.css"; @import "@fontsource/ibm-plex-sans-arabic/600.css"; @import "@fontsource/ibm-plex-sans-arabic/700.css"; @import "tailwindcss"; @theme { --color-hasanat: #047857; --color-hasanat-light: #10b981; --color-hasanat-dark: #064e3b; --color-gold: #b8860b; --color-ink: #16271d; --color-surface: #f7f5ee; --color-surface-dark: #08110d; --font-sans: "IBM Plex Sans Arabic", system-ui, sans-serif; } ``` 3. في الطبقة `base` من الملف نفسه، استبدل `text-slate-800` بـ `text-ink`. جرّبنا هذه التعديلات على نسخة من القالب، ونجح البناء. الصنف الجاهز `btn-primary` في القالب يأخذ الزمرّدي تلقائيًا، لأنه مبني على لون `hasanat`. أما `btn-secondary` و`card` فمبنيان على ألوان `slate` والأبيض، فعدّلهما في الملف نفسه إن أردت. ## المبادئ * **العربية أولًا:** الاتجاه من اليمين إلى اليسار هو الأصل. انظر [العربية والاتجاه](/services/arabic-and-rtl/). * **الوضوح قبل الزخرفة:** فعل أساسي واحد في كل صفحة، ونص قصير واضح. * **محتوى حقيقي:** صمّم بنصوص المنتج الحقيقية، لا بنص تجريبي. ولا تضع رموزًا تعبيرية (إيموجي) في الواجهة. * **إمكانية الوصول:** حالات تركيز ظاهرة، وتباين لا يقل عن 4.5:1 للنص العادي، وعمل كامل بلوحة المفاتيح، وتسميات لقارئات الشاشة. * **الجوال أولًا:** افحص كل صفحة على عرض 360 بكسل، ومع تكبير النص إلى 200%. * **الأيقونات:** يستخدم القالب `lucide-react`. أعطِ الأيقونة ذات المعنى اسمًا، وأخفِ الزخرفية عن قارئ الشاشة، واقلب الأسهم الاتجاهية في العربية. * **الوضع الداكن اختياري:** لا يضيفه القالب افتراضيًا. # العربية والاتجاه من اليمين إلى اليسار > كيف تبني واجهة عربية أولًا تعمل بالعربية والإنجليزية، وما الذي تفحصه قبل النشر. مشاريع حسنات عربية أولًا. العربية ليست ترجمة تُضاف في النهاية، والواجهة العربية ليست الواجهة الإنجليزية معكوسة. ## اللغة والاتجاه في HTML * اضبط `lang` و`dir` على عنصر `html`: `lang="ar" dir="rtl"` للعربية، و`lang="en" dir="ltr"` للإنجليزية. يفعل ذلك `Layout.astro` في القالب بحسب لغة الصفحة. * الاتجاه معلومة دلالية في HTML، لا مجرد تنسيق CSS. * للنص الذي يكتبه المستخدم ولا تعرف لغته، استخدم `dir="auto"`، أو العنصر `` للأسماء داخل الجمل. * الروابط والأوامر والأكواد والأرقام اللاتينية داخل نص عربي قد تنقلب مواضعها. ضعها في عنصر بـ `dir="ltr"` أو داخل ``، وجرّبها بنصوص حقيقية. ## الترجمة في القالب يدعم القالب العربية (الافتراضية) والإنجليزية: * الصفحات في `src/pages/ar/` و`src/pages/en/`، والجذر يحوّل إلى `/ar/`. * النصوص في `src/i18n/ar.json` و`src/i18n/en.json`. أضف كل نص جديد إلى الملفين معًا، ولا تكتبه مباشرة في الصفحة. * في `src/i18n/utils.ts`: الدالة `useTranslations(locale)` لجلب النصوص، و`getDirection(locale)` و`isRTL(locale)` للاتجاه، و`getTranslatedPath(path, locale)` لرابط الصفحة نفسها في اللغة الأخرى. ```astro --- import { useTranslations } from "@/i18n/utils"; const t = useTranslations("ar"); ---

{t("hero.title")}

``` ## خصائص CSS المنطقية استخدم الخصائص المنطقية بدل اليسار واليمين، فتعمل الواجهة في الاتجاهين دون تعديل: | لا تستخدم | استخدم | | -------------- | -------------- | | `ml-4` | `ms-4` | | `mr-4` | `me-4` | | `pl-4` | `ps-4` | | `pr-4` | `pe-4` | | `left-0` | `start-0` | | `right-0` | `end-0` | | `text-left` | `text-start` | | `text-right` | `text-end` | | `border-l` | `border-s` | | `border-r` | `border-e` | | `rounded-l-lg` | `rounded-s-lg` | | `rounded-r-lg` | `rounded-e-lg` | وفي CSS العادي: `margin-inline-start` بدل `margin-left`، و`padding-inline-end` بدل `padding-right`، و`inset-inline-start` بدل `left`. ## ما لا ينقلب تلقائيًا * **الأسهم والأيقونات الاتجاهية:** سهم «التالي» يشير إلى اليسار في العربية. اقلبه، ولا تقلب الأيقونات التي لا اتجاه لها. * **ترتيب القراءة:** راجع أن يتبع ترتيب العناصر منطق القراءة العربي، لا أن يكون مرآة شكلية للإنجليزية. * **الأرقام والتواريخ:** اختر تنسيقًا واحدًا واضحًا، وجرّبه مع النص المحيط به. * **الرسوم والصور** التي فيها نص أو اتجاه. ## الخط والكتابة * استخدم خطًا عربيًا واضحًا، مثل IBM Plex Sans Arabic. انظر [نظام التصميم](/services/design-system/). * اجعل ارتفاع السطر واسعًا، ولا تضف تباعدًا بين الحروف العربية. * اكتب بعربية فصيحة بسيطة، وجمل قصيرة، وفكرة واحدة في كل فقرة. * اطلب من متحدث أصلي أن يراجع النصوص في اللغتين، كما في مهمة [مراجعة الترجمة والاتجاه](/start-here/first-week/). النصوص الدينية لا تولّد نصوص القرآن أو الحديث أو الأحكام، ولا تعيد صياغتها ولا تكملها، بيدك أو بوكيل البرمجة. انقلها كما هي من مصدر موثّق تسمّيه المواصفات، والتزم شروط المصدر. انظر [بنك الموارد](/resources/resource-bank/). ## قبل النشر * [ ] كل صفحة لها `lang` و`dir` صحيحان. * [ ] لا خصائص يسار أو يمين في التنسيق، إلا لسبب مقصود. * [ ] تعمل الصفحة على عرض 360 بكسل، ومع تكبير النص إلى 200%. * [ ] جرّبت أسماء وروابط وأرقامًا حقيقية داخل النص العربي. * [ ] الأسهم والأيقونات الاتجاهية صحيحة في اللغتين. * [ ] كل نص موجود في ملفي الترجمة معًا. # أدر تجربة مع مستخدمين حقيقيين > كل مشروع في حسنات ينتهي بتجربة مع مجموعة محدودة من المستخدمين. هكذا تحضّرها وتديرها وتتعلّم منها. ينتهي كل مشروع في حسنات بتجربة حقيقية، لا بإطلاق موقع فقط: مجموعة محدودة من المستخدمين تستعمل النسخة الأولى في حياتها المعتادة، ونتعلّم منها قبل التوسّع. لا ينتقل المشروع إلى «يعمل» قبل أن تتمّ التجربة. ## ابدأ من المواصفات القسم 7 في المواصفات «التجربة الأولى مع مستخدمين حقيقيين» يحدّد أربعة أشياء. اتفق عليها مع الفريق قبل أن تبدأ: * **مع من:** من هم المستخدمون، وكم عددهم. * **كيف:** ماذا سيفعلون، وإلى متى. * **ماذا نقيس:** ما الذي نراقبه، وأين يتوقّف الناس. * **متى تنجح:** الدليل الذي نعدّ به التجربة ناجحة. مثال من مواصفات المقرأة الذكية: مقرأتان أو ثلاث تدير جولاتها المعتادة بالتطبيق 4 أسابيع، ونراقب القرّاء الأكبر سنًا وهم يحجزون دون مساعدة. ## قبل التجربة * **رابط قابل للتجربة:** انشر نسخة تعمل على نطاقها، وتأكّد من المسار الأساسي على هاتف حقيقي. انظر [النشر والنطاقات الفرعية](/services/deploy-and-subdomains/). * **خطة اختبار قصيرة:** المسار الأساسي، والجوال، وإمكانية الوصول، وحالات الخطأ. * **دعوة المختبرين:** حدّد الجمهور، وادعُ مجموعة صغيرة بنفسك أو عبر من يعرفهم من الفريق. * **قناة للملاحظات:** اتفقوا على طريقة بسيطة يصل بها رأي المستخدمين، مثل مجموعة واتساب للتجربة، أو مقابلات قصيرة، أو نموذج. أداة الملاحظات المشتركة متوقفة الآن، فإن احتاجت تجربتكم ملاحظات من داخل التطبيق فاطلبها من [لوحة المنصة](https://platform.hasanat.dev/dashboard) في طلب «غير ذلك». * **الخصوصية:** لا أسماء أو أرقام حقيقية في الاختبارات أو لقطات الشاشة أو ملاحظات التجربة. وضع في التطبيق ملاحظة خصوصية قصيرة. ## أثناء التجربة * راقب المستخدمين وهم يستعملون المنتج دون أن تساعدهم، ودوّن أين يتوقّفون. * اسأل عمّا فعلوه، لا عمّا يتوقّعون أن يفعلوه. * سجّل لكل جلسة: ما نجح، وما أربك المستخدم، وما يجب تغييره. * راجع الملاحظات مع الفريق في اللقاء الأسبوعي، وحوّل كل مشكلة إلى مهمة على GitHub. * أصلح ما يمنع المستخدم من إكمال المسار الأساسي أولًا، وأجّل ما سواه. ## بعد التجربة * قارن النتيجة بمعيار النجاح الذي اتفقتم عليه، واكتب الخلاصة في سطور قليلة. * حدّث المواصفات بما تعلّمتم، في طلب سحب إلى مستودع المشاريع. * حين تتمّ التجربة، ينقل القائد المشروع إلى «يعمل» على hasanat.dev ويضبط رابط المنتج. * راجع [قائمة الإطلاق](/pilot-and-launch/launch-checklist/) قبل أن تعلن المشروع على نطاق أوسع. # قائمة الإطلاق > ما تتحقّق منه قبل أن تعلن مشروعك وتنقله إلى «يعمل». راجع هذه القائمة مع الفريق قبل أن يُعلَن المشروع أو يُدرج في أي مكان. ## المنتج * [ ] الصفحة تشرح فائدتها بالتجربة نفسها، لا بنصوص دعائية. * [ ] المسار الأساسي يعمل من البداية إلى النهاية على هاتف حقيقي. * [ ] حالات التحميل، والقوائم الفارغة، والأخطاء واضحة ومكتوبة بلغة المستخدم. * [ ] النصوص العربية، والإنجليزية إن وُجدت، والبيانات الوصفية للصفحات متّسقة. * [ ] التجربة الأولى تمّت مع مستخدمين حقيقيين، وكُتبت خلاصتها. انظر [أدر تجربة](/pilot-and-launch/run-a-pilot/). ## العربية وإمكانية الوصول * [ ] `lang` و`dir` صحيحان في كل صفحة. * [ ] تعمل الصفحات على عرض 360 بكسل، ومع تكبير النص إلى 200%. * [ ] كل الوظائف تعمل بلوحة المفاتيح، والتركيز ظاهر. * [ ] تباين النص 4.5:1 على الأقل. * [ ] راجعت [العربية والاتجاه](/services/arabic-and-rtl/). ## المحتوى والمصادر * [ ] لا نصوص دينية مولّدة أو معاد صياغتها. كل آية أو حديث منقول كما هو من مصدر موثّق، مع ذكر المصدر. * [ ] رخص البيانات والخطوط والصور محترمة، وذُكرت المصادر حيث تشترط. انظر [بنك الموارد](/resources/resource-bank/). ## البيانات والأمان * [ ] لا أسرار، ولا بيانات شخصية، ولا ملفات بيئة محلية، ولا ملفات بناء في المستودع. * [ ] الاستعلامات بمعاملات، والمدخلات يُتحقّق منها، والكتابة تتطلّب تسجيل الدخول. * [ ] في التطبيق ملاحظة خصوصية يصل إليها المستخدم، كما في [سياسة البيانات](https://github.com/hasanat-dev/starter/blob/main/DATA_POLICY.md) في القالب. ## التقنية * [ ] `npm run check` و`npm run build` ينجحان، أو أوامر المشروع المقابلة. * [ ] النطاق الفرعي يعمل بشهادة صحيحة، وتسجيل الدخول المشترك مجرّب عليه إن استُخدم. * [ ] رابط المستودع ورابط المنتج صحيحان في صفحة المشروع على hasanat.dev. ## الإعلان * [ ] القائد نقل المشروع إلى «يعمل» وضبط رابط المنتج. * [ ] رسالة الإطلاق جاهزة: المشكلة، والفائدة، وطريقة التجربة، في سطور قليلة. * [ ] طلبات الميزات الجديدة توجَّه إلى مهامّ المشروع على GitHub. * [ ] إن أردت أن يجد الناس التطبيق، اطلب إدراجه في [apps.hasanat.dev](/pilot-and-launch/apps-listing/). # الإدراج في apps.hasanat.dev > كيف يصل تطبيقك إلى دليل تطبيقات حسنات، وكيف تُراجع التطبيقات قبل نشرها. [apps.hasanat.dev](https://apps.hasanat.dev) دليل لمن يبحث عن تطبيقات مفيدة. يجمع منتجات من مشاريع تعمل مع مجتمع حسنات، وتطبيقات مستقلة يراجعها القائمون على الدليل. يساعد الدليل الناس على اكتشاف التطبيقات، ولا تستضيف حسنات كل منتج فيه ولا تديره. ## متى تطلب الإدراج بعد أن يصبح مشروعك «يعمل»: تمّت التجربة الأولى، والمنتج متاح على رابط ثابت، وراجعت [قائمة الإطلاق](/pilot-and-launch/launch-checklist/). ## كيف تطلبه اطلب من [لوحة المنصة](https://platform.hasanat.dev/dashboard) طلب «غير ذلك»، واكتب أنك تريد الإدراج في apps.hasanat.dev. اذكر في الطلب: * اسم التطبيق، ورابطه الرسمي. * من يساعد التطبيق، وكيف، في جملتين أو ثلاث. * رابط صفحة المشروع على hasanat.dev. * رابط ملاحظة الخصوصية. ## كيف تتمّ المراجعة بحسب صفحة [«كيف ندرج التطبيقات؟»](https://apps.hasanat.dev/about) في الدليل: * تبقى الاقتراحات خاصة إلى أن يراجع المسؤول المصدر الرسمي، والفائدة، والتكرار، ثم يحرّر المعلومات ويوافق على النشر. لا يُنشر شيء تلقائيًا. * يُبيّن الدليل على كل بطاقة مصدر التطبيق: «من مجتمع حسنات» أو «تطبيق مستقل». * الإدراج ليس اعتمادًا شرعيًا، ولا ضمانًا للأمان أو الخصوصية أو الاستمرار. * يستطيع أي شخص إرسال تصحيح من صفحة التطبيق في الدليل. ## تطبيق لا تملكه إن عرفت تطبيقًا مفيدًا لغيرك، فاقترحه من صفحة [«اقترح تطبيقًا»](https://apps.hasanat.dev/suggest) في الدليل. الاقتراح يذهب إلى قائمة مراجعة خاصة، ولا يمنحك ملكية التطبيق ولا صلاحية إدارته. # بنك الموارد > واجهات وبيانات وخطوط وأدوات منتقاة لبناء منتجات إسلامية موثوقة، مع رخصة كل مورد وتنبيهاته. مكتبة منتقاة من الواجهات والبيانات والخطوط والأدوات التي تدعم بناء منتجات إسلامية موثوقة. لكل مورد طريقة الوصول، والرخصة أو الشروط، وما يجب الانتباه إليه قبل استخدامه. الرخصة ليست تفصيلًا اقرأ رخصة كل مورد وشروطه قبل أن تستخدمه. رخصة الكود لا تعني دائمًا رخصة البيانات أو الخطوط أو الصور التي يعيدها. وانقل النصوص الدينية كما هي من مصدرها، ولا تولّدها ولا تعد صياغتها. راجعنا الروابط والرخص في 13 أكتوبر 2026. إن وجدت رابطًا لا يعمل أو رخصة تغيّرت، أو عرفت موردًا يستحق الإضافة، فاكتب ذلك في مجموعة البنّائين. ## القرآن والتفسير ### [quran-mcp](https://github.com/quran/quran-mcp)نقطة بداية جيدة يوصل وكلاء الذكاء الاصطناعي بنص قرآني موثّق، وترجمات، وتفاسير، وبحث صرفي عبر أدوات منظّمة. **النوع:** MCP · **الوصول:** Remote + self-hosted · **الرخصة أو الشروط:** QFGPL-1.0 **مفيد لـ:** الهندسة والتقنية، المحتوى والمصادر **قبل الاستخدام:** المصدر من مشاريع Quran Foundation؛ انسب النص والتفسير إلى مصدرهما ولا تولّد تفسيرًا بلا سند. رخصة QFGPL تمنع الاستخدام التجاري، وتشترط نشر الكود المعدّل بالرخصة نفسها، وتخصّ البرنامج لا البيانات. ### [QuranHub MCP](https://qurani.ai/en/docs/mcp)نقطة بداية جيدة أدوات للآيات والسور والصفحات والقراءات والصوت والتجويد والخطوط وتخطيطات المصحف. **النوع:** MCP · **الوصول:** Hosted HTTP · **الرخصة أو الشروط:** Terms to verify **مفيد لـ:** الهندسة والتقنية، المحتوى والمصادر **قبل الاستخدام:** الخادم متاح على api.qurani.ai/gw/mcp، لكن تحقّق من شروط إعادة استخدام كل إصدار وصوت وخط قبل الإطلاق. ### [Quran Foundation JavaScript SDK](https://api-docs.quran.foundation/docs/sdk/javascript/)نقطة بداية جيدة الحزمة الرسمية ‎@quranjs/api للوصول إلى المحتوى والبحث من Node وWorkers وتطبيقات الويب. **النوع:** TypeScript SDK · **الوصول:** Client credentials · **الرخصة أو الشروط:** MIT (SDK) **مفيد لـ:** الهندسة والتقنية، المحتوى والمصادر **قبل الاستخدام:** يلزم client_id دائمًا، ويبقى client_secret في الخادم. رخصة SDK لا تعني تلقائيًا ترخيص كل محتوى يعيده API. ### [Tanzil Quran Text](https://tanzil.net/download/) نص قرآني UTF-8 مدقّق بعدة صيغ رسمية للاستخدام في التطبيقات والبحث. **النوع:** Text dataset · **الوصول:** Download · **الرخصة أو الشروط:** CC BY 3.0 + terms **مفيد لـ:** الهندسة والتقنية، المحتوى والمصادر **قبل الاستخدام:** يسمح بنسخ النص كما هو فقط؛ يمنع تغييره، ويجب ذكر Tanzil وربطه وإبقاء إشعار الحقوق. ### [Quranic Arabic Corpus](https://corpus.quran.com/download/) بيانات صرفية ونحوية وشجرية كلمةً بكلمة لبناء البحث اللغوي وأدوات الدراسة. **النوع:** Morphology dataset · **الوصول:** Email-gated download · **الرخصة أو الشروط:** GNU GPL + terms **مفيد لـ:** الهندسة والتقنية، المحتوى والمصادر **قبل الاستخدام:** يجب عرض المصدر والرابط وإبقاء إشعار الحقوق، وتمنع الشروط تغيير ملف البيانات الموزّع. ### [Quran Image Generator](https://github.com/quran/quran.com-images) ينتج صفحات مصحف وصورًا وحدود الحروف لتمييز الكلمات والآيات داخل القارئ. **النوع:** Rendering tool · **الوصول:** Self-hosted · **الرخصة أو الشروط:** GPL code; fonts restricted **مفيد لـ:** الهندسة والتقنية، المحتوى والمصادر **قبل الاستخدام:** الكود GPL، لكن الخطوط والصفحات داخل res/fonts ملك مجمع الملك فهد وتحتاج حقوقًا منفصلة. ## الحديث والمصادر ### [Tafsir.app](https://tafsir.app/) باحث غني في عشرات كتب التفسير واللغة والبلاغة والآثار، مناسب للتحقق واكتشاف المصادر. **النوع:** Research reference · **الوصول:** Web interface · **الرخصة أو الشروط:** No public API license **مفيد لـ:** المحتوى والمصادر، التخطيط والبحث **قبل الاستخدام:** استخدمه مرجعًا بحثيًا؛ لا توجد واجهة API أو رخصة بيانات عامة ظاهرة، فتواصل مع نقاية قبل النسخ البرمجي. ### [Sunnah.com API](https://sunnah.com/developers) وصول إلى الجزء الذي اكتمل تدقيقه يدويًا من بيانات الحديث، مع مشاريع مفتوحة المصدر مساندة. **النوع:** Hadith API · **الوصول:** API key by request · **الرخصة أو الشروط:** Terms to verify **مفيد لـ:** المحتوى والمصادر، التخطيط والبحث **قبل الاستخدام:** اطلب مفتاحًا عبر GitHub؛ التغطية جزئية وتتوسع بعد التدقيق، فتحقّق من شروط البيانات قبل التخزين أو التوزيع. ### [Hadith API](https://github.com/fawazahmed0/hadith-api) ملفات JSON ثابتة متعددة اللغات والدرجات يمكن تثبيت إصدارها أو استضافتها محليًا. **النوع:** Static JSON API · **الوصول:** jsDelivr + download · **الرخصة أو الشروط:** Unlicense (repository) **مفيد لـ:** المحتوى والمصادر، التخطيط والبحث **قبل الاستخدام:** الرخصة تخص المستودع؛ المصادر والطبعات ودرجات الأحاديث متفاوتة، فاحفظ بيانات المصدر واطلب مراجعة علمية. ### [OpenITI Python Library](https://github.com/OpenITI/openiti) أدوات لتنظيف النصوص العربية التراثية وتحويلها وترميزها والبحث فيها وقراءة بيانات OpenITI. **النوع:** Corpus tooling · **الوصول:** Python package · **الرخصة أو الشروط:** MIT (library) **مفيد لـ:** المحتوى والمصادر، التخطيط والبحث **قبل الاستخدام:** رخصة المكتبة لا تشمل تلقائيًا كل نص في المدونات؛ افحص بيانات النسخة والرخصة لكل كتاب. ### [Creative Commons License Chooser](https://creativecommons.org/chooser/) يساعد مالك المحتوى على فهم خيارات الترخيص المفتوح وتوليد إشعار واضح قابل للنشر. **النوع:** Licensing tool · **الوصول:** Open web tool · **الرخصة أو الشروط:** Creative Commons site terms **مفيد لـ:** المحتوى والمصادر، الشراكات والتمويل، التشغيل والاستدامة **قبل الاستخدام:** الأداة ليست استشارة قانونية ولا تمنحك حقوقًا في محتوى الغير؛ تحقّق من الملكية والصلاحيات أولًا. ## العبادات والمواقع ### [Adhan JS](https://github.com/batoulapps/adhan-js)نقطة بداية جيدة حساب مواقيت الصلاة وقيام الليل واتجاه القبلة في المتصفح والخادم مع تعريفات TypeScript. **النوع:** TypeScript library · **الوصول:** npm: adhan · **الرخصة أو الشروط:** MIT **مفيد لـ:** الهندسة والتقنية، المحتوى والمصادر **قبل الاستخدام:** اطلب طريقة الحساب والمذهب وقاعدة خطوط العرض من المستخدم، واعرض الوقت بمنطقة الموقع لا منطقة جهازه. ### [OpenStreetMap Overpass API](https://wiki.openstreetmap.org/wiki/Overpass_API) البحث عن المساجد والمصليات والمراكز الإسلامية وخدمات الإتاحة حسب الموقع والوسوم. **النوع:** Geodata API · **الوصول:** Public endpoints · **الرخصة أو الشروط:** ODbL data; AGPL server **مفيد لـ:** الهندسة والتقنية، المحتوى والمصادر **قبل الاستخدام:** البيانات مجتمعية وقد تكون ناقصة؛ انسب OpenStreetMap، وخزّن النتائج، وعرّف تطبيقك عند استخدام الخوادم العامة. ## العربية والاتجاه ### [Amiri](https://github.com/aliftype/amiri)نقطة بداية جيدة خط نسخي عربي ناضج للنصوص الطويلة والكتب والآيات، مستوحى من مطبعة بولاق. **النوع:** Arabic font · **الوصول:** Font files + source · **الرخصة أو الشروط:** OFL-1.1 **مفيد لـ:** التصميم والتجربة، المحتوى والمصادر، الهندسة والتقنية **قبل الاستخدام:** مناسب للنص والآيات لكنه ليس بديلًا عن نص مصحف موثّق؛ اختبر التشكيل والحجم والارتفاع على الأجهزة. ### [Noto Arabic](https://github.com/notofonts/arabic) عائلات نسخ وكوفي واسعة التغطية للواجهات متعددة اللغات وخطوط الاحتياط. **النوع:** Arabic font family · **الوصول:** Font files + source · **الرخصة أو الشروط:** OFL-1.1 **مفيد لـ:** التصميم والتجربة، المحتوى والمصادر، الهندسة والتقنية **قبل الاستخدام:** يضم المستودع عائلات وأوزانًا كثيرة؛ استضف فقط ما تحتاجه وقلّل ملفات الويب لتحسين الأداء. ### [W3C RTL guidance](https://www.w3.org/International/questions/qa-html-dir) مرجع عملي لاستخدام lang وdir وbdi وdir=auto وخصائص CSS المنطقية في المحتوى العربي المختلط. **النوع:** Implementation guide · **الوصول:** Open web standard · **الرخصة أو الشروط:** W3C document terms **مفيد لـ:** التصميم والتجربة، المحتوى والمصادر، الهندسة والتقنية **قبل الاستخدام:** الاتجاه معلومة دلالية في HTML لا مجرد CSS؛ اختبر الأسماء والروابط والأرقام وعلامات الترقيم الحقيقية. ## الجودة والإتاحة ### [WCAG 2.2](https://www.w3.org/TR/WCAG22/)نقطة بداية جيدة خط أساس قابل للاختبار للإتاحة يشمل لوحة المفاتيح والتباين وإعادة التدفق والتركيز والمصادقة. **النوع:** Accessibility standard · **الوصول:** W3C Recommendation · **الرخصة أو الشروط:** Royalty-free implementation **مفيد لـ:** الاختبار والجودة، التصميم والتجربة، الهندسة والتقنية **قبل الاستخدام:** المطابقة تخص الصفحات والعمليات كاملة، وتحتاج اختبارات بشرية وتقنيات مساندة لا فحصًا آليًا فقط. ### [axe-core](https://github.com/dequelabs/axe-core) فحوص إتاحة آلية داخل Playwright أو المتصفح أو CI مع قواعد WCAG 2.2. **النوع:** Testing engine · **الوصول:** npm: axe-core · **الرخصة أو الشروط:** MPL-2.0 **مفيد لـ:** الاختبار والجودة، التصميم والتجربة، الهندسة والتقنية **قبل الاستخدام:** بحسب مطوّريه يكتشف في المتوسط نحو 57% من مشكلات WCAG؛ أكمل باختبار لوحة المفاتيح وقارئ الشاشة والعربية يدويًا. ### [GOV.UK Service Manual](https://www.gov.uk/service-manual)نقطة بداية جيدة خطوات عملية لفهم المستخدمين، وتحديد الحاجة، وتصميم الخدمة، وقياس النجاح، وتشغيل فرق متعددة التخصصات. **النوع:** Service design guide · **الوصول:** Open web guidance · **الرخصة أو الشروط:** Open Government Licence 3.0 **مفيد لـ:** التخطيط والبحث، التصميم والتجربة، الاختبار والجودة **قبل الاستخدام:** كُتب لخدمات الحكومة البريطانية؛ استعمل المبادئ وعدّل الضوابط والسياق لحاجة المشروع والمجتمع. ### [OWASP Application Security Verification Standard](https://owasp.org/www-project-application-security-verification-standard/) قائمة متدرجة لمتطلبات أمان تطبيقات الويب يمكن تحويلها إلى مهام واختبارات قبل الإطلاق. **النوع:** Security checklist · **الوصول:** Open standard · **الرخصة أو الشروط:** CC BY-SA 4.0 **مفيد لـ:** الهندسة والتقنية، الاختبار والجودة، التشغيل والاستدامة **قبل الاستخدام:** اختر المستوى المناسب للمخاطر؛ اجتياز القائمة لا يغني عن نمذجة التهديد ومراجعة مختص عند الحاجة. ## التصميم والتشغيل ### [Lucide](https://github.com/lucide-icons/lucide) أيقونات SVG متناسقة بحزم رسمية لـ Astro وReact وVue وSvelte وFigma. **النوع:** Icon system · **الوصول:** Framework packages · **الرخصة أو الشروط:** ISC **مفيد لـ:** الهندسة والتقنية، التشغيل والاستدامة، الوصول والمجتمع **قبل الاستخدام:** أضف اسمًا للأيقونة ذات المعنى وأخفِ الزخرفية عن قارئ الشاشة؛ راجع الأسهم الدلالية في RTL. ### [Umami](https://github.com/umami-software/umami) تحليلات ويب ومنتج تركّز على الخصوصية مع أحداث ورحلات ولوحات قابلة للاستضافة الذاتية. **النوع:** Product analytics · **الوصول:** Cloud + self-hosted · **الرخصة أو الشروط:** MIT **مفيد لـ:** الهندسة والتقنية، التشغيل والاستدامة، الوصول والمجتمع **قبل الاستخدام:** الاستضافة الذاتية تحتاج PostgreSQL وتشغيلًا آمنًا؛ ضع سياسة احتفاظ وصلاحيات وإفصاحًا واضحًا للمستخدم. ### [Cloudflare Workers SDK](https://github.com/cloudflare/workers-sdk) تطوير ومحاكاة ونشر تطبيقات Astro على Workers مع D1 وKV وR2 ومعاينات محلية. **النوع:** Edge tooling · **الوصول:** npm: wrangler · **الرخصة أو الشروط:** MIT or Apache-2.0 **مفيد لـ:** الهندسة والتقنية، التشغيل والاستدامة، الوصول والمجتمع **قبل الاستخدام:** ثبّت الإصدارات واختبر على بيئة Workers الفعلية واضبط compatibility_date بحذر لأن تغييرات runtime قد تؤثر في SSR. ### [Google Search Central SEO Starter Guide](https://developers.google.com/search/docs/fundamentals/seo-starter-guide) أساسيات قابلة للتنفيذ لهيكلة المحتوى والروابط والبيانات الوصفية كي يجد الجمهور المنتج عند البحث عن حاجته. **النوع:** Discovery guide · **الوصول:** Open web guidance · **الرخصة أو الشروط:** Google Developers site terms **مفيد لـ:** الوصول والمجتمع، المحتوى والمصادر، الهندسة والتقنية **قبل الاستخدام:** لا تَعِد بترتيب أو زيارات؛ اكتب للمستخدم أولًا وقِس وصولًا حقيقيًا بدل مطاردة مؤشرات شكلية. ### [GitHub Projects documentation](https://docs.github.com/en/issues/planning-and-tracking-with-projects) تنظيم القضايا والمهام والأولويات والحالات في لوحة مرتبطة مباشرة بالمستودع وسير العمل. **النوع:** Project operations guide · **الوصول:** GitHub account · **الرخصة أو الشروط:** GitHub documentation terms **مفيد لـ:** التخطيط والبحث، التشغيل والاستدامة، الهندسة والتقنية **قبل الاستخدام:** أبقِ مهامّ المشروع في مكان واحد؛ لا تنشئ لوحة موازية دون حاجة، واجعل لكل مهمة مالكًا واضحًا. ### [Open Collective documentation](https://documentation.opencollective.com/) مرجع لإدارة ميزانية مجتمعية شفافة، والمصروفات، والمساهمات المالية، والرعاة ضمن كيان مضيف عند الحاجة. **النوع:** Funding operations guide · **الوصول:** Open documentation · **الرخصة أو الشروط:** Repository and site terms **مفيد لـ:** الشراكات والتمويل، التشغيل والاستدامة، الوصول والمجتمع **قبل الاستخدام:** التوفّر والرسوم والالتزامات تختلف حسب البلد والمضيف؛ احسم الحوكمة والمحاسبة قبل جمع الأموال. # دليل مسؤولي الخدمات > كيف ينفّذ مسؤول الخدمات كل نوع من طلبات المنصة، خطوة بخطوة. يرسل البنّاؤون طلبات الخدمات المشتركة من [لوحة المنصة](https://platform.hasanat.dev/dashboard)، وينفّذها مسؤولو الخدمات يدويًا من هذا الدليل. يمنح المسؤول (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، ثم انشره: ```jsonc { "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. تحقّق وأغلق الطلب ```sh curl -sI https://your-app.hasanat.dev ``` * تأكّد أن الصفحة تعمل بشهادة صحيحة. * إن كان التطبيق يستخدم تسجيل الدخول المشترك، فجرّب الدخول والعودة إلى النطاق الجديد. * اكتب الرابط في ملاحظة الطلب، وأغلقه بحالة «تمّ». ## تسجيل دخول لتطبيق خارجي ما يوجد في خدمة الدخول اليوم: * تسجيل الدخول المشترك يعمل فقط للمواقع التي تُعرض على `*.hasanat.dev`، عبر ملف الجلسة المشترك. التفاصيل في [تسجيل الدخول](/services/sign-in/). * لا يوجد تدفق OAuth للتطبيقات الخارجية، ولا تسجيل لتطبيقات عميلة، ولا معرّفات أو أسرار تُصدر لها. * في الخدمة تدفق للتطبيقات المثبّتة على الأجهزة (`/native/*`)، لكنه مربوط في الكود بتطبيق «دايمة» وحده. دعم تطبيق آخر يحتاج تغييرًا في كود الخدمة، وهو في مستودع خاص يملكه المسؤول. كيف تتعامل مع الطلب: 1. اسأل صاحب الطلب: هل يمكن عرض التطبيق على نطاق فرعي من hasanat.dev؟ إن أمكن، فهذا هو الحل: نفّذه طلبَ نطاق فرعي، ودلّه على صفحة [تسجيل الدخول](/services/sign-in/). 2. إن لم يمكن، مثل تطبيق جوال أو نطاق لا بد منه، فاكتب الحاجة في ملاحظة الطلب، وارفعها إلى المسؤول، لأنها تحتاج تغييرًا في خدمة الدخول. لا تعِد بموعد. 3. لا تشارك أسرار خدمة الدخول مع أي تطبيق، مهما كان السبب. ## قاعدة بيانات 1. تأكّد أن التطبيق سيعمل في حساب حسنات على Cloudflare. إن كان صاحب الطلب ينشر من حسابه، فالأسهل أن ينشئ قاعدته بنفسه. دلّه على [قاعدة البيانات](/services/database/)، وأغلق الطلب. 2. سجّل الدخول إلى Wrangler بحساب له صلاحية على حساب حسنات، ثم أنشئ القاعدة باسم المشروع: ```sh npx wrangler login npx wrangler d1 create your-app-db ``` 3. اكتب في ملاحظة الطلب ما يضيفه صاحبه إلى إعداد تطبيقه، مع المعرّف الذي طبعه الأمر: ```toml [[d1_databases]] binding = "DB" database_name = "your-app-db" database_id = "" ``` 4. اتفق مع صاحب الطلب على من يطبّق المخطّط على القاعدة. إن لم تكن له صلاحية على حساب حسنات، فطبّقه أنت من مجلد مستودع المشروع، بعد أن تراجع ملف SQL: ```sh 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](https://developers.cloudflare.com/d1/reference/time-travel/)، فاعرف كيف تعمل قبل أي تغيير كبير. قاعدة `hasanat-db` خاصة بـ hasanat.dev والمنصة، ولا تُستخدم لتطبيقات المشاريع. أي تغيير في مخطّطها يتمّ في مستودع hasanat أولًا. ## إدراج مشروع قائم في hasanat.dev المشاريع القائمة تدخل مشروعًا مباشرة، وصاحبها قائدها. 1. افتح رابط المشروع، وتأكّد أنه يعمل ويخدم حاجة حقيقية، وأن صاحب الطلب صاحبه أو قائده. 2. تأكّد أن للمشروع موجزًا بقالب حسنات. إن لم يوجد، فساعد صاحبه في كتابته من [القالب](/start-a-project/spec-template/). 3. أضف الموجز إلى مستودع المشاريع في مجلد جديد برقم المشروع التالي، في طلب سحب. 4. بعد دمجه، تُنقل نصوص الموجزات إلى hasanat.dev بالأمر `bun run sync:briefs` في مستودع hasanat. إن لم تكن لديك صلاحية تشغيله، فاطلبه ممن يدير hasanat.dev. 5. في صفحة المشرفين على hasanat.dev، عيّن صاحب الطلب قائدًا، واضبط المرحلة: «قيد البناء» أو «يعمل». إن لم تكن مشرفًا، فاطلب ذلك من أحد المشرفين. 6. أرسل لصاحب الطلب رابط صفحة المشروع، وذكّره بأن يفتح الأدوار التي يحتاجها. ## الإدراج في apps.hasanat.dev يعمل [دليل التطبيقات](https://apps.hasanat.dev) على موقع حسنات السابق، وتُراجع فيه الاقتراحات قبل نشرها من صفحة مراجعة خاصة بالمسؤولين. 1. تأكّد أن المشروع «يعمل»، وأن الطلب فيه الرابط الرسمي، ومن يساعد التطبيق وكيف، ورابط ملاحظة الخصوصية. 2. انقل الطلب بهذه المعلومات إلى المسؤول، أو إلى من له صلاحية مراجعة الدليل. 3. بعد انتقال hasanat.dev إلى الموقع الجديد، تأكّد مع المسؤول من طريقة الوصول إلى صفحة المراجعة. ## طلبات أخرى * **ملاحظات من داخل التطبيق:** أداة الملاحظات السابقة متوقفة حتى تحتاجها تجربة حقيقية. إن كان الطلب لتجربة جارية، فارفعه إلى المسؤول مع وصف الحاجة. * **أي خدمة غير مذكورة هنا:** ليست خدمة مشتركة اليوم. اشرح لصاحب الطلب ما الممكن، وارفع الحاجة إلى المسؤول إن تكرّرت، أو اعتذر عن الطلب مع السبب. حين يتكرّر نوع جديد من الطلبات، أضف خطواته إلى هذا الدليل في طلب سحب إلى مستودع المنصة.