کد مشکل 1: خطای “فایل زیپ معتبر نیست” یا “پوشه افزونه دارای فایل اصلی plugin.php نیست”

❌ نشانه خطا: هنگام آپلود فایل zip در پیشخوان وردپرس، خطای عدم وجود فایل اصلی یا عدم اعتبار فایل زیپ نمایش داده می‌شود.

🔍 علت ریشه‌ای: فایل دانلود شده ابتدا باید آنزیپ شود (Double Zip) یا ساختار پوشه‌های داخلی در آرشیو زیپ به درستی استخراج نشده است.

// ساختار استاندارد فایل‌های افزونه سمافاکتور در پوشه /wp-content/plugins/samafactor/
samafactor/
├── samafactor.php (فایل اصلی)
├── readme.txt
├── assets/
│   ├── css/tazhib-style.css
│   └── js/tazhib-script.js
└── includes/
    ├── class-samafactor-pdf.php
    └── class-samafactor-admin.php

کد مشکل 2: خطای Fatal Error: Cannot redeclare class SamaFactor_Invoice

❌ نشانه خطا: هنگام فعال‌سازی افزونه، خطای تعاریف تکراری کلاس یا توابع وردپرس ظاهر می‌شود.

🔍 علت ریشه‌ای: نسخه قدیمی یا آزمایشی دیگری از افزونه سمافاکتور در مسیر افزونه‌ها وجود دارد یا کلاسی با نام مشابه توسط قالب بارگذاری شده است.

if ( ! class_exists( 'SamaFactor_Invoice' ) ) {
    class SamaFactor_Invoice {
        // کلاس اصلی افزونه سمافاکتور
    }
}

کد مشکل 3: خطای PHP Parse Error: syntax error, unexpected T_STRING در نسخه قدیمی PHP

❌ نشانه خطا: پس از فعال‌سازی، خطای سنتکس PHP در لاگ‌های هاست ثبت می‌شود.

🔍 علت ریشه‌ای: سرور هاست شما از نسخه منسوخ شده PHP (کمتر از 7.4) استفاده می‌کند در حالی که سمافاکتور نیازمند PHP 7.4 یا 8.1+ است.

کد مشکل 4: صفحه سفید مرگ وردپرس (White Screen of Death – WSOD) پس از فعال‌سازی

❌ نشانه خطا: کل پیشخوان یا سایت پس از زدن دکمه فعال‌سازی افزونه کاملاً سفید و بی‌متن می‌شود.

🔍 علت ریشه‌ای: اغلب به دلیل اتمام حافظه تخصیص یافته PHP سرور (Memory Exhaustion) یا تداخل یک خطای نامشخص.

// افزوده شود به فایل wp-config.php
define( 'WP_MEMORY_LIMIT', '512M' );
define( 'WP_MAX_MEMORY_LIMIT', '1024M' );
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

کد مشکل 5: عدم نمایش منوی “سمافاکتور” در منوی سمت راست پیشخوان وردپرس

❌ نشانه خطا: افزونه فعال است اما گزینه‌ای برای تنظیمات فاکتور در مدیریت دیده نمی‌شود.

🔍 علت ریشه‌ای: نقش کاربری فعلی شما دسترسی manage_options ندارد یا منو زیرمجموعه منوی “ووکامرس” یا “تنظیمات” رفته است.

کد مشکل 6: خطای “You do not have sufficient permissions to access this page”

❌ نشانه خطا: هنگام کلیک روی برگه تنظیمات سمافاکتور، خطای عدم دسترسی کافی نمایش داده می‌شود.

🔍 علت ریشه‌ای: اختلال در جدول Role & Capabilities وردپرس یا استفاده از افزونه‌های مدیریت سطح دسترسی مانند User Role Editor.

add_action('admin_init', function() {
    $role = get_role('administrator');
    if ($role) {
        $role->add_cap('manage_samafactor_invoices');
    }
});

کد مشکل 7: عدم بارگیری استایل‌ها و آیکون‌های افزونه در صفحه تنظیمات

❌ نشانه خطا: صفحه تنظیمات افزونه به شکل متنی و بدون ظاهر شکیل و بدون فونت نمایش داده می‌شود.

🔍 علت ریشه‌ای: مسدود شدن فایل‌های CSS/JS توسط افزونه‌های کش یا خطای SSL/Mixed Content.

کد مشکل 8: خطای Direct Access Forbidden هنگام فراخوانی فایل‌های PHP افزونه

❌ نشانه خطا: هنگام دسترسی مستقیم به لینک فایل‌ها پیام امنیتی Direct Access نمایش داده می‌شود.

🔍 علت ریشه‌ای: این یک مکانیزم امنیتی استاندارد در سمافاکتور برای جلوگیری از اجرای مستقیم اسکریپت‌ها بدون وردپرس است.

کد مشکل 9: خطای “The package could not be installed. PCLZIP_ERR_BAD_FORMAT (-10)”

❌ نشانه خطا: هنگام آپلود فایل زیپ در وردپرس خطای PCLZIP رخ می‌دهد.

🔍 علت ریشه‌ای: فایل زیپ به طور ناقص دانلود شده یا فرمت فشرده‌سازی آن با لایبرری Zip وردپرس ناسازگار است.

کد مشکل 10: عدم ساخته شدن گزینه‌های تنظیمات در دیتابیس (wp_options)

❌ نشانه خطا: تغییرات در صفحه تنظیمات ذخیره می‌شود اما پس از رفرش رست می‌شود.

🔍 علت ریشه‌ای: محدودیت max_input_vars در تنظیمات PHP هاست یا وجود کاراکترهای غیرمجاز در متن شعار یا آدرس.

// افزودن به فایل .htaccess هاست
php_value max_input_vars 5000
php_value post_max_size 64M

