Seyyed_arc/docs/QUICK_SALES_PAYMENT_DOCK.md

# نوار پرداخت سریع فروش

## هدف

این قابلیت ورود پرداخت‌های یک فاکتور فروش سریع را به نوار پایین صفحه منتقل می‌کند. کاربر می‌تواند مبلغ فاکتور را بین چند صندوق، حساب بانکی یا شخص تقسیم کند و هر پرداخت به‌صورت یک ردیف مستقل ثبت می‌شود.

## رفتار رابط کاربری

- فیلد «مبلغ پرداخت» در شروع، مانده فعلی فاکتور را نشان می‌دهد و قابل ویرایش است.
- فشردن یک دکمه پرداخت، مبلغ داخل فیلد را به مقصد همان دکمه اضافه می‌کند.
- پس از افزودن پرداخت، فیلد مبلغ با مانده جدید به‌روزرسانی می‌شود.
- پرداخت‌های ثبت‌شده در یک فهرست مستقل و اسکرول‌دار نمایش داده می‌شوند. مبلغ هر ردیف قابل ویرایش و خود ردیف قابل حذف است.
- هر ردیف پرداخت، آیکون متناسب با نوع مقصد، تاریخ و ساعت ثبت و دکمه حذف قرمز دارد.
- کاربر می‌تواند مرز بین فضای دکمه‌ها و فهرست پرداخت‌ها را با ماوس جابه‌جا کند. عرض انتخاب‌شده برای همان کاربر و کسب‌وکار در مرورگر ذخیره می‌شود. دوبار کلیک روی مرز، عرض پیش‌فرض را برمی‌گرداند و کلیدهای جهت نیز مرز را حرکت می‌دهند.
- خلاصه فاکتور و دکمه‌های «ثبت» و «ثبت و چاپ» در پایین سمت چپ ثابت هستند. پنل سمت راست شامل مبلغ، دکمه‌ها و فهرست پرداخت‌ها با فلش جمع یا باز می‌شود تا در حالت جمع‌شده فضای بیشتری به فهرست کالاها برسد. وضعیت انتخاب‌شده برای همان کاربر و کسب‌وکار در مرورگر ذخیره می‌شود.
- «جزئیات سند» و بخش «شرح سند» در ستون سمت چپ به‌صورت پیش‌فرض باز هستند.
- جمع پرداخت‌ها اگر از مبلغ فاکتور بیشتر شود، مبلغ اضافه‌دریافت با رنگ خطا نمایش داده می‌شود. با انتخاب آن، پنجره «تعیین تکلیف اضافه‌دریافت» باز می‌شود. خود فیلد مبلغ در این حالت صفر می‌ماند.
- ثبت فاکتور بدون هیچ پرداختی، پس از تأیید کاربر، کل مبلغ را بدهی مشتری ثبت می‌کند.

## دکمه‌های پرداخت

هر دکمه یکی از این مقصدها را دارد:

1. صندوق
2. حساب بانکی
3. شخص

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

دکمه می‌تواند شخصی یا مشترک باشد. دکمه شخصی فقط برای سازنده دیده می‌شود. ایجاد، ویرایش، حذف و تغییر ترتیب دکمه مشترک به دسترسی تنظیمات کسب‌وکار نیاز دارد.

میانبرهای مجاز شامل `F1` تا `F12` به‌جز `F5` و ترکیب‌هایی مانند `Alt+1` یا `Ctrl+Shift+K` هستند. میانبرهای رزروشده فروش سریع و مرورگر پذیرفته نمی‌شوند و یک میانبر مؤثر نمی‌تواند برای دو دکمه تکرار شود.

اگر هنوز هیچ دکمه‌ای تعریف نشده باشد و در تنظیمات فروش سریع صندوق پیش‌فرض وجود داشته باشد، یک دکمه سیستمی موقت برای همان صندوق نمایش داده می‌شود. با تعریف اولین دکمه، چیدمان تعریف‌شده کاربر جای آن را می‌گیرد.

## مدل داده و مهاجرت

جدول `quick_sales_payment_buttons` توسط migration زیر ساخته می‌شود:

`20261013_000001_quick_sales_payment_buttons`

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

این جدول همراه کد در Git منتقل می‌شود. پس از دریافت شاخه، اجرای migrationهای Alembic جدول را در محیط مقصد ایجاد می‌کند؛ انتقال دستی SQL لازم نیست.

## API

- `GET /api/v1/businesses/{business_id}/quick-sales/payment-buttons`
- `POST /api/v1/businesses/{business_id}/quick-sales/payment-buttons`
- `PUT /api/v1/businesses/{business_id}/quick-sales/payment-buttons/reorder`
- `PUT /api/v1/businesses/{business_id}/quick-sales/payment-buttons/{button_id}`
- `DELETE /api/v1/businesses/{business_id}/quick-sales/payment-buttons/{button_id}`

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

## تعیین تکلیف و ثبت حسابداری اضافه‌دریافت

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

1. **صندوق:** صندوق فعال و هم‌ارز فاکتور انتخاب می‌شود.
2. **بانک:** حساب بانکی فعال و هم‌ارز فاکتور همراه مبلغ کارمزد اختیاری انتخاب می‌شود.
3. **شخص:** هر شخص متعلق به کسب‌وکار به‌جز خود مشتری فاکتور قابل انتخاب است. حساب دریافتنی `10401` او به مبلغ برگشتی بستانکار می‌شود؛ بنابراین ممکن است بدهی او کاهش یابد یا شخص از کسب‌وکار طلبکار شود.
4. **بستانکاری مشتری:** تمام یا بخشی از مبلغ به مشتری برگردانده نمی‌شود و به‌عنوان بستانکاری او باقی می‌ماند. زدن دکمه ثبت با وجود اضافه‌دریافت همیشه پنجره تعیین تکلیف را باز می‌کند. کاربر می‌تواند برای مشتری مشخص «ادامه بدون تعیین تکلیف» را بزند تا تمام اضافه‌دریافت به بستانکاری همان مشتری منتقل شود. این گزینه برای مشتری ناشناس نمایش داده نمی‌شود.

