# 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):**
  - در صورتی که تغییر کد باعث بروز هرگونه خطا، شکست کامپایل یا توقف ران بودن پنل شود، ایجنت موظف است فوراً منشأ ارور را شناسایی و اصلاح کند تا پنل مدیریت مجدداً در حالت ران، کاملاً سالم و پایدار قرار گیرد.