کد مشکل 11: خطای نیاز به نصب و فعال‌سازی ووکامرس (WooCommerce Missing Notice)

❌ نشانه خطا: هشدار “برای استفاده از سمافاکتور ابتدا ووکامرس را فعال کنید” ظاهر می‌شود.

🔍 علت ریشه‌ای: افزونه ووکامرس غیرفعال است یا قبل از سمافاکتور بارگذاری نشده است.

کد مشکل 12: نمایش علامت سوال (؟؟؟) یا کاراکترهای مربعی به جای حروف فارسی در PDF

❌ نشانه خطا: متون فارسی در خروجی PDF دانلود شده به صورت علامت سوال یا مربع سیاه دیده می‌شوند.

🔍 علت ریشه‌ای: فونت‌های فارسی (مانند Vazirmatan یا Shabnam) در کتابخانه PDF خوانی (mPDF/Dompdf) به درستی Embed نشده‌اند.

// فعال‌سازی mbstring و UTF-8 در PHP
extension=mbstring
mbstring.internal_encoding = UTF-8

کد مشکل 13: حروف فارسی جدا از هم و معکوس (مثلاً: ر و ت ک ا ف به جای فاکتور)

❌ نشانه خطا: متن فارسی در فایل PDF از چپ به راست و حروف به صورت جدا جدا رندر می‌شوند.

🔍 علت ریشه‌ای: کتابخانه PDF ساز فاقد پردازشگر متون راست‌چین RTL (Complex Script Shaping) است.

کد مشکل 14: خطای Fatal error: Allowed memory size of 134217728 bytes exhausted در زمان تولید PDF

❌ نشانه خطا: هنگام زدن دکمه دانلود PDF، فرایند متوقف شده و خطای اتمام حافظه صادر می‌شود.

🔍 علت ریشه‌ای: رندر کادر تذهیب با کیفیت بالا و تبدیل فونت‌ها نیاز به حداقل ۲۵۶ مگابایت رم PHP دارد.

// در فایل php.ini یا user.ini
memory_limit = 512M
max_execution_time = 300

کد مشکل 15: عدم نمایش تصاویر و لوگو در فایل PDF (جای خالی یا علامت x سرخ)

❌ نشانه خطا: لوگوی فروشگاه یا آیکون‌ها در نسخه وب هست اما در فایل PDF سفید یا خراب ظاهر می‌شوند.

🔍 علت ریشه‌ای: محدودیت allow_url_fopen یا عدم دسترسی cURL موتور PDF ساز برای خواندن آدرس‌های URL تصویر.

// تبدیل URL تصویر به مسیر فیزیکی سرور
$logo_path = str_replace( site_url('/'), ABSPATH, $logo_url );

کد مشکل 16: دانلود نشدن خودکار PDF و باز شدن کدهای متنی عجیب (%PDF-1.4…) در مرورگر

❌ نشانه خطا: به جای دانلود فایل .pdf، متون باینری ناخوانا روی مرورگر باز می‌شوند.

🔍 علت ریشه‌ای: عدم ارسال صحیح هدرهای HTTP (Content-Type: application/pdf و Content-Disposition).

header('Content-Type: application/pdf');
header('Content-Disposition: attachment; filename="Factor-' . $order_id . '.pdf"');
header('Cache-Control: private, max-age=0, must-revalidate');

کد مشکل 17: قطع شدن انتهای جدول محصولات در مرز صفحه (Page Break Collision)

❌ نشانه خطا: در فاکتورهای با تعداد آیتم زیاد، یک سطر محصول نصفه در صفحه اول و نصفه در صفحه دوم چاپ می‌شود.

🔍 علت ریشه‌ای: عدم تنظیم ویژگی page-break-inside: avoid روی سطرهای جدول .

tr, table, .invoice-header {
    page-break-inside: avoid !important;
}
.page-break {
    page-break-after: always;
}

کد مشکل 18: خطای SSL Certificate Problem هنگام دانلود تصاویر وب‌سایت درون PDF

❌ نشانه خطا: خطای cURL error 60: SSL certificate prblem: unable to get local issuer certificate.

🔍 علت ریشه‌ای: گواهی SSL هاست شما self-signed است یا زنجیره CA در cURL سرور به‌روز نیست.

کد مشکل 19: تاری و کیفیت پایین حاشیه تذهیب و لوگو در فایل PDF

❌ نشانه خطا: تذهیب اطراف فاکتور در نمایش وب شفاف است اما در PDF پیکسل‌پیکسل و تار می‌شود.

🔍 علت ریشه‌ای: استفاده از فایل‌های PNG کم‌کیفیت به جای وکتور SVG یا با کیفیت 300 DPI.

کد مشکل 20: عدم نمایش شماره صفحه (صفحه ۱ از ۲) در فاکتورهای طولانی

❌ نشانه خطا: پاپرگ فاکتور در صفحات دوم و سوم شماره صفحه ندارد.

🔍 علت ریشه‌ای: عدم تنظیم کدهای جایگزین {PAGENO} و {NBPG} در کدهای mPDF.

<htmlpagefooter name="myFooter">
    <div style="text-align: center; font-size: 9pt; color: #666;">
        صفحه {PAGENO} از {NBPG} - فاکتور رسمی فروشگاه
    </div>
</htmlpagefooter>

کد مشکل 21: خطای “mPDF error: Image type not supported” برای فرمت WebP

❌ نشانه خطا: هنگام آپلود لوگو با فرمت .webp موتور PDF ساز خطا می‌دهد.

🔍 علت ریشه‌ای: کتابخانه‌های قدیمی mPDF از فرمت WebP پشتیبانی نمی‌کنند مگر ماژول GD/ImageMagick به روز باشد.

کد مشکل 22: مشکل عدم دانلود PDF روی مرورگرهای آیفون و سافاری (Safari iOS)

