arc/docs/TAX_SYSTEM_FIXES.md

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

تاریخ: 2025-12-05

خلاصه تغییرات

این مستند تمامی تغییرات و بهبودهای انجام شده در بخش اتصال به سامانه مودیان مالیاتی را شرح می‌دهد.

---

✅ مشکلات حل شده

1. پیاده‌سازی ارتباط واقعی با API سامانه مودیان

مشکل قبلی: فقط شبیه‌سازی فعال بود و هیچ ارتباط واقعی با سامانه برقرار نمی‌شد.

راه‌حل:

• کامل کردن MoadianClient با متدهای:
  • get_server_information(): دریافت کلید عمومی سرور
  • login(): احراز هویت و دریافت token
  • send_invoice(): ارسال واقعی فاکتور با امضای دیجیتال
  • inquire_status(): استعلام واقعی وضعیت
• مدیریت خودکار token و انقضای آن
• پشتیبانی از Sandbox و Production

فایل‌های تغییر یافته:

• hesabixAPI/app/integrations/moadian/client.py

---

2. ساخت DTO استاندارد فاکتور

مشکل قبلی: فرمت payload با استاندارد سامانه مودیان مطابقت نداشت.

راه‌حل:

• ایجاد InvoiceHeaderDto با تمام فیلدهای الزامی و اختیاری
• ایجاد InvoiceBodyDto برای اقلام فاکتور
• ایجاد InvoicePaymentDto برای روش‌های پرداخت
• ایجاد InvoiceDto به عنوان container کامل
• پشتیبانی از فیلدهای اختیاری و validation

فایل‌های جدید:

• hesabixAPI/app/integrations/moadian/dto.py

---

3. توابع کمکی و اعتبارسنجی

مشکل قبلی: توابع لازم برای تولید شناسه، اعتبارسنجی کدها و... وجود نداشت.

راه‌حل:

• generate_tax_id(): تولید TAXID یکتای 32 کاراکتری
• normalize_invoice_number(): نرمالایز شماره فاکتور
• validate_tax_code(): اعتبارسنجی کد مالیاتی 13 رقمی
• validate_national_id(): اعتبارسنجی کد ملی (10 رقم) و شناسه ملی (11 رقم)
• validate_economic_code(): اعتبارسنجی کد اقتصادی
• extract_moadian_error_message(): تبدیل کدهای خطا به پیام فارسی

فایل‌های جدید:

• hesabixAPI/app/integrations/moadian/utils.py

---

4. ساخت فاکتور از داده‌های داخلی

مشکل قبلی: هیچ سرویسی برای تبدیل فاکتورهای داخلی به فرمت مودیان وجود نداشت.

راه‌حل:

• کلاس InvoiceBuilder برای ساخت DTOها
• _build_header(): ساخت header با تمام فیلدها
• _build_body(): ساخت body از اقلام فاکتور
• _build_payments(): ساخت اطلاعات پرداخت
• تشخیص خودکار نوع فاکتور (عادی/ساده/ابطالی)
• محاسبه خودکار نرخ مالیات

فایل‌های جدید:

• hesabixAPI/app/integrations/moadian/invoice_builder.py

---

5. امضای دیجیتال Payload

مشکل قبلی: هیچ پیاده‌سازی برای امضای دیجیتال وجود نداشت.

راه‌حل:

• متد _sign_payload() در MoadianClient
• استفاده از RSA-SHA256 برای امضا
• تبدیل امضا به base64
• ساختار صحیح payload امضا شده

فایل‌های تغییر یافته:

• hesabixAPI/app/integrations/moadian/client.py

---

6. تکمیل اعتبارسنجی فاکتور

مشکل قبلی: اعتبارسنجی ابتدایی و ناقص بود.

راه‌حل:

• بررسی دقیق کد ملی (10 یا 11 رقم)
• بررسی کد اقتصادی (11 یا 14 رقم)
• بررسی کد مالیاتی کالاها (دقیقا 13 رقم)
• بررسی صحیح بودن مبالغ مالیات (بدون اعشار)
• بررسی منفی نبودن مبالغ
• پیام‌های خطای دقیق با شماره ردیف و نام کالا

فایل‌های تغییر یافته:

• hesabixAPI/app/services/tax_validation_service.py

---

7. رمزنگاری کلید خصوصی

مشکل قبلی: کلید خصوصی به صورت plain text در دیتابیس ذخیره می‌شد.

راه‌حل:

• سرویس EncryptionService با استفاده از Fernet
• رمزنگاری خودکار هنگام ذخیره
• رمزگشایی خودکار هنگام خواندن
• سازگاری با داده‌های قدیمی (fallback)
• استفاده از PBKDF2 برای derive کردن کلید از secret

فایل‌های جدید:

• hesabixAPI/app/services/encryption_service.py

فایل‌های تغییر یافته:

• hesabixAPI/app/services/tax_setting_service.py

---

8. به‌روزرسانی سرویس ارسال

مشکل قبلی: سرویس قدیمی از payload ساده استفاده می‌کرد.

راه‌حل:

• استفاده از InvoiceBuilder برای ساخت DTO
• ارسال InvoiceDto به MoadianClient
• ذخیره نتیجه با جزئیات بیشتر

فایل‌های تغییر یافته:

• hesabixAPI/app/services/tax_submission_service.py

---

9. API تست اتصال

مشکل قبلی: هیچ راهی برای تست اتصال به سامانه قبل از ارسال واقعی وجود نداشت.

راه‌حل:

• Endpoint جدید /tax-settings/business/{id}/test-connection
• تست دریافت اطلاعات سرور
• تست لاگین
• بازگشت جزئیات اتصال

