arc/docs/WARRANTY_ACTIVATION_PROCESS.md

فرآیند فعال‌سازی گارانتی - گزارش بررسی

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

مراحل کلی فرآیند

مرحله 1: تولید کدهای گارانتی (پیش از فعال‌سازی)

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

Endpoint: POST /api/v1/warranty/business/{business_id}/generate

پارامترهای مورد نیاز:

• product_id: شناسه کالا
• quantity: تعداد کدهای مورد نیاز
• warranty_duration_days: مدت گارانتی به روز (مثلاً 365 روز)
• code_format: فرمت کد (random, sequential, custom)
• serial_format: فرمت سریال (random, custom)
• custom_codes: لیست کدهای دلخواه (در صورت استفاده از فرمت custom)
• custom_serials: لیست سریال‌های دلخواه (در صورت استفاده از فرمت custom)

نتیجه: لیستی از کدهای گارانتی تولید شده با:

• code: کد گارانتی (مثلاً WR-ABC12345)
• warranty_serial: سریال گارانتی (مثلاً XYZ789012)
• status: وضعیت که در ابتدا generated است
• expires_at: تاریخ انقضا

---

مرحله 2: فعال‌سازی گارانتی توسط مشتری

مشتری می‌تواند گارانتی را از طریق endpoint عمومی فعال کند.

روش فعال‌سازی

از طریق UI (فرانت‌اند)

مسیر: صفحه عمومی فعال‌سازی گارانتی

فرم فعال‌سازی شامل فیلدهای زیر است:

فیلدهای الزامی:

1. کد گارانتی (warranty_code): کد تولید شده در مرحله قبل
2. سریال گارانتی (warranty_serial): سریال تولید شده در مرحله قبل
3. نام مشتری (customer_name)
4. شماره تماس (customer_phone)

فیلدهای اختیاری:

5. ایمیل مشتری (customer_email)
6. سریال کالا (product_serial): در صورتی که نیاز به تأیید سریال کالا باشد

از طریق API

Endpoint: POST /api/v1/warranty/public/activate

مشخصات:

• عمومی است (نیازی به احراز هویت ندارد)
• IP آدرس و User Agent خودکار ثبت می‌شود

Request Body:

{
  "warranty_code": "WR-ABC12345",
  "warranty_serial": "XYZ789012",
  "customer_name": "علی احمدی",
  "customer_phone": "09123456789",
  "customer_email": "ali@example.com",  // اختیاری
  "product_serial": "PROD-SERIAL-123"    // اختیاری
}

بررسی‌های انجام شده در فرآیند فعال‌سازی

1. بررسی وجود کد گارانتی

• سیستم کد گارانتی را در دیتابیس جستجو می‌کند
• در صورت عدم یافتن: خطای WARRANTY_CODE_NOT_FOUND

2. بررسی فعال بودن پلاگین

• بررسی می‌کند که پلاگین گارانتی برای کسب و کار فعال باشد
• در صورت غیرفعال بودن: خطای PLUGIN_NOT_ACTIVE

3. بررسی صحت سریال گارانتی

• سریال وارد شده باید با سریال ثبت شده در دیتابیس مطابقت داشته باشد
• در صورت عدم تطابق: خطای INVALID_WARRANTY_SERIAL

4. بررسی وضعیت گارانتی

گارانتی باید در وضعیت generated باشد:

• اگر قبلاً فعال شده: خطای WARRANTY_ALREADY_ACTIVATED
• اگر منقضی شده: خطای WARRANTY_EXPIRED
• اگر لغو شده: خطای WARRANTY_REVOKED
• اگر وضعیت نامعتبر: خطای INVALID_WARRANTY_STATUS

5. بررسی تاریخ انقضا

• اگر expires_at وجود داشته باشد و تاریخ گذشته باشد، گارانتی منقضی می‌شود
• در صورت انقضا: خطای WARRANTY_EXPIRED

6. بررسی محدودیت تلاش‌های فعال‌سازی