❌ نشانه خطا: کاربران آیفون پس از لمس دکمه دانلود PDF با صفحه خالی یا مسدود شدن پاپ‌آپ روبرو می‌شوند.

🔍 علت ریشه‌ای: محدودیت مرورگر Safari در باز کردن پاپ‌آپ‌های ناهمگام (Async Popup Blocker).

کد مشکل 23: چاپ شدن دکمه‌های دانلود، دکمه پرینت و منوهای سایت در برگه پرینت فاکتور

❌ نشانه خطا: وقتی دکمه Print زده می‌شود عناصر کنترلی و هدر سایت هم روی کاغذ چاپ می‌شوند.

🔍 علت ریشه‌ای: عدم اعمال درست کلاس‌های no-print در استایل‌های @media print.

@media print {
    .no-print, header, footer, sidebar, .admin-bar {
        display: none !important;
    }
    body {
        background: #fff !important;
        padding: 0 !important;
    }
}

کد مشکل 24: حذف شدن کادرهای تذهیب طلایی و رنگ‌های پس‌زمینه در خروجی پرینتر

❌ نشانه خطا: در پیش‌نمایش پرینت، کادر تذهیب و خطوط رنگی به صورت سفید بی‌رنگ ظاهر می‌شوند.

🔍 علت ریشه‌ای: تنظیمات مرورگر گزینه‌ی “Background Graphics” را به صورت غیرفعال نگه داشته است.

@media print {
    * {
        -webkit-print-color-adjust: exact !important;
        print-color-adjust: exact !important;
    }
}

کد مشکل 25: بهم خوردن سایز کاغذ و عدم انطباق با برگه A4 یا A5

❌ نشانه خطا: فاکتور روی برگه A4 به صورت خیلی کوچک در گوشه چاپ می‌شود یا از کادر بیرون می‌زند.

🔍 علت ریشه‌ای: تنظیم نبودن سایز کاغذ در دستور CSS @page.

@page {
    size: A4 portrait;
    margin: 10mm 10mm 10mm 10mm;
}

کد مشکل 26: افزوده شدن هدر و فوتر مرورگر (مانند تاریخ، لینک URL و شماره صفحه مرورگر)

❌ نشانه خطا: در بالا و پایین کاغذ چاپ‌شده آدرس سایت و تاریخ متنی مرورگر چاپ می‌شود.

🔍 علت ریشه‌ای: تنظیمات استاندارد مرورگر برای Headers and Footers.

کد مشکل 27: ریز شدن بیش از حد متون هنگام پرینت با پرینتر حرارتی فیش پرینتر (80mm)

❌ نشانه خطا: فاکتور در دستگاه حرارتی صدور فیش بسیار ریز و ناخوانا می‌شود.

🔍 علت ریشه‌ای: استفاده از الگوی فاکتور A4 برای پرینترهای حرارتی ۸ سانتی‌متری.

کد مشکل 28: حاشیه‌های سفید اضافی (Margins) ناخواسته دور برگه چاپ

❌ نشانه خطا: کادر تذهیب به چسبیده به حاشیه برگه نمی‌افتد و دور آن سفیدی زیاد است.

🔍 علت ریشه‌ای: تنظیمات Margin مرورگر روی Default قرار دارد.

کد مشکل 29: افتادن تیتر جدول در یک صفحه و سطر اول محصول در صفحه بعدی

❌ نشانه خطا: تیتر جدول در انتهای برگه اول و جزییات در برگه بعدی می‌افتد.

🔍 علت ریشه‌ای: عدم تنظیم keep-with-next روی جدول.

thead {
    display: table-header-group;
}
tfoot {
    display: table-footer-group;
}

کد مشکل 30: عدم چاپ لوگوی شفاف PNG با پس‌زمینه مشکی یا تیره در پرینتر

❌ نشانه خطا: لوگو دارای background شفاف است اما در چاپ مشکی می‌شود.

🔍 علت ریشه‌ای: عدم پشتیبانی برخی درایورهای قدیمی پرینتر از آلفا چنل PNG.

کد مشکل 31: کند شدن فرایند پرینت به علت حجم بالای فونت‌های جاگذاری شده

❌ نشانه خطا: ارسال دستور پرینت به پرینتر شبکه چندین ثانیه طول می‌کشد.

🔍 علت ریشه‌ای: لود فونت‌های سنگین TTF با حجم بیش از ۳ مگابایت.

کد مشکل 32: عدم چاپ بارکد یا QR Code سفارش در پرینترهای قدیمی

❌ نشانه خطا: QR کد استعلام فاکتور به صورت یک مربع توپر یا خالی چاپ می‌شود.

🔍 علت ریشه‌ای: رزولوشن پایین نازل پرینتر یا کنتراست کم رنگ بارکد.

کد مشکل 33: بهم ریختگی حروف فارسی به صورت کاراکترهای ناشناخته (??? / ÅØ) در اکسل

❌ نشانه خطا: فایل CSV خروجی وقتی در نرم‌افزار Microsoft Excel باز می‌شود متون فارسی ناخوانا هستند.

🔍 علت ریشه‌ای: عدم وجود علامت UTF-8 BOM (Byte Order Mark) در ابتدای فایل CSV.

// افزودن UTF-8 BOM جهت شناسایی زبان فارسی در Microsoft Excel
$bom = "";
file_put_contents('invoices.csv', $bom . $csv_content);

کد مشکل 34: قرار گرفتن تمام ستون‌های خروجی CSV در یک ستون اکسل (عدم تفکیک ستون‌ها)

❌ نشانه خطا: همه اطلاعات مانند نام، شماره سفارش و قیمت در اولین ستون (Column A) اکسل چسبیده به هم دیده می‌شوند.

🔍 علت ریشه‌ای: تنظیمات جداکننده (Delimiter) اکسل سیستم شما روی نقطه-ویرگول (;) یا کاما (,) متفاوت است.

