# معماری Marketplace چندفروشندگی ویراشاپ

## هدف

ویراشاپ دو تجربه مستقل دارد: **پنل مدیر Marketplace** برای کنترل شبکه فروشندگان و **Seller Panel** برای عملیات روزانه هر فروشنده. هر دو از هسته مشترک Modal و RBAC ویراوان استفاده می‌کنند، اما Namespace داده، منو، Roleها و Scope دسترسی آن‌ها مستقل است.

## تفکیک Admin و Seller Panel

- مدیر Marketplace همه فروشندگان، درخواست‌های احراز، محصولات در انتظار بررسی، سفارش‌های مادر، قوانین کمیسیون، تسویه‌ها، اختلافات و تخلفات را می‌بیند.
- Seller Panel فقط فروشگاه‌ها/شعب مجاز همان حساب فروشنده را نمایش می‌دهد.
- تغییر فروشگاه فعال در Seller Panel باعث Scope شدن ردیف‌های محصول، سفارش، مشتری، موجودی و گزارش مالی می‌شود.
- لینک رفت‌وبرگشت بین پنل مدیر و Seller Panel وجود دارد، ولی Role و Permission مشترک نیست.

## Roleهای Seller

| Role | دامنه اصلی |
|---|---|
| Seller Owner | دسترسی کامل حساب فروشندگی و همه فروشگاه‌های مجاز |
| Seller Manager | عملیات روزمره به‌جز تنظیمات مالک |
| Seller Product Manager | محصول، قیمت، تخفیف و موجودی محصول؛ بدون تسویه |
| Seller Order Manager | سفارش، بسته‌بندی، ارسال و مرجوعی |
| Seller Warehouse Staff | انبار، موجودی، بسته‌بندی و ارسال |
| Seller Finance | درآمد، کمیسیون، کیف پول، فاکتور و تسویه؛ بدون ویرایش محصول |
| Seller Support | مشتریان مجاز، تیکت و مشاهده سفارش |

تمام Roleها در صفحه «نقش‌ها و دسترسی‌ها» قابل مشاهده‌اند و Permissionهای `page:*` و `action:*` روی منو، صفحه و Modal اعمال می‌شوند.

## جریان پذیرش فروشنده

1. مدیر Modal شش‌مرحله‌ای «افزودن فروشنده» را باز می‌کند.
2. هویت حقیقی/حقوقی، مالک/نماینده و اطلاعات تماس ثبت می‌شود.
3. برند فروشگاه، لوگو/کاور، دسته فعالیت، استان/شهر و آدرس تکمیل می‌شود.
4. اطلاعات بانکی، شبا، کف/سقف و دوره تسویه ثبت می‌شود.
5. مدارک هویتی/حقوقی/بانکی بارگذاری می‌شوند.
6. مدل کمیسیون و درصد یا مبلغ پایه تعیین می‌شود.
7. درخواست در صف احراز قرار می‌گیرد و مدیر می‌تواند تأیید، رد یا درخواست اصلاح ثبت کند.
8. در صورت نیاز، حساب با دلیل و مدت مشخص تعلیق می‌شود.

## جریان محصول فروشنده

Seller از همان موتور محصول مدیر استفاده می‌کند؛ بنابراین محصول ساده و متغیر از یک هسته ساخته می‌شوند. در Seller Panel فیلد انتخاب فروشنده حذف شده و فروشگاه فعال Scope محصول را مشخص می‌کند.

وضعیت‌ها:

`پیش‌نویس → در انتظار تأیید → منتشرشده`

در صورت ایراد:

`در انتظار تأیید → نیازمند اصلاح → ارسال مجدد → در انتظار تأیید`

یا:

`در انتظار تأیید → ردشده`

مدیر Marketplace در صف بررسی می‌تواند محصول ساده یا متغیر، SKU و Variationها را کنترل کند، تأیید/رد/درخواست اصلاح ثبت کند و در صورت لزوم محصول فروشنده را غیرفعال کند. تاریخچه تصمیم‌ها در UI نگه داشته می‌شود.

## محصول متغیر

- Attributeهای متعدد قابل انتخاب‌اند.
- ترکیب Variationها خودکار تولید می‌شود.
- هر Variation دارای SKU، تصویر، قیمت، قیمت ویژه، موجودی، حد هشدار، ابعاد، وزن، انبار و وضعیت مستقل است.
- Bulk Edit قیمت/موجودی/وزن وجود دارد.
- SKU در Scope فروشگاه فروشنده کنترل می‌شود.

## سفارش چندفروشندگی

یک سفارش مادر Marketplace می‌تواند چند `Sub-order` داشته باشد. هر Sub-order به یک فروشنده تعلق دارد و موارد زیر مستقل هستند:

- اقلام و تعداد
- سهم فروش فروشنده
- کمیسیون
- وضعیت پردازش
- بسته‌بندی
- روش ارسال و هزینه ارسال
- مرسوله و شماره رهگیری
- لغو بخشی
- مرجوعی بخشی
- بازپرداخت بخشی

در Seller Panel فقط Sub-orderهای متعلق به فروشگاه فعال نمایش داده می‌شوند. تغییر مالی یک Sub-order نباید مانده سایر فروشندگان سفارش مادر را تغییر دهد.

## کمیسیون

قانون کمیسیون می‌تواند درصدی، ثابت یا ترکیبی باشد و بر اساس محصول، فروشنده یا دسته تعریف شود. هر قانون بازه زمانی و اولویت دارد. ترتیب نمونه اعمال Rule:

`محصول خاص → فروشنده خاص → دسته خاص → قانون عمومی`

کمیسیون بر پایه سهم همان فروشنده از سفارش محاسبه می‌شود.

## کیف پول و تسویه

کیف پول Seller چهار مانده اصلی دارد: کل، در انتظار آزادسازی، قابل تسویه و مسدود. درخواست تسویه فقط از موجودی قابل تسویه انجام می‌شود و حداقل مبلغ و حساب بانکی تأییدشده در Modal نمایش داده می‌شوند.

در پنل مدیر، تسویه شامل فروش ناخالص، مرجوعی، کمیسیون، سایر کسورات، مبلغ قابل تسویه، شبا، وضعیت، شماره پیگیری بانکی و فایل رسید است. مرجوعی/بازپرداخت بخشی فقط سهم همان فروشنده را اصلاح می‌کند.

## انبار و موجودی

هر فروشنده انبارهای مستقل دارد. موجودی محصول ساده و هر Variation به تفکیک انبار نمایش داده می‌شود. رزرو سفارش، حد هشدار، اصلاح موجودی با علت و تاریخچه گردش وجود دارد.

## Role & Permission

- Namespace مدیر و Seller جداست.
- مدیر پلتفرم از Roleهای فروشندگی استفاده نمی‌کند.
- Seller Finance به ویرایش محصول دسترسی پیش‌فرض ندارد.
- Seller Product Manager به تسویه دسترسی پیش‌فرض ندارد.
- Seller Order Manager فقط سفارش و عملیات مرتبط را می‌بیند.
- Modal بدون Permission باز نمی‌شود.
- ورود مستقیم به صفحه بدون `page:<id>` به Access Denied تبدیل می‌شود.

## QA

اجرای کنترل‌های مرتبط:

```bash
python tools/qa_marketplace_seller.py
python tools/qa_ecommerce_modal.py
python tools/qa_modal_rbac.py
python tools/qa_static.py
```

گزارش‌های JSON در پوشه `docs/` ذخیره می‌شوند.