14 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).

۲. خطوط قرمز سراسری و مدیریت گردش کار (Workflow & Git Guardrails)

محدوده صریح تسک (Strict Scope): تغییرات باید دقیقاً محدود به همان ماژول یا تسک محول‌شده باشند. از دستکاری، ریفکتور ناخواسته یا تغییر فایل‌های نامرتبط اکیداً خودداری شود. تغییرات همواره باید به صورت جراحی موضعی (Surgical Fixes) انجام شوند.
اطلاع‌رسانی و اخذ تأیید قبل از تغییرات ساختاری یا کلان (Architectural Guardrail): هرگونه تغییر بزرگ (Big Changes)، دستکاری در ساختار معماری، تغییر در ساختار لایه‌بندی کامپوننت‌ها یا روت‌های پنل مدیریت، اکیداً ممنوع است مگر اینکه ابتدا جزئیات تغییر به صورت شفاف به کاربر اطلاع داده شده و تأیید صریح کاربر اخذ گردد.
ممنوعیت مطلق خروج از برنچ فعلی گیت بدون تأیید صریح کاربر (Git Branch Guardrail):
- به هیچ عنوان و تحت هیچ شرایطی، دستیار هوش مصنوعی حق تعویض شاخه (git checkout یا git switch)، ادغام شاخه‌ها (git merge)، پوش روی سایر برنچ‌ها، یا خروج از برنچ فعلی مخزن را بدون اخذ اجازه و تأیید صریح کاربر ندارد.
- کلیه اقدامات و تغییرات باید منحصراً روی همان برنچی که کاربر پروژه را روی آن تحویل داده یا مشخص کرده انجام شود.
قوانین نگارش متون و اصلاح جهت متن (RTL Formatting):
- کلیه پاسخ‌ها و توضیحات متنی فارسی باید داخل بلوک <div dir="rtl"> قرار گیرند تا جهت پایه متن همیشه RTL بماند.
- اصطلاحات انگلیسی، کدها و نام فایل‌ها باید از پرانتزها و علائم نگارشی فارسی ایزوله شوند تا چینش متنی برعکس نشود.
ترجمه اصطلاحات و کلمات خاص مذهبی و فرهنگی (Religious & Cultural Terminology):
- اصل آوانویسی (Transliteration): اصطلاحات مذهبی نظیر حسینیه، صلات و... نباید به صورت تفسیری ترجمه شوند؛ بلکه باید با حفظ تلفظ اصلی و آوانویسی با الفبای زبان مقصد درج شوند.

۳. سیستم طراحی و استانداردهای بصری پنل (UI Design System & Typography)