کد مشکل 35: حذف صفر اول شماره موبایل خریداران (مثلاً تبدیل 09123456789 به 9123456789)

❌ نشانه خطا: در خروجی اکسل شماره تماس مشتریان صفر ابتدایی را از دست می‌دهد.

🔍 علت ریشه‌ای: اکسل به طور پیش‌فرض ستون شماره تلفن را به عنوان عدد (Numeric) تشخیص داده و صفر قبل را حذف می‌کند.

// فورس کردن فرمت متنی در اکسل جهت حفظ صفر اول
$phone_formatted = '="' . $phone_number . '"';

کد مشکل 36: تبدیل شدن شماره‌های طولانی تراکنش به فرمت علمی (مثلاً 1.2345E+11) در اکسل

❌ نشانه خطا: کد پیگیری بانک به صورت اعداد اعشاری نماد علمی دیده می‌شود.

🔍 علت ریشه‌ای: بزرگ بودن اعداد از ۱۱ رقم و تشخیص اتوماتیک علمی توسط Microsoft Excel.

کد مشکل 37: خطای Memory Limit هنگام خروجی گرفتن از بیش از ۵۰۰۰ سفارش همزمان

❌ نشانه خطا: هنگام گرفتن خروجی گزارش کلی فاکتورها، سیستم تایم‌اوت شده یا ۵۰۰ می‌دهد.

🔍 علت ریشه‌ای: لود کردن تمام سفارشات در حافظه RAM سرور به صورت یکجا.

$output = fopen('php://output', 'w');
// خروجی دادن خط به خط بدون اشغال رم سرور
foreach ($orders_chunk as $order) {
    fputcsv($output, $order_data);
}

کد مشکل 38: عدم نمایش متغیرهای سفارشی محصول و ویژگی‌ها در فایل اکسل

❌ نشانه خطا: رنگ، سایز یا ویژگی‌های انتخابی محصول در فایل گزارش اکسل خالی است.

🔍 علت ریشه‌ای: عدم استخراج متادیتاهای item_meta ووکامرس.

کد مشکل 39: عدم تطابق تاریخ شمسی خریدهای قبلی در خروجی CSV

❌ نشانه خطا: تاریخ‌ها به صورت میلادی (2024-05-12) ذخیره می‌شوند یا در اکسل اشتباه محاسبه می‌شوند.

🔍 علت ریشه‌ای: عدم فراخوانی توابع تبدیل تاریخ Jalali/JDF.

کد مشکل 40: عدم دانلود فایل CSV و دانلود یک فایل index.html یا 0 بایت

❌ نشانه خطا: دکمه خروجی اکسل کلیک می‌شود اما فایلی با حجم صفر یا صفحه HTML خطا دانلود می‌شود.

🔍 علت ریشه‌ای: ارسال هشدار PHP (Notice/Warning) قبل از کدهای خروجی فایل CSV.

if (ob_get_length()) {
    ob_end_clean();
}
header('Content-Type: text/csv; charset=utf-8');
header('Content-Disposition: attachment; filename=invoices-export.csv');

کد مشکل 41: عدم محاسبه درست مجموع کل درآمد و مالیات در فرمول‌های ریاضی اکسل

❌ نشانه خطا: وقتی در اکسل روی ستون قیمت فرمول SUM می‌زنید مقدار صفر حاصل می‌شود.

🔍 علت ریشه‌ای: وجود کاراکترهای ویرگول جداکننده هزارگان (،) یا کلمه “تومان” داخل سلول عددی.

کد مشکل 42: عدم امکان باز کردن همزمان فایل CSV خروجی در چند سیستم شبکه

❌ نشانه خطا: خطای “File is locked by another user” در نرم‌افزار اکسل.

🔍 علت ریشه‌ای: قفل فایل توسط اکسل در سیستم اول.

کد مشکل 43: عدم نمایش لوگوی آپلود شده فروشگاه در بالای فاکتور تذهیب

❌ نشانه خطا: تصویر لوگو در صفحه تنظیمات مشخص شده اما در فاکتور نشان داده نمی‌شود.

🔍 علت ریشه‌ای: آدرس لوگو با HTTP است در حالی که سایت رو HTTPS قرار دارد (Mixed Content) یا مسیر تصویر اشتباه است.

کد مشکل 44: بهم ریختگی و دفرمه شدن کادر اسلیمی تذهیب در رزولوشن‌های مختلف

❌ نشانه خطا: کادر طلایی تذهیب دور فاکتور کشیده یا قطع می‌شود.

🔍 علت ریشه‌ای: استفاده از CSS border-image غیر استاندارد یا عدم تنظیم صحیح responsive container.

.tazhib-box {
    border-style: solid;
    border-width: 28px;
    border-image: url('assets/images/tazhib-frame-gold.svg') 60 repeat;
}

کد مشکل 45: عدم تبدیل اعداد انگلیسی به فارسی (مثلاً نمایش 125000 به جای ۱۲۵,۰۰۰)

❌ نشانه خطا: اعداد قیمت و تاریخ در فاکتور انگلیسی باقی می‌مانند.

🔍 علت ریشه‌ای: غیرفعال بودن گزینه “فارسی‌سازی خودکار اعداد” در تنظیمات سمافاکتور.

function toPersianNum($num) {
    $en = array('0','1','2','3','4','5','6','7','8','9');
    $fa = array('۰','۱','۲','۳','۴','۵','۶','۷','۸','۹');
    return str_replace($en, $fa, $num);
}

کد مشکل 46: اعمال نشدن تغییر رنگ تم تذهیب (مثلاً سوئیچ از طلایی به فیروزه‌ای یا زمردی)

❌ نشانه خطا: تم را روی فیروزه‌ای قرار می‌دهید اما فاکتور همچنان طلایی نمایش داده می‌شود.

