calculff

Imported from mohamed09090-xmd/calculff (AGENTS.md). Install upstream with npx skills add mohamed09090-xmd/calculff. Copyright stays with the author.

AGENTS.md — CalculFF Engineering Governance

1. هوية المشروع

• اسم المشروع: CalculFF / Game Credit Profit Manager.
• التقنية الأساسية: Flutter + Dart + SQLite.
• يحتوي المستودع على منصة اختيارية معتمدة مبنية على Supabase لخدمة المنصة الإدارية وتطبيق الزبائن.
• معرّف Android المحمي هو com.gm0h1.gamecreditmanager، ولا يجوز تغييره دون موافقة صريحة.
• يجب قراءة رقم الإصدار الفعلي دائمًا من pubspec.yaml، ولا يجوز الاعتماد على رقم محفوظ في محادثة أو تقرير قديم.

2. مصدر الحقيقة

• مستودع GitHub mohamed09090-xmd/calculff وفرع main هما مصدر الحقيقة.
• قبل أي تخطيط أو تنفيذ، افحص آخر commit، والفروع ذات الصلة، وPull Requests المفتوحة، وGitHub Actions، والملفات المرتبطة بالمهمة.
• لا تعتمد على تقارير، محادثات، خطط، نسب إنجاز، أو فروع قديمة عندما تتعارض مع الحالة الحالية في main.
• لا تكرر تغييرًا موجودًا بالفعل، ولا تسقط تغييرات حديثة عند إنشاء فرع جديد.

3. الفحص الإجباري قبل كل مهمة

قبل بدء أي تعديل:

1. اقرأ هذا الملف AGENTS.md كاملًا.
2. اقرأ README.md وpubspec.yaml.
3. اقرأ workflows المرتبطة بالمهمة داخل .github/workflows/.
4. افحص الملفات والاختبارات والمهاجرات المتعلقة بالنطاق.
5. حدّد السبب الحقيقي للمشكلة والنطاق الأدنى الآمن.
6. تحقق من عدم وجود تنفيذ سابق للمهمة في main أو PR مفتوحة أو فرع ذي صلة.
7. سجّل أي مشكلة خارج النطاق بدل إصلاحها تلقائيًا.

4. أدوار المحادثات

محادثة المخطط

• تحدد الأولويات والاعتماديات وترتيب التنفيذ.
• توزع المهام وتكتب برومتات الفحص والتنفيذ والإصلاح.
• تراجع التقارير وPull Requests ونتائج CI.
• لا تنفذ تغييرات على المستودع إلا بطلب صريح ومنفصل يغيّر دورها إلى التنفيذ.

محادثة التنفيذ

• تنفذ مهمة واحدة أو مهمتين مترابطتين كحد أقصى.
• تستخدم فرعًا واحدًا وPull Request واحدًا للمهمة.
• لا توسع النطاق من تلقاء نفسها.
• تسجل المشكلات الخارجة عن النطاق في تقرير PR والتقرير النهائي دون إصلاحها.
• لا تعتبر المهمة مكتملة قبل انتهاء دورة التحقق والدمج وما بعد الدمج المطلوبة.

5. العمل المتوازي

• يسمح بمحادثتين متوازيتين فقط عندما تكون المهام مستقلة فعليًا.
• يجب تحديد ملكية الملفات والمسارات لكل فرع قبل بدء العمل.
• يمنع تعديل المسارات نفسها أو الملفات المتداخلة في فرعين متوازيين.
• لا يبدأ فرع يعتمد على ناتج فرع آخر قبل دمج الفرع الأول وإعادة فحص main.
• يمنع force push أو أي إعادة كتابة خطرة للتاريخ.
• بعد كل دمج، أعد فحص رأس main وPRs وActions قبل بدء العمل التالي.

6. معمارية Flutter

• عدّل المشروع الحالي؛ لا تعِد بناءه من الصفر.
• حافظ على Feature-first architecture.
• لا تضع منطق الأعمال أو الوصول إلى البيانات داخل Widgets.
• استخدم طبقات application وdomain وinfrastructure وpresentation عندما يلائم ذلك حدود الميزة الحالية.
• عدّل أقل عدد ممكن من الملفات لتحقيق الهدف بأمان.
• لا تضف dependency جديدة عندما يوجد حل سليم وقابل للصيانة بالمكتبات الحالية.
• حافظ على العقود والاختبارات المعمارية الموجودة ولا تتجاوزها بحلول مختصرة داخل الواجهة.

7. التطبيق المحلي والمنصة

