همگام‌سازی محتوا

پس از اتصال افزونه به فضای کاری خود، باید محتوای وردپرس خود را به Pitchbar ارسال کنید تا دستیار فروش بتواند از آن بازیابی کند. افزونه در دو حالت مکمل همگام‌سازی می‌کند: یک همگام‌سازی انبوه دستی که از صفحه تنظیمات فعال می‌کنید و دلتاهای خودکار که در هر هوک وردپرس برای نوع پست / محصولاتی که انتخاب کرده‌اید، فعال می‌شوند.

هر دو حالت براساس external_id idempotent هستند — اجرای مجدد آنها رایگان است.

منابع محتوا

نهاد وردپرس	نوع منبع Pitchbar	فرمت شناسه خارجی
پست‌ها، صفحات، نوع پست‌های سفارشی	wordpress	wp:{post_id}
محصولات ووکامرس	woocommerce_products	wc:{product_id}
کوپن‌های ووکامرس	نصب‌شده در منبع woocommerce_products در config['coupons']	—

یک ردیف منبع به ازای هر (دستیار فروش، میزبان سایت). دو نوع در یک دستیار فروش همزیستی دارند — پست‌ها به سوالات سبک سوالات متداول پاسخ می‌دهند، محصولات به قصد خرید سبک "آیا X را دارید؟" پاسخ می‌دهند. Pitchbar هر منبع را در اولین همگام‌سازی به‌طور خودکار ایجاد می‌کند.

همگام‌سازی انبوه (دستی)

تنظیمات ← Pitchbar را باز کنید. پس از پیکربندی افزونه، دو دکمه ظاهر می‌شوند:

• همگام‌سازی پست‌ها اکنون — همیشه قابل مشاهده است. از هر پست با وضعیت publish از نوع پست‌های فعال‌شده، ۵۰ عدد در هر دسته HTTP، عبور می‌کند.
• همگام‌سازی محصولات اکنون — فقط زمانی که ووکامرس فعال باشد قابل مشاهده است. از محصولات simple، variable، grouped و external، ۵۰ عدد در هر دسته، عبور می‌کند.

روی هر دکمه کلیک کنید. خط وضعیت پیشرفت و تعداد نهایی را نشان می‌دهد: "همگام‌سازی کامل شد. (۱۲۴ پست، ۸۷ در صف، ۳۷ رد شد)". رد شدن به این معنی است که هش محتوا با همگام‌سازی قبلی مطابقت داشته است — بدون نیاز به بازپردازش، بدون هزینه هوش مصنوعی.

همگام‌سازی قابل ازسرگیری (سایت‌های بزرگ)

هاست اشتراکی معمولاً سقف اجرای PHP ۳۰ ثانیه را اعمال می‌کند. همگام‌سازهای Pitchbar به این موضوع احترام می‌گذارند: هر بار یک محافظ زمان دیواری TIME_BUDGET_SECONDS = 20 را اعمال می‌کند. زمانی که بودجه تمام شود و صفحات بیشتری برای پردازش باقی بمانند، همگام‌ساز:

1. یک نشانگر ازسرگیری را به‌عنوان یک داده موقت وردپرس ذخیره می‌کند: pitchbar_post_sync_resume برای پست‌ها، pitchbar_product_sync_resume برای محصولات. شکل: { "page": 7, "at": 1715472000 }.
2. یک ادامه WP-Cron را ۳۰ ثانیه بعد در همان هوک (pitchbar_run_full_sync_event / pitchbar_run_product_sync_event) زمان‌بندی می‌کند.
3. بلافاصله با more: true، next_page: 7 در پاسخ برمی‌گردد تا رابط مدیریت بداند "سایت بزرگ تشخیص داده شد، بقیه در پس‌زمینه ادامه دارد."

اجرای مجدد "همگام‌سازی اکنون" در حالی که یک نشانگر ازسرگیری وجود دارد، از جایی که آخرین بار متوقف شده است، ادامه می‌دهد. تکمیل موفقیت‌آمیز (بدون صفحه بیشتر) نشانگر ازسرگیری را پاک می‌کند.

در حالی که یک همگام‌سازی تکه‌تکه در حال انجام است، هر صفحه مدیریت وردپرس یک اعلان ملایم نشان می‌دهد: "Pitchbar در حال اتمام یک همگام‌سازی سایت بزرگ در پس‌زمینه است (پست‌ها). ویجت در حال حاضر کار می‌کند. محتوای جدید پس از اتمام این کار ظاهر می‌شود."

همگام‌سازی دلتا (خودکار)

در هر save_post، wp_trash_post یا before_delete_post برای یک نوع پست فعال‌شده با وضعیت publish، افزونه یک فراخوانی دلتای واحد به Pitchbar ارسال می‌کند:

