hesabixCore/docs/accounting/REASONABLE_CODE_GENERATION.md

# تولید کدهای معقول حسابداری

## مشکل
کدهای تولید شده خیلی بلند و خارج از عرف حسابداری بودند (مثل `1,756,382,866,131,764`).

## راه‌حل‌های پیاده‌سازی شده

### 1. محدودیت طول کد
- **حداکثر 6 رقم**: کدهای حسابداری حداکثر 6 رقم هستند
- **عرف حسابداری**: مطابق با استانداردهای حسابداری

### 2. متد `generateReasonableCode`

#### عملکرد:
- تولید کدهای 1 تا 6 رقمی
- استفاده از شمارنده ترتیبی
- استفاده از اعداد تصادفی در صورت نیاز
- بررسی تکراری نبودن

#### الگوریتم:
1. **شمارنده ترتیبی**: `currentCode + 1`
2. **عدد تصادفی 4 رقمی**: `1000-9999`
3. **عدد تصادفی 5 رقمی**: `10000-99999`
4. **عدد تصادفی 6 رقمی**: `100000-999999`

### 3. بهبود متدهای موجود

#### `generateTimestampCode`:
- حذف timestamp های بلند
- استفاده از شمارنده معقول
- حداکثر 6 رقم

#### `generateFallbackCode`:
- کاهش افزایش شمارنده از 10000 به 500
- استفاده از اعداد تصادفی معقول

#### `validateCode`:
- محدودیت طول از 20 رقم به 6 رقم

## نمونه کدهای تولید شده

### ✅ کدهای معقول:
```
1001, 1002, 1003, ... (ترتیبی)
1234, 5678, 9012, ... (تصادفی 4 رقمی)
12345, 67890, ... (تصادفی 5 رقمی)
123456, 789012, ... (تصادفی 6 رقمی)
```

### ❌ کدهای نامعتبر (قبلی):
```
1,756,382,866,131,764 (خیلی بلند)
170312345678901234 (timestamp بلند)
```

## مزایای راه‌حل

1. **مطابق عرف**: کدهای 1-6 رقمی مطابق استاندارد حسابداری
2. **قابل خواندن**: کدهای کوتاه و قابل فهم
3. **عملکرد بهتر**: تولید سریع‌تر کدها
4. **ذخیره‌سازی بهینه**: فضای کمتری در دیتابیس
5. **نمایش بهتر**: در گزارش‌ها و فاکتورها بهتر نمایش داده می‌شوند

## نحوه استفاده

### تولید کد جدید:
```php
$code = $provider->getAccountingCode($bid, 'accounting');
// نتیجه: 1001, 1002, 1234, 12345, 123456
```

### ترمیم کدهای تکراری:
```php
$result = $provider->fixDuplicateCodes($bid, 'accounting');
// کدهای تکراری با کدهای معقول جایگزین می‌شوند
```

## قوانین جدید

### اعتبارسنجی کد:
- ✅ عدد مثبت
- ✅ حداکثر 6 رقم
- ✅ فقط اعداد

### تولید کد:
1. **اولویت اول**: شمارنده ترتیبی
2. **اولویت دوم**: عدد تصادفی 4 رقمی
3. **اولویت سوم**: عدد تصادفی 5 رقمی
4. **اولویت چهارم**: عدد تصادفی 6 رقمی

## تست

### تست کدهای معقول:
```php
// تست تولید کد
$code = $provider->getAccountingCode($bid, 'accounting');
$this->assertLessThanOrEqual(999999, $code); // حداکثر 6 رقم
$this->assertGreaterThan(0, $code); // مثبت

// تست اعتبارسنجی
$this->assertTrue($provider->validateCode(1234)); // معتبر
$this->assertFalse($provider->validateCode(1234567)); // خیلی بلند
```

## نکات مهم

1. **عرف حسابداری**: کدهای 1-6 رقمی استاندارد هستند
2. **عملکرد**: تولید سریع‌تر کدها
3. **خوانایی**: کدهای کوتاه قابل فهم‌تر
4. **نمایش**: در گزارش‌ها بهتر نمایش داده می‌شوند
5. **Backward Compatibility**: با کدهای موجود سازگار

## تغییرات در API

### قبل:
```json
{
    "code": "1756382866131764"
}
```

### بعد:
```json
{
    "code": "1234"
}
```

این تغییرات کدهای حسابداری را مطابق با عرف و استانداردهای حسابداری می‌کند.