190 lines
9 KiB
Markdown
Executable file
190 lines
9 KiB
Markdown
Executable file
# TODO: پیاده‌سازی کامل قابلیت چاپ فاکتور بعد از صدور
|
|
|
|
این فایل شامل لیست کارهای لازم برای پیاده‌سازی کامل قابلیت "چاپ فاکتور بعد از صدور" در صفحه فاکتور جدید است.
|
|
|
|
## وضعیت فعلی
|
|
|
|
### مشکلات شناسایی شده:
|
|
1. ✅ UI برای تنظیمات چاپ وجود دارد اما اجرا نمی‌شود
|
|
2. ✅ تنظیمات چاپ (پرینتر، سایز کاغذ، قالب) hard-coded هستند
|
|
3. ✅ متد دریافت PDF در `InvoiceService` وجود ندارد
|
|
4. ✅ شناسه فاکتور از پاسخ `createInvoice` استخراج نمی‌شود
|
|
5. ✅ بعد از ذخیره فاکتور، چاپ انجام نمی‌شود
|
|
|
|
### قابلیت‌های موجود:
|
|
- ✅ API endpoint برای دریافت PDF: `/invoices/business/{business_id}/{invoice_id}/pdf`
|
|
- ✅ API از query parameters `paper_size` و `orientation` پشتیبانی می‌کند
|
|
- ✅ API از `template_id` پشتیبانی می‌کند
|
|
- ✅ سیستم تنظیمات چاپ کسب‌وکار (`BusinessPrintSettings`) وجود دارد
|
|
- ✅ `ApiClient.downloadPdf()` برای دانلود PDF موجود است
|
|
|
|
---
|
|
|
|
## کارهای لازم برای پیاده‌سازی
|
|
|
|
### 1. پیاده‌سازی اولیه چاپ بعد از ذخیره (MVP)
|
|
|
|
#### 1.1. افزودن متد دریافت PDF به InvoiceService
|
|
- [ ] افزودن متد `downloadInvoicePdf()` به کلاس `InvoiceService`
|
|
- [ ] پشتیبانی از پارامترهای `paper_size`, `orientation`, `template_id`
|
|
- [ ] استفاده از endpoint موجود: `/invoices/business/{business_id}/{invoice_id}/pdf`
|
|
|
|
#### 1.2. اصلاح متد `_saveInvoice` در NewInvoicePage
|
|
- [ ] استخراج `id` فاکتور از پاسخ `createInvoice`
|
|
- [ ] بررسی وضعیت `_printAfterSave`
|
|
- [ ] در صورت فعال بودن، دانلود PDF بعد از ذخیره موفق
|
|
- [ ] مدیریت خطا در صورت عدم موفقیت در چاپ
|
|
|
|
#### 1.3. استفاده از تنظیمات پیش‌فرض
|
|
- [ ] استفاده از `paper_size` و `orientation` از تنظیمات کسب‌وکار (در صورت موجود بودن)
|
|
- [ ] استفاده از `template_id` از تنظیمات کسب‌وکار (در صورت موجود بودن)
|
|
|
|
---
|
|
|
|
### 2. بهبود UI و تنظیمات چاپ
|
|
|
|
#### 2.1. بارگذاری تنظیمات چاپ کسب‌وکار
|
|
- [ ] بارگذاری تنظیمات چاپ از `BusinessApiService.getPrintSettings()`
|
|
- [ ] استفاده از تنظیمات اختصاصی نوع فاکتور (در صورت موجود بودن)
|
|
- [ ] استفاده از تنظیمات عمومی (در صورت عدم وجود تنظیمات اختصاصی)
|
|
|
|
#### 2.2. لیست پرینترهای واقعی
|
|
- [ ] بررسی امکان استفاده از Web Printing API در Flutter Web
|
|
- [ ] پیاده‌سازی دریافت لیست پرینترهای سیستم (در صورت امکان)
|
|
- [ ] در صورت عدم امکان، استفاده از تنظیمات ذخیره‌شده کاربر
|
|
- [ ] جایگزینی لیست hard-coded با لیست داینامیک
|
|
|
|
**نکته:** در Flutter Web، چاپ مستقیم به پرینتر از طریق JavaScript امکان‌پذیر است:
|
|
- استفاده از `window.print()` برای چاپ PDF
|
|
- استفاده از Web Printing API (در صورت پشتیبانی مرورگر)
|
|
- استفاده از `html.window` برای دسترسی به API های مرورگر
|
|
|
|
#### 2.3. لیست قالب‌های چاپ واقعی
|
|
- [ ] بارگذاری لیست قالب‌های چاپ از API
|
|
- [ ] استفاده از `ReportTemplateService` برای دریافت قالب‌های موجود
|
|
- [ ] فیلتر قالب‌ها بر اساس `module_key: "invoices"` و `subtype: "detail"`
|
|
- [ ] جایگزینی لیست hard-coded با لیست داینامیک
|
|
|
|
#### 2.4. سایز کاغذ و جهت
|
|
- [ ] استفاده از لیست استاندارد سایزهای کاغذ (A4, A5, A6, Letter, Legal, 80mm, ...)
|
|
- [ ] پشتیبانی از جهت عمودی (portrait) و افقی (landscape)
|
|
- [ ] استفاده از تنظیمات پیش‌فرض از `BusinessPrintSettings`
|
|
|
|
---
|
|
|
|
### 3. قابلیت "فاکتور رسمی"
|
|
|
|
#### 3.1. تعریف و پیاده‌سازی
|
|
- [ ] تعریف دقیق "فاکتور رسمی" (احتمالاً شامل مهر و امضا)
|
|
- [ ] بررسی اینکه آیا این قابلیت باید از `BusinessPrintSettings.show_stamp` استفاده کند
|
|
- [ ] در صورت نیاز، افزودن پارامتر `is_official` به API endpoint
|
|
|
|
#### 3.2. یکپارچه‌سازی با تنظیمات کسب‌وکار
|
|
- [ ] استفاده از `show_stamp` و `show_logo` از تنظیمات کسب‌وکار
|
|
- [ ] نمایش/عدم نمایش مهر و امضا بر اساس تنظیمات
|
|
|
|
---
|
|
|
|
### 4. چاپ مستقیم به پرینتر (پیشرفته)
|
|
|
|
#### 4.1. بررسی امکان‌پذیری
|
|
- [ ] بررسی پشتیبانی مرورگر از Web Printing API
|
|
- [ ] بررسی امکان استفاده از `window.print()` در Flutter Web
|
|
- [ ] بررسی نیاز به استفاده از پکیج‌های third-party
|
|
|
|
#### 4.2. پیاده‌سازی (در صورت امکان)
|
|
- [ ] استفاده از `dart:html` برای دسترسی به `window.print()`
|
|
- [ ] ایجاد یک iframe موقت برای نمایش PDF
|
|
- [ ] فراخوانی `window.print()` روی iframe
|
|
- [ ] مدیریت خطا و fallback به دانلود PDF
|
|
|
|
**نکته:** در Flutter Web، می‌توان از کد زیر استفاده کرد:
|
|
```dart
|
|
import 'dart:html' as html;
|
|
import 'dart:js' as js;
|
|
|
|
// برای چاپ مستقیم
|
|
html.window.print();
|
|
```
|
|
|
|
---
|
|
|
|
### 5. بهبود تجربه کاربری
|
|
|
|
#### 5.1. مدیریت وضعیت چاپ
|
|
- [ ] نمایش loading indicator هنگام دانلود PDF
|
|
- [ ] نمایش پیام موفقیت/خطا بعد از چاپ
|
|
- [ ] عدم هدایت به لیست فاکتورها تا زمان تکمیل چاپ (در صورت نیاز)
|
|
|
|
#### 5.2. ذخیره تنظیمات کاربر
|
|
- [ ] ذخیره تنظیمات چاپ آخرین استفاده شده در localStorage
|
|
- [ ] بارگذاری تنظیمات ذخیره‌شده در بارگذاری صفحه
|
|
- [ ] استفاده از تنظیمات پیش‌فرض در صورت عدم وجود تنظیمات ذخیره‌شده
|
|
|
|
#### 5.3. اعتبارسنجی تنظیمات
|
|
- [ ] بررسی صحت `template_id` قبل از ارسال به API
|
|
- [ ] بررسی صحت `paper_size` و `orientation`
|
|
- [ ] نمایش پیام خطا در صورت تنظیمات نامعتبر
|
|
|
|
---
|
|
|
|
### 6. تست و مستندسازی
|
|
|
|
#### 6.1. تست عملکرد
|
|
- [ ] تست چاپ بعد از ذخیره فاکتور
|
|
- [ ] تست با انواع مختلف فاکتور (فروش، خرید، تولید، ...)
|
|
- [ ] تست با تنظیمات مختلف (سایز کاغذ، جهت، قالب)
|
|
- [ ] تست مدیریت خطا
|
|
|
|
#### 6.2. مستندسازی
|
|
- [ ] مستندسازی نحوه استفاده از قابلیت
|
|
- [ ] مستندسازی تنظیمات چاپ
|
|
- [ ] مستندسازی API endpoints مرتبط
|
|
|
|
---
|
|
|
|
## اولویت‌بندی
|
|
|
|
### اولویت بالا (MVP):
|
|
1. ✅ افزودن متد دریافت PDF به InvoiceService
|
|
2. ✅ اصلاح متد `_saveInvoice` برای چاپ بعد از ذخیره
|
|
3. ✅ استفاده از تنظیمات پیش‌فرض از BusinessPrintSettings
|
|
|
|
### اولویت متوسط:
|
|
4. ✅ بارگذاری تنظیمات چاپ کسب‌وکار
|
|
5. ✅ لیست قالب‌های چاپ واقعی
|
|
6. ✅ بهبود تجربه کاربری (loading, error handling)
|
|
|
|
### اولویت پایین (ویژگی‌های پیشرفته):
|
|
7. ✅ لیست پرینترهای واقعی
|
|
8. ✅ چاپ مستقیم به پرینتر
|
|
9. ✅ ذخیره تنظیمات کاربر
|
|
|
|
---
|
|
|
|
## نکات فنی
|
|
|
|
### API Endpoints مرتبط:
|
|
- `GET /invoices/business/{business_id}/{invoice_id}/pdf` - دریافت PDF فاکتور
|
|
- Query parameters: `template_id`, `paper_size`, `orientation`, `disposition`
|
|
- `GET /businesses/{business_id}/print-settings` - دریافت تنظیمات چاپ
|
|
- `PUT /businesses/{business_id}/print-settings` - به‌روزرسانی تنظیمات چاپ
|
|
|
|
### فایل‌های مرتبط:
|
|
- `hesabixUI/hesabix_ui/lib/pages/business/new_invoice_page.dart` - صفحه فاکتور جدید
|
|
- `hesabixUI/hesabix_ui/lib/services/invoice_service.dart` - سرویس فاکتور
|
|
- `hesabixUI/hesabix_ui/lib/services/business_api_service.dart` - سرویس کسب‌وکار
|
|
- `hesabixUI/hesabix_ui/lib/core/api_client.dart` - کلاینت API
|
|
- `hesabixAPI/adapters/api/v1/invoices.py` - API endpoint فاکتورها
|
|
- `hesabixAPI/app/services/business_service.py` - سرویس کسب‌وکار (backend)
|
|
|
|
### مدل‌های مرتبط:
|
|
- `BusinessPrintSettings` - تنظیمات چاپ کسب‌وکار
|
|
- `ReportTemplate` - قالب‌های گزارش
|
|
|
|
---
|
|
|
|
## تاریخچه تغییرات
|
|
|
|
- **2024-XX-XX**: ایجاد فایل TODO اولیه
|
|
|