نقطه پایانی	محرک	شکل بدنه
POST /api/v1/wp/posts/changed	save_post / wp_trash_post / before_delete_post روی یک نوع پست فعال‌شده.	یک payload پست + action: "upsert" یا "delete".
POST /api/v1/wp/products/changed	woocommerce_new_product، woocommerce_update_product، woocommerce_delete_product، woocommerce_trash_product.	یک payload محصول + action: "upsert" یا "delete".

همگام‌سازی انبوه از نقاط پایانی موازی /posts/sync و /products/sync با حداکثر ۵۰ نهاد در هر دسته استفاده می‌کند. هر دو نقطه پایانی دقیقاً به یک روش احراز هویت می‌شوند (حامل + HMAC).

نرمال‌سازی محتوا

PostContentExtractor افزونه، HTML قابل مشاهده را برای هر پست قبل از ارسال به Pitchbar حل می‌کند:

1. تشخیص سازنده صفحه — اگر پست متعلق به Elementor، Beaver Builder، Oxygen یا Bricks باشد، به‌جای post_content، نمایش‌دهنده بومی سازنده فراخوانی می‌شود. مشاهده کنید سازندگان صفحه.
2. مقداردهی اولیه داده‌های پست — $GLOBALS['post'] تنظیم شده و setup_postdata() فراخوانی می‌شود تا فیلترهای the_content شخص ثالث (Yoast، Jetpack، Divi، نصب‌ها) یک $post سراسری معتبر ببینند.
3. گسترش بلوک — do_blocks() هر بلوک گوتنبرگ را حل می‌کند.
4. زنجیره فیلتر — apply_filters('the_content', …) هر هوک تم/افزونه را اجرا می‌کند (بارگذاری تنبل، جایگزینی تصویر، پست‌های مرتبط و غیره).
5. حل کد کوتاه — do_shortcode() هر کد کوتاه باقی‌مانده را حل می‌کند.
6. لغو فیلتر — HTML نهایی از طریق فیلتر pitchbar_post_content_html خود شما اجرا می‌شود که به شما امکان می‌دهد ظاهر ناوبری را حذف کنید، یک قالب سفارشی را اعمال کنید یا به‌طور کامل مسیر را کوتاه کنید. "لغو HTML همگام‌سازی‌شده" را در زیر مشاهده کنید.
7. پاک‌سازی — $GLOBALS['post'] بازیابی شده و wp_reset_postdata() در داخل یک بلوک finally فراخوانی می‌شود، بنابراین یک فراخوانی فیلتر خطا‌دهنده نمی‌تواند وضعیت حلقه را نشت دهد.

هش محتوا و رد شدن در صورت عدم تغییر

هر همگام‌سازی (انبوه یا دلتا) یک فیلد content_hash ارسال می‌کند. Pitchbar آن را با هش ذخیره‌شده سند موجود مقایسه می‌کند. در صورت تطابق، سرور بلافاصله بدون تکه‌تکه کردن یا بازپردازش، پاسخ می‌دهد. اجرای مجدد "همگام‌سازی اکنون" در یک سایت پایدار عملاً رایگان است — فقط تفاوت هزینه دارد.

هش SHA-256 از الحاق نرمال‌شده است:

sha256( title + "\n" + content_html + "\n" + excerpt + "\n" + taxonomy_term_names )

فاصله‌ها قبل از هش به‌صورت preg_replace('/\s+/u', ' ', …) به یک فاصله واحد تبدیل می‌شوند تا یک بازچینش ساده باعث بازپردازش نشود.

آنچه به ازای هر پست پردازش می‌شود

• عنوان پست (متن ساده، رمزگشایی نهادها، تگ‌ها حذف شده‌اند)
• خلاصه — خلاصه صریح پست در صورت تنظیم، در غیر این صورت ۴۰ کلمه اول محتوای حذف‌شده
• نام‌های اصطلاحات طبقه‌بندی — هر اصطلاح در هر طبقه‌بندی که نوع پست ثبت می‌کند (دسته‌بندی‌ها، برچسب‌ها، طبقه‌بندی‌های سفارشی)
• بدنه HTML — به‌طور کامل همانطور که در بالا توضیح داده شد گسترش یافته، در سمت سرور از تگ‌ها به تکه‌ها حذف شده است
• لینک دائمی، نوع پست، زمان‌مهر تغییر، زبان تشخیص‌داده‌شده (از محلی وردپرس)

آنچه به ازای هر محصول ووکامرس پردازش می‌شود

• نام، SKU، لینک دائمی، آدرس تصویر اصلی (اندازه متوسط)
• توضیحات کوتاه + توضیحات بلند (بلوک‌های گوتنبرگ گسترش یافته، کدهای کوتاه حل شده، فیلتر the_content اعمال شده)
• قیمت، regular_price، sale_price، واحد پول، پرچم on_sale، stock_status
• نام‌های دسته‌بندی (از طریق طبقه‌بندی product_cat)
• نام ویژگی + جفت‌های مقدار به رشته‌های "color: blue, red" مسطح می‌شوند تا جستجوی هوشمند هر دو را دریافت کند
• SHA-256 content_hash + ISO 8601 modified_at

همگام‌سازی کوپن

