# הנחיות תרומה מסמך זה מספק הנחיות מקיפות לתרומה ל-WooAI Chatbot Pro. עקביות בסטנדרטים אלה מבטיחה קוד עקבי, ניתן לתחזוקה ושיתוף פעולה יעיל. > **בקיצור:** Fork → Branch → Code → Test → PR. בדרך כלל אנחנו סוקרים תוך 48 שעות. > > **בבקשה אל:** > – לשלוח PR ללא בדיקות (פשוט נבקש ממך להוסיף אותן) > – "לתקן" סגנון קוד בקבצים שלא שינית (מקשה על הסקירה) > – להוסיף תלויות ללא דיון קודם (גודל ה-bundle חשוב) — ## 1. תחילת העבודה ### דרישות מקדימות ודא שסביבת הפיתוח שלך עומדת בדרישות אלה: | דרישה | גרסה מינימלית | מומלץ | |——-|—————|——-| | PHP | 8.1 | 8.2+ | | Node.js | 18.0.0 | 20 LTS | | npm | 9.0.0 | 10+ | | Composer | 2.0 | 2.7+ | | WordPress | 6.0 | 6.4+ | | WooCommerce | 8.0 | 9.0+ | ### מבנה המאגר

WP_plugin_chat_ai/
├── assets/                 # נכסי Frontend (מקומפלים)
│   ├── admin/             # נכסי לוח ניהול
│   └── chat/              # נכסי ווידג'ט הצ'אט
├── assets/src/            # קבצי מקור TypeScript/React
├── includes/              # קוד PHP (PSR-4 autoloaded)
├── templates/             # קבצי תבניות PHP
├── tests/                 # חבילות בדיקות
├── docs/                  # תיעוד
├── vendor/                # תלויות Composer (git-ignored)
├── node_modules/          # תלויות npm (git-ignored)
├── composer.json          # תלויות PHP
├── package.json           # תלויות Node
├── webpack.config.js      # קונפיגורציית Build
├── tsconfig.json          # קונפיגורציית TypeScript
├── phpcs.xml              # קונפיגורציית PHP_CodeSniffer
└── woo-ai-chatbot-pro.php # קובץ הפלאגין הראשי

— ## 2. הגדרת סביבת פיתוח ### שכפול והתקנה

# Clone the repository
git clone https://github.com/LeoWebMarketing/WP_plugin_chat_ai.git
cd WP_plugin_chat_ai

# Install PHP dependencies
composer install

# Install Node dependencies
npm install

### קונפיגורציית סביבה העתק את קובץ הסביבה לדוגמה והגדר את מפתחות ה-API שלך:

cp .env.example .env

קונפיגורציה נדרשת ב-`.env`:

# AI Provider API Keys (at least one required)
GEMINI_API_KEY=your_gemini_api_key
OPENAI_API_KEY=your_openai_api_key
ANTHROPIC_API_KEY=your_anthropic_api_key

# Supabase Configuration (for RAG features)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your_anon_key
SUPABASE_SERVICE_KEY=your_service_key

# Development
DEBUG_MODE=true
LOG_LEVEL=debug