جمع مبالغ برگشتی و بستانکاری باید دقیقاً برابر اضافه‌دریافت باشد. کارمزد بانک جزو مبلغ دریافتی مشتری نیست و جداگانه محاسبه می‌شود.

در یک تراکنش دیتابیس این عملیات انجام می‌شود:

1. فاکتور فروش ثبت می‌شود.
2. برای هر ردیف پرداخت، سند دریافت مستقل ساخته می‌شود.
3. برای مجموع مبلغی که واقعاً برگردانده شده، یک سند پرداخت با تمام منابع انتخاب‌شده ساخته می‌شود.
4. شناسه سند برگشت وجه جدا از اسناد دریافت در `extra_info.links.quick_sale_change_payment_document_id` ذخیره می‌شود.

ثبت‌های منبع وجه چنین هستند:

- صندوق: حساب صندوق به مبلغ برگشتی بستانکار می‌شود.
- بانک: حساب بانک به اندازه «مبلغ برگشتی + کارمزد» بستانکار و حساب `70902` با عنوان «کارمزد خدمات بانکی» به مبلغ کارمزد بدهکار می‌شود.
- شخص: حساب دریافتنی اشخاص `10401` برای شخص پرداخت‌کننده بستانکار می‌شود. اگر مانده قبلی او بدهکار باشد، بدهی کاهش می‌یابد؛ اگر مبلغ برگشت بیشتر از بدهی باشد، شخص به همان میزان از کسب‌وکار طلبکار می‌شود.
- مشتری: حساب دریافتنی مشتری فقط به اندازه مبلغی که واقعاً پس داده شده بدهکار می‌شود؛ بخش پس‌داده‌نشده به‌صورت بستانکاری مشتری باقی می‌ماند.

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

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

## نکات سازگاری

- پرداخت خودکار کل مبلغ با صندوق پیش‌فرض حذف شده است؛ فاکتور جدید بدون اقدام کاربر، ردیف پرداخت ندارد.
- حالت موبایل همچنان از فرم فشرده قبلی استفاده می‌کند، ولی پرداخت بیشتر از مبلغ فاکتور و سقف ۵۰ ردیف را پشتیبانی می‌کند.
- قابلیت اشتراک‌گذاری مانده فاکتور در ستون اطلاعات سند دسکتاپ حفظ شده است.
- اگر ساخت خودکار سند دریافت در تنظیمات غیرفعال باشد، نوار دکمه‌های پرداخت نمایش داده نمی‌شود و رفتار قبلی اشتراک‌گذاری و ثبت باقی می‌ماند.

## سناریوهای پذیرش

1. مبلغ فاکتور ۱۰ میلیون است؛ ۴ میلیون نقدی و ۶ میلیون بانکی ثبت می‌شود و مانده به صفر می‌رسد.
2. مبلغ فاکتور ۱۰ میلیون است؛ ۴ میلیون بانکی ثبت می‌شود و فیلد مبلغ ۶ میلیون را نشان می‌دهد.
3. مبلغ فاکتور ۱۰ میلیون است؛ ۱۱ میلیون دریافت می‌شود و ۶۰۰ هزار از صندوق و ۴۰۰ هزار از بانک به مشتری برگردانده می‌شود.
4. از یک میلیون اضافه‌دریافت، ۷۰۰ هزار به مشتری برگردانده و ۳۰۰ هزار به بستانکاری همان مشتری منتقل می‌شود.
5. یک میلیون از بانک به مشتری برگردانده و ۲۰ هزار کارمزد ثبت می‌شود؛ بانک ۱٬۰۲۰٬۰۰۰ بستانکار، حساب `70902` بیست هزار بدهکار و مانده فاکتور فقط یک میلیون تعدیل می‌شود.
6. برگشت از شخص حتی بیشتر از بدهی قبلی او مجاز است و مازاد، شخص را در حساب `10401` بستانکار می‌کند.
7. دو پرداخت به دو حساب بانکی متفاوت به‌صورت دو ردیف مستقل باقی می‌مانند.
8. پرداخت به شخص، آن شخص را بدهکار و مشتری فاکتور را به همان مبلغ بستانکار می‌کند.
9. حذف یا ویرایش فاکتور دارای وجه برگشتی، اسناد دریافت و برگشت مرتبط را نیز هماهنگ می‌کند.
10. کاربر عرض بخش دکمه‌ها را تغییر می‌دهد و پس از بازکردن دوباره صفحه همان عرض بازیابی می‌شود.
11. میانبر تعریف‌شده، مبلغ جاری فیلد را به مقصد همان دکمه اضافه می‌کند.

## بررسی‌های خودکار

- تست منطق پرداخت Flutter: مستقل ماندن ردیف‌ها و مجاز بودن اضافه‌پرداخت.
- تست سرویس بک‌اند: نرمال‌سازی و محدودیت میانبرها.
- تست محاسبه مبلغ برگشتی با پرداخت معمولی و بین‌ارزی.
- بررسی head مهاجرت Alembic و تحلیل استاتیک فایل‌های جدید Flutter.