Seyyed_arc/docs/ZOHAL_INQUIRIES_INTEGRATION.md

یکپارچه‌سازی دیالوگ استعلام هویتی با صفحه استعلامات

Identity Inquiry Dialog Integration with Inquiries Page

📋 خلاصه تغییرات / Summary

دیالوگ شخصی‌سازی شده استعلام اطلاعات هویتی به صفحه استعلامات (ZohalInquiriesPage) یکپارچه شد.

The custom Identity Inquiry Dialog has been integrated into the Inquiries Page.

---

🔄 تغییرات انجام شده / Changes Made

1️⃣ فایل تغییر یافته / Modified File

📍 hesabixUI/hesabix_ui/lib/pages/business/zohal_inquiries_page.dart

2️⃣ تغییرات کد / Code Changes

✅ افزودن Import:

import '../../widgets/zohal/identity_inquiry_dialog.dart';

✅ تغییر متد _selectService:

قبل از انتخاب سرویس، بررسی می‌شود که آیا سرویس "استعلام اطلاعات هویتی" است یا خیر:

void _selectService(Map<String, dynamic> service) async {
  final serviceCode = service['service_code']?.toString() ?? '';
  
  // برای استعلام اطلاعات هویتی، دیالوگ شخصی‌سازی شده را نمایش می‌دهیم
  if (_isIdentityInquiry(serviceCode)) {
    await _showIdentityInquiryDialog();
    return;
  }
  
  // ... بقیه کد
}

✅ افزودن متد _isIdentityInquiry:

برای شناسایی سرویس استعلام هویتی:

bool _isIdentityInquiry(String serviceCode) {
  final normalized = serviceCode.toLowerCase().replaceAll('/', '_').replaceAll('-', '_');
  return normalized.contains('identity') || 
         normalized.contains('national_identity') ||
         normalized.contains('national_code') ||
         serviceCode.contains('national_identity_inquiry');
}

✅ افزودن متد _showIdentityInquiryDialog:

برای نمایش دیالوگ و مدیریت نتیجه:

Future<void> _showIdentityInquiryDialog() async {
  final result = await IdentityInquiryDialog.show(
    context,
    businessId: widget.businessId,
  );

  if (result != null) {
    // به‌روزرسانی موجودی کیف پول
    await _load();
    
    // نمایش نتیجه در صفحه (اختیاری)
    setState(() {
      _lastResult = result;
    });
  }
}

---

🎯 نحوه کارکرد / How It Works

مراحل اجرا / Execution Flow:

1. کاربر وارد صفحه استعلامات می‌شود
   ↓
2. لیست سرویس‌های موجود نمایش داده می‌شود
   ↓
3. کاربر روی "استعلام اطلاعات هویتی" کلیک می‌کند
   ↓
4. سیستم تشخیص می‌دهد این سرویس identity inquiry است
   ↓
5. به جای فرم عمومی، دیالوگ زیبای شخصی‌سازی شده نمایش داده می‌شود
   ↓
6. کاربر اطلاعات را وارد می‌کند و استعلام را انجام می‌دهد
   ↓
7. نتیجه در دیالوگ نمایش داده می‌شود
   ↓
8. پس از بستن دیالوگ، موجودی کیف پول به‌روزرسانی می‌شود

تصویر مقایسه / Comparison:

❌ قبل (فرم عمومی):

┌─────────────────────────────┐
│ فرم استعلام                 │
├─────────────────────────────┤
│ national_code: [_________]  │
│ birth_date:    [_________]  │
│                             │
│        [ارسال درخواست]      │
└─────────────────────────────┘

✅ بعد (دیالوگ شخصی‌سازی شده):

┌──────────────────────────────────┐
│  🔍 استعلام اطلاعات هویتی       │
│     Identity Inquiry             │
├──────────────────────────────────┤
│  ℹ️ لطفاً کد ملی و تاریخ تولد را │
│     وارد کنید                    │
│                                  │
│  🪪 کد ملی / National ID        │
│  [_________________]             │
│  ✓ اعتبارسنجی کامل کد ملی      │
│                                  │
│  📅 تاریخ تولد / Birth Date      │
│  [_________________] 📆          │
│  ✓ اعتبارسنجی فرمت تاریخ       │
│                                  │
│           [🔍 استعلام / Inquire] │
└──────────────────────────────────┘

---

✨ مزایای تغییرات / Benefits

1. تجربه کاربری بهتر / Better UX

• ✅ رابط کاربری زیبا و حرفه‌ای
• ✅ راهنمایی‌های واضح برای کاربر
• ✅ نمایش نتایج با طراحی مدرن

2. اعتبارسنجی قوی‌تر / Stronger Validation

• ✅ الگوریتم استاندارد کد ملی
• ✅ بررسی فرمت تاریخ شمسی
• ✅ پیام‌های خطای واضح

3. چند زبانگی کامل / Full Multilingual

• ✅ تمام متن‌ها به دو زبان فارسی و انگلیسی
• ✅ سازگار با سیستم i18n موجود

4. نمایش نتایج بهتر / Better Results Display

• ✅ کارت‌های اطلاعاتی زیبا
• ✅ نمایش وضعیت حیات
• ✅ قابلیت کپی اطلاعات

5. سازگاری با سایر سرویس‌ها / Compatibility

• ✅ سایر سرویس‌ها همچنان با فرم عمومی کار می‌کنند
• ✅ عدم تداخل با عملکرد فعلی

---