فایل‌های تغییر یافته:

• hesabixAPI/adapters/api/v1/tax_settings.py

---

10. بهبودهای UI (Flutter)

مشکل قبلی: صفحه تنظیمات دکمه تست اتصال نداشت.

راه‌حل:

• اضافه کردن متد testConnection() به TaxSettingsService
• اضافه کردن دکمه "تست اتصال" در صفحه تنظیمات
• نمایش dialog با نتیجه تست
• نشان دادن حالت Sandbox با warning

فایل‌های تغییر یافته:

• hesabixUI/hesabix_ui/lib/services/tax_settings_service.dart
• hesabixUI/hesabix_ui/lib/pages/business/tax_settings_page.dart

---

📁 فایل‌های جدید

hesabixAPI/
├── app/
│   ├── integrations/
│   │   └── moadian/
│   │       ├── dto.py                    # DTOهای استاندارد
│   │       ├── utils.py                  # توابع کمکی
│   │       └── invoice_builder.py        # ساخت فاکتور
│   └── services/
│       └── encryption_service.py         # رمزنگاری

---

📝 فایل‌های تغییر یافته

hesabixAPI/
├── app/
│   ├── integrations/
│   │   └── moadian/
│   │       └── client.py                 # کامل شده با API واقعی
│   └── services/
│       ├── tax_validation_service.py     # اعتبارسنجی کامل
│       ├── tax_setting_service.py        # رمزنگاری کلید
│       └── tax_submission_service.py     # استفاده از DTO
├── adapters/
│   └── api/
│       └── v1/
│           └── tax_settings.py           # endpoint تست اتصال

hesabixUI/
└── hesabix_ui/
    ├── lib/
    │   ├── services/
    │   │   └── tax_settings_service.dart # متد testConnection
    │   └── pages/
    │       └── business/
    │           └── tax_settings_page.dart # دکمه تست اتصال

---

🔧 نحوه استفاده

تست اتصال

// در فلاتر
final service = TaxSettingsService();
final result = await service.testConnection(businessId);

ارسال فاکتور

# در بکند
from app.services.tax_submission_service import send_document_to_tax_system

result = send_document_to_tax_system(db, document)

---

⚙️ تنظیمات لازم

محیط Development

1. در .env یا settings.py موارد زیر را تنظیم کنید:

TAX_SYSTEM_SANDBOX_BASE_URL = "https://sandboxrc.tax.gov.ir"
TAX_SYSTEM_PRODUCTION_BASE_URL = "https://tp.tax.gov.ir"
TAX_SYSTEM_TIMEOUT_SECONDS = 30
TAX_SYSTEM_FORCE_SIMULATION = False  # True برای شبیه‌سازی
SECRET_KEY = "your-secret-key-for-encryption"

2. کلیدهای رمزنگاری موجود رمزنگاری می‌شوند (سازگاری با گذشته)

---

🧪 تست

تست اتصال

1. وارد صفحه تنظیمات مالیاتی شوید
2. تنظیمات را پر کنید (شناسه حافظه، کد اقتصادی، کلید خصوصی)
3. روی "ذخیره" کلیک کنید
4. روی "تست اتصال" کلیک کنید
5. نتیجه در dialog نمایش داده می‌شود

تست ارسال فاکتور

1. فاکتوری ایجاد کنید با:
   • طرف حساب دارای کد ملی
   • کالاهایی با کد مالیاتی 13 رقمی
   • واحد مالیاتی برای هر کالا
2. فاکتور را به کارپوشه مودیان اضافه کنید
3. روی "ارسال به سامانه" کلیک کنید
4. وضعیت ارسال نمایش داده می‌شود

---

🔒 امنیت

• ✅ کلید خصوصی با Fernet رمزنگاری می‌شود
• ✅ کلید رمزنگاری از SECRET_KEY مشتق می‌شود
• ✅ در production باید ENCRYPTION_KEY جداگانه تعریف شود
• ✅ Payload با RSA-SHA256 امضا می‌شود
• ✅ Token احراز هویت به صورت خودکار مدیریت می‌شود

---

📊 وضعیت پوشش (Coverage)

بخش	قبل	بعد
ارتباط با API	❌ 0% (شبیه‌سازی)	✅ 100% (واقعی)
DTO استاندارد	❌ 0%	✅ 100%
امضای دیجیتال	❌ 0%	✅ 100%
اعتبارسنجی	⚠️ 40%	✅ 100%
رمزنگاری کلید	❌ 0%	✅ 100%
تست اتصال	❌ 0%	✅ 100%

---

🚀 مراحل بعدی (اختیاری)

بهبودهای پیشنهادی

1. Celery Task: ارسال گروهی به صورت async
2. Retry Logic: تلاش مجدد خودکار برای فاکتورهای failed
3. Webhook: دریافت نتایج از سامانه به صورت realtime
4. Dashboard: داشبورد آماری از ارسال‌ها
5. Audit Log: جدول جداگانه برای لاگ تمام تراکنش‌ها
6. Rate Limiting: محدود کردن تعداد request به سامانه
7. Queue System: صف برای مدیریت ارسال‌های همزمان
8. Monitoring: اضافه کردن metrics و alerting

---

📞 پشتیبانی

در صورت بروز مشکل:

1. لاگ‌های بکند را بررسی کنید
2. دکمه "تست اتصال" را امتحان کنید
3. گزارش کیفیت داده را بررسی کنید
4. مطمئن شوید تنظیمات صحیح است

---

📚 منابع

• مستندات رسمی سامانه مودیان
• Sandbox مودیان
• راهنمای استفاده قدیمی
• وضعیت پیاده‌سازی