مرجع الزامی و بدون استثنا: کلیه تغییرات بصری، طراحی صفحات جدید، کامپوننت‌ها، فرم‌ها، فیلترها، جداول، تگ‌ها و وضعیت‌های لودینگ در پنل مدیریت باید کاملاً و بدون استثنا مطابق با سند مرجع guide/aqila_panel_ui_design_system_standard.md پیاده‌سازی شوند.
اصول کلیدی پنل:
1. پالت خنثی و مینیمال (پرهیز قطعی از رابط کاربری مدادرنگی / Crayon-like): بیش از ۹۰٪ رابط کاربری از رنگ‌های خنثی (slate, card, border-soft, muted) تشکیل شود. رنگ‌های تند و اشباع صرفاً برای وضعیت‌های معنایی (Success: سبز، Warning: زرد/امبر، Error: قرمز/رز) رزرو شوند.
2. تایپوگرافی چندزبانه: استفاده از فونت استاندارد Vazirmatn برای متون فارسی/عربی، Inter یا Plus Jakarta Sans برای انگلیسی، و منحصراً font-mono برای ارقام مالی، شناسه‌ها (#1024)، مقادیر جدول و کدها.
3. استاندارد واحد لودینگ (Shimmer): تمام صفحات دارای لودینگ باید از کامپوننت استاندارد Shimmer با پالت خنثی اسلیت (#E2E8F0 / #22252C) و انیمیشن پالس استفاده کنند.
4. سیستم فاصله‌گذاری و گوشه‌ها: پدینگ افقی استاندارد ۱۶ پیکسل (p-4 یا p-6)، فواصل مضرب ۴ و ۸، و گوشه‌های گرد استاندارد (rounded-xl برای دکمه‌ها و فیلدها، rounded-2xl برای کارت‌ها و جداول).
5. کنتراست و دسترسی‌پذیری: رعایت کامل استاندارد WCAG AA در هر دو حالت Light Mode و Dark Mode و پرهیز از متن خاکستری ناخوانا روی پس‌زمینه‌های تیره یا روشن.

۴. استانداردهای توسعه رابط کاربری و محلی‌سازی (Localization & i18n)

فناوری و ساختار: پروژه بر پایه 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) با ترجمه حرفه‌ای و بومی اعمال شود تا تست اعتبارسنجی npm run check:i18n و هوک پیش از کامیت (pre-commit) کاملاً پاس شود و هیچ کلید ناقص، خالی یا نامتقارنی باقی نماند.
- تقارن کامل تغییرات کلمات (Word Modification Parity): هر زمان کلمه‌ای در یک متن تغییر کند یا کلماتی حذف شوند، باید همان تغییر مفهومی بلافاصله در هر ۳ فایل اعمال گردد (مطابق قانون اختصاصی .agents/rules/translation_synchronization.md).
استاندارد سراسری نمایش و انتخاب دوگانه تاریخ میلادی و قمری با نام ماه (Mandatory Dual Gregorian + Hijri Date Standard):
- در تمامی بخش‌ها، جداول، مودال‌ها، کارت‌ها و فرم‌های پنل مدیریت (aqila_panel)، کلیه تاریخ‌ها باید به‌صورت همزمان میلادی و هجری قمری (ام‌القری) همراه با ذکر نام ماه (مشابه بخش سفر انتخابی / Custom Trip) نمایش داده شوند:
  - در زبان فارسی (fa): نوامبر 2، 2026 (جمادی‌الاول 22، 1448)
  - در زبان عربی (ar): نوفمبر 2، 2026 (جمادى الأولى 22، 1448 هـ)
  - در زبان انگلیسی (en): November 2, 2026 (Jumada al-Awwal 22, 1448 AH)
- برای نمایش هرگونه تاریخ یا زمان در پنل، استفاده از toLocaleDateString خام یا نمایش تک‌تقویمی (صرفاً شمسی یا صرفاً عددی YYYY-MM-DD) ممنوع است و باید منحصراً از توابع استاندارد formatDualDate، formatDateByLanguage، formatDateRangeByLanguage و formatDateTimeByLanguage در src/lib/date-utils.ts استفاده شود.
- برای کلیه فیلدهای انتخاب تاریخ در فرم‌ها و دیالوگ‌ها، استفاده از <input type="date"> بومی مرورگر ممنوع بوده و باید منحصراً از کامپوننت <UniversalDatePicker> با allowedModes={['islamic', 'gregorian']} استفاده گردد.

۵. همگام‌سازی فول‌استک سامانه و پایگاه داده (Full-Stack Sync & DB Integrity)

تغییرات پنل در مدیریت تورها، کاربران، کاتالوگ‌ها و تراکنش‌ها باید مستقیماً با مدل‌ها و مایگریشن‌های بک‌اند و دیتابیس هماهنگ باشد.
هیچ فیلد یا دیتای جدیدی نباید در حالت ماک باقی بماند.

۶. اسکیل‌های فعال ایجنت (Active Project Skills)

در مسیر .agents/skills/ این پروژه اسکیل‌های زیر برای هدایت خودکار هوش مصنوعی مستقر هستند:

safe-web-builder: ساخت خودکار و یکپارچه‌سازی کامپوننت‌ها و ویژگی‌های وب در مخزن.
universal-safe-fixer: رفع جراحی باگ‌ها با حداقل تغییر کد و تضمین عدم بروز رگرسیون.
critical-reset-debugger: شکستن حلقه‌های خطای تکراری و بازبینی کامل فرضیات معماری.

۷. بررسی الزامی سلامت و ران بودن پنل مدیریت پس از هر تغییر کد (Mandatory Runtime Check & Zero Breakage)

در انتهای هر پاسخ، تسک یا پیامی که در آن کدی ایجاد یا تغییر داده می‌شود:

شرط اختصاصی اعمال (صرفاً پس از تغییر کد - عدم اعمال در چت‌های عادی): این بررسی و هرگونه اعتبارسنجی سلامت ران‌تایم، صرفاً و منحصراً در پیام‌ها و تسک‌هایی که کدی در آن ویرایش یا ایجاد شده باشد اعمال می‌شود. در چت‌ها و پیام‌های عادی که تغییری در کدها داده نشده است، اجرای این بررسی‌ها اکیداً لازم نیست.
بررسی سریع و بلادرنگ ران بودن پنل مدیریت (Immediate Runtime & Health Check):
- بلافاصله بررسی شود که تغییرات در کامپوننت‌ها، هوک‌ها، تایپ‌ها یا استایل‌ها باعث خطای کامپایل TypeScript، خطای بیلد Vite یا کرش داشبورد نشده باشد.
- سلامت ران بودن با بررسی تایپ‌ها (npm run typecheck / tsc --noEmit) یا وضعیت سرور Vite تضمین شود.
اصل بازیابی فوری و خودکار (Instant Self-Healing):
- در صورتی که تغییر کد باعث بروز هرگونه خطا، شکست کامپایل یا توقف ران بودن پنل شود، ایجنت موظف است فوراً منشأ ارور را شناسایی و اصلاح کند تا پنل مدیریت مجدداً در حالت ران، کاملاً سالم و پایدار قرار گیرد.

14 KiB Raw Blame History