hesabixCore/docs/accounting/NUMERIC_CODE_GUIDELINES.md

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

اصل کلی

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

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

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 اضافه شد که شامل:

• تست تولید کد عددی
• تست اعتبارسنجی کد
• تست کدهای معتبر و نامعتبر

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

# اجرای تست‌های 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 ترمیم کدهای تکراری

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

{
    "part": "accounting"
}

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