فهم فلو MoonStack والـ Staging
هذا الملف ملخص لما قرأته من الـ Knowledge Base وملفات MoonStack وذاكرة المشروع بخصوص طريقة الشغل الصحيحة قبل أي تعديل أو Release.
الخلاصة الملزمة
فهمت أن staging ليس مصدر الكود وليس مكان النشر اليدوي الطبيعي. النسخة الموجودة على
s-elmadina.elbaset.com هي مرآة اختبار بداتا قريبة من اللايف، والمالك هو الذي يحدثها بعد الريليس.
دوري الصحيح: أقرأ الفلو، أصلح في السورس، أوثق، أبني/أختبر على بيئة التطوير، أعمل Git push، وأسجل الـ changelog.
بعد ذلك المالك يعمل MoonStack release/update بنفسه ويجرب على staging.
البيئات ومعنى كل واحدة
| البيئة | الدور | ما المسموح لي به | ما لا أعمله بدون إذن صريح |
|---|---|---|---|
moonui source/dev/home/moonui/public_html/moon-erp/home/moonui/moon-erp-be |
مصدر التطوير والبناء والتجربة على /app. |
أعدل في السورس، أبني Angular، أختبر، أحدث KB وChangelog، وأجهز الشغل للـ Git. | لا أعتبر بناء /app بديل عن Git أو عن MoonStack release. |
GitHub / brancheshazemdev ثم main |
المسار الرسمي للكود بين المطورين والريليس. | الشغل يكون على hazemdev، ثم المالك يراجع/يدمج إلى main للريليس المستقر. |
لا أفترض أن أي تعديل غير معمول له commit/push سيدخل في build-from-git. |
MoonStackmoonstack-release.phpversions.json |
نظام توزيع التحديثات: package موقعة + manifest + updater + rollback. | أسجل release notes وأتأكد أن السورس والبناء جاهزين. | لا أتخطى MoonStack بنسخ ملفات مباشرة للعميل كمسار عادي. |
elmadina stagings-elmadina.elbaset.com/home/selmadina/public_html |
مرآة اختبار بداتا شبيهة باللايف. الـ refresh ينسخ الداتا فقط، وليس الكود. | أفحص وأشخص وأقارن بعد أن يطلب المالك ذلك، خصوصا بعد أن يحدثها هو عبر MoonStack. | لا أعمل cp أو patch أو deploy مباشر على staging إلا لو المالك طلب ذلك صراحة كاستثناء. |
الفلو الصحيح قبل وبعد أي تعديل
- أبدأ بقراءة
knowledge-base/README.mdثمknowledge-base/INDEX.mdثم الموضوع المرتبط، مثل LIS أو MoonStack أو staging. - لو الشغل في الواجهة: أعدل في
/home/moonui/public_html/moon-erp. لو Backend: أعدل في/home/moonui/moon-erp-be. - أحافظ على قواعد المشروع: لا أعمل commit لـ
src/assets/config.json، وبعد deploy محلي للـ/appأرجع config الخاص بالبيئة. - أبني وأختبر في بيئة moonui/dev فقط، مثلا Angular build بـ
npx ng build --base-href /app/عند الحاجة. - أي تغيير user-facing لازم يتسجل في
/home/moonui/moon-erp-be/docs/moonstack/CHANGELOG.mdتحت[Unreleased]بصياغة إنجليزي + عربي. - أي تحليل أو قرار مهم يتوثق في KB، غالبا داخل
knowledge-base/plans/أو topic مناسب. - أعمل commit/push على branch الشغل، غالبا
hazemdev. الدمج إلىmainوالـ release النهائي قرار المالك. - المالك يستخدم MoonStack release page أو CLI لبناء package موقعة وتحديث
versions.json. - المالك يحدث staging أولا، يجرب هناك، ثم يقرر live. بعد تحديث staging قد أساعد في الفحص، لكن لا أغير staging يدويا بدون إذن.
ما فهمته عن MoonStack
- MoonStack لا يسحب من GitHub مباشرة على العميل. العميل يرى
versions.jsonويحمل package موقعة. - الـ package تضم Backend code و
vendorوFrontend dist تحتpublic/app، مع hash وتوقيع. - التحديث يفصل الكود عن الداتا: يحافظ على
.envوstorageوالـ uploads وAPP_KEYوقاعدة البيانات. - الـ updater يعمل backup، maintenance، apply، migrate، cache rebuild، ثم health/finalize، ومع الفشل يرجع rollback.
- في current-server release: Backend يؤخذ من الشجرة الحالية، والواجهة تؤخذ من
/home/moonui/public_html/appبعد build مسبق. - في from-git release: يتم clone للـ ref المطلوب، ثم composer install وAngular build، لذلك لا يدخل إلا العمل committed/pushed.
قواعد الـ Changelog والـ Release Notes
فهمت أن ملف /home/moonui/moon-erp-be/docs/moonstack/CHANGELOG.md هو مصدر "What's new".
صفحة moonstack-release.php تقرأ وتكتب هذا الملف، وmoonstack:ship ينقل محتوى
[Unreleased] إلى نسخة مرقمة ويعرضه للعملاء داخل شاشة Updates.
لذلك أي تعديل يظهر للمستخدم، حتى لو صغير، لازم يتكتب في [Unreleased] قبل الريليس. ولو الملف أو ملفات BE اتعدلت كـ root،
لازم يتراجع موضوع ownership قبل الشحن لأن release يعمل كمستخدم moonui.
مشكلة B2B / ABO كمثال عملي
في مشكلة باركود B2B الخاصة بطلب MRN-011876 والباركود 26070700105، المطلوب الصحيح ليس أن أفتح
/home/selmadina/public_html وأعدل هناك مباشرة. التصرف الصحيح من الآن:
- أشخص الفرق بين شاشة المعمل الداخلية
/app/lab/requestsوبوابة الشريك/app/external-lab-portal/requests. - أرجع للسورس في FE/BE على moonui وأحدد هل المشكلة في إعدادات label أو endpoint أو portal session scope.
- أصلح في السورس فقط، وأضيف/أحدث تقرير HTML في KB يشرح السبب والأثر.
- أضيف release note في changelog يشرح للمستخدم أن بوابة B2B صارت تطبع اسم التحليل مثل الداخلي.
- أعمل build/test محلي على moonui عند الحاجة، ثم commit/push.
- المالك يعمل MoonStack release/update على staging، وبعدها نتحقق أن ABO ظهر في بورتال B2B كما يظهر داخليا.
الخطأ الذي يجب ألا يتكرر
أي تعديل مباشر على /home/selmadina/public_html أو نسخ build مباشر إلى staging يتخطى GitHub وMoonStack والـ changelog والـ rollback/signature،
ويخلق drift: staging يصبح مختلفا عن السورس وعن الـ package التي ستصل للعميل. هذا ليس الفلو الطبيعي للمشروع.
القاعدة الجديدة عندي: no cp / no patch to clients or staging إلا بأمر واضح من المالك، ومع توثيق أنه استثناء وليس مسار release.
مراجع قرأتها
knowledge-base/README.mdوknowledge-base/INDEX.mdknowledge-base/topics/dev-workflow.mdknowledge-base/topics/moonstack-update.mdknowledge-base/topics/staging-mirror.mdknowledge-base/plans/moonstack-release-update-flow.htmlknowledge-base/plans/moonstack-plan.htmlknowledge-base/plans/moonstack-docroot-ready-plan.html/home/moonui/public_html/moon-erp/CLAUDE.md/home/moonui/public_html/moonstack-release.php/home/moonui/moon-erp-be/docs/moonstack/CHANGELOG.md
تعهد التشغيل من الآن
قبل أي تعديل قادم سأتعامل مع moonui كسورس وبناء، GitHub كمسار رسمي، MoonStack كوسيلة التوزيع، وstaging كمكان اختبار يحدّثه المالك. لو احتجت أفحص staging سأفعل ذلك كتشخيص فقط، ولن أغيره يدويا إلا لو الطلب قال ذلك صراحة.