کوپن‌ها همراه با همگام‌سازی محصولات ارسال می‌شوند. پس از هر همگام‌سازی محصول موفق (تکمیل‌شده تا انتها، نه در میانه راه)، CouponSyncer افزونه یک تصویر لحظه‌ای اجرا می‌کند:

1. تا ۵۰ ورودی با وضعیت publish از نوع پست سفارشی shop_coupon را از طریق get_posts() شمارش می‌کند — این در هر نسخه ووکامرس از زمانی که کوپن‌ها در WC 2.0 ارسال شدند، کار می‌کند. (قبلاً افزونه از wc_get_coupons() استفاده می‌کرد که در هر نسخه یک API عمومی ووکامرس نیست.)
2. هر تطابق را از طریق new WC_Coupon($id) (یک کلاس پایدار ووکامرس) هیدراته می‌کند.
3. کوپن‌هایی که منقضی شده‌اند (get_date_expires() < now) یا قبلاً از محدودیت استفاده خود گذشته‌اند را فیلتر می‌کند.
4. نتیجه را به POST /api/v1/wp/coupons/sync ارسال می‌کند. Pitchbar آنها را در آرایه config['coupons'] منبع ذخیره می‌کند.

برای هر کوپن، افزونه ارسال می‌کند: code (حروف بزرگ)، label (انسانی: "۱۰٪ تخفیف"، "۵ دلار تخفیف در سفارش" و غیره)، discount، expires_at. برای نحوه استفاده هوش مصنوعی از این موارد، لینک‌های عمیق ووکامرس را مشاهده کنید.

تغییر خودکار به عمودی فروشگاهی

در اولین درج موفق محصول در برابر یک دستیار فروش که site_type آن generic است، Pitchbar به‌طور خودکار دستیار فروش را به site_type = "ecommerce" تغییر می‌دهد. این کار قطعه راهنمای سیستم EcommercePreset و قوانین انتشار بلوک درون‌خطی <product/> را فعال می‌کند تا هوش مصنوعی بتواند محصولات را به‌عنوان کارت‌های غنی به‌جای متن ساده توصیه کند.

این تغییر فقط زمانی فعال می‌شود که site_type generic باشد. دستیاران فروش که قبلاً روی saas، documentation یا ecommerce صریح هستند، هرگز بازنویسی نمی‌شوند.

معانی حذف

before_delete_post / woocommerce_delete_product یک دلتای delete واحد را فعال می‌کنند. Pitchbar سند، تکه‌های آن و نقاط جستجوی هوشمند مرتبط با آن را حذف می‌کند. حذف یک نهاد که Pitchbar هرگز ندیده است، یک عملیات بی‌صدا است (HTTP 200 با deleted: false) بنابراین پاک‌سازی مکرر ایمن است.

لغو HTML همگام‌سازی‌شده

فیلتر خود را برای تغییر HTML که افزونه به Pitchbar ارسال می‌کند، اعمال کنید — هدر سایت را حذف کنید، یک قالب Elementor را اعمال کنید، یک بخش را محرمانه کنید و غیره.

add_filter('pitchbar_post_content_html', function ($html, $post, $builder) {
    // $builder نامک سازنده صفحه تشخیص‌داده‌شده است، یا null برای
    // پست‌های ساده گوتنبرگ. به عنوان مثال 'elementor', 'divi', 'bricks'.
    if ($post->post_type === 'product') {
        return $html;
    }

    // هر ظاهر ناوبری باقی‌مانده‌ای که تم ما از طریق
    // the_content تزریق می‌کند را حذف کنید. Pitchbar قبلاً کار حذف تگ‌های خود را انجام می‌دهد،
    // اما انجام آن در اینجا سربار تکه‌ها را کاهش می‌دهد.
    $html = preg_replace('#<nav[^>]*>.*?</nav>#is', '', $html);

    return $html;
}, 10, 3);

فیلتر HTML کاملاً نمایش داده شده را قبل از هش و ارسال POST دریافت می‌کند. بازگرداندن '' به‌طور مؤثر همگام‌سازی را برای آن پست غیرفعال می‌کند (Pitchbar محتوای خالی را می‌بیند و از نصب چیزی خودداری می‌کند).

همگام‌سازی برنامه‌نویسی (از PHP)

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

// پست‌ها
$result = (new \Pitchbar\Sync\PostSyncer)->runFullSync();
// $result['ok'], $result['posts'], $result['more'], $result['next_page']

// محصولات (نیاز به ووکامرس دارد)
$result = (new \Pitchbar\Sync\ProductSyncer)->runFullSync();

// کوپن‌ها
$result = (new \Pitchbar\Sync\CouponSyncer)->run();

هیچ‌کدام از اینها خطا نمی‌دهند — آنها آرایه‌های نتیجه را با یک کلید ok، یک آرایه errors و (برای همگام‌سازهای تکه‌تکه) فیلدهای more + next_page برای پیگیری ازسرگیری برمی‌گردانند.