מקורות מפתחות API: – **Gemini**: [Google AI Studio](https://aistudio.google.com/app/apikey) – **OpenAI**: [OpenAI Platform](https://platform.openai.com/api-keys) – **Claude**: [Anthropic Console](https://console.anthropic.com/settings/keys) ### הגדרת WordPress מקומי 1. התקן [Local](https://localwp.com/) או הגדר LAMP/LEMP stack 2. צור אתר WordPress חדש 3. צור symlink או העתק את הפלאגין ל-`wp-content/plugins/` 4. הפעל את WooCommerce ו-WooAI Chatbot Pro

# Symlink example (macOS/Linux)
ln -s /path/to/WP_plugin_chat_ai /path/to/wordpress/wp-content/plugins/woo-ai-chatbot-pro

### תהליך Build

# Development build with watch mode
npm run dev

# Production build (minified, optimized)
npm run build

# Development build (single run)
npm run build:dev

# Type checking
npm run typecheck

# Linting
npm run lint          # ESLint with auto-fix
npm run lint:check    # ESLint check only

# PHP Code Sniffer
composer run phpcs    # Check standards
composer run phpcbf   # Auto-fix violations

# PHPStan static analysis
composer run phpstan

# Run tests
npm run test          # Jest tests
composer run test     # PHPUnit tests

— ## 3. סטנדרטים לקוד ### PHP #### סטנדרטים לקוד WordPress כל קוד PHP חייב לעמוד ב-[WordPress Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/):

<?php
/**
 * Class description.
 *
 * @package WooAIChatbot
 * @since   1.0.0
 */

declare(strict_types=1);

namespace WooAIChatbotServices;

use WooAIChatbotContractsProviderInterface;
use WooAIChatbotExceptionsApiException;

/**
 * Handles AI provider operations.
 */
class AIService {

    /**
     * Provider instance.
     *
     * @var ProviderInterface
     */
    private ProviderInterface $provider;

    /**
     * Constructor.
     *
     * @param ProviderInterface $provider AI provider instance.
     */
    public function __construct( ProviderInterface $provider ) {
        $this->provider = $provider;
    }

    /**
     * Generate response from AI.
     *
     * @param string $prompt User prompt.
     * @param array  $context Conversation context.
     *
     * @return string Generated response.
     *
     * @throws ApiException If API request fails.
     */
    public function generate_response( string $prompt, array $context = [] ): string {
        if ( empty( $prompt ) ) {
            throw new InvalidArgumentException( 'Prompt cannot be empty.' );
        }

        return $this->provider->complete( $prompt, $context );
    }
}

#### PSR-4 Autoloading מוסכמת Namespace: `WooAIChatbot{SubNamespace}`

{
    "autoload": {
        "psr-4": {
            "WooAIChatbot": "includes/"
        }
    }
}

מבנה הקבצים חייב לשקף את ה-namespace: – `WooAIChatbotServicesAIService` ממופה ל-`includes/Services/AIService.php` – `WooAIChatbotProvidersOpenAI` ממופה ל-`includes/Providers/OpenAI.php` #### קונפיגורציית PHPCS הפרויקט משתמש ב-WordPress Coding Standards. הרץ לפני כל commit:

# Check violations
composer run phpcs

# Auto-fix where possible
composer run phpcbf

### JavaScript/TypeScript #### כללי ESLint הפרויקט אוכף תבניות TypeScript ו-React קפדניות:

# Lint with auto-fix
npm run lint

# Check only (used in CI)
npm run lint:check

#### TypeScript Strict Mode כל TypeScript חייב לעבור בדיקת טיפוסים קפדנית:

// tsconfig.json strict mode is enabled
// Avoid 'any' - use proper types

// Bad
const processData = (data: any) => { ... };

// Good
interface ChatMessage {
    id: string;
    content: string;
    role: 'user' | 'assistant';
    timestamp: Date;
}

const processData = (data: ChatMessage): void => { ... };

#### תבניות React השתמש ב-functional components עם hooks:

import React, { useState, useCallback, useMemo } from 'react';
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
import { Button } from '@/components/ui/button';

interface ChatWidgetProps {
    initialMessage?: string;
    onSend: (message: string) => Promise<void>;
}

export const ChatWidget: React.FC<ChatWidgetProps> = ({
    initialMessage = '',
    onSend,
}) => {
    const [message, setMessage] = useState(initialMessage);
    const [isLoading, setIsLoading] = useState(false);

    const handleSubmit = useCallback(async () => {
        if (!message.trim()) return;

        setIsLoading(true);
        try {
            await onSend(message);
            setMessage('');
        } finally {
            setIsLoading(false);
        }
    }, [message, onSend]);

    const isDisabled = useMemo(
        () => isLoading || !message.trim(),
        [isLoading, message]
    );

    return (
        <Card>
            <CardHeader>
                <CardTitle>Chat</CardTitle>
            </CardHeader>
            <CardContent>
                <Button onClick={handleSubmit} disabled={isDisabled}>
                    {isLoading ? 'Sending...' : 'Send'}
                </Button>
            </CardContent>
        </Card>
    );
};

### CSS #### מוסכמות Tailwind השתמש ב-Tailwind CSS utility classes. העדף הרכבה על פני CSS מותאם אישית:

// Use Tailwind utilities
<div className="flex items-center gap-4 p-4 bg-white dark:bg-gray-900 rounded-lg shadow-sm">
    <span className="text-sm font-medium text-gray-700 dark:text-gray-200">
        {label}
    </span>
</div>

#### מתודולוגיית BEM (CSS ישן) עבור CSS שאינו Tailwind, השתמש במתודולוגיית BEM:

/* Block */
.woo-chatbot {}

/* Element */
.woo-chatbot__header {}
.woo-chatbot__message {}

/* Modifier */
.woo-chatbot__message--user {}
.woo-chatbot__message--assistant {}

#### שיקולי RTL הפרויקט תומך בשפות RTL (עברית). השתמש ב-logical properties:

/* Use logical properties for RTL support */
.element {
    margin-inline-start: 1rem;  /* Not margin-left */
    padding-inline-end: 1rem;   /* Not padding-right */
    text-align: start;          /* Not text-align: left */
}

PostCSS מייצר אוטומטית וריאנטים RTL דרך `postcss-rtlcss`. — ## 4. תהליך עבודה עם Git ### מתן שמות לענפים

# Features
feature/add-claude-provider
feature/rag-vector-search
feature/multilingual-support

# Bug fixes
fix/session-timeout-issue
fix/api-rate-limiting
fix/rtl-alignment

# Refactoring
refactor/provider-abstraction
refactor/database-queries

# Documentation
docs/api-reference
docs/installation-guide

# Chores
chore/update-dependencies
chore/ci-configuration

### הודעות Commit עקוב אחר [Conventional Commits](https://www.conventionalcommits.org/):

# Format
<type>(<scope>): <description>

[optional body]

[optional footer(s)]

#### סוגים | סוג | תיאור | |—–|——-| | `feat` | פיצ'ר חדש | | `fix` | תיקון באג | | `docs` | תיעוד בלבד | | `style` | סגנון קוד (פורמט, נקודה-פסיק) | | `refactor` | שינוי קוד ללא פיצ'ר/תיקון | | `perf` | שיפור ביצועים | | `test` | הוספה/עדכון בדיקות | | `build` | שינויים במערכת ה-build | | `ci` | קונפיגורציית CI | | `chore` | משימות תחזוקה | #### דוגמאות Scope – `chat` – ווידג'ט הצ'אט – `admin` – לוח הניהול – `api` – REST API – `rag` – RAG/חיפוש וקטורי – `providers` – ספקי AI – `i18n` – בינלאומיות #### דוגמאות

feat(providers): add Anthropic Claude support

Implement ClaudeProvider class with streaming support.
Includes rate limiting and error handling.

Closes #42

---

fix(chat): resolve message duplication on reconnect

Messages were being duplicated when WebSocket reconnected.
Added deduplication based on message ID.

Fixes #87

---

refactor(api): extract validation to dedicated class

Move request validation logic from controllers to
RequestValidator class for better separation of concerns.

BREAKING CHANGE: ValidationException now extends ApiException

### Pull Requests #### תבנית PR

## Summary

Brief description of changes.

## Type of Change

- [ ] Bug fix (non-breaking change fixing an issue)
- [ ] New feature (non-breaking change adding functionality)
- [ ] Breaking change (fix or feature causing existing functionality to change)
- [ ] Documentation update

## Changes Made

- Bullet points describing specific changes
- Include file paths for significant changes

## Testing

- [ ] Unit tests pass (`composer run test`)
- [ ] Integration tests pass
- [ ] Manual testing performed
- [ ] Tested on PHP 8.1 and 8.2

## Screenshots (if applicable)

## Checklist

- [ ] Code follows project coding standards
- [ ] Self-reviewed the code
- [ ] Added/updated documentation
- [ ] Added/updated tests
- [ ] No new warnings generated

#### תהליך סקירה 1. צור PR מענף פיצ'ר ל-`main` 2. ודא שכל בדיקות CI עוברות 3. בקש סקירה ממתחזק 4. התייחס למשוב הסקירה 5. Squash and merge לאחר אישור #### דרישות מיזוג – כל בדיקות CI עוברות – לפחות אישור אחד ממתחזק – אין שיחות פתוחות – מעודכן עם ענף `main` — ## 5. דרישות בדיקות ### כיסוי נדרש – מינימום 80% כיסוי קוד לקוד חדש – לכל המתודות הציבוריות חייבות להיות בדיקות – נתיבים קריטיים דורשים בדיקות אינטגרציה ### הרצת בדיקות

# PHP Tests
composer run test                    # All tests
composer run test:unit              # Unit tests only
composer run test:integration       # Integration tests
composer run test:coverage          # Generate coverage report

# JavaScript Tests
npm run test                        # Run Jest tests
npm run test:watch                  # Watch mode
npm run test:coverage               # Coverage report

### רשימת בדיקה לפני PR

# Run all checks before creating PR
npm run typecheck && npm run lint && npm run test
composer run phpcs && composer run phpstan && composer run test

### בדיקות CI כל PR מפעיל: 1. בדיקת תחביר PHP (`php -l`) 2. PHPCS (WordPress Coding Standards) 3. PHPStan (Level 5) 4. בדיקות PHPUnit 5. ESLint 6. קומפילציית TypeScript 7. בדיקות Jest 8. אימות Build — ## 6. תיעוד ### תיעוד Inline #### סטנדרטים PHPDoc

/**
 * Generate AI response based on user input and context.
 *
 * This method orchestrates the AI response generation by:
 * 1. Validating input parameters
 * 2. Retrieving relevant context via RAG
 * 3. Calling the configured AI provider
 * 4. Processing and sanitizing the response
 *
 * @since 1.0.0
 *
 * @param string $prompt      User's input message.
 * @param array  $options {
 *     Optional. Configuration options.
 *
 *     @type string $model       AI model to use.
 *     @type int    $max_tokens  Maximum response tokens.
 *     @type float  $temperature Response creativity (0.0-1.0).
 *     @type bool   $use_rag     Whether to use RAG context.
 * }
 *
 * @return string Sanitized AI response.
 *
 * @throws ApiException        If API request fails.
 * @throws ValidationException If input validation fails.
 */
public function generate( string $prompt, array $options = [] ): string;

#### סטנדרטים JSDoc

/**
 * Custom hook for managing chat state and API interactions.
 *
 * Handles message sending, receiving, and conversation history.
 * Implements optimistic updates and error recovery.
 *
 * @param config - Configuration options
 * @param config.endpoint - API endpoint URL
 * @param config.sessionId - Current session identifier
 * @param config.onError - Error callback
 *
 * @returns Chat state and control functions
 *
 * @example
 * ```tsx
 * const { messages, sendMessage, isLoading } = useChat({
 *     endpoint: '/wp-json/woo-ai-chatbot/v1/chat',
 *     sessionId: 'abc123',
 * });
 * ```
 */
export function useChat(config: ChatConfig): UseChatReturn;

### עדכוני README בעת הוספת פיצ'רים: 1. עדכן את רשימת הפיצ'רים ב-README הראשי 2. הוסף אפשרויות קונפיגורציה לתיעוד 3. כלול דוגמאות שימוש 4. עדכן את ה-changelog — ## 7. תהליך שחרור ### עדכון גרסה עקוב אחר [Semantic Versioning](https://semver.org/): – **MAJOR** (1.0.0): שינויים שוברים – **MINOR** (0.1.0): פיצ'רים חדשים, תואם לאחור – **PATCH** (0.0.1): תיקוני באגים, תואם לאחור עדכן גרסה ב: 1. `woo-ai-chatbot-pro.php` (כותרת הפלאגין) 2. `package.json` 3. `composer.json` ### עדכוני Changelog תחזק `CHANGELOG.md` בעקבות [Keep a Changelog](https://keepachangelog.com/):

## [1.2.0] - 2025-01-15

### Added
- Claude AI provider support
- Streaming responses for all providers
- Hebrew language support

### Changed
- Improved RAG retrieval accuracy
- Updated shadcn/ui components

### Fixed
- Session persistence across page reloads
- RTL layout issues in chat widget

### Security
- Added input sanitization for message content

### יצירת Tag

# Create annotated tag
git tag -a v1.2.0 -m "Release v1.2.0 - Claude provider support"

# Push tags
git push origin v1.2.0

— ## 8. אבטחה ### דיווח על פגיעויות **אל תפתח issues ציבוריים עבור פגיעויות אבטחה.** דווח על בעיות אבטחה באימייל: `security@leowebmarketing.pro` כלול: – תיאור הפגיעות – שלבים לשחזור – השפעה פוטנציאלית – תיקון מוצע (אם יש) ### שיקולי אבטחה #### סניטציה של קלט תמיד סנן קלט משתמש:

// Sanitize text input
$message = sanitize_text_field( wp_unslash( $_POST['message'] ?? '' ) );

// Sanitize HTML content
$content = wp_kses_post( $raw_content );

// Escape output
echo esc_html( $message );
echo esc_attr( $attribute );
echo esc_url( $url );

#### בדיקות הרשאות אמת הרשאות משתמש לפני פעולות:

// Check capability before admin actions
if ( ! current_user_can( 'manage_woocommerce' ) ) {
    wp_die( esc_html__( 'Unauthorized access.', 'woo-ai-chatbot-pro' ) );
}

// Verify nonces for form submissions
if ( ! wp_verify_nonce( $_POST['_wpnonce'] ?? '', 'woo_ai_chatbot_settings' ) ) {
    wp_die( esc_html__( 'Security check failed.', 'woo-ai-chatbot-pro' ) );
}

#### הגנה על מפתחות API לעולם אל תחשוף מפתחות API:

// Store securely in options (encrypted if possible)
update_option( 'woo_ai_chatbot_api_key', $encrypted_key );

// Never log API keys
error_log( 'API request failed' ); // OK
error_log( 'API key: ' . $api_key ); // NEVER DO THIS

— ## 9. קהילה ### קוד התנהגות אנו עוקבים אחר [Contributor Covenant](https://www.contributor-covenant.org/) Code of Conduct. היו מכבדים, מכילים ובונים. ### ערוצי תקשורת – **GitHub Issues**: דיווחי באגים, בקשות פיצ'רים – **GitHub Discussions**: שאלות כלליות, רעיונות – **אימייל**: `support@leowebmarketing.pro` ### דיווח על בעיות #### דיווחי באגים השתמש בתבנית דיווח הבאגים:

**Describe the bug**
Clear description of the bug.

**To Reproduce**
1. Go to '...'
2. Click on '...'
3. See error

**Expected behavior**
What you expected to happen.

**Environment**
- WordPress version: [e.g., 6.4.2]
- WooCommerce version: [e.g., 8.5.1]
- PHP version: [e.g., 8.2.0]
- Plugin version: [e.g., 1.2.0]
- Browser: [e.g., Chrome 120]

**Screenshots**
If applicable.

**Additional context**
Any other relevant information.

#### בקשות פיצ'רים השתמש בתבנית בקשת פיצ'רים:

**Is your feature request related to a problem?**
Clear description of the problem.

**Describe the solution you'd like**
Clear description of desired behavior.

**Describe alternatives you've considered**
Alternative solutions or features considered.

**Additional context**
Any other context, mockups, or examples.

— ## התייחסות מהירה ### פקודות חיוניות

# Development
npm run dev              # Start development with watch
npm run build            # Production build

# Quality Checks
npm run typecheck        # TypeScript check
npm run lint             # ESLint
composer run phpcs       # PHP CodeSniffer
composer run phpstan     # PHPStan

# Testing
npm run test             # JavaScript tests
composer run test        # PHP tests

# Full Pre-commit Check
npm run typecheck && npm run lint && composer run phpcs && composer run phpstan

### תהליך עבודה עם ענפים

main
 └── feature/your-feature
      └── Commit → Push → PR → Review → Merge

— תודה על תרומתך ל-WooAI Chatbot Pro. התרומות שלך עוזרות להפוך את הפלאגין הזה לטוב יותר עבור כולם.