• تطبيق CalculFF المحلي يعمل أساسًا باستخدام SQLite، ويجب أن تبقى وظائفه المحلية مستقلة وقابلة للعمل دون إعداد Supabase.
• Supabase يخدم المنصة الإدارية وتطبيق الزبائن.
• Supabase الحالي جزء مصرح به ومعتمد من المشروع؛ لا يجوز حذفه أو معاملته كخدمة خارجية غير معتمدة.
• لا تخلط بين اكتمال التطبيق المحلي وتقدم توسعة المنصة.
• نسب تقدم المنصة متغيرة ولا تُكتب كحقيقة ثابتة داخل AGENTS.md.
• أي نسبة تقدم يجب أن تكون مبنية على رأس main الحالي، وأن تذكر صراحة أنها تخص CalculFF Platform + تطبيق الزبائن، وأن تحفظ في وثيقة حالة مشروع مخصصة لا في قواعد الحوكمة.

8. SQLite وحماية البيانات

• لا تحذف بيانات المستخدم.
• لا تكسر النسخ الاحتياطية القديمة أو تغير صيغتها دون خطة توافق واختبارات.
• حافظ على التوافق الخلفي مع قواعد البيانات والنسخ الاحتياطية المدعومة.
• استخدم SQLite migrations واضحة، متسلسلة، وقابلة للاختبار.
• امنع migrations المدمرة أو إعادة إنشاء الجداول دون ضرورة مثبتة وموافقة صريحة.
• اختبر ترقية قواعد البيانات القديمة إلى الإصدار الحالي.
• اختبر الاستيراد والتصدير، والتحقق من النسخة، والتراجع الآمن عند الفشل.
• أي حذف بيانات أو migration غير متوافقة يحتاج موافقة المستخدم قبل الدمج، حتى لو نجحت الاختبارات.

9. Supabase

• بعد تطبيق migration على أي بيئة مستضافة، تصبح migrations forward-only.
• لا تعدّل أو تحذف أو تعيد تسمية أو ترتب أو تسحق migration مطبقة.
• نفّذ الإصلاحات بواسطة migration جديدة ومراجعة.
• حافظ على RLS والصلاحيات والخصوصية والعقود الضيقة للـRPC وStorage.
• يمنع استخدام service_role أو أي مفتاح إداري داخل تطبيق Flutter.
• يمنع كشف المسارات الخاصة أو مفاتيح الإدارة أو الأسرار أو بيانات الاعتماد في الكود أو السجلات أو Artifacts.
• لا تنفذ عملية على Hosted Supabase دون طلب أو تفويض صريح ومحدد.
• وجود migration في المستودع لا يعني أنها مطبقة على Hosted Supabase؛ تحقق من حالة التطبيق الفعلية قبل أي ادعاء أو متابعة.

10. الخدمات الخارجية

• لا تضف Firebase أو Analytics أو Backend جديدًا أو خدمة سحابية أو اتصالًا بجهة خارجية دون طلب صريح.
• لا تغيّر بنية منصة Supabase الحالية من تلقاء نفسك.
• لا تجمع بيانات إضافية دون حاجة موثقة ونطاق واضح ومراجعة خصوصية.
• لا تضف telemetry أو تتبعًا صامتًا أو اتصالًا شبكيًا غير مطلوب.

11. Android والتوقيع

• لا تغيّر Package ID: com.gm0h1.gamecreditmanager.
• لا تغيّر مفاتيح التوقيع أو alias أو كلمات المرور أو مسار keystore دون موافقة صريحة.
• لا تضف إلى المستودع .env أو android/key.properties أو ملفات .jks أو أي ملفات keystore.
• لا تطبع قيم الأسرار أو بيانات التوقيع أو محتوى GitHub Secrets.
• لا تستبدل إعدادات التوقيع أو تنشئ مفتاحًا جديدًا دون مهمة منفصلة وموافقة صريحة.

12. اللغات وتجربة الاستخدام

• حافظ على العربية RTL والفرنسية LTR.
• ادعم النص المختلط واتجاه الحقول الحساسة مثل الأرقام والمعرفات والبريد.
• ادعم الشاشات الصغيرة والخطوط الكبيرة دون قص أو overflow.
• حافظ على Semantics وإمكانية الوصول وترتيب التنقل المنطقي.
• لا تعتمد على اللون وحده لإيصال الحالة أو النجاح أو الخطأ.
• اختبر حالات التحميل والفراغ والفشل وإعادة المحاولة في الواجهات المتأثرة.

13. الفروع وPull Requests

• استخدم فرعًا مستقلًا لكل مهمة.
• أنشئ commits صغيرة ومنطقية ذات رسائل واضحة.
• راجع git diff قبل كل commit.
• أنشئ Draft Pull Request أولًا.
• يجب أن يشرح وصف PR السبب، والنطاق، والملفات، والاختبارات، والمخاطر، وفحص الأسرار، وطريقة التراجع.
• لا تحوّل PR إلى Ready for review قبل نجاح الفحوص المطلوبة ومراجعة changed files كاملة.

14. التحقق الإجباري

نفّذ ما يناسب المهمة، ولا تدّع نجاح أي أمر لم يُشغّل فعليًا.

الأوامر الأساسية:

dart format --output=none --set-exit-if-changed .
flutter analyze
flutter test
flutter test --coverage

عند تأثر Supabase:

python3 scripts/validate_supabase_tests.py
supabase db reset --local
supabase db lint --local --level error --fail-on error
supabase test db --local
python3 supabase/tests/storage/payment_proofs_storage_test.py

استخدم صيغة الأوامر المثبتة في workflows والوثائق الحالية إذا تغيرت واجهة Supabase CLI.

عند مرحلة البناء:

flutter build apk --release
flutter build appbundle --release

15. مراجعة التغييرات والأمان

قبل كل commit وقبل الدمج:

git status --short
git diff --check

• راجع diff كاملًا وchanged files.
• تأكد من عدم وجود ملفات أو إصلاحات غير مرتبطة بالمهمة.
• افحص الأسرار وملفات التوقيع والبيانات الحساسة.
• لا تعطل أو تتخطى أو تخفف اختبارًا لإخفاء مشكلة.
• لا تفسر غياب فحص على أنه نجاح.

16. سياسة الدمج التلقائي

للمستخدم إذن دائم بأن تدمج محادثة التنفيذ Pull Request الذي أنشأته دون طلب موافقة إضافية بعد تحقق جميع الشروط التالية:

• المهمة ضمن النطاق المطلوب.
• التنسيق ناجح.
• flutter analyze ناجح.
• الاختبارات المطلوبة ناجحة.
• GitHub Actions المطلوبة ناجحة.
• PR قابل للدمج ولا يحتوي conflicts.
• diff وchanged files مراجعان.
• لا توجد أسرار أو ملفات توقيع.
• لا توجد تغييرات غير مرتبطة.
• لا توجد اختبارات معطلة أو متخطاة لإخفاء مشكلة.

إذا كانت ميزة GitHub native auto-merge غير مفعلة، فالمقصود هو:

1. تحويل Draft PR إلى Ready for review.
2. تنفيذ الدمج بواسطة محادثة التنفيذ.
3. استخدام merge commit فقط.
4. عدم استخدام squash أو rebase.
5. مراقبة Actions الناتجة بعد الدمج.

17. استثناءات الدمج التلقائي

توقف واطلب موافقة المستخدم قبل الدمج فقط إذا كان التغيير يتضمن:

• حذف بيانات المستخدم.
• migration غير متوافقة مع البيانات الحالية.
• تغيير Package ID.
• تغيير مفاتيح التوقيع.
• حذف ميزة أساسية.
• إضافة خدمة سحابية أو طرف ثالث جديد.
• تغييرًا ماليًا جوهريًا في حساب الأرباح.
• النشر إلى Google Play.
• إنشاء GitHub Release عام.

18. ما بعد الدمج

عندما يشغّل main بناء Android:

• راقب التنسيق والتحليل والاختبارات حتى النهاية.
• تحقق من إنشاء APK وAAB المطلوبين.
• تحقق من توقيع APK وAAB.
• تحقق من SHA-256.
• افحص Artifacts ومحتوياتها وأسماءها وحالة انتهاء صلاحيتها.
• لا تعتبر المهمة مكتملة عند وجود فشل غير محلول؛ أصلح السبب الحقيقي داخل فرع hotfix منفصل إذا كان ضمن التفويض.

19. Gmail

• GitHub وسجلات GitHub Actions هما مصدر الحقيقة للـCI.
• يمكن استخدام Gmail فقط لقراءة إشعارات GitHub عند الحاجة.
• يمنع إرسال أو حذف أو أرشفة أو تعديل رسائل Gmail ضمن مهام المشروع.
• لا تعتمد على Gmail بدل سجلات Actions أو تفاصيل jobs والـArtifacts.

20. التقرير النهائي

ابدأ بالنتيجة واستخدم الرموز التالية حسب الحالة:

• ✅ ناجح
• ❌ فاشل
• ⚠️ تحذير
• 🔧 إصلاح
• 🧪 اختبار
• 📦 Artifact
• 🔐 أمان
• 🚀 GitHub
• ↩️ تراجع

يجب أن يذكر التقرير، حسب ما ينطبق:

• النتيجة النهائية والسبب الجذري.
• ما تم والملفات المنشأة والمعدلة والمنقولة والمحذوفة.
• اسم الفرع.
• commits مع SHA مختصر.
• رابط Pull Request وحالة الدمج.
• نتيجة format وflutter analyze.
• عدد اختبارات Flutter الناجحة والفاشلة.
• حالة GitHub Actions وروابط runs.
• نتيجة APK وAAB والتوقيع وSHA-256.
• روابط Artifacts النهائية.
• نتيجة فحص الأسرار.
• القيود والمشكلات الخارجة عن النطاق.
• طريقة التراجع.
• طريقة تجربة التطبيق على الهاتف أولًا عندما ينتج ملف Android جديد.

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