arc/docs/IDENTITY_INQUIRY_DIALOG.md

دیالوگ استعلام اطلاعات هویتی

Identity Inquiry Dialog

📋 توضیحات / Description

یک دیالوگ مستقل، زیبا و چند زبانه برای استعلام اطلاعات هویتی (کد ملی و تاریخ تولد) در سیستم حسابیکس.

A standalone, beautiful, and multilingual dialog for identity inquiry (national ID and birth date) in Hesabix system.

✨ ویژگی‌ها / Features

🎨 طراحی زیبا و مدرن / Beautiful & Modern Design

• رابط کاربری جذاب با گرادینت‌های رنگی
• انیمیشن‌ها و افکت‌های بصری
• طراحی ریسپانسیو برای اندازه‌های مختلف صفحه
• استفاده از Material Design 3

🌍 چند زبانه / Multilingual

• پشتیبانی کامل از فارسی و انگلیسی
• تمام متن‌ها به صورت دوزبانه نمایش داده می‌شوند
• استفاده از سیستم i18n موجود در پروژه

✅ اعتبارسنجی قوی / Strong Validation

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

📊 نمایش نتایج / Results Display

• نمایش اطلاعات شخصی با طراحی کارت‌گونه
• نمایش وضعیت حیات با آیکون و رنگ مناسب
• قابلیت کپی کردن اطلاعات با یک کلیک
• مدیریت حالت‌های مختلف: موفقیت، خطا، عدم تطابق

🔐 امنیت / Security

• ارسال امن درخواست به API
• مدیریت صحیح خطاها
• اطلاعات محرمانه کاربر محافظت می‌شود

📦 نصب و استفاده / Installation & Usage

1. فایل قرار گرفته در:

lib/widgets/zohal/identity_inquiry_dialog.dart

2. Import کردن:

import 'package:hesabix_ui/widgets/zohal/identity_inquiry_dialog.dart';

3. نمایش دیالوگ:

روش ساده:

await IdentityInquiryDialog.show(
  context,
  businessId: currentBusinessId,
);

دریافت نتیجه:

final result = await IdentityInquiryDialog.show(
  context,
  businessId: currentBusinessId,
);

if (result != null) {
  final data = result['result']?['response_body']?['data'];
  print('نام: ${data['first_name']} ${data['last_name']}');
}

🎯 موارد استفاده / Use Cases

1. در منوی استعلامات:

ListTile(
  leading: const Icon(Icons.person_search),
  title: const Text('استعلام اطلاعات هویتی'),
  subtitle: const Text('Identity Inquiry'),
  onTap: () => IdentityInquiryDialog.show(
    context,
    businessId: widget.businessId,
  ),
)

2. در Floating Action Button:

floatingActionButton: FloatingActionButton.extended(
  onPressed: () => IdentityInquiryDialog.show(
    context,
    businessId: businessId,
  ),
  icon: const Icon(Icons.person_search),
  label: const Text('استعلام هویتی'),
)

3. در AppBar:

actions: [
  IconButton(
    icon: const Icon(Icons.person_search),
    tooltip: 'استعلام اطلاعات هویتی',
    onPressed: () => IdentityInquiryDialog.show(
      context,
      businessId: businessId,
    ),
  ),
]

4. در فرم ثبت مشتری:

ElevatedButton.icon(
  onPressed: () async {
    final result = await IdentityInquiryDialog.show(
      context,
      businessId: businessId,
    );
    
    if (result != null) {
      final data = result['result']?['response_body']?['data'];
      if (data?['matched'] == true) {
        // پر کردن خودکار فرم
        firstNameController.text = data['first_name'] ?? '';
        lastNameController.text = data['last_name'] ?? '';
        nationalIdController.text = data['national_code'] ?? '';
      }
    }
  },
  icon: const Icon(Icons.auto_fix_high),
  label: const Text('تکمیل خودکار از طریق استعلام'),
)

📸 اسکرین‌شات‌ها / Screenshots

فرم ورودی / Input Form

┌─────────────────────────────────────┐
│  🔍 استعلام اطلاعات هویتی          │
│     Identity Inquiry                │
├─────────────────────────────────────┤
│  ℹ️ لطفاً کد ملی و تاریخ تولد را    │
│     وارد کنید                       │
│                                     │
│  🪪 کد ملی / National ID           │
│  [1234567890]                       │
│  کد ملی 10 رقمی                    │
│                                     │
│  📅 تاریخ تولد / Birth Date         │
│  [1370-01-01]           📆          │
│  تاریخ شمسی                         │
│                                     │
│              [🔍 استعلام / Inquire] │
└─────────────────────────────────────┘

نمایش نتیجه موفق / Success Result

┌─────────────────────────────────────┐
│  👤                                 │
│  محمد محمدی                         │
│  🪪 1234567890                      │
│  [✅ زنده / Alive]                  │
├─────────────────────────────────────┤
│  👤 اطلاعات شخصی                    │
│  ─────────────────────────────────  │
│  🪪 نام / First Name                │
│     محمد                      📋    │
│                                     │
│  🪪 نام خانوادگی / Last Name       │
│     محمدی                     📋    │
│                                     │
│  👨‍👩‍👦 نام پدر / Father Name          │
│     علی                       📋    │
│                                     │
│  [🔄 استعلام جدید]    [✅ بستن]    │
└─────────────────────────────────────┘