🔍 علت ریشه‌ای: کش شدن فایل CSS در مرورگر یا افزونه کش سایت (LiteSpeed / WP Rocket).

کد مشکل 47: عدم نمایش صحیح فونت‌های سفارشی (مانند ایران‌یکان، کلمه یا وزیرمتن)

❌ نشانه خطا: فاکتور با فونت عمومی سیستم (Arial یا Tahoma) نشان داده می‌شود.

🔍 علت ریشه‌ای: مسدود شدن آدرس CDN فونت یا عدم بارگذاری صحیح فایل‌های WOFF2 فونت در هاست.

کد مشکل 48: هم‌پوشانی و روی هم افتادن متن اسم خریدار با شماره فاکتور

❌ نشانه خطا: در عنوان‌های طولانی متون روی یکدیگر می‌افتند.

🔍 علت ریشه‌ای: استفاده از height ثابت به جای min-height در استایل‌های CSS.

کد مشکل 49: عدم نمایش مهر و امضای دیجیتال فروشگاه در انتهای فاکتور

❌ نشانه خطا: تصویر مهر فروشگاه در کادر انتهای فاکتور نشان داده نمی‌شود.

🔍 علت ریشه‌ای: عدم آپلود تصویر مهر یا فعال نبودن تیک “نمایش مهر و امضای فروشگاه”.

کد مشکل 50: شکسته شدن خطوط آدرس‌های طولانی مشتری و بیرون زدن از جدول

❌ نشانه خطا: آدرس‌های طولانی از کادر جدول فاکتور خارج می‌شوند.

🔍 علت ریشه‌ای: عدم وجود دستور word-break: break-word در استایل جدول.

.customer-address, .item-name {
    word-wrap: break-word;
    word-break: break-word;
    white-space: normal;
}

کد مشکل 51: عدم نمایش کد پستی و شماره ملی مشتری در بخش اطلاعات خریدار

❌ نشانه خطا: فیلد کدپستی یا کد ملی در فاکتور نشان داده نمی‌شود.

🔍 علت ریشه‌ای: مشتری فیلد را در برگه تسویه حساب پر نکرده یا نام فیلد سفارشی در تنظیمات افزونه ست نشده است.

کد مشکل 52: مشکل نمایش رنگ‌های گرادینت تذهیب در مانیتورهای قدیمی با پنل TN

❌ نشانه خطا: گرادینت‌های طلایی و فیروزه‌ای به صورت پله‌پله (Banding) دیده می‌شوند.

🔍 علت ریشه‌ای: عمق رنگ پایین نمایشگرهای قدیمی.

کد مشکل 53: پیام “کلید لایسنس معتبر نیست” یا “دامنه فعال‌سازی شده مطابقت ندارد”

❌ نشانه خطا: هنگام وارد کردن کد لایسنس خریده شده از samavie.ir پیام نامعتبر بودن صادر می‌شود.

🔍 علت ریشه‌ای: اشتباه در تایپ کاراکترها، وجود فاصله اضافی (Space) در ابتدا یا انتهای کد، یا عدم مطابقت دامنه ثبت‌شده در پنل.

کد مشکل 54: خطای cURL error 60: SSL certificate problem هنگام استعلام لایسنس از سرور سماویه

❌ نشانه خطا: بررسی لایسنس با خطای عدم امکان ارتباط با سرور سامانه لایسنس روبرو می‌شود.

🔍 علت ریشه‌ای: قدیمی بودن بسته cacert.pem در نسخه PHP سرور شما.

کد مشکل 55: عدم دریافت خودکار اعلامیه بروزرسانی‌های جدید در پیشخوان وردپرس

❌ نشانه خطا: نسخه جدید افزونه در سایت samavie.ir منتشر شده اما در پیشخوان آپدیت نشان داده نمی‌شود.

🔍 علت ریشه‌ای: کش شدن پاسخ‌های سیستم آپدیت وردپرس (Transient Cache).

کد مشکل 56: غیرفعال شدن ناگهانی لایسنس پس از تغییر دامنه یا انتقال سایت به هاست جدید

❌ نشانه خطا: پس از جابجایی سایت لایسنس غیرفعال شده و پیغام لایسنس منقضی شده صادر می‌شود.

🔍 علت ریشه‌ای: تغییر آدرس IP یا نام دامنه اصلی سایت.

کد مشکل 57: خطای Timeout (ارتباط قطعی) هنگام اتصال به سرور لایسنس سماویه

❌ نشانه خطا: ثبت لایسنس بیش از ۳۰ ثانیه معطل شده و خطای Connection Timed Out صادر می‌شود.

🔍 علت ریشه‌ای: مسدود بودن پورت‌های خروجی HTTP/HTTPS یا دیوار آتش (Firewall) سرور هاست شما.

کد مشکل 58: پیام “حداکثر تعداد دامنه‌های مجاز برای این لایسنس تکمیل شده است”

❌ نشانه خطا: امکان فعال‌سازی روی سایت دوم وجود ندارد.

🔍 علت ریشه‌ای: لایسنس تک‌دامنه‌ای خریداری شده و قبلا روی یک دامنه فعال گردیده است.

کد مشکل 59: تداخل لایسنس در محیط‌های لوکال‌هست (Localhost / XAMPP / Laragon)

❌ نشانه خطا: لایسنس روی سیستم شخصی و لوکال فعال نمی‌شود.

🔍 علت ریشه‌ای: عدم دسترسی لوکال‌هست به اینترنت یا نام دامنه غیر استاندارد.

کد مشکل 60: عدم شناسایی زیردامنه‌ها (Subdomains) در لایسنس دامنه اصلی

❌ نشانه خطا: سایت روی sub.domain.com است اما لایسنس domain.com را نمی‌پذیرد.

