arc/docs/INVOICE_PRINT_FEATURE_TODO.md

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، می‌توان از کد زیر استفاده کرد:

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 اولیه