hesabixArc/docs/EMAIL_SERVICE_README.md

سرویس ایمیل حسابیکس

نمای کلی

سرویس ایمیل حسابیکس یک سیستم داخلی برای ارسال ایمیل است که توسعه‌دهندگان می‌توانند به راحتی از آن استفاده کنند. این سرویس از SMTP استفاده می‌کند و تنظیمات اتصال در دیتابیس ذخیره می‌شود.

ویژگی‌ها

• ✅ ارسال ایمیل با SMTP
• ✅ پشتیبانی از TLS و SSL
• ✅ ذخیره تنظیمات در دیتابیس
• ✅ مدیریت چندین پیکربندی
• ✅ تست اتصال
• ✅ رابط کاربری برای مدیریت
• ✅ پشتیبانی از چندزبانه (فارسی/انگلیسی)
• ✅ امنیت و رمزگذاری

ساختار فایل‌ها

Backend

hesabixAPI/
├── adapters/db/models/email_config.py          # مدل دیتابیس
├── adapters/db/repositories/email_config_repository.py  # Repository
├── adapters/api/v1/schema_models/email.py      # Schema models
├── adapters/api/v1/admin/email_config.py       # API endpoints
├── app/services/email_service.py               # سرویس اصلی
└── locales/
    ├── fa/LC_MESSAGES/messages.po              # ترجمه‌های فارسی
    └── en/LC_MESSAGES/messages.po              # ترجمه‌های انگلیسی

Frontend

hesabixUI/hesabix_ui/lib/
├── models/email_models.dart                    # مدل‌های Flutter
├── services/email_service.dart                 # سرویس Flutter
├── pages/admin/email_settings_page.dart        # صفحه مدیریت
└── l10n/
    ├── app_fa.arb                              # ترجمه‌های فارسی
    └── app_en.arb                              # ترجمه‌های انگلیسی

استفاده برای توسعه‌دهندگان

1. ارسال ایمیل ساده

import 'package:hesabix_ui/services/email_service.dart';

final emailService = EmailService();

// ارسال ایمیل سفارشی
await emailService.sendCustomEmail(
  to: 'user@example.com',
  subject: 'عنوان ایمیل',
  body: 'متن ایمیل',
  htmlBody: '<h1>عنوان</h1><p>متن</p>',
);

2. ارسال ایمیل خوش‌آمدگویی

await emailService.sendWelcomeEmail(
  'user@example.com',
  'نام کاربر',
);

3. ارسال ایمیل بازیابی رمز عبور

await emailService.sendPasswordResetEmail(
  'user@example.com',
  'https://example.com/reset?token=abc123',
);

4. ارسال ایمیل اطلاع‌رسانی

await emailService.sendNotificationEmail(
  'user@example.com',
  'عنوان اطلاع‌رسانی',
  'پیام اطلاع‌رسانی',
);

مدیریت تنظیمات

1. دسترسی به صفحه تنظیمات

1. وارد بخش "تنظیمات سیستم" شوید
2. روی "تنظیمات ایمیل" کلیک کنید

2. افزودن پیکربندی جدید

1. فرم را پر کنید:

   • نام پیکربندی: نام منحصر به فرد
   • میزبان SMTP: آدرس سرور SMTP
   • پورت SMTP: پورت سرور (معمولاً 587 یا 465)
   • نام کاربری: نام کاربری SMTP
   • رمز عبور: رمز عبور SMTP
   • ایمیل فرستنده: آدرس ایمیل فرستنده
   • نام فرستنده: نام نمایشی فرستنده
   • TLS/SSL: نوع رمزگذاری

2. روی "ذخیره پیکربندی" کلیک کنید

3. تست اتصال

1. پیکربندی مورد نظر را انتخاب کنید
2. روی "تست اتصال" کلیک کنید
3. وضعیت اتصال نمایش داده می‌شود

4. ارسال ایمیل تست

1. پیکربندی مورد نظر را انتخاب کنید
2. روی "ارسال ایمیل تست" کلیک کنید
3. ایمیل تست به آدرس "ایمیل فرستنده" ارسال می‌شود

API Endpoints

مدیریت پیکربندی‌ها

• GET /api/v1/admin/email/configs - دریافت لیست پیکربندی‌ها
• GET /api/v1/admin/email/configs/{id} - دریافت پیکربندی خاص
• POST /api/v1/admin/email/configs - ایجاد پیکربندی جدید
• PUT /api/v1/admin/email/configs/{id} - بروزرسانی پیکربندی
• DELETE /api/v1/admin/email/configs/{id} - حذف پیکربندی

تست و ارسال

• POST /api/v1/admin/email/configs/{id}/test - تست اتصال
• POST /api/v1/admin/email/configs/{id}/activate - فعال‌سازی پیکربندی
• POST /api/v1/admin/email/send - ارسال ایمیل

امنیت

• رمزهای عبور SMTP در دیتابیس ذخیره می‌شوند (باید رمزگذاری شوند)
• تمام endpoint ها نیاز به احراز هویت دارند
• تست اتصال قبل از فعال‌سازی انجام می‌شود

چندزبانه

فارسی

• تمام متن‌ها به فارسی ترجمه شده‌اند
• پشتیبانی از RTL
• فرمت تاریخ شمسی

انگلیسی

• پشتیبانی کامل از انگلیسی
• فرمت تاریخ میلادی

عیب‌یابی

مشکلات رایج

1. خطا در اتصال SMTP

   • بررسی صحت آدرس میزبان و پورت
   • بررسی نام کاربری و رمز عبور
   • بررسی تنظیمات TLS/SSL

2. ایمیل ارسال نمی‌شود

   • بررسی پیکربندی فعال
   • تست اتصال
   • بررسی لاگ‌های سرور

3. خطا در رابط کاربری

   • بررسی اتصال به API
   • بررسی مجوزهای کاربر
   • بررسی ترجمه‌ها

لاگ‌ها

• لاگ‌های ارسال ایمیل در console نمایش داده می‌شوند
• خطاهای SMTP در response API نمایش داده می‌شوند

توسعه آینده

ویژگی‌های پیشنهادی

• سیستم قالب‌های ایمیل
• صف ارسال ایمیل
• آمار ارسال
• لاگ‌گیری کامل
• رمزگذاری رمزهای عبور
• پشتیبانی از چندین ارائه‌دهنده SMTP
• تست خودکار اتصال

بهبودهای فنی

• Cache کردن پیکربندی‌ها
• Connection pooling
• Retry mechanism
• Rate limiting
• Monitoring و alerting

پشتیبانی

برای گزارش مشکلات یا درخواست ویژگی‌های جدید، لطفاً با تیم توسعه تماس بگیرید.

---

نسخه: 1.0.0
تاریخ: 2025-01-17
نویسنده: تیم توسعه حسابیکس