🔍 علت ریشه‌ای: تفاوت ساختاری دامنه اصلی و ساب‌دامنه در سامانه اعتبارسنجی.

کد مشکل 61: پاک شدن تنظیمات سفارشی فاکتور پس از بروزرسانی افزونه

❌ نشانه خطا: پس از زدن دکمه آپدیت، تنظیمات تم و لوگوی شما رست شده است.

🔍 علت ریشه‌ای: ذخیره‌سازی غیر استاندارد تنظیمات در پوشه افزونه به جای جدول wp_options.

کد مشکل 62: خطای 403 Forbidden هنگام فراخوانی لایسنس از طریق REST API

❌ نشانه خطا: خطای عدم دسترسی در کنسول مرورگر هنگام ذخیره لایسنس.

🔍 علت ریشه‌ای: مسدود بودن REST API وردپرس توسط افزونه‌های امنیتی مانند iThemes Security یا Wordfence.

کد مشکل 63: عدم سازگاری با ذخیره‌سازی بالای ووکامرس (WooCommerce HPOS / High-Performance Order Storage)

❌ نشانه خطا: هنگام فعال بودن HPOS ووکامرس، فاکتورها لود نشده یا اطلاعات سفارشات سفارشی نشان داده نمیشوند.

🔍 علت ریشه‌ای: استفاده از توابع قدیمی get_post_meta به جای $order->get_meta() در سفارشات ووکامرس 8+.

add_action( 'before_woocommerce_init', function() {
    if ( class_exists( \Automattic\WooCommerce\Utilities\FeaturesUtil::class ) ) {
        \Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility( 'custom_order_tables', __FILE__, true );
    }
} );

کد مشکل 64: تداخل با افزونه‌های چندزبانه WPML و Polylang در ترجمه متون فاکتور

❌ نشانه خطا: در زبان انگلیسی یا عربی، متون فاکتور همچنان فارسی باقی می‌مانند.

🔍 علت ریشه‌ای: عدم استفاده از توابع ترجمه استاندارد __() و e_() و عدم درج فایل‌های po/mo.

کد مشکل 65: تداخل با افزونه‌های کش و بهینه‌سازی (WP Rocket, LiteSpeed Cache, Autoptimize)

❌ نشانه خطا: تغییرات فاکتور نشان داده نمی‌شود یا لینک دانلود PDF برای همه کاربران یکسان می‌شود.

🔍 علت ریشه‌ای: کش شدن صفحات دینامیک فاکتور یا مینیفای شدن اشتباه اسکریپت‌های PDF.

