Seyyed_arc/docs/QUICK_SALES_EXTERNAL_REFERENCE.md

# مرجع قابلیت‌های یک سامانه فروش سریع برای توسعه تدریجی آرک

## هدف سند

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

این سند مشخصات رسمی نرم‌افزار مرجع نیست. موارد بخش «رفتارهای تأییدشده» مستقیماً توسط کاربرِ آشنا با عملکرد آن تأیید شده‌اند. موارد نامشخص در بخش «پرسش‌های باز» باقی می‌مانند و نباید هنگام طراحی آرک به‌عنوان واقعیت قطعی فرض شوند.

### منابع تصویری گفتگو

- تصویر اول گفتگو: نمای کلی صفحه فروش سریع
- تصویر دوم گفتگو: نمونه تقسیم پرداخت میان دو کارت‌خوان و وجه نقد
- تاریخ ثبت این دانش: ۱۴۰۵/۰۷/۲۱ (۲۰۲۶/۱۰/۱۳)

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

## مدل کلی صفحه

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

1. زمینه مشتری و فاکتور فعال
2. فیلد ورود کالا با بارکد، کد یا نام
3. جدول اقلام فاکتور با ویرایش سریع مقدار
4. کالاهای دم‌دستی قابل تعریف
5. خلاصه مبلغ، پرداخت‌شده، مانده و مبلغ برگشتی
6. ردیف‌های مستقل پرداخت
7. دکمه‌های عملیاتی قابل تعریف با کلید میانبر و زنجیره عملیات

## رفتارهای تأییدشده

### ۱. چند فروش هم‌زمان و پارک سفارش

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

### ۲. حرکت میان فاکتورهای ثبت‌شده

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

### ۳. ورود و جست‌وجوی کالا

- ورود با بارکد، کد کالا یا نام کالا انجام می‌شود.
- بارکد یا کد یکتا مستقیماً کالا را وارد جدول فاکتور می‌کند.
- جست‌وجوی نام، نتایج را در منوی شناور نشان می‌دهد.
- حرکت در نتایج و انتخاب با کلیدهای جهت، Enter یا موس انجام می‌شود.
- منطق فعلی جست‌وجو و انتخاب کالای فروش سریع آرک رفتار مشابهی دارد.

### ۴. کالاهای دم‌دستی

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

### ۵. ثبت سریع مشتری

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

### ۶. تقسیم مبلغ بین چند روش پرداخت

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

در نمونه مشاهده‌شده:

| عنوان | مبلغ |
|---|---:|
| مبلغ نهایی فاکتور | ۳۷٬۷۰۰٬۰۰۰ |
| پرداخت با کارت‌خوان سامان | ۵٬۰۰۰٬۰۰۰ |
| پرداخت با کارت‌خوان رسالت | ۲٬۶۰۰٬۰۰۰ |
| پرداخت نقدی | ۲۶٬۴۰۰٬۰۰۰ |
| مجموع پرداخت‌ها | ۳۴٬۰۰۰٬۰۰۰ |
| مانده | ۳٬۷۰۰٬۰۰۰ |

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

فرمول مفهومی مانده:

```text
مانده = مبلغ نهایی فاکتور - مجموع پرداخت‌های منظورشده
```

### ۷. اضافه‌پرداخت و برگرداندن وجه

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

نمونه حسابداری مفهومی برای فاکتور ۱۰۰ و دریافت کارتی ۱۲۰:

```text
دریافت کارت: ۱۲۰
مبلغ فاکتور: ۱۰۰
پرداخت نقدی از صندوق پیش‌فرض به مشتری: ۲۰
```

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

### ۸. صندوق‌ها و کارت‌خوان‌های قابل تعریف

- نام‌هایی مانند «سامان» و «رسالت» قابلیت ثابت نرم‌افزار نیستند؛ کاربر آن‌ها را تعریف می‌کند.
- هر دکمه پرداخت به یک صندوق یا کارت‌خوان تعریف‌شده متصل می‌شود.
- عملیات می‌تواند فقط پرداخت را در صندوق مربوط ثبت کند و الزاماً مبلغی به دستگاه کارت‌خوان نفرستد.
- اگر اتصال کارت‌خوان تنظیم شده باشد، مبلغ می‌تواند به‌صورت خودکار برای دستگاه ارسال شود.
- مشتری یا فروشنده می‌تواند برای یک فاکتور از چند کارت یا چند کارت‌خوان استفاده کند.

### ۹. شکست تراکنش کارت‌خوان

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

این رفتار نباید بدون ردپای حسابرسی در آرک تکرار شود. اگر چنین اختیاری در آرک طراحی شود، حداقل کاربر، زمان، دستگاه، پاسخ دریافتی، علت و تأیید دستی باید ثبت شوند.

### ۱۰. دکمه‌های عملیاتی قابل تعریف

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

نمونه زنجیره معتبر:

```text
ثبت پرداخت در صندوق سامان
→ ذخیره فاکتور
→ چاپ فاکتور
→ بستن فاکتور
→ نمایش فاکتور خالی جدید
```

چاپ اختیاری است و زنجیره زیر نیز معتبر است:

```text
ثبت پرداخت
→ ذخیره فاکتور
→ بستن فاکتور
```

