# قوانین Modal در ویراوان ادمین

این سند قرارداد سراسری Modal برای تمام پنل‌ها، دموها و Seller Panel است.

## قواعد اجباری

1. هر عملیات ایجاد/افزودن/ثبت رکورد از CTA اصلی باید Modal باز کند؛ صفحه مستقل Add مسیر اصلی نیست.
2. صفحه جزئیات می‌تواند مستقل باشد. ویرایش در اولویت باید همان فرم Modal ایجاد را با `initialData` استفاده کند.
3. هر Modal عملیاتی باید Permission داشته باشد؛ کلید پیشنهادی `action:<page>:create|edit|delete|approve|export` است.
4. فرم‌های صنفی باید فیلدهای واقعی همان کسب‌وکار را داشته باشند، نه فرم عمومی ۲ یا ۳ فیلدی.
5. فرم بلند باید Section، `more`، Tab یا Stepper داشته باشد. اطلاعات پیشرفته در حالت عادی نباید فرم را شلوغ کنند.
6. تمام Modalها باید عنوان، توضیح کوتاه، بستن، انصراف و Submit واضح داشته باشند.
7. Validation کنار فیلد و در Summary داخلی نمایش داده شود؛ استفاده از `alert()` ممنوع است.
8. Submit باید Loading داشته باشد و Double Submit مسدود شود.
9. بستن فرم Dirty باید Confirm داخلی نشان دهد.
10. Escape، Focus Trap و Return Focus اجباری‌اند.
11. در عرض <= 820px فرم‌های بزرگ Full Screen هستند و Body به‌صورت داخلی Scroll می‌شود؛ Header/Footer باید در دسترس بمانند.
12. پس از Submit موفق، رکورد نمونه بدون Refresh در List/Table قابل مشاهده باشد یا نتیجه عملیاتی واضح ثبت شود.
13. Edit و Duplicate، در صورت وجود List Runtime، همان Modal را با داده از قبل پرشده باز می‌کنند.
14. Role فعال باید هم نمایش CTA و هم فراخوانی مستقیم Modal را کنترل کند؛ مخفی‌کردن دکمه به‌تنهایی امنیت UI محسوب نمی‌شود.
15. Seller Panel namespace، Role و Permission مستقل از Admin Marketplace دارد.

## اندازه‌ها

- `sm`: تأییدها و فرم‌های بسیار کوتاه.
- `md`: فرم کوتاه تا متوسط.
- `lg`: فرم تخصصی چندبخشی.
- `xl`: Stepper، محصول، فروشنده، قرارداد و فرم‌های پیچیده.

## رفتار موبایل

Modal در موبایل تمام عرض/ارتفاع قابل استفاده را می‌گیرد. `form` داخل Modal یک Flex Column است، Body دارای `min-height:0` و Scroll داخلی است و Footer خارج از Body باقی می‌ماند. جدول‌های پیچیده باید به Card/Accordion یا Container قابل Scroll تبدیل شوند؛ Variation محصول در موبایل به Card تبدیل شده است.

## قواعد محتوا

- Label فارسی روشن و کوتاه.
- Placeholder واقعی مثل «مثلاً فروشگاه مرکزی» به‌جای Lorem Ipsum.
- مقدار پیش‌فرض فقط وقتی منطقی است.
- وضعیت‌ها با Badge معنی‌دار نمایش داده شوند.
- فیلدهای مالی قبل از Submit Summary زنده داشته باشند.
- فیلدهای شرطی فقط وقتی شرط مرتبط برقرار است نمایش داده شوند.

## فایل‌های مرجع

- `core/js/modal-runtime.js`
- `core/css/modal-rbac.css`
- `core/js/rbac.js`
- `core/js/common-modal-forms.js`
- `core/js/industry-modal-forms.js`
- `industries/01-ecommerce/assets/js/ecommerce-modal-forms.js`