מדריך פתרון בעיות

בעיות נפוצות ופתרונות למפתחי WooAI Chatbot Pro.

מסמך זה קיים כי נמאס לי לענות על אותן שאלות ב-Slack.
אם מצאת בעיה חדשה + פתרון, בבקשה הוסף אותו כאן. העתיד שלך יודה לך.

---

1. בעיות התקנה

הפעלת הפלאגין נכשלת

סימפטומים: מסך לבן או שגיאת PHP fatal בהפעלה.

פתרונות:

// Check PHP version (requires 8.1+)
echo phpversion(); // Must be >= 8.1.0

// Check memory limit
echo ini_get('memory_limit'); // Should be >= 256M

// Verify WooCommerce is active
if ( ! class_exists( 'WooCommerce' ) ) {
    // WooCommerce must be installed and activated first
}

שלבי ניפוי באגים:

1. הפעל WP_DEBUG ב-wp-config.php:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

1. בדוק /wp-content/debug.log לשגיאות
2. אמת תלויות Composer: composer install --no-dev

נכסים לא נטענים

סימפטומים: ווידג'ט הצ'אט לא מופיע, לוח הניהול ריק.

פתרונות:

# Rebuild assets
cd /path/to/woo-ai-chatbot-pro
npm install
npm run build

# Verify build output
ls -la assets/dist/
# Should contain: admin.js, chat.js, admin.css, chat.css

סיבות נפוצות:

• חסר npm run build אחרי git pull
• גרסת Node.js < 18
• פלאגין מתנגש שמטעין scripts עם אותו handle

---

2. בעיות ספק AI

אימות מפתח API נכשל

שגיאה: Invalid API key או Authentication failed

// Debug API key configuration
$settings = get_option( 'woo_ai_chatbot_settings' );
error_log( 'Provider: ' . $settings['ai_provider'] );
error_log( 'Key set: ' . ( ! empty( $settings['openai_api_key'] ) ? 'yes' : 'no' ) );

// Test API key directly
add_action( 'admin_init', function() {
    $orchestrator = WooAIChatbotAIAIOrchestrator::instance();
    $result = $orchestrator->validate_current_provider();
    if ( is_wp_error( $result ) ) {
        error_log( 'API Error: ' . $result->get_error_message() );
    }
});

הגבלת קצב

שגיאה: 429 Too Many Requests

// Check rate limit status
$user_id = get_current_user_id() ?: $_SERVER['REMOTE_ADDR'];
$transient_key = 'wooai_rate_' . md5( $user_id );
$requests = get_transient( $transient_key );
error_log( "Current requests: $requests / 30 per minute" );

// Temporarily increase limit (not recommended for production)
add_filter( 'wooai_rate_limit', fn() => 60 );
add_filter( 'wooai_rate_window', fn() => 120 );

Fallback ספק לא עובד

// Debug provider chain
add_action( 'wooai_before_ai_request', function( $provider, $messages ) {
    error_log( "Using provider: " . get_class( $provider ) );
}, 10, 2 );

add_action( 'wooai_provider_fallback', function( $failed_provider, $next_provider, $error ) {
    error_log( "Fallback from {$failed_provider} to {$next_provider}: {$error->get_error_message()}" );
}, 10, 3 );

---

3. בעיות ווידג'ט צ'אט

הווידג'ט לא מופיע

רשימת בדיקה:

1. בדוק החרגות עמודים ב-Settings > Display
2. אמת הגדרות מכשיר (מובייל/דסקטופ)
3. בדוק שה-footer של התבנית מכיל <?php wp_footer(); ?>

// Debug widget rendering
add_action( 'wp_footer', function() {
    error_log( 'wp_footer fired' );
    $settings = get_option( 'woo_ai_chatbot_settings' );
    error_log( 'Widget enabled: ' . ( $settings['enabled'] ?? 'not set' ) );
}, 1 );

// Check if widget script is enqueued
add_action( 'wp_print_scripts', function() {
    global $wp_scripts;
    $is_enqueued = wp_script_is( 'woo-ai-chatbot-widget', 'enqueued' );
    error_log( "Widget script enqueued: " . ( $is_enqueued ? 'yes' : 'no' ) );
});

קונפליקטים בסגנון הווידג'ט

/* Reset conflicting theme styles */
#woo-ai-chatbot-widget {
    all: initial;
    font-family: inherit;
}

/* Increase specificity */
body #woo-ai-chatbot-widget .chat-message {
    /* Your overrides */
}

// Dequeue conflicting styles
add_action( 'wp_enqueue_scripts', function() {
    wp_dequeue_style( 'conflicting-plugin-css' );
}, 100 );

הודעות לא נשלחות

// Debug in browser console
window.WooAIChatbot.debug = true;

// Check nonce
console.log('Nonce:', window.wooAiChatbot?.nonce);

// Manual API test
fetch('/wp-json/woo-ai/v1/chat/message', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-WP-Nonce': window.wooAiChatbot.nonce
    },
    body: JSON.stringify({
        session_id: 'test-session-123',
        message: 'Hello'
    })
}).then(r => r.json()).then(console.log);

---

4. בעיות Playbook

Playbook לא מופעל

// Debug playbook matching
add_filter( 'wooai_playbook_match_debug', '__return_true' );

add_action( 'wooai_playbook_match_result', function( $playbook_id, $matched, $context ) {
    error_log( "Playbook {$playbook_id} matched: " . ( $matched ? 'yes' : 'no' ) );
    error_log( "Context: " . print_r( $context, true ) );
});

