5.5 KiB

Raw Blame History

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