409 lines
16 KiB
Markdown
Executable file
409 lines
16 KiB
Markdown
Executable file
# تحلیل بخش فاکتور سریع (Quick Sales)
|
|
|
|
این سند شامل تحلیل کامل مشکلات فنی و ظاهری بخش فاکتور سریع و پیشنهادات بهبود است.
|
|
|
|
## 📋 فهرست مطالب
|
|
1. [مشکلات فنی](#مشکلات-فنی)
|
|
2. [مشکلات ظاهری (UI/UX)](#مشکلات-ظاهری-uiux)
|
|
3. [مشکلات عملکردی](#مشکلات-عملکردی)
|
|
4. [پیشنهادات بهبود](#پیشنهادات-بهبود)
|
|
|
|
---
|
|
|
|
## 🔴 مشکلات فنی
|
|
|
|
### 1. مشکلات کد ناقص و خطاها
|
|
|
|
#### 1.1. Import غیرضروری
|
|
```352:352:hesabixUI/hesabix_ui/lib/pages/business/quick_sales_page.dart
|
|
void _increaseQuantity(int index) {
|
|
```
|
|
- **مشکل**: `import 'dart:math' as math;` در خط 20 import شده اما استفاده نشده است.
|
|
- **تأثیر**: کد تمیز نیست و ممکن است باعث سردرگمی شود.
|
|
|
|
#### 1.2. قابلیت چاپ پیاده‌سازی نشده
|
|
```313:316:hesabixUI/hesabix_ui/lib/pages/business/quick_sales_page.dart
|
|
// چاپ در صورت نیاز
|
|
if (print || _autoPrint) {
|
|
// TODO: چاپ فاکتور
|
|
}
|
|
```
|
|
- **مشکل**: قابلیت چاپ فاکتور بعد از ثبت وجود دارد اما پیاده‌سازی نشده است.
|
|
- **تأثیر**: دکمه "ثبت و چاپ" کاربردی ندارد و کاربر انتظار دارد که چاپ انجام شود.
|
|
|
|
#### 1.3. عدم استخراج شناسه فاکتور از پاسخ
|
|
```306:309:hesabixUI/hesabix_ui/lib/pages/business/quick_sales_page.dart
|
|
final result = await _invoiceService.createInvoice(
|
|
businessId: widget.businessId,
|
|
payload: payload,
|
|
);
|
|
```
|
|
- **مشکل**: نتیجه `createInvoice` در متغیر `result` ذخیره می‌شود اما استفاده نمی‌شود.
|
|
- **تأثیر**: برای چاپ فاکتور به `invoice_id` نیاز است اما استخراج نمی‌شود.
|
|
|
|
### 2. مشکلات اعتبارسنجی
|
|
|
|
#### 2.1. عدم اعتبارسنجی موجودی قبل از افزودن به سبد
|
|
```174:214:hesabixUI/hesabix_ui/lib/pages/business/quick_sales_page.dart
|
|
void _addToCart(Map<String, dynamic> product, {int? instanceId}) {
|
|
// ... کد افزودن به سبد بدون بررسی موجودی
|
|
}
|
|
```
|
|
- **مشکل**: قبل از افزودن محصول به سبد، موجودی بررسی نمی‌شود.
|
|
- **تأثیر**: ممکن است محصولی بدون موجودی به سبد اضافه شود و در زمان ثبت فاکتور خطا رخ دهد.
|
|
|
|
#### 2.2. عدم اعتبارسنجی مبلغ پرداخت
|
|
```719:728:hesabixUI/hesabix_ui/lib/pages/business/quick_sales_page.dart
|
|
if (option != null && _totalAmount > 0) {
|
|
_payment = InvoiceTransaction(
|
|
id: DateTime.now().millisecondsSinceEpoch.toString(),
|
|
type: TransactionType.cashRegister,
|
|
cashRegisterId: option.id,
|
|
cashRegisterName: option.name,
|
|
transactionDate: DateTime.now(),
|
|
amount: _totalAmount,
|
|
);
|
|
}
|
|
```
|
|
- **مشکل**: هیچ اعتبارسنجی برای مطابقت مبلغ پرداخت با مبلغ فاکتور وجود ندارد.
|
|
- **تأثیر**: ممکن است مبلغ پرداخت بیشتر یا کمتر از مبلغ فاکتور باشد.
|
|
|
|
#### 2.3. عدم بررسی وجود صندوق قبل از ثبت
|
|
```244:248:hesabixUI/hesabix_ui/lib/pages/business/quick_sales_page.dart
|
|
Future<void> _saveInvoice({bool print = false}) async {
|
|
if (_cartItems.isEmpty) {
|
|
SnackBarHelper.show(context, message: 'سبد خرید خالی است', isError: true);
|
|
return;
|
|
}
|
|
```
|
|
- **مشکل**: بررسی وجود `_selectedCashRegisterId` قبل از ثبت انجام نمی‌شود.
|
|
- **تأثیر**: ممکن است فاکتور بدون انتخاب صندوق ثبت شود یا خطا رخ دهد.
|
|
|
|
#### 2.4. عدم اعتبارسنجی currency_id
|
|
```286:286:hesabixUI/hesabix_ui/lib/pages/business/quick_sales_page.dart
|
|
'currency_id': _defaultCurrencyId,
|
|
```
|
|
- **مشکل**: اگر `_defaultCurrencyId` null باشد، فاکتور بدون ارز ثبت می‌شود.
|
|
- **تأثیر**: ممکن است خطا در سرور رخ دهد.
|
|
|
|
### 3. مشکلات مدیریت خطا
|
|
|
|
#### 3.1. مدیریت ناکافی خطا برای مشتری ناشناس
|
|
```89:119:hesabixUI/hesabix_ui/lib/pages/business/quick_sales_page.dart
|
|
Future<void> _loadSettings() async {
|
|
// ... در صورت خطا فقط یک SnackBar نمایش داده می‌شود
|
|
}
|
|
```
|
|
- **مشکل**: اگر دریافت مشتری ناشناس با خطا مواجه شود، صفحه در حالت loading می‌ماند یا خطا به خوبی مدیریت نمی‌شود.
|
|
- **تأثیر**: تجربه کاربری ضعیف در صورت بروز خطا.
|
|
|
|
#### 3.2. عدم مدیریت خطای شبکه
|
|
```121:172:hesabixUI/hesabix_ui/lib/pages/business/quick_sales_page.dart
|
|
Future<void> _searchByBarcode(String code) async {
|
|
// ... مدیریت خطای عمومی
|
|
}
|
|
```
|
|
- **مشکل**: خطاهای شبکه به صورت عمومی مدیریت می‌شوند و نوع خطا مشخص نمی‌شود.
|
|
- **تأثیر**: کاربر نمی‌داند مشکل چیست (عدم اتصال، خطای سرور، محصول پیدا نشد).
|
|
|
|
### 4. مشکلات معماری
|
|
|
|
#### 4.1. عدم استفاده از State Management مناسب
|
|
- **مشکل**: استفاده از `setState` مستقیم برای مدیریت state پیچیده.
|
|
- **تأثیر**: کد سخت‌تر برای نگهداری و تست می‌شود.
|
|
|
|
#### 4.2. منطق تجاری در UI
|
|
- **مشکل**: محاسبات و منطق تجاری مستقیماً در ویجت انجام می‌شود.
|
|
- **تأثیر**: دشوار بودن تست و استفاده مجدد از کد.
|
|
|
|
---
|
|
|
|
## 🎨 مشکلات ظاهری (UI/UX)
|
|
|
|
### 1. مشکلات رابط کاربری
|
|
|
|
#### 1.1. عدم نمایش موجودی محصولات
|
|
- **مشکل**: هیچ نمایشی از موجودی محصول در کارت سبد خرید وجود ندارد.
|
|
- **تأثیر**: کاربر نمی‌داند آیا محصول موجود است یا نه.
|
|
|
|
#### 1.2. عدم نمایش مبلغ باقیمانده
|
|
- **مشکل**: در صورت پرداخت جزئی، مبلغ باقیمانده نمایش داده نمی‌شود.
|
|
- **تأثیر**: کاربر نمی‌داند چقدر از فاکتور باقی مانده است.
|
|
|
|
#### 1.3. عدم وجود جستجوی سریع محصول
|
|
- **مشکل**: فقط جستجو از طریق بارکد وجود دارد، جستجو از طریق نام محصول نیست.
|
|
- **تأثیر**: برای محصولاتی که بارکد ندارند یا کاربر می‌خواهد از نام جستجو کند، محدودیت وجود دارد.
|
|
|
|
#### 1.4. طراحی سبد خرید برای تعداد زیاد محصول
|
|
- **مشکل**: لیست سبد خرید برای تعداد زیاد محصول (مثلاً 50+ محصول) مناسب نیست.
|
|
- **تأثیر**: اسکرول طولانی و کاهش سرعت کار.
|
|
|
|
#### 1.5. عدم نمایش اطلاعات کامل محصول
|
|
- **مشکل**: در کارت محصول فقط نام، کد و قیمت نمایش داده می‌شود.
|
|
- **تأثیر**: اطلاعات مهم مانند واحد اندازه‌گیری، موجودی، و توضیحات نمایش داده نمی‌شود.
|
|
|
|
#### 1.6. عدم وجود فیدبک بصری برای عملیات
|
|
- **مشکل**: هنگام افزودن محصول به سبد، فیدبک بصری واضحی وجود ندارد.
|
|
- **تأثیر**: کاربر ممکن است مطمئن نباشد که محصول اضافه شده است.
|
|
|
|
### 2. مشکلات دسترسی‌پذیری
|
|
|
|
#### 2.1. عدم پشتیبانی از صفحه‌خوان
|
|
- **مشکل**: برچسب‌های Semantics برای صفحه‌خوان وجود ندارد.
|
|
- **تأثیر**: کاربران نابینا نمی‌توانند از این بخش استفاده کنند.
|
|
|
|
#### 2.2. مشکل در صفحه کلید
|
|
- **مشکل**: Shortcut keys فقط برای برخی عملیات وجود دارد.
|
|
- **تأثیر**: استفاده سریع با صفحه کلید کامل نیست.
|
|
|
|
---
|
|
|
|
## ⚡ مشکلات عملکردی
|
|
|
|
### 1. مشکلات بهینه‌سازی
|
|
|
|
#### 1.1. عدم Cache کردن نتایج جستجو
|
|
- **مشکل**: هر بار جستجو، درخواست جدید به API ارسال می‌شود.
|
|
- **تأثیر**: افزایش بار سرور و کاهش سرعت.
|
|
|
|
#### 1.2. عدم Debounce برای جستجو
|
|
- **مشکل**: هر تغییر در فیلد بارکد، بلافاصله جستجو انجام می‌شود.
|
|
- **تأثیر**: درخواست‌های اضافی به API.
|
|
|
|
#### 1.3. Rebuild غیرضروری
|
|
- **مشکل**: `setState` زیاد باعث rebuild کل صفحه می‌شود.
|
|
- **تأثیر**: کاهش عملکرد UI.
|
|
|
|
### 2. مشکلات تجربه کاربری
|
|
|
|
#### 2.1. عدم وجود Auto-complete برای محصولات
|
|
- **مشکل**: هنگام تایپ در فیلد بارکد، پیشنهادات محصول نمایش داده نمی‌شود.
|
|
- **تأثیر**: کاربر باید دقیق بارکد را وارد کند.
|
|
|
|
#### 2.2. عدم وجود History محصولات اخیر
|
|
- **مشکل**: محصولاتی که اخیراً به سبد اضافه شده‌اند ذخیره نمی‌شوند.
|
|
- **تأثیر**: برای افزودن مجدد همان محصولات، باید دوباره جستجو کرد.
|
|
|
|
---
|
|
|
|
## 💡 پیشنهادات بهبود
|
|
|
|
### 1. بهبودهای فنی فوری
|
|
|
|
#### 1.1. پیاده‌سازی قابلیت چاپ
|
|
```dart
|
|
// افزودن متد به InvoiceService
|
|
Future<List<int>> downloadInvoicePdf({
|
|
required int businessId,
|
|
required int invoiceId,
|
|
Map<String, dynamic>? query,
|
|
}) async {
|
|
// ...
|
|
}
|
|
|
|
// استفاده در QuickSalesPage
|
|
if (print || _autoPrint) {
|
|
final invoiceId = result['data']?['id'] as int?;
|
|
if (invoiceId != null) {
|
|
await _printInvoice(invoiceId);
|
|
}
|
|
}
|
|
```
|
|
|
|
#### 1.2. افزودن اعتبارسنجی موجودی
|
|
```dart
|
|
Future<bool> _checkStockAvailability(int productId, num quantity) async {
|
|
try {
|
|
final stock = await _productService.getProductStock(
|
|
businessId: widget.businessId,
|
|
productId: productId,
|
|
warehouseId: _defaultWarehouseId,
|
|
);
|
|
return stock >= quantity;
|
|
} catch (e) {
|
|
return false;
|
|
}
|
|
}
|
|
```
|
|
|
|
#### 1.3. اعتبارسنجی مبلغ پرداخت
|
|
```dart
|
|
if (_payment != null && _payment!.amount != _totalAmount) {
|
|
SnackBarHelper.show(
|
|
context,
|
|
message: 'مبلغ پرداخت باید برابر با مبلغ فاکتور باشد',
|
|
isError: true,
|
|
);
|
|
return;
|
|
}
|
|
```
|
|
|
|
#### 1.4. اعتبارسنجی صندوق و ارز
|
|
```dart
|
|
if (_selectedCashRegisterId == null) {
|
|
SnackBarHelper.show(
|
|
context,
|
|
message: 'لطفاً صندوق را انتخاب کنید',
|
|
isError: true,
|
|
);
|
|
return;
|
|
}
|
|
|
|
if (_defaultCurrencyId == null) {
|
|
SnackBarHelper.show(
|
|
context,
|
|
message: 'ارز پیش‌فرض تنظیم نشده است',
|
|
isError: true,
|
|
);
|
|
return;
|
|
}
|
|
```
|
|
|
|
### 2. بهبودهای UI/UX
|
|
|
|
#### 2.1. افزودن نمایش موجودی
|
|
- نمایش موجودی در کارت محصول در سبد
|
|
- نمایش هشدار در صورت موجودی کم
|
|
- غیرفعال کردن دکمه افزایش تعداد در صورت نبود موجودی
|
|
|
|
#### 2.2. افزودن جستجوی محصول از طریق نام
|
|
```dart
|
|
// افزودن فیلد جستجو
|
|
TextField(
|
|
controller: _productSearchController,
|
|
decoration: InputDecoration(
|
|
labelText: 'جستجوی محصول',
|
|
prefixIcon: Icon(Icons.search),
|
|
),
|
|
onChanged: _debounceSearch,
|
|
)
|
|
```
|
|
|
|
#### 2.3. بهبود طراحی سبد خرید
|
|
- استفاده از DataTable برای نمایش جدولی
|
|
- افزودن فیلتر و جستجو در سبد
|
|
- افزودن قابلیت مرتب‌سازی
|
|
|
|
#### 2.4. افزودن فیدبک بصری
|
|
- نمایش SnackBar با انیمیشن هنگام افزودن محصول
|
|
- تغییر رنگ موقت کارت محصول اضافه شده
|
|
- نمایش انیمیشن لودینگ هنگام جستجو
|
|
|
|
#### 2.5. افزودن نمایش مبلغ باقیمانده
|
|
```dart
|
|
if (_payment != null && _payment!.amount < _totalAmount) {
|
|
_buildSummaryRow(
|
|
'باقیمانده',
|
|
_formatNumber(_totalAmount - _payment!.amount),
|
|
isWarning: true,
|
|
);
|
|
}
|
|
```
|
|
|
|
### 3. بهبودهای عملکرد
|
|
|
|
#### 3.1. افزودن Debounce برای جستجو
|
|
```dart
|
|
Timer? _searchDebounce;
|
|
|
|
void _onSearchChanged(String value) {
|
|
_searchDebounce?.cancel();
|
|
_searchDebounce = Timer(const Duration(milliseconds: 500), () {
|
|
_searchByBarcode(value);
|
|
});
|
|
}
|
|
```
|
|
|
|
#### 3.2. Cache کردن نتایج جستجو
|
|
```dart
|
|
final Map<String, List<Map<String, dynamic>>> _searchCache = {};
|
|
|
|
Future<List<Map<String, dynamic>>> _searchProducts(String query) async {
|
|
if (_searchCache.containsKey(query)) {
|
|
return _searchCache[query]!;
|
|
}
|
|
// ... جستجو و ذخیره در cache
|
|
}
|
|
```
|
|
|
|
#### 3.3. استفاده از const constructors
|
|
- استفاده از `const` برای ویجت‌های استاتیک
|
|
- کاهش rebuild های غیرضروری
|
|
|
|
#### 3.4. بهینه‌سازی setState
|
|
- استفاده از `ValueNotifier` برای state های ساده
|
|
- استفاده از Provider یا Riverpod برای state management پیچیده
|
|
|
|
### 4. بهبودهای معماری
|
|
|
|
#### 4.1. جداسازی منطق تجاری
|
|
- ایجاد یک Controller یا Bloc برای مدیریت state
|
|
- انتقال محاسبات به کلاس‌های جداگانه
|
|
|
|
#### 4.2. بهبود مدیریت خطا
|
|
- ایجاد یک Error Handler مرکزی
|
|
- نمایش خطاهای مشخص و قابل فهم برای کاربر
|
|
|
|
#### 4.3. افزودن تست‌های واحد
|
|
- تست برای محاسبات (جمع کل، تخفیف، مالیات)
|
|
- تست برای اعتبارسنجی‌ها
|
|
- تست برای منطق افزودن/حذف از سبد
|
|
|
|
### 5. ویژگی‌های جدید پیشنهادی
|
|
|
|
#### 5.1. History محصولات اخیر
|
|
- ذخیره 10-20 محصول اخیر
|
|
- نمایش به صورت Quick Access
|
|
|
|
#### 5.2. قابلیت ذخیره سبد خرید
|
|
- امکان ذخیره سبد خرید برای بعد
|
|
- بارگذاری سبد ذخیره شده
|
|
|
|
#### 5.3. قابلیت Copy/Paste محصولات
|
|
- کپی سبد خرید از فاکتور دیگر
|
|
- Paste چند محصول به صورت یکجا
|
|
|
|
#### 5.4. قابلیت پیش‌فاکتور
|
|
- امکان ذخیره به عنوان پیش‌فاکتور
|
|
- تبدیل پیش‌فاکتور به فاکتور
|
|
|
|
#### 5.5. گزارشات فروش سریع
|
|
- نمایش آمار فروش روزانه
|
|
- نمایش محصولات پرفروش
|
|
- نمایش ساعات شلوغی
|
|
|
|
---
|
|
|
|
## 📊 اولویت‌بندی
|
|
|
|
### اولویت بالا (فوری)
|
|
1. ✅ پیاده‌سازی قابلیت چاپ
|
|
2. ✅ اعتبارسنجی موجودی قبل از افزودن به سبد
|
|
3. ✅ اعتبارسنجی صندوق و ارز قبل از ثبت
|
|
4. ✅ استخراج invoice_id از پاسخ
|
|
|
|
### اولویت متوسط
|
|
1. ✅ افزودن جستجوی محصول از طریق نام
|
|
2. ✅ نمایش موجودی در سبد
|
|
3. ✅ بهبود مدیریت خطا
|
|
4. ✅ افزودن Debounce برای جستجو
|
|
|
|
### اولویت پایین (بهبود)
|
|
1. ✅ استفاده از State Management بهتر
|
|
2. ✅ افزودن History محصولات
|
|
3. ✅ بهبود طراحی UI
|
|
4. ✅ افزودن تست‌ها
|
|
|
|
---
|
|
|
|
## 📝 نتیجه‌گیری
|
|
|
|
بخش فاکتور سریع عملکرد اصلی خود را انجام می‌دهد اما نیاز به بهبودهای قابل توجهی در زمینه‌های زیر دارد:
|
|
|
|
1. **پیاده‌سازی قابلیت‌های ناقص** (چاپ، اعتبارسنجی‌ها)
|
|
2. **بهبود تجربه کاربری** (نمایش اطلاعات بیشتر، جستجوی بهتر)
|
|
3. **بهینه‌سازی عملکرد** (کاهش درخواست‌ها، بهبود rendering)
|
|
4. **افزودن ویژگی‌های جدید** (history، پیش‌فاکتور)
|
|
|
|
با توجه به اولویت‌بندی انجام شده، پیشنهاد می‌شود ابتدا مشکلات فوری برطرف شوند و سپس به بهبودهای عملکردی و ظاهری پرداخته شود.
|
|
|