// Check playbook status
$playbook = get_post( $playbook_id );
error_log( "Status: {$playbook->post_status}" ); // Must be 'publish'

שגיאות ביצוע שלב

// Log step execution
add_action( 'wooai_playbook_step_execute', function( $step, $state ) {
    error_log( "Executing step: {$step['id']} type: {$step['type']}" );
}, 10, 2 );

add_action( 'wooai_playbook_step_error', function( $step, $error ) {
    error_log( "Step error: {$step['id']} - {$error->getMessage()}" );
}, 10, 2 );

---

5. בעיות מסד נתונים

טבלאות לא נוצרו

// Manually run table creation
$activator = new WooAIChatbotActivator();
$activator->create_tables();

// Check if tables exist
global $wpdb;
$tables = [
    $wpdb->prefix . 'wooai_conversations',
    $wpdb->prefix . 'wooai_messages',
    $wpdb->prefix . 'wooai_analytics'
];
foreach ( $tables as $table ) {
    $exists = $wpdb->get_var( "SHOW TABLES LIKE '$table'" ) === $table;
    error_log( "$table exists: " . ( $exists ? 'yes' : 'no' ) );
}

אובדן נתוני Session

// Check session storage
$session_id = 'your-session-id';
global $wpdb;
$session = $wpdb->get_row( $wpdb->prepare(
    "SELECT * FROM {$wpdb->prefix}wooai_conversations WHERE session_id = %s",
    $session_id
));
error_log( "Session: " . print_r( $session, true ) );

// Clear stale sessions (run via WP-CLI or cron)
$wpdb->query( $wpdb->prepare(
    "DELETE FROM {$wpdb->prefix}wooai_conversations WHERE updated_at < %s",
    date( 'Y-m-d H:i:s', strtotime( '-7 days' ) )
));

---

6. בעיות ביצועים

תגובות AI איטיות

// Profile AI request time
add_action( 'wooai_before_ai_request', function() {
    defined( 'WOOAI_REQUEST_START' ) || define( 'WOOAI_REQUEST_START', microtime( true ) );
});

add_action( 'wooai_after_ai_response', function( $response ) {
    $duration = microtime( true ) - WOOAI_REQUEST_START;
    error_log( "AI request took: {$duration}s" );
    if ( $duration > 5 ) {
        error_log( "WARNING: Slow AI response. Consider caching or reducing context." );
    }
});

שימוש גבוה בזיכרון

// Monitor memory
add_action( 'wooai_before_ai_request', function() {
    error_log( 'Memory before: ' . memory_get_usage( true ) / 1024 / 1024 . 'MB' );
});

add_action( 'wooai_after_ai_response', function() {
    error_log( 'Memory after: ' . memory_get_usage( true ) / 1024 / 1024 . 'MB' );
    error_log( 'Peak memory: ' . memory_get_peak_usage( true ) / 1024 / 1024 . 'MB' );
});

---

7. קודי שגיאה נפוצים

קוד	הודעה	פתרון
invalid_session	Session not found	צור session חדש דרך /chat/session
rate_limit_exceeded	Too many requests	המתן 60 שניות או הגדל מגבלה
ai_provider_error	Provider API failed	בדוק מפתח API ומכסה
tool_execution_failed	Tool returned error	בדוק מוצר/עגלה ב-WooCommerce
playbook_not_found	Playbook ID invalid	ודא שה-playbook מפורסם
permission_denied	Insufficient caps	המשתמש צריך manage_woocommerce
validation_error	Invalid request data	בדוק פרמטרים נדרשים

---

8. מצב Debug

הפעל ניפוי באגים מקיף:

// wp-config.php
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WOOAI_DEBUG', true );
define( 'WOOAI_LOG_AI_REQUESTS', true ); // Logs full AI requests/responses

// Browser console
localStorage.setItem('wooai_debug', 'true');

---

9. "ניסיתי הכל וזה עדיין לא עובד"

מקרים אמיתיים מפרודקשן שלקח הרבה זמן לנפות:

מקרה 1: הווידג'ט עבד מקומית, שבור ב-staging

• סיבה: Cloudflare Rocket Loader שכתב את ה-JS שלנו
• תיקון: הוספת data-cfasync="false" לתג הסקריפט

מקרה 2: הצ'אט עבד, אבל מוצרים אף פעם לא הוצגו

• סיבה: WooCommerce REST API היה מושבת על ידי פלאגין אבטחה (Wordfence)
• תיקון: הוספת /wp-json/wc/v3/* לרשימה הלבנה בהגדרות Wordfence

מקרה 3: תגובות AI תמיד היו באנגלית למרות ממשק באוקראינית

• סיבה: ה-system prompt לא כלל הוראת שפה
• תיקון: הוספת פילטר wooai_system_prompt עם Respond in {locale} – ראה מסמך hooks

מקרה 4: דליפת זיכרון באתר עם תעבורה גבוהה (5k+ sessions/יום)

• סיבה: Sessions לא נוקו
• תיקון: הוספת WP-Cron job למחיקת sessions ישנים מ-7 ימים

10. קבלת עזרה

1. בדוק לוגים: /wp-content/debug.log
2. קונסול דפדפן: F12 > לשונית Console
3. לשונית Network: בדוק תגובות API
4. Slack: ערוץ #wooai-dev (צוות פנימי בלבד)