# راهنمای کدهای عددی حسابداری

## اصل کلی
**تمام کدهای اسناد حسابداری باید فقط عدد باشند و هیچ حرفی نداشته باشند.**

## تغییرات اعمال شده

### 1. اعتبارسنجی کد
متد `validateCode()` اضافه شد که موارد زیر را بررسی می‌کند:
- کد باید عدد باشد
- کد باید مثبت باشد (بزرگتر از صفر)
- طول کد حداکثر 20 رقم باشد

### 2. بهبود متد `getAccountingCode`
- **بررسی تکراری بودن**: قبل از ذخیره، بررسی می‌شود که کد قبلاً وجود نداشته باشد
- **Retry Logic**: تا 10 بار تلاش برای تولید کد منحصر به فرد
- **Fallback Strategy**: در صورت عدم موفقیت، از شمارنده بزرگتر استفاده می‌کند
- **Timestamp Fallback**: در نهایت از timestamp استفاده می‌کند

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

#### `generateFallbackCode()`
تولید کد جایگزین با افزایش شمارنده به مقدار بزرگی (10000+)

#### `generateTimestampCode()`
تولید کد منحصر به فرد با استفاده از timestamp (فقط عدد)

#### `validateCode()`
اعتبارسنجی کد برای اطمینان از عددی بودن

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

### کدهای عادی (ترتیبی):
```
1001, 1002, 1003, 1004, ...
```

### کدهای Fallback (در صورت تداخل):
```
11001, 11002, 11003, ...
```

### کدهای Timestamp (در صورت نیاز):
```
170312345678901234, 170312345678901235, ...
```

## قوانین اعتبارسنجی

### ✅ کدهای معتبر:
- `123`
- `1000`
- `999999`
- `170312345678901234`

### ❌ کدهای نامعتبر:
- `abc`
- `123abc`
- `0`
- `-1`
- `123.45`

## تست‌ها

فایل `ProviderTest.php` اضافه شد که شامل:
- تست تولید کد عددی
- تست اعتبارسنجی کد
- تست کدهای معتبر و نامعتبر

## نحوه اجرای تست

```bash
# اجرای تست‌های Provider
php bin/phpunit tests/ProviderTest.php

# اجرای تست خاص
php bin/phpunit --filter testGetAccountingCodeReturnsNumericValue
```

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

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

## نکات مهم

1. **فقط عدد**: هیچ حرفی در کدها استفاده نمی‌شود
2. **مثبت**: تمام کدها بزرگتر از صفر هستند
3. **منحصر به فرد**: هیچ کد تکراری تولید نمی‌شود
4. **قابل پیش‌بینی**: کدها ترتیبی هستند (مگر در موارد خاص)
5. **قابل ترمیم**: ابزار ترمیم کدهای تکراری موجود

## API ترمیم کدهای تکراری

```bash
POST /api/accounting/fix-duplicate-codes
Content-Type: application/json

{
    "part": "accounting"
}
```

این API کدهای تکراری موجود را پیدا کرده و با کدهای عددی منحصر به فرد جایگزین می‌کند.