نمونه ترتیب نامعتبر:

```text
بستن فاکتور
→ ذخیره یا چاپ فاکتور بسته‌شده
```

ویرایشگر دکمه باید وابستگی و ترتیب عملیات را هنگام تعریف کنترل کند، نه اینکه خطا فقط زمان فروش رخ دهد.

### ۱۱. سیاست پرداخت‌های قبلی در دکمه زنجیره‌ای

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

- **حذف پرداخت‌های قبلی:** همه ردیف‌های قبلی حذف و کل مبلغ فاکتور با روش پرداخت دکمه جدید منظور می‌شود.
- **حفظ پرداخت‌های قبلی:** ردیف‌های قبلی باقی می‌مانند و اگر مانده‌ای وجود داشته باشد، فقط همان مانده با روش پرداخت دکمه تسویه می‌شود.

### ۱۲. کنترل کسری موجودی

- رفتار فروش با کسری موجودی در نرم‌افزار مرجع به تنظیمات وابسته است.
- فروش سریع آرک اکنون گردش‌کار مشخص انصراف، پارک فروش، اصلاح موجودی و ثبت یک‌باره با موجودی منفی دارد.
- ثبت منفی در آرک پرونده مغایرت می‌سازد و از مسیر «انبار ← مغایرت‌های موجودی فروش سریع» قابل رسیدگی است.
- جزئیات این پیاده‌سازی در `docs/QUICK_SALES_STOCK_SHORTAGE_WORKFLOW.md` ثبت شده است.

## قابلیت‌های پیشنهادی برای بررسی مرحله‌ای در آرک

این فهرست به‌معنای تأیید پیاده‌سازی نیست. برای هر مورد باید ابتدا وضعیت فعلی آرک بررسی و سپس نیازمندی مستقل تأیید شود.

| قابلیت مرجع | وضعیت شناخته‌شده در آرک | اقدام بعدی پیشنهادی |
|---|---|---|
| چند فروش و پارک سفارش | موجود | نگهداری و تکمیل تست‌های پایداری |
| جست‌وجوی بارکد/کد/نام و انتخاب شناور | موجود | نگهداری رفتار فعلی |
| ثبت سریع مشتری | موجود با منطق متفاوت | نگهداری رفتار فعلی و ارزیابی جداگانه |
| کسری موجودی و پرونده مغایرت | موجود | نگهداری مستند و تست‌شده |
| کالاهای دم‌دستی قابل تعریف | نیازمند بررسی کد فعلی | تحلیل دامنه شخصی/عمومی و طراحی مدیریت چیدمان |
| تقسیم پرداخت و نمایش مانده | نیازمند بررسی دقیق رفتار فعلی | تحلیل مدل پرداخت پیش از تغییر UI |
| اضافه‌پرداخت و برگشت نقدی | نیازمند بررسی | طراحی سند خروج از صندوق و کنترل صندوق پیش‌فرض |
| صندوق/کارت‌خوان قابل اتصال به دکمه | نیازمند بررسی | تفکیک ثبت حسابداری از ارتباط سخت‌افزاری |
| دکمه زنجیره‌ای قابل تعریف | نیازمند طراحی | تعریف عملیات، ترتیب، اعتبارسنجی و مجوزها |
| کلید میانبر قابل تعریف | نیازمند بررسی | طراحی جلوگیری از تداخل میانبرها |
| حرکت میان فاکتورهای ثبت‌شده | نیازمند بررسی | تعیین دامنه مشاهده، ویرایش و برگشت |
| ویرایش یا برگشت کلی فاکتور ثبت‌شده | نیازمند بررسی معماری | حفظ ردپای حسابرسی و معکوس‌سازی اسناد وابسته |

## اصول پیشنهادی برای طراحی آرک

هنگام تبدیل هر قابلیت به طراحی اجرایی، این اصول حفظ شوند:

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

## پرسش‌های باز

### ویرایش و برگشت فاکتور ثبت‌شده

هنوز مشخص نیست نرم‌افزار مرجع هنگام ویرایش یا برگشت کلی:

- اسناد پرداخت، حسابداری و انبار قبلی را معکوس و اسناد جدید ایجاد می‌کند؛
- یا همان اسناد قبلی را مستقیماً تغییر می‌دهد.

برای طراحی آرک، روش مبتنی بر ردپای تغییر و اسناد معکوس باید مبنای بررسی باشد.

### جزئیات کارت‌خوان واقعی

تصویر بعدی کاربر قرار است رفتار دو کارت‌خوان یا دو حالت کارت‌کشیدن واقعی را نشان دهد. پس از دریافت آن باید موارد زیر به این سند افزوده شود:

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

## روش ادامه کار

برای هر قابلیت جدید:

1. رفتار مرجع با مثال و تصویر ثبت شود.
2. وضعیت فعلی آرک در فرانت، API، مدل داده و حسابداری بررسی شود.
3. تفاوت‌ها و تصمیم محصول مشخص شوند.
4. طرح اجرایی مستقل نوشته و تأیید شود.
5. تغییر در شاخه جدا یا شاخه مورد توافق اجرا شود.
6. سناریوهای پذیرش و مستندات همراه کد اضافه شوند.
7. پس از تست کاربر، تغییرات commit و push شوند.