// آدرس‌های مستثنی شده از کش در راکت یا لایت‌اسپید:
/checkout/order-received/*
/*samafactor_download_pdf=*

کد مشکل 66: عدم ارسال یا پیوست شدن لینک فاکتور در ایمیل‌های خودکار ووکامرس

❌ نشانه خطا: در ایمیل “تکمیل سفارش” دکمه مشاهده فاکتور آنلاین یا لینک PDF وجود ندارد.

🔍 علت ریشه‌ای: غیرفعال بودن هوک‌های پیوست ایمیل ووکامرس.

کد مشکل 67: تداخل با صفحه ساز المنتور (Elementor) هنگام ویرایش برگه تسویه حساب

❌ نشانه خطا: هنگام ویرایش برگه خرید با المنتور، باکس فاکتور ارور المنتور صادر می‌کند.

🔍 علت ریشه‌ای: عدم بررسی حالت ایجکس یا ویرایشگر المنتور is_elementor_active().

کد مشکل 68: عدم نمایش فیلدهای سفارشی افزوده‌شده توسط Checkout Field Editor

❌ نشانه خطا: فیلدهایی مثل “زمان تحویل” یا “کد اقتصادی” در فاکتور چاپ نمی‌شوند.

🔍 علت ریشه‌ای: عدم فراخوانی متاداده‌های سفارشی سفارش.

کد مشکل 69: عدم کارکرد در شبکه وردپرس چندسایته (WordPress Multisite)

❌ نشانه خطا: افزونه در سایت‌های زیرمجموعه چندسایته فعال می‌شود اما دیتابیس جداگانه نمی‌سازد.

🔍 علت ریشه‌ای: عدم پشتیبانی از اکشن switch_to_blog().

کد مشکل 70: تداخل با افزونه‌های پنل کاربری خریدار (مثل دیجیتس یا پنل‌های پیشرفته)

❌ نشانه خطا: دکمه فاکتور در صفحه “حساب کاربری من > سفارش‌ها” ظاهر نمی‌شود.

🔍 علت ریشه‌ای: بازنویسی الگوی my-orders.php توسط افزونه‌های پنل کاربری.

کد مشکل 71: عدم نمایش تخفیف‌های گروهی و افزونه‌های قیمت‌گذاری پویا (Dynamic Pricing)

❌ نشانه خطا: مبلغ تخفیف در فاکتور با مبلغ کسرشده در سبد خرید متفاوت است.

🔍 علت ریشه‌ای: استفاده از قیمت پایه کالا به جای $order->get_discount_total().

کد مشکل 72: تداخل با افزونه‌های امنیتی (Wordfence / iThemes Security) و مسدود شدن AJAX

❌ نشانه خطا: هنگام زدن دکمه دانلود PDF خطای Forbidden یا 403 صادر می‌شود.

🔍 علت ریشه‌ای: شناسایی نونس (Nonce) یا پارامترهای درخواست به عنوان حمله CSRF.

کد مشکل 73: کندی شدید در هنگام صدور همزمان ده‌ها فاکتور PDF

❌ نشانه خطا: چاپ یا دانلود گروهی فاکتورها سرور را معطل می‌کند.

🔍 علت ریشه‌ای: پردازش سنگین رندر کردن موتور HTML to PDF به صورت همزمان روی یک Thread.

کد مشکل 74: خطای Maximum Execution Time Exceeded (30 seconds) در زمان خروجی گرفتن

❌ نشانه خطا: سرور پس از ۳۰ ثانیه معطلی پیغام زمان مجاز به پایان رسید صادر می‌کند.

🔍 علت ریشه‌ای: محدودیت max_execution_time در php.ini سرور.

// افزایش زمان اجرای اسکریپت PHP به ۳۰۰ ثانیه
set_time_limit(300);
ini_set('max_execution_time', 300);

کد مشکل 75: پر شدن حجم دایرکتوری uploads سرور به دلیل فایل‌های موقت PDF

❌ نشانه خطا: فضای هاست شما بدون دلیل مشخصی پر می‌شود.

🔍 علت ریشه‌ای: عدم پاکسازی فایل‌های PDF موقت تولید شده پس از دانلود کاربر.

// پاکسازی خودکار فایل‌های موقت توسط سمافاکتور
if ( ! wp_next_scheduled( 'samafactor_daily_cleanup' ) ) {
    wp_schedule_event( time(), 'daily', 'samafactor_daily_cleanup' );
}

کد مشکل 76: کندی کوئری‌های دیتابیس در سایت‌های با بیش از ۵۰ هزار سفارش

❌ نشانه خطا: جستجوی شماره فاکتور در مدیریت وردپرس بسیار کند صورت می‌گیرد.

🔍 علت ریشه‌ای: عدم وجود ایندکس (Index) روی کلیدهای متادیتای سفارشات.

کد مشکل 77: افزایش ناگهانی مصرف CPU و RAM سرور هنگام دانلود فاکتور

❌ نشانه خطا: هشدار مصرف بالای منابع از طرف شرکت هاستینگ صادر می‌شود.

🔍 علت ریشه‌ای: رندر چندباره فونت‌های سنگین TTF در هر درخواست دانلود.

کد مشکل 78: کند شدن دکمه ثبت سفارش در برگه تسویه حساب ووکامرس

❌ نشانه خطا: مشتریان هنگام زدن دکمه “ثبت سفارش” چند ثانیه اضافه منتظر می‌مانند.

🔍 علت ریشه‌ای: تولید همزمان فایل PDF فاکتور در لحظه ثبت سفارش به جای تولید در زمان درخواست دانلود.

کد مشکل 79: خطای Too Many Database Connections هنگام چاپ دسته‌جمعی

❌ نشانه خطا: دیتابیس با خطای عدم پذیرش اتصال جدید متوقف می‌شود.

🔍 علت ریشه‌ای: باز ماندن اتصال‌های دیتابیس در حلقه فورایچ.

کد مشکل 80: تداخل اسکریپت‌های سنگین جاوااسکریپت در برگه فاکتور

❌ نشانه خطا: صفحه فاکتور دیر لود می‌شود یا انیمیشن‌ها لگ دارند.

🔍 علت ریشه‌ای: بارگذاری اسکریپت‌های سنگین سایر افزونه‌ها در برگه فاکتور.

کد مشکل 81: عدم پشتیبانی از Redis / Memcached برای کش کردن الگوهای فاکتور

❌ نشانه خطا: عدم افزایش سرعت با وجود داشتن سرور قدرتمند Redis.

🔍 علت ریشه‌ای: عدم استفاده از توابع wp_cache_get و wp_cache_set.

کد مشکل 82: عدم پاکسازی خودکار فایل‌های کش شده فاکتور پس از ویرایش سفارش

❌ نشانه خطا: سفارش ویرایش شده اما فاکتور قدیمی را نشان می‌دهد.

🔍 علت ریشه‌ای: کش شدن فایل PDF قدیمی روی سرور.

کد مشکل 83: خطای HTTP 500 Internal Server Error هنگام باز کردن فاکتور

❌ نشانه خطا: صفحه فاکتور با پیغام ۵۰۰ خطای داخلی سرور روبرو می‌شود.

🔍 علت ریشه‌ای: معمولاً به دلیل خطای سنتکس، کمبود حافظه PHP یا عدم وجود یک کتابخانه سروری.

کد مشکل 84: خطای HTTP 504 Gateway Timeout در سرورهای Nginx / LiteSpeed

❌ نشانه خطا: پس از دئ دقیقه معطلی مرورگر ارور 504 Gateway Timeout می‌دهد.

🔍 علت ریشه‌ای: پاسخ ندادن PHP-FPM به وب سرور Nginx در زمان مقرر.

// در فایل کانفیگ Nginx (nginx.conf)
fastcgi_read_timeout 300;
proxy_read_timeout 300;

کد مشکل 85: پیام “Warning: Cannot modify header information – headers already sent”

❌ نشانه خطا: در بالای صفحه فاکتور هشدارهای PHP چاپ شده و فایل دانلود نمی‌شود.

🔍 علت ریشه‌ای: وجود فاصله خالی (Whitespace) یا کدهای echo در فایل functions.php یا افزونه‌های دیگر قبل از ارسال هدرهای HTTP.

کد مشکل 86: خطای “Call to undefined function gd_info()” یا نبود ماژول GD Library

❌ نشانه خطا: هنگام پردازش تصاویر تذهیب و لوگو خطای عدم وجود تابع GD صادر می‌شود.

🔍 علت ریشه‌ای: غیرفعال بودن ماژول پردازش تصویر php-gd روی سرور هاست.

کد مشکل 87: خطای “Uncaught Error: Class WooCommerce not found”

❌ نشانه خطا: فراخوانی توابع ووکامرس با خطا روبرو می‌شود.

🔍 علت ریشه‌ای: اجرای کد افزونه قبل از فعال شدن کامل ووکامرس.

کد مشکل 88: خطای “JSON.parse: unexpected character at line 1 column 1” در ایجکس

❌ نشانه خطا: پاسخ ایجکس با خطای JSON روبرو می‌شود.

🔍 علت ریشه‌ای: ارسال هشدارهای PHP ناخواسته همراه با پاسخ JSON.

کد مشکل 89: خطای “404 Not Found” هنگام کلیک روی لینک عمومی فاکتور

❌ نشانه خطا: لینک مشاهده آنلاین فاکتور ارور ۴۰۴ صفحه پیدا نشد می‌دهد.

🔍 علت ریشه‌ای: عدم بازسازی پیوندهای یکتا (Permalink Structure) پس از نصب افزونه.

کد مشکل 90: خطای “CSRF / Nonce verification failed” هنگام ذخیره تنظیمات

❌ نشانه خطا: پیام “نشست شما منقضی شده است دوباره تلاش کنید” صادر می‌شود.

🔍 علت ریشه‌ای: منقضی شدن کد امنیتی wp_nonce به علت باز ماندن طولانی صفحه.

کد مشکل 91: خطای “DOMDocument::loadHTML(): Opening and ending tag mismatch”

❌ نشانه خطا: هشدارهای متوالی مربوط به DOMDocument در لاگ‌های دیباگ.

🔍 علت ریشه‌ای: وجود بسته‌نشدن کدهای HTML یا کاراکترهای غیر مجاز در متون توضیحات محصول.

کد مشکل 92: خطای “Permission Denied” در دسترسی به پوشه /wp-content/uploads/samafactor/

❌ نشانه خطا: عدم امکان ذخیره‌سازی فایل‌های PDF در پوشه اپلودها.

🔍 علت ریشه‌ای: تنظیم نبودن سطح دسترسی پوشه (File Permissions) روی 755 یا owner نادرست.

کد مشکل 93: نحوه تست افزونه در محیط Staging قبل از اعمال روی سایت اصلی

❌ نشانه خطا: نگرانی از بروز تداخل روی سایت زنده و خریداران واقعی.

🔍 علت ریشه‌ای: تغییر مستقیم کدهای سایت اصلی زنده بدون تست اولیه.

کد مشکل 94: ایمن‌سازی دایرکتوری ذخیره فاکتورها در برابر دسترسی مستقیم گوگل و هکرها

❌ نشانه خطا: خطر ایندکس شدن فاکتورهای حاوی آدرس و شماره مشتریان در گوگل.

🔍 علت ریشه‌ای: باز بودن دایرکتوری‌ها بدون فایل .htaccess محافظ.

# محافظت از فایل‌های فاکتور در پوشه uploads
<Files *.pdf>
    Order Deny,Allow
    Deny from all
</Files>

کد مشکل 95: روش صحیح بکاپ‌گیری از تنظیمات و الگوی فاکتور قبل از بروزرسانی

❌ نشانه خطا: خطر از دست رفتن شخصی‌سازی‌های انجام شده.

🔍 علت ریشه‌ای: عدم تهیه خروجی تنظیمات (Export Settings).

کد مشکل 96: تنظیمات بهینه فایل php.ini و .htaccess برای فروشگاه‌های ووکامرسی بزرگ

❌ نشانه خطا: کاهش کندی عمومی و بهینه‌سازی پردازش‌ها.

🔍 علت ریشه‌ای: تنظیمات پیش‌فرض و محدود کننده هاست‌های اشتراکی.

// کانفیگ پیشنهادی PHP برای ووکامرس و سمافاکتور
memory_limit = 512M
upload_max_filesize = 64M
post_max_size = 64M
max_execution_time = 300
max_input_vars = 5000

کد مشکل 97: فعال‌سازی سیستم لاگ دیباگ اختصاصی سمافاکتور جهت رفع سریع مشکلات

❌ نشانه خطا: نیاز به ردیابی علت خطاهای ناگهانی بدون قطع کردن سایت.

🔍 علت ریشه‌ای: عدم دسترسی به خطاهای داخلی.

کد مشکل 98: چک‌لیست سلامت افزونه پس از بروزرسانی بزرگ ووکامرس (Major Updates)

❌ نشانه خطا: اطمینان از صحت کارکرد پس از آپدیت‌های اصلی ووکامرس (مثل ووکامرس 9.0).

🔍 علت ریشه‌ای: تغییر هوک‌ها و متاداده‌ها در نسخه‌های اصلی ووکامرس.

کد مشکل 99: تنظیم سطح دسترسی کارمندان (User Roles) برای مشاهده و چاپ فاکتورها

❌ نشانه خطا: جلوگیری از دسترسی انباردار به تنظیمات افزونه.

🔍 علت ریشه‌ای: اعطای دسترسی کل administrator به همه کارمندان.

کد مشکل 100: استفاده از الگوی پشتیبان (Fallback HTML Template) در صورت قطع شدن PDF ساز

❌ نشانه خطا: عدم توقف ارائه فاکتور به مشتری حتی در صورت اختلال سروری.

🔍 علت ریشه‌ای: اختلال لحظه‌ای سرور در رندر PDF.

کد مشکل 101: تنظیم صحیح زمان‌بندی Cron Job در سرور به جای WP-Cron استاندارد

❌ نشانه خطا: کندی کشف وظایف زمان‌بندی شده یا عدم پاکسازی فایل‌های موقت.

🔍 علت ریشه‌ای: وابستگی WP-Cron به بازدید کاربران از سایت.

کد مشکل 102: اقدامات امنیتی پیشرفته برای جلوگیری از جعل فاکتورهای رسمی (Anti-Fraud)

❌ نشانه خطا: خطر دستکاری کدهای HTML فاکتور توسط افراد سودجو.

🔍 علت ریشه‌ای: عدم وجود هش امنیتی یا لینک استعلام اصالت.

$security_hash = md5( $order_id . $order_date . $order_total . SAMAFACTOR_AUTH_SALT );