• سیستم تعداد تلاش‌های ناموفق را در cache نگه می‌دارد
• اگر تعداد تلاش‌ها بیش از حد مجاز باشد، کاربر قفل می‌شود
• در صورت قفل: خطای TOO_MANY_ATTEMPTS با مدت زمان قفل

7. بررسی نیاز به تأیید سریال کالا (شرطی)

اگر در تنظیمات گارانتی (require_serial_verification یا require_product_instance_match) فعال باشد:

• سریال کالا باید وارد شود
• سیستم ProductInstance را جستجو می‌کند
• در صورت عدم یافتن: خطای PRODUCT_SERIAL_NOT_FOUND

فرآیند فعال‌سازی پس از بررسی‌ها

1. اتصال به Person (در صورت فعال بودن)

• اگر auto_link_to_person در تنظیمات فعال باشد:
  • سیستم بر اساس شماره تماس، Person را در سیستم جستجو می‌کند
  • اگر Person یافت شود، به گارانتی متصل می‌شود

2. به‌روزرسانی وضعیت گارانتی

warranty_code.status = "activated"
warranty_code.activated_at = datetime.utcnow()
warranty_code.activated_by_person_id = person.id if person else None

3. ثبت اطلاعات مشتری

• اگر Person یافت نشد، اطلاعات مشتری در activated_by_customer_info ذخیره می‌شود
• شامل: نام، تلفن، ایمیل

4. اتصال به ProductInstance (در صورت وجود)

• اگر سریال کالا تأیید شد، product_instance_id تنظیم می‌شود

5. ایجاد لینک رهگیری (در صورت فعال بودن)

اگر enable_tracking_link در تنظیمات فعال باشد و Person وجود داشته باشد:

• یک کد یکتا برای لینک رهگیری تولید می‌شود
• لینک رهگیری با تاریخ انقضا (در صورت تنظیم) ایجاد می‌شود
• کد لینک در tracking_link_code ذخیره می‌شود

6. ثبت سابقه فعال‌سازی

• یک رکورد در جدول warranty_activations ایجاد می‌شود
• شامل تمام اطلاعات ورودی، IP، User Agent، و روش تأیید

7. ثبت رویداد رهگیری

• یک رویداد از نوع activation در جدول warranty_tracking ثبت می‌شود
• برای تاریخچه تغییرات گارانتی

8. پاک کردن تلاش‌های ناموفق

• پس از موفقیت، تعداد تلاش‌های ناموفق از cache پاک می‌شود

پاسخ API

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

{
  "id": 123,
  "code": "WR-ABC12345",
  "warranty_serial": "XYZ789012",
  "status": "activated",
  "activated_at": "2024-01-20T10:30:00Z",
  "expires_at": "2025-01-20T10:30:00Z",
  "tracking_link_code": "TRACK-CODE-123456",  // در صورت وجود
  "person_id": 456  // در صورت اتصال به Person
}

تنظیمات موثر در فرآیند فعال‌سازی

تنظیمات کسب و کار (WarrantySettings):

1. require_serial_verification: نیاز به تأیید سریال کالا
2. require_product_instance_match: نیاز به تطابق با ProductInstance
3. max_activation_attempts: حداکثر تلاش برای فعال‌سازی
4. activation_lockout_duration_minutes: مدت قفل شدن پس از تلاش‌های ناموفق
5. auto_link_to_person: اتصال خودکار به Person
6. enable_tracking_link: فعال‌سازی لینک رهگیری
7. tracking_link_expires_days: مدت اعتبار لینک رهگیری

مثال کامل فرآیند

سناریو 1: فعال‌سازی ساده

1. تولید کد گارانتی (توسط کسب و کار):

   POST /api/v1/warranty/business/1/generate
   {
     "product_id": 100,
     "quantity": 1,
     "warranty_duration_days": 365
   }
   

   نتیجه:

   • code: "WR-ABC12345"
   • warranty_serial: "XYZ789012"