نمایش خطا / Error Display

┌─────────────────────────────────────┐
│          ⚠️                         │
│     عدم تطابق                       │
│     No Match                        │
│                                     │
│  کد ملی و تاریخ تولد با یکدیگر     │
│  مطابقت ندارند                      │
│                                     │
│  [🔄 استعلام جدید]    [✅ بستن]    │
└─────────────────────────────────────┘

🔧 پارامترها / Parameters

پارامتر	نوع	الزامی	توضیحات
businessId	int?	خیر	شناسه کسب‌وکار برای ارسال به API

📤 خروجی / Output

در صورت موفقیت، یک Map<String, dynamic> برمی‌گرداند که شامل:

{
  "result": {
    "response_body": {
      "data": {
        "matched": true,
        "first_name": "محمد",
        "last_name": "محمدی",
        "father_name": "علی",
        "national_code": "1234567890",
        "alive": true,
        "is_dead": false
      },
      "message": "عملیات موفق",
      "error_code": null
    }
  }
}

در صورت انصراف کاربر، null برمی‌گرداند.

🎨 سفارشی‌سازی / Customization

تغییر رنگ‌ها:

دیالوگ به صورت خودکار از Theme اپلیکیشن استفاده می‌کند. برای تغییر رنگ‌ها، تم اپلیکیشن را تغییر دهید:

MaterialApp(
  theme: ThemeData(
    colorScheme: ColorScheme.fromSeed(
      seedColor: Colors.blue,
    ),
  ),
)

تغییر متن‌ها:

متن‌ها از سیستم i18n استفاده می‌کنند. برای افزودن یا تغییر متن‌ها:

1. فایل lib/l10n/app_fa.arb را ویرایش کنید
2. فایل lib/l10n/app_en.arb را ویرایش کنید
3. دستور flutter gen-l10n را اجرا کنید

🧪 تست / Testing

برای تست دیالوگ:

testWidgets('Identity inquiry dialog test', (WidgetTester tester) async {
  await tester.pumpWidget(
    MaterialApp(
      home: Scaffold(
        body: Builder(
          builder: (context) => ElevatedButton(
            onPressed: () => IdentityInquiryDialog.show(
              context,
              businessId: 1,
            ),
            child: const Text('Test'),
          ),
        ),
      ),
    ),
  );
  
  await tester.tap(find.text('Test'));
  await tester.pumpAndSettle();
  
  expect(find.text('استعلام اطلاعات هویتی'), findsOneWidget);
});

📝 نکات مهم / Important Notes

1. اتصال به API: اطمینان حاصل کنید که ApiClient به درستی پیکربندی شده است.

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

3. وابستگی‌ها: این دیالوگ به موارد زیر وابسته است:

   • AppLocalizations (i18n)
   • ApiClient
   • NumberNormalizer
   • SnackBarHelper

4. تطابق با Material Design 3: این دیالوگ با MD3 سازگار است و از کامپوننت‌های جدید استفاده می‌کند.

5. Responsive Design: دیالوگ در اندازه‌های مختلف صفحه (موبایل، تبلت، دسکتاپ) به خوبی کار می‌کند.

🐛 رفع مشکلات / Troubleshooting

خطای "ApiClient not found"

// اطمینان حاصل کنید که ApiClient به درستی import شده است:
import 'package:hesabix_ui/core/api_client.dart';

خطای "AppLocalizations not found"

// اطمینان حاصل کنید که i18n تنظیم شده است:
MaterialApp(
  localizationsDelegates: AppLocalizations.localizationsDelegates,
  supportedLocales: AppLocalizations.supportedLocales,
)

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

// اطمینان حاصل کنید که context معتبر است:
Builder(
  builder: (context) => ElevatedButton(
    onPressed: () => IdentityInquiryDialog.show(context),
  ),
)

🔄 به‌روزرسانی‌ها / Updates

نسخه 1.0.0 (2024-12-04)

• ✅ ایجاد اولیه دیالوگ
• ✅ پشتیبانی کامل از دو زبان
• ✅ اعتبارسنجی کامل ورودی‌ها
• ✅ نمایش نتایج با طراحی زیبا
• ✅ مدیریت خطاها
• ✅ قابلیت کپی اطلاعات

📞 پشتیبانی / Support

در صورت بروز مشکل یا نیاز به راهنمایی:

• مستندات: /docs/IDENTITY_INQUIRY_DIALOG.md
• مثال استفاده: lib/widgets/zohal/identity_inquiry_dialog_example.dart
• تیکت پشتیبانی: از بخش Support در اپلیکیشن

📄 مجوز / License

این کامپوننت بخشی از پروژه Hesabix است و تحت مجوز پروژه منتشر شده است.

---

نکته: این دیالوگ می‌تواند به راحتی برای سایر انواع استعلامات نیز تعمیم داده شود.