diff --git a/.agents/AGENTS.md b/.agents/AGENTS.md index b8047fc..49687ce 100644 --- a/.agents/AGENTS.md +++ b/.agents/AGENTS.md @@ -1,21 +1,34 @@ # Admin Panel Agent Rules & Guidelines - Aqila (پنل مدیریت عقیله) -این سند شامل قوانین، استانداردها و اصول مهندسی الزامی برای توسعه بخش پنل مدیریت ادمین (`aqila_panel`) است. +این سند شامل قوانین، استانداردها، اصول مهندسی الزامی و خطوط قرمز سراسری برای توسعه بخش پنل مدیریت ادمین (`aqila_panel`) است. کلیه دستورات سراسری سامانه عقیله و خطوط قرمز پنل مدیریت باید به صورت کامل اطاعت شوند. --- -## ۱. استانداردهای توسعه رابط کاربری و معماری +## ۱. استقرار منحصراً درون سورس کد و همکاری تیمی (Strict In-Source Agent Rule) +- **ممنوعیت مطلق ایجاد فایل/پوشه خارج از سورس:** هیچ پوشه یا فایل ایجنتی تحت هیچ شرایطی نباید در بیرون از این پروژه یا در روت‌های بالادستی ایجاد شود. کلیه دستورالعمل‌ها، تنظیمات و قوانین ایجنت باید منحصراً در فایل `AGENTS.md` و پوشه `.agents/` درون همین مخزن سورس کد قرار گیرد. +- **همکاری چندنفره و همگام‌سازی گیت:** با توجه به کار کردن چندین توسعه‌دهنده روی پروژه، تمام فایل‌های ایجنت باید درون مخزن گیت قرار داشته باشند تا با هر `git pull` روی تمام سیستم‌های تیم بدون نقص همگام شوند. +- **اعتبار سراسری دستورات:** هر قانونی که برای سامانه عقیله یا رفتار ایجنت تعریف می‌شود، در تمامی پوشه‌ها و پروژه‌ها (بک‌اند، فرانت‌اند وب، اپ فلاتر، پنل مدیریت) صادق است و باید به طور مجزا و دقیق در این مخزن خوانده و اطاعت شود. + +--- + +## ۲. استانداردهای توسعه رابط کاربری و معماری - **فناوری و ساختار:** پروژه بر پایه Vite + React + TypeScript توسعه یافته است. -- **تایپوگرافی و جهت متن (RTL/LTR):** رعایت فونت‌های `Vazirmatn` و `Plus Jakarta Sans`، استفاده از `rtlUtils.ts` جهت تشخیص خودکار جهت متن ورودی کاربران و حفظ ثبات کرسر. +- **تایپوگرافی و جهت متن (RTL/LTR):** رعایت فونت‌های `Vazirmatn` و `Plus Jakarta Sans`، استفاده از `rtlUtils.ts` جهت تشخیص خودکار جهت متن ورودی کاربران و حفظ ثبات کرسر (`unicode-bidi: plaintext !important; text-align: start !important;`). - **چندزبانه بودن کامل پنل مدیریت (۳ زبان):** پنل مدیریت منحصراً از ۳ زبان (`fa` فارسی، `ar` عربی، `en` انگلیسی) در مسیر `src/locales/` استفاده می‌کند. تمام متون جدول‌ها، فیلدها، دکمه‌ها و نشان‌ها باید در هر ۳ فایل دیکشنری زبان (`fa.json`, `ar.json`, `en.json`) تعریف و همگام شوند. - **قانون هماهنگی ترجمه:** هیچ تغییری نباید تک‌زبانه باشد؛ هر کلید جدید یا اصلاح‌شده در یکی از این ۳ زبان باید همزمان در دو زبان دیگر اعمال شود تا تست `locales.test.ts` کاملاً پاس شود و هیچ کلید ناقص یا نامتعادلی وجود نداشته باشد. --- -## ۲. بررسی الزامی سلامت و ران بودن پروژه پس از هر تغییر کد (Mandatory Runtime Check) +## ۳. همگام‌سازی فول‌استک سامانه و پایگاه داده (Full-Stack Sync & DB Integrity) +- تغییرات پنل در مدیریت تورها، کاربران، کاتالوگ‌ها و تراکنش‌ها باید مستقیماً با مدل‌ها و مایگریشن‌های بک‌اند و دیتابیس هماهنگ باشد. +- هیچ فیلد یا دیتای جدیدی نباید در حالت ماک باقی بماند. + +--- + +## ۴. بررسی الزامی سلامت و ران بودن پنل مدیریت پس از هر تغییر کد (Mandatory Runtime Check & Zero Breakage) در انتهای هر پاسخ، تسک یا پیامی که در آن کدی ایجاد یا تغییر داده می‌شود: - **بررسی سریع و بلادرنگ ران بودن پنل مدیریت (Immediate Runtime & Health Check):** - بلافاصله بررسی شود که تغییرات در کامپوننت‌ها، هوک‌ها، تایپ‌ها یا استایل‌ها باعث خطای کامپایل TypeScript، خطای بیلد Vite یا کرش داشبورد نشده باشد. - سلامت ران بودن با بررسی تایپ‌ها (`npm run typecheck` / `tsc --noEmit`) یا وضعیت سرور Vite تضمین شود. -- **رفع فوری مشکل تا بازگشت به وضعیت ران (Self-Healing & Auto-Fix):** - - در صورتی که تغییر کد باعث بروز هرگونه خطا، شکست کامپایل یا توقف ران بودن پنل شود، بلافاصله باید منشأ ارور شناسایی و اصلاح گردد تا پنل مدیریت مجدداً در حالت ران، سالم و پایدار قرار گیرد. +- **اصل بازیابی فوری و خودکار (Instant Self-Healing):** + - در صورتی که تغییر کد باعث بروز هرگونه خطا، شکست کامپایل یا توقف ران بودن پنل شود، ایجنت موظف است فوراً منشأ ارور را شناسایی و اصلاح کند تا پنل مدیریت مجدداً در حالت ران، کاملاً سالم و پایدار قرار گیرد. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..49687ce --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,34 @@ +# Admin Panel Agent Rules & Guidelines - Aqila (پنل مدیریت عقیله) + +این سند شامل قوانین، استانداردها، اصول مهندسی الزامی و خطوط قرمز سراسری برای توسعه بخش پنل مدیریت ادمین (`aqila_panel`) است. کلیه دستورات سراسری سامانه عقیله و خطوط قرمز پنل مدیریت باید به صورت کامل اطاعت شوند. + +--- + +## ۱. استقرار منحصراً درون سورس کد و همکاری تیمی (Strict In-Source Agent Rule) +- **ممنوعیت مطلق ایجاد فایل/پوشه خارج از سورس:** هیچ پوشه یا فایل ایجنتی تحت هیچ شرایطی نباید در بیرون از این پروژه یا در روت‌های بالادستی ایجاد شود. کلیه دستورالعمل‌ها، تنظیمات و قوانین ایجنت باید منحصراً در فایل `AGENTS.md` و پوشه `.agents/` درون همین مخزن سورس کد قرار گیرد. +- **همکاری چندنفره و همگام‌سازی گیت:** با توجه به کار کردن چندین توسعه‌دهنده روی پروژه، تمام فایل‌های ایجنت باید درون مخزن گیت قرار داشته باشند تا با هر `git pull` روی تمام سیستم‌های تیم بدون نقص همگام شوند. +- **اعتبار سراسری دستورات:** هر قانونی که برای سامانه عقیله یا رفتار ایجنت تعریف می‌شود، در تمامی پوشه‌ها و پروژه‌ها (بک‌اند، فرانت‌اند وب، اپ فلاتر، پنل مدیریت) صادق است و باید به طور مجزا و دقیق در این مخزن خوانده و اطاعت شود. + +--- + +## ۲. استانداردهای توسعه رابط کاربری و معماری +- **فناوری و ساختار:** پروژه بر پایه Vite + React + TypeScript توسعه یافته است. +- **تایپوگرافی و جهت متن (RTL/LTR):** رعایت فونت‌های `Vazirmatn` و `Plus Jakarta Sans`، استفاده از `rtlUtils.ts` جهت تشخیص خودکار جهت متن ورودی کاربران و حفظ ثبات کرسر (`unicode-bidi: plaintext !important; text-align: start !important;`). +- **چندزبانه بودن کامل پنل مدیریت (۳ زبان):** پنل مدیریت منحصراً از ۳ زبان (`fa` فارسی، `ar` عربی، `en` انگلیسی) در مسیر `src/locales/` استفاده می‌کند. تمام متون جدول‌ها، فیلدها، دکمه‌ها و نشان‌ها باید در هر ۳ فایل دیکشنری زبان (`fa.json`, `ar.json`, `en.json`) تعریف و همگام شوند. + - **قانون هماهنگی ترجمه:** هیچ تغییری نباید تک‌زبانه باشد؛ هر کلید جدید یا اصلاح‌شده در یکی از این ۳ زبان باید همزمان در دو زبان دیگر اعمال شود تا تست `locales.test.ts` کاملاً پاس شود و هیچ کلید ناقص یا نامتعادلی وجود نداشته باشد. + +--- + +## ۳. همگام‌سازی فول‌استک سامانه و پایگاه داده (Full-Stack Sync & DB Integrity) +- تغییرات پنل در مدیریت تورها، کاربران، کاتالوگ‌ها و تراکنش‌ها باید مستقیماً با مدل‌ها و مایگریشن‌های بک‌اند و دیتابیس هماهنگ باشد. +- هیچ فیلد یا دیتای جدیدی نباید در حالت ماک باقی بماند. + +--- + +## ۴. بررسی الزامی سلامت و ران بودن پنل مدیریت پس از هر تغییر کد (Mandatory Runtime Check & Zero Breakage) +در انتهای هر پاسخ، تسک یا پیامی که در آن کدی ایجاد یا تغییر داده می‌شود: +- **بررسی سریع و بلادرنگ ران بودن پنل مدیریت (Immediate Runtime & Health Check):** + - بلافاصله بررسی شود که تغییرات در کامپوننت‌ها، هوک‌ها، تایپ‌ها یا استایل‌ها باعث خطای کامپایل TypeScript، خطای بیلد Vite یا کرش داشبورد نشده باشد. + - سلامت ران بودن با بررسی تایپ‌ها (`npm run typecheck` / `tsc --noEmit`) یا وضعیت سرور Vite تضمین شود. +- **اصل بازیابی فوری و خودکار (Instant Self-Healing):** + - در صورتی که تغییر کد باعث بروز هرگونه خطا، شکست کامپایل یا توقف ران بودن پنل شود، ایجنت موظف است فوراً منشأ ارور را شناسایی و اصلاح کند تا پنل مدیریت مجدداً در حالت ران، کاملاً سالم و پایدار قرار گیرد.