2. فعال‌سازی (توسط مشتری):

   POST /api/v1/warranty/public/activate
   {
     "warranty_code": "WR-ABC12345",
     "warranty_serial": "XYZ789012",
     "customer_name": "علی احمدی",
     "customer_phone": "09123456789"
   }
   

   نتیجه: گارانتی با موفقیت فعال می‌شود

سناریو 2: فعال‌سازی با تأیید سریال

1. در تنظیمات گارانتی: require_serial_verification = true
2. مشتری باید علاوه بر کد و سریال گارانتی، سریال کالا را هم وارد کند:

   {
     "warranty_code": "WR-ABC12345",
     "warranty_serial": "XYZ789012",
     "product_serial": "PROD-SERIAL-123",
     "customer_name": "علی احمدی",
     "customer_phone": "09123456789"
   }
   

3. سیستم سریال کالا را در ProductInstance جستجو می‌کند
4. در صورت تطابق، فعال‌سازی انجام می‌شود

سناریو 3: فعال‌سازی با Person موجود

1. در تنظیمات: auto_link_to_person = true
2. مشتری با شماره تماسی که در سیستم به عنوان Person ثبت شده است فعال‌سازی می‌کند
3. سیستم به صورت خودکار:
   • Person را پیدا می‌کند
   • گارانتی را به Person متصل می‌کند
   • در صورت فعال بودن tracking link، لینک رهگیری ایجاد می‌کند

نکات مهم

1. امنیت:

   • Endpoint فعال‌سازی عمومی است اما محدودیت تلاش دارد
   • IP و User Agent ثبت می‌شود
   • بررسی‌های امنیتی متعددی انجام می‌شود

2. تاریخچه:

   • تمام فعال‌سازی‌ها در warranty_activations ثبت می‌شود
   • رویدادها در warranty_tracking ثبت می‌شود

3. انعطاف‌پذیری:

   • تنظیمات کسب و کار می‌تواند فرآیند را سفارشی کند
   • می‌تواند ساده یا پیچیده باشد

4. یکتایی:

   • هر کد گارانتی فقط یکبار قابل فعال‌سازی است
   • سریال گارانتی یکتا است

خطاهای ممکن

خطا	کد	توضیح
کد گارانتی یافت نشد	WARRANTY_CODE_NOT_FOUND	کد وارد شده در دیتابیس وجود ندارد
پلاگین فعال نیست	PLUGIN_NOT_ACTIVE	پلاگین گارانتی برای کسب و کار فعال نیست
سریال نامعتبر	INVALID_WARRANTY_SERIAL	سریال با کد گارانتی مطابقت ندارد
قبلاً فعال شده	WARRANTY_ALREADY_ACTIVATED	این گارانتی قبلاً فعال شده است
منقضی شده	WARRANTY_EXPIRED	تاریخ انقضای گارانتی گذشته است
لغو شده	WARRANTY_REVOKED	گارانتی توسط کسب و کار لغو شده است
سریال کالا الزامی	PRODUCT_SERIAL_REQUIRED	در تنظیمات نیاز به سریال کالا است
سریال کالا یافت نشد	PRODUCT_SERIAL_NOT_FOUND	سریال کالا در سیستم ثبت نشده است
تلاش بیش از حد	TOO_MANY_ATTEMPTS	تعداد تلاش‌های ناموفق بیش از حد مجاز است

خلاصه

فرآیند فعال‌سازی گارانتی شامل مراحل زیر است:

1. ✅ تولید کد گارانتی (پیش از فعال‌سازی)
2. ✅ ورود اطلاعات توسط مشتری (کد، سریال، اطلاعات مشتری)
3. ✅ انجام بررسی‌های امنیتی و اعتبارسنجی
4. ✅ به‌روزرسانی وضعیت گارانتی به activated
5. ✅ ثبت اطلاعات و ایجاد سوابق
6. ✅ ایجاد لینک رهگیری (در صورت نیاز)
7. ✅ بازگرداندن نتیجه به مشتری

این فرآیند از طریق UI (صفحه عمومی) یا مستقیماً از طریق API قابل انجام است.