הנחיות תרומה

הנחיות תרומה

מסמך זה מספק הנחיות מקיפות לתרומה ל-WooAI Chatbot Pro. עקביות בסטנדרטים אלה מבטיחה קוד עקבי, ניתן לתחזוקה ושיתוף פעולה יעיל.

בקיצור: Fork → Branch → Code → Test → PR. בדרך כלל אנחנו סוקרים תוך 48 שעות.
בבקשה אל:
– לשלוח PR ללא בדיקות (פשוט נבקש ממך להוסיף אותן)
– "לתקן" סגנון קוד בקבצים שלא שינית (מקשה על הסקירה)
– להוסיף תלויות ללא דיון קודם (גודל ה-bundle חשוב)

1. תחילת העבודה

דרישות מקדימות

ודא שסביבת הפיתוח שלך עומדת בדרישות אלה:

דרישהגרסה מינימליתמומלץ
PHP8.18.2+
Node.js18.0.020 LTS
npm9.0.010+
Composer2.02.7+
WordPress6.06.4+
WooCommerce8.09.0+

מבנה המאגר

woo-ai-chatbot-pro/
├── assets/                 # Frontend assets (compiled)
│   ├── admin/             # Admin panel assets
│   └── chat/              # Chat widget assets
├── assets/src/            # Source TypeScript/React files
├── includes/              # PHP source (PSR-4 autoloaded)
├── templates/             # PHP template files
├── tests/                 # Test suites
├── docs/                  # Documentation
├── vendor/                # Composer dependencies (git-ignored)
├── node_modules/          # npm dependencies (git-ignored)
├── composer.json          # PHP dependencies
├── package.json           # Node dependencies
├── webpack.config.js      # Build configuration
├── tsconfig.json          # TypeScript configuration
├── phpcs.xml              # PHP_CodeSniffer config
└── woo-ai-chatbot-pro.php # Main plugin file

2. הגדרת סביבת פיתוח

שכפול והתקנה

# Clone the repository
git clone https://your-repository-url.git
cd woo-ai-chatbot-pro

# 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:

הגדרת WordPress מקומי

  1. התקן Local או הגדר LAMP/LEMP stack
  2. צור אתר WordPress חדש
  3. צור symlink או העתק את הפלאגין ל-wp-content/plugins/
  4. הפעל את WooCommerce ו-WooAI Chatbot Pro
# Symlink example (macOS/Linux)
ln -s /path/to/woo-ai-chatbot-pro /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:

<?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:

# 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:

  • 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:

## [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 ציבוריים עבור פגיעויות אבטחה.

דווח על בעיות אבטחה ליצירת קשר עם מנהל החשבון שלך.

כלול:

  • תיאור הפגיעות
  • שלבים לשחזור
  • השפעה פוטנציאלית
  • תיקון מוצע (אם יש)

שיקולי אבטחה

סניטציה של קלט

תמיד סנן קלט משתמש:

// 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 Code of Conduct. היו מכבדים, מכילים ובונים.

ערוצי תקשורת

  • אימייל: support@wooai.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. התרומות שלך עוזרות להפוך את הפלאגין הזה לטוב יותר עבור כולם.

Previousמדריך בדיקותNextמדריך פתרון בעיות