🔍 شناسایی سرویس / Service Detection

دیالوگ برای سرویس‌هایی نمایش داده می‌شود که service_code آنها شامل یکی از موارد زیر باشد:

• identity
• national_identity
• national_code
• national_identity_inquiry

مثال‌های Service Code:

✅ نمایش دیالوگ:

• /services/inquiry/national_identity_inquiry
• /services/identity
• /services/national-code-inquiry
• identity_verification

❌ نمایش فرم عمومی:

• /services/inquiry/card_inquiry
• /services/company_inquiry
• /services/vehicle_inquiry

---

🧪 تست / Testing

تست دستی / Manual Testing:

1. وارد صفحه استعلامات شوید:

   /business/{id}/zohal/inquiries
   

2. فیلتر را روی "احراز هویت" قرار دهید

3. روی سرویس "استعلام اطلاعات هویتی" کلیک کنید

4. بررسی کنید که دیالوگ شخصی‌سازی شده نمایش داده می‌شود

5. یک استعلام نمونه انجام دهید:

   • کد ملی: یک کد ملی معتبر
   • تاریخ تولد: مثلاً 1370-01-01

6. نتیجه را بررسی کنید

7. موجودی کیف پول را بررسی کنید (باید به‌روز شده باشد)

تست خودکار / Automated Testing:

testWidgets('Identity inquiry uses custom dialog', (WidgetTester tester) async {
  // Build ZohalInquiriesPage
  await tester.pumpWidget(
    MaterialApp(
      home: ZohalInquiriesPage(
        businessId: 1,
        authStore: mockAuthStore,
      ),
    ),
  );
  
  // Wait for services to load
  await tester.pumpAndSettle();
  
  // Tap on identity inquiry service
  await tester.tap(find.text('استعلام اطلاعات هویتی'));
  await tester.pumpAndSettle();
  
  // Verify custom dialog is shown
  expect(find.text('Identity Inquiry'), findsOneWidget);
  expect(find.text('کد ملی / National ID'), findsOneWidget);
});

---

📝 یادداشت‌های توسعه / Development Notes

1. افزودن سرویس‌های جدید / Adding New Services

اگر می‌خواهید برای سرویس دیگری هم دیالوگ شخصی‌سازی شده داشته باشید:

void _selectService(Map<String, dynamic> service) async {
  final serviceCode = service['service_code']?.toString() ?? '';
  
  // استعلام اطلاعات هویتی
  if (_isIdentityInquiry(serviceCode)) {
    await _showIdentityInquiryDialog();
    return;
  }
  
  // استعلام کارت بانکی (مثال)
  if (_isCardInquiry(serviceCode)) {
    await _showCardInquiryDialog();
    return;
  }
  
  // ... فرم عمومی برای بقیه
}

2. مدیریت خطاها / Error Handling

خطاها در داخل دیالوگ مدیریت می‌شوند و نیازی به مدیریت خارجی نیست:

// دیالوگ خودش خطاها را مدیریت می‌کند
final result = await IdentityInquiryDialog.show(context, businessId: id);

// اگر result null بود یعنی کاربر کنسل کرده
if (result == null) {
  // کاربر دیالوگ را بست
  return;
}

// اگر result مقداری داشت، موفق بوده

3. به‌روزرسانی موجودی / Balance Update

پس از هر استعلام موفق، موجودی به‌روز می‌شود:

if (result != null) {
  await _load(); // بارگذاری مجدد اطلاعات صفحه
}

---

🔧 عیب‌یابی / Troubleshooting

مشکل: دیالوگ نمایش داده نمی‌شود

علت: احتمالاً service_code به درستی تشخیص داده نمی‌شود.

راه حل:

1. service_code را در API بررسی کنید
2. لاگ اضافه کنید:

   if (_isIdentityInquiry(serviceCode)) {
     debugPrint('Showing identity dialog for: $serviceCode');
     await _showIdentityInquiryDialog();
     return;
   }
   

مشکل: موجودی به‌روز نمی‌شود

علت: متد _load() بعد از دیالوگ صدا زده نمی‌شود.

راه حل: مطمئن شوید که بعد از result != null متد _load() فراخوانی می‌شود.

مشکل: خطای Import

علت: فایل دیالوگ پیدا نمی‌شود.

راه حل: مطمئن شوید فایل در مسیر صحیح است:

lib/widgets/zohal/identity_inquiry_dialog.dart

---

📊 آمار / Statistics

• خطوط کد اضافه شده: ~50 خط
• خطوط کد حذف شده: 0 خط
• فایل‌های تغییر یافته: 1 فایل
• Linter errors: 0 ❌
• Breaking changes: 0 ❌
• Backward compatible: ✅

---

✅ چک‌لیست / Checklist

• دیالوگ ایجاد شد
• Import به صفحه اضافه شد
• متد _selectService تغییر کرد
• متد _isIdentityInquiry اضافه شد
• متد _showIdentityInquiryDialog اضافه شد
• خطاها رفع شدند
• تست دستی انجام شد
• مستندات نوشته شد

---

📞 پشتیبانی / Support

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

1. مستندات دیالوگ: /docs/IDENTITY_INQUIRY_DIALOG.md
2. این مستندات: /docs/ZOHAL_INQUIRIES_INTEGRATION.md
3. تیکت پشتیبانی در سیستم

---

تاریخ یکپارچه‌سازی: 2024-12-04 نسخه: 1.0.0 وضعیت: ✅ فعال و آماده استفاده