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. نمایش بهتر: در گزارش‌ها و فاکتورها بهتر نمایش داده می‌شوند

نحوه استفاده

تولید کد جدید:

$code = $provider->getAccountingCode($bid, 'accounting');
// نتیجه: 1001, 1002, 1234, 12345, 123456

ترمیم کدهای تکراری:

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

قوانین جدید

اعتبارسنجی کد:

• ✅ عدد مثبت
• ✅ حداکثر 6 رقم
• ✅ فقط اعداد

تولید کد:

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

تست

تست کدهای معقول:

// تست تولید کد
$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

قبل:

{
    "code": "1756382866131764"
}

بعد:

{
    "code": "1234"
}

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