Watch
1
0
Fork
You've already forked arc
0
forked from hesabix/arc
arc/docs/quick-sales-customer-field-behavior.md
Babak Alizadeh 88ef9a6b9b fix: harden quick customer resolve auth and candidate loading
Require can_access_business for customer body/query endpoints, prefilter
person candidates in SQL instead of loading the whole business, and limit
local web API port rewriting to loopback/LAN hosts.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 19:21:54 +00:00

5.9 KiB

رفتار فیلد مشتری در فروش سریع

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

رفتار Enter

ترتیب تصمیم‌گیری پس از زدن Enter به شکل زیر است:

  1. اگر نتایج متن فعلی هنوز بارگذاری نشده‌اند، ابتدا جست‌وجو کامل می‌شود.
  2. اگر دقیقاً یک نتیجه وجود داشته باشد، همان مشتری انتخاب می‌شود.
  3. اگر چند نتیجه وجود داشته باشد و کاربر با جهت‌نما ردیفی را مشخص کرده باشد، همان ردیف انتخاب می‌شود.
  4. اگر چند نتیجه وجود داشته باشد و ردیفی صریحاً مشخص نشده باشد، API تطبیق دقیق و نتایج مشابه را بررسی می‌کند؛ نتیجه‌های مشابه در همان منوی شناور می‌مانند تا کاربر با جهت‌نما و Enter یا موس انتخاب کند.
  5. اگر نتیجه‌ای وجود نداشته باشد، ورودی برای یافتن یا ساختن سریع مشتری به API ارسال می‌شود.

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

قالب‌های ورودی ثبت سریع

ورودی می‌تواند شامل نام، موبایل یا هر دو باشد. ترتیب نام و موبایل مهم نیست و تمام بخش نام به‌صورت یکپارچه در alias_name قرار می‌گیرد.

ورودی نام مستعار موبایل
علی رضایی علی رضایی خالی
09121234567 09121234567 09121234567
09121234567 سید محمد مهدی رضوی سید محمد مهدی رضوی 09121234567
زهرا سادات موسوی +989121234567 زهرا سادات موسوی 09121234567
۰۹۱۲۱۲۳۴۵۶۷ کاظمی کاظمی 09121234567

اعداد فارسی و عربی به انگلیسی تبدیل می‌شوند. قالب‌های 09xxxxxxxxx، 9xxxxxxxxx، +989xxxxxxxxx، 989xxxxxxxxx و 00989xxxxxxxxx پشتیبانی می‌شوند. فاصله و خط تیره داخل شماره نیز پذیرفته می‌شود. وجود بیش از یک موبایل معتبر، ورودی را مبهم می‌کند و ثبت خودکار انجام نمی‌شود.

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

جلوگیری از ثبت تکراری

API پیش از ایجاد شخص، کاندیداهای همان کسب‌وکار را با فیلتر موبایل/نام (با درنظرگرفتن حروف عربی/فارسی) از دیتابیس می‌گیرد و سپس دقیق تطبیق می‌دهد:

  • موبایل پس از استانداردسازی با فیلدهای موبایل، موبایل دوم، موبایل سوم و تلفن مقایسه می‌شود.
  • نام با یکسان‌سازی فاصله‌ها، نیم‌فاصله و حروف عربی/فارسی مقایسه می‌شود.
  • نام مستعار، نام، نام خانوادگی، نام شرکت و ترکیب نام و نام خانوادگی در بررسی تشابه شرکت دارند.
  • اگر یک شخص مشابه پیدا شود، همان شخص انتخاب می‌شود و رکورد جدید ساخته نمی‌شود.
  • اگر چند شخص مشابه پیدا شوند، فهرست آن‌ها نمایش داده می‌شود تا کاربر انتخاب کند.
  • تطبیق موبایل دقیق بر تطبیق نام و تطبیق نام دقیق بر نام‌های جزئی اولویت دارد.
  • در PostgreSQL، بررسی و ایجاد سریع برای هر کسب‌وکار با قفل تراکنشی سریالی می‌شود تا دو درخواست هم‌زمان رکورد تکراری نسازند.
  • endpoint فقط برای اعضای همان کسب‌وکار مجاز است (can_access_business).

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

در پیش‌نمایش وب محلی، اگر API_BASE_URL صریحاً تنظیم نشده باشد، درخواست‌ها به پورت 8000 همان میزبان ارسال می‌شوند؛ برای نمونه، رابط 192.168.50.101:8080 از API آدرس 192.168.50.101:8000 استفاده می‌کند. این fallback مانع ارسال اشتباه درخواست‌ها به وب‌سرور Flutter روی پورت ۸۰۸۰ و دریافت خطای 405 Method Not Allowed می‌شود. در محیط‌های غیرمحلی، همان origin و reverse proxy برنامه استفاده می‌شود.

مسیرهای پیاده‌سازی

  • رابط و رفتار صفحه‌کلید: hesabixUI/hesabix_ui/lib/widgets/invoice/customer_combobox_widget.dart
  • تجزیهٔ نام و موبایل: hesabixUI/hesabix_ui/lib/utils/customer_quick_entry.dart
  • فراخوانی API: hesabixUI/hesabix_ui/lib/services/customer_service.dart
  • endpoint: POST /api/v1/customers/quick-resolve
  • منطق تطبیق و ایجاد: hesabixAPI/app/services/customer_quick_entry_service.py