7.1 KiB

Raw Blame History

Admin Panel Agent Rules & Guidelines - Aqila (پنل مدیریت عقیله)

این سند شامل قوانین، استانداردها، اصول مهندسی الزامی و خطوط قرمز سراسری برای توسعه بخش پنل مدیریت ادمین (aqila_panel) است. کلیه دستورات سراسری سامانه عقیله و خطوط قرمز پنل مدیریت باید به صورت کامل اطاعت شوند.

۱. استقرار منحصراً درون سورس کد و همکاری تیمی (Strict In-Source Agent Rule)

ممنوعیت مطلق ایجاد فایل/پوشه خارج از سورس: هیچ پوشه یا فایل ایجنتی تحت هیچ شرایطی نباید در بیرون از این پروژه یا در روت‌های بالادستی ایجاد شود. کلیه دستورالعمل‌ها، تنظیمات و قوانین ایجنت باید منحصراً در فایل AGENTS.md و پوشه .agents/ درون همین مخزن سورس کد قرار گیرد.
همکاری چندنفره و همگام‌سازی گیت: با توجه به کار کردن چندین توسعه‌دهنده روی پروژه، تمام فایل‌های ایجنت باید درون مخزن گیت قرار داشته باشند تا با هر git pull روی تمام سیستم‌های تیم بدون نقص همگام شوند.
اعتبار سراسری دستورات: هر قانونی که برای سامانه عقیله یا رفتار ایجنت تعریف می‌شود، در تمامی پوشه‌ها و پروژه‌ها (بک‌اند، فرانت‌اند وب، اپ فلاتر، پنل مدیریت) صادق است و باید به طور مجزا و دقیق در این مخزن خوانده و اطاعت شود.
تشخیص و استقرار خودکار قوانین جدید در تمام بخش‌های لازم (Automatic Rule Propagation): هر زمان قانون جدیدی تعریف، آموخته یا تصویب شود، ایجنت موظف است به‌صورت خودکار و بدون نیاز به تذکر کاربر تشخیص دهد کدام بخش‌های دیگر سامانه (فلاتر، فرانت‌اند وب، بک‌اند) به این قانون نیاز دارند و آن را متناسب با نیاز هر بخش فوراً در فایل‌های راهنمای همان پروژه مستقر کند (مطابق با .agents/rules/automatic_rule_propagation.md).

۲. استانداردهای توسعه رابط کاربری و معماری

فناوری و ساختار: پروژه بر پایه Vite + React + TypeScript توسعه یافته است.
تایپوگرافی و جهت متن (RTL/LTR): رعایت فونت‌های Vazirmatn و Plus Jakarta Sans، استفاده از rtlUtils.ts جهت تشخیص خودکار جهت متن ورودی کاربران و حفظ ثبات کرسر (unicode-bidi: plaintext !important; text-align: start !important;).
چندزبانه بودن کامل، صفر متن هاردکد و همگام‌سازی صددرصدی (۳ زبان): پنل مدیریت منحصراً از ۳ زبان (fa فارسی، ar عربی، en انگلیسی) در مسیر src/locales/ استفاده می‌کند.
- ممنوعیت مطلق متن هاردکد: تمام متون جدول‌ها، ستون‌ها، فیلدها، دکمه‌ها، نشان‌ها، پیام‌های مودال و نوتیفیکیشن‌ها باید منحصراً از طریق useTranslation فراخوانی شوند.
- همگام‌سازی همزمان در هر ۳ زبان: هر کلید جدید یا اصلاح‌شده در یکی از این ۳ زبان باید الزماً و همزمان در دو زبان دیگر (fa.json, ar.json, en.json) با ترجمه حرفه‌ای و بومی اعمال شود تا تست اعتبارسنجی locales.test.ts کاملاً پاس شود و هیچ کلید ناقص، خالی یا نامتقارنی باقی نماند.
- تقارن کامل تغییرات کلمات (Word Modification Parity): هر زمان کلمه‌ای در یک متن تغییر کند، کلماتی حذف شوند (مانند حذف لیست فرمت‌های مجاز یا کوتاه‌سازی برچسب‌ها) یا به متنی اضافه شوند، باید همان تغییر مفهومی و گرامری بلافاصله در هر ۳ فایل اعمال گردد و قرار دادن متن انگلیسی به عنوان موقت در زبان‌های فارسی یا عربی اکیداً ممنوع است (مطابق قانون اختصاصی .agents/rules/translation_synchronization.md).

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