278 lines
12 KiB
Markdown
Executable file
278 lines
12 KiB
Markdown
Executable file
# فرآیند فعال‌سازی گارانتی - گزارش بررسی
|
|
|
|
این سند فرآیند کامل فعال‌سازی گارانتی یک محصول را در سیستم شرح می‌دهد.
|
|
|
|
## مراحل کلی فرآیند
|
|
|
|
### مرحله 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**:
|
|
```json
|
|
{
|
|
"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. به‌روزرسانی وضعیت گارانتی
|
|
```python
|
|
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
|
|
|
|
پس از فعال‌سازی موفق، پاسخ شامل موارد زیر است:
|
|
|
|
```json
|
|
{
|
|
"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. مشتری باید علاوه بر کد و سریال گارانتی، سریال کالا را هم وارد کند:
|
|
```json
|
|
{
|
|
"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 قابل انجام است.
|
|
|
|
|