cloud-ru · mr8bit · Jul 28, 2025
diff --git a/.github/CI_DOCUMENTATION.md b/.github/CI_DOCUMENTATION.md
@@ -0,0 +1,137 @@
+# CI/CD Documentation
+
+Этот проект использует GitHub Actions для автоматического тестирования на разных версиях Python и операционных системах.
+
+## 🔄 Workflow Overview
+
+### 1. **CI (Primary Pipeline)** - `.github/workflows/ci.yml`
+Основной CI pipeline, который запускается при каждом push и pull request.
+
+**Задачи:**
+- **Lint**: Проверка кода с помощью ruff, pyright, mypy
+- **Build**: Сборка пакета
+- **Test**: Полное тестирование на matrix из:
+  - **Python версии**: 3.8, 3.9, 3.10, 3.11, 3.12  
+  - **Операционные системы**: Ubuntu, Windows, macOS
+- **Docs**: Генерация документации (только Ubuntu)
+- **Coverage**: Генерация отчетов покрытия кода
+- **Examples**: Тестирование примеров кода с реальным API
+
+**Особенности:**
+- ✅ Кроссплатформенная установка Rye
+- ✅ Отдельные команды для Windows (обход Makefile)
+- ✅ Матричное тестирование: 15 комбинаций (5 Python × 3 OS)
+- ✅ Условная загрузка артефактов покрытия (только Ubuntu + Python 3.12)
+
+### 2. **Python Compatibility Check** - `.github/workflows/compatibility-check.yml`
+Быстрая проверка совместимости со всеми версиями Python.
+
+**Задачи:**
+- **Compatibility Test**: Проверка импорта и базовых тестов на Python 3.8-3.12
+- **Quick Install Test**: Установка через pip на всех ОС
+
+**Особенности:**
+- ⚡ Быстрый запуск (15 минут)
+- 🔄 Запускается на push/PR и для develop ветки
+- 📦 Тестирует установку через pip (не Rye)
+
+### 3. **Windows Tests** - `.github/workflows/windows-test.yml`
+Специализированное тестирование для Windows без Makefile.
+
+**Задачи:**
+- **Windows Test**: Прямое использование pip и pytest
+- **Windows Build Test**: Тестирование сборки пакета
+
+**Особенности:**
+- 🪟 Обход проблем с Makefile на Windows
+- 📅 Ежедневный запуск по расписанию (cron)
+- 🧪 Прямые Python команды вместо make
+
+### 4. **Test Status Summary** - `.github/workflows/status.yml`
+Мониторинг статуса всех тестов.
+
+**Задачи:**
+- **Status Summary**: Отображение результатов всех workflow
+- **Failure Notification**: Автоматическое создание issues при ошибках
+
+**Особенности:**
+- 📊 Сводный отчет по всем тестам
+- 🚨 Автоматическое создание issues для main ветки
+- 🔗 Ссылки на failed runs
+
+## 📋 Test Matrix
+
+| OS | Python Versions | Workflow | Frequency |
+|---|---|---|---|
+| Ubuntu | 3.8, 3.9, 3.10, 3.11, 3.12 | CI, Compatibility | Push/PR |
+| Windows | 3.8, 3.9, 3.10, 3.11, 3.12 | CI, Windows Tests | Push/PR + Daily |
+| macOS | 3.8, 3.9, 3.10, 3.11, 3.12 | CI | Push/PR |
+
+**Всего комбинаций:** 15 (основной CI) + 5 (compatibility) + 5 (Windows) = **25 test jobs**
+
+## 🚀 Triggers
+
+### Push Events
+- `main` branch: Все workflow + примеры + документация
+- Feature branches: CI + Compatibility
+
+### Pull Request Events  
+- Targeting `main`: Все workflow
+- Targeting `develop`: Compatibility
+
+### Scheduled Events
+- Windows Tests: Ежедневно в 02:00 UTC
+
+## 🔧 Environment Variables
+
+Для запуска примеров требуются secrets:
+```yaml
+EVOLUTION_KEY_ID: ${{ secrets.EVOLUTION_KEY_ID }}
+EVOLUTION_SECRET: ${{ secrets.EVOLUTION_SECRET }}  
+EVOLUTION_BASE_URL: ${{ secrets.EVOLUTION_BASE_URL }}
+EVOLUTION_PROJECT_ID: ${{ secrets.EVOLUTION_PROJECT_ID }}
+```
+
+## 📊 Artifacts
+
+- **dist/**: Собранные пакеты (.whl, .tar.gz)
+- **coverage/**: Отчеты покрытия кода (HTML, XML, JSON)
+- **docs/**: Сгенерированная документация
+
+## 🛠️ Tools & Dependencies
+
+- **Build System**: Rye (primary), pip (fallback)
+- **Linting**: ruff, pyright, mypy
+- **Testing**: pytest, pytest-cov, pytest-asyncio
+- **Documentation**: Sphinx
+- **Coverage**: coverage.py + badge generation
+
+## 🔍 Debugging Failed Tests
+
+1. **Check Status Summary**: Workflow status показывает общее состояние
+2. **Review Logs**: Каждый job имеет детальные логи
+3. **Auto Issues**: Для main ветки создаются автоматические issues
+4. **Matrix Strategy**: `fail-fast: false` позволяет видеть все ошибки
+
+## 📈 Performance Optimization
+
+- **Parallel Jobs**: Максимальное использование GitHub Actions runners
+- **Selective Runs**: 
+  - Примеры только на PR/main
+  - Coverage только Ubuntu + Python 3.12
+  - Документация только на Linux
+- **Caching**: Rye and pip dependencies cached
+- **Timeouts**: Разумные timeout для каждого job
+
+## 🏷️ Badge Status
+
+README.md содержит бейджи для мониторинга:
+- CI status
+- Python compatibility  
+- Windows tests
+- Platform support
+- Python version coverage
+
+---
+
+> **Примечание**: Этот CI/CD setup обеспечивает надежное тестирование на всех поддерживаемых платформах и версиях Python, гарантируя высокое качество и совместимость пакета. 
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -63,34 +63,64 @@ jobs:
           path: dist/
 
   test:
-    timeout-minutes: 20
-    name: test
-    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    name: test (Python ${{ matrix.python-version }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
     needs: [lint, build]
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+      fail-fast: false
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install Rye
+      - name: Install Rye (Unix)
+        if: runner.os != 'Windows'
         run: |
           curl -sSf https://rye.astral.sh/get | bash
           echo "$HOME/.rye/shims" >> $GITHUB_PATH
         env:
           RYE_VERSION: '0.44.0'
           RYE_INSTALL_OPTION: '--yes'
 
-      - name: Install dependencies
+      - name: Install Rye (Windows)
+        if: runner.os == 'Windows'
+        run: |
+          Invoke-WebRequest -Uri "https://github.com/astral-sh/rye/releases/download/0.44.0/rye-x86_64-windows.exe" -OutFile "rye-installer.exe"
+          .\rye-installer.exe --yes
+          echo "$env:USERPROFILE\.rye\shims" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
+        shell: powershell
+
+      - name: Configure Rye Python version
+        run: rye pin ${{ matrix.python-version }}
+
+      - name: Install dependencies (Unix)
+        if: runner.os != 'Windows'
         run: make install-dev
+
+      - name: Install dependencies (Windows)
+        if: runner.os == 'Windows'
+        run: |
+          rye sync --all-features
 
       - name: Download build artifacts
         uses: actions/download-artifact@v4
         with:
           name: dist
           path: dist/
 
-      - name: Run tests with coverage
+      - name: Run tests with coverage (Unix)
+        if: runner.os != 'Windows'
         run: make test
+
+      - name: Run tests with coverage (Windows)
+        if: runner.os == 'Windows'
+        run: |
+          rye run pytest tests/ -v --cov=evolution_openai --cov-report=html --cov-report=term --cov-report=xml:coverage.xml --cov-report=json:coverage.json
 
-      - name: Upload coverage artifacts
+      - name: Upload coverage artifacts (Ubuntu only)
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
         uses: actions/upload-artifact@v4
         with:
           name: coverage
@@ -154,56 +184,124 @@ jobs:
 
   test-examples:
     timeout-minutes: 20
-    name: test-examples
-    runs-on: ubuntu-latest
+    name: test-examples (Python ${{ matrix.python-version }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
     needs: [test]
     if: github.event_name == 'pull_request' && github.base_ref == 'main' || github.event_name == 'push' && github.ref == 'refs/heads/main'
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.12"]  # Тестируем примеры только на двух версиях для экономии ресурсов
+      fail-fast: false
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install Rye
+      - name: Install Rye (Unix)
+        if: runner.os != 'Windows'
         run: |
           curl -sSf https://rye.astral.sh/get | bash
           echo "$HOME/.rye/shims" >> $GITHUB_PATH
         env:
           RYE_VERSION: '0.44.0'
           RYE_INSTALL_OPTION: '--yes'
 
-      - name: Install dependencies
+      - name: Install Rye (Windows)
+        if: runner.os == 'Windows'
+        run: |
+          Invoke-WebRequest -Uri "https://github.com/astral-sh/rye/releases/download/0.44.0/rye-x86_64-windows.exe" -OutFile "rye-installer.exe"
+          .\rye-installer.exe --yes
+          echo "$env:USERPROFILE\.rye\shims" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
+        shell: powershell
+
+      - name: Configure Rye Python version
+        run: rye pin ${{ matrix.python-version }}
+
+      - name: Install dependencies (Unix)
+        if: runner.os != 'Windows'
         run: make install-dev
+
+      - name: Install dependencies (Windows)
+        if: runner.os == 'Windows'
+        run: rye sync --all-features
 
-      - name: Run basic examples
+      - name: Run basic examples (Unix)
+        if: runner.os != 'Windows'
         env:
           EVOLUTION_KEY_ID: ${{ secrets.EVOLUTION_KEY_ID }}
           EVOLUTION_SECRET: ${{ secrets.EVOLUTION_SECRET }}
           EVOLUTION_BASE_URL: ${{ secrets.EVOLUTION_BASE_URL }}
         run: make run-examples
+
+      - name: Run basic examples (Windows)
+        if: runner.os == 'Windows'
+        env:
+          EVOLUTION_KEY_ID: ${{ secrets.EVOLUTION_KEY_ID }}
+          EVOLUTION_SECRET: ${{ secrets.EVOLUTION_SECRET }}
+          EVOLUTION_BASE_URL: ${{ secrets.EVOLUTION_BASE_URL }}
+        run: rye run python examples/basic_usage.py
 
-      - name: Run async examples
+      - name: Run async examples (Unix)
+        if: runner.os != 'Windows'
         env:
           EVOLUTION_KEY_ID: ${{ secrets.EVOLUTION_KEY_ID }}
           EVOLUTION_SECRET: ${{ secrets.EVOLUTION_SECRET }}
           EVOLUTION_BASE_URL: ${{ secrets.EVOLUTION_BASE_URL }}
         run: make run-async
+
+      - name: Run async examples (Windows)
+        if: runner.os == 'Windows'
+        env:
+          EVOLUTION_KEY_ID: ${{ secrets.EVOLUTION_KEY_ID }}
+          EVOLUTION_SECRET: ${{ secrets.EVOLUTION_SECRET }}
+          EVOLUTION_BASE_URL: ${{ secrets.EVOLUTION_BASE_URL }}
+        run: rye run python examples/async_examples.py
 
-      - name: Run streaming examples
+      - name: Run streaming examples (Unix)
+        if: runner.os != 'Windows'
         env:
           EVOLUTION_KEY_ID: ${{ secrets.EVOLUTION_KEY_ID }}
           EVOLUTION_SECRET: ${{ secrets.EVOLUTION_SECRET }}
           EVOLUTION_BASE_URL: ${{ secrets.EVOLUTION_BASE_URL }}
         run: make run-streaming
+
+      - name: Run streaming examples (Windows)
+        if: runner.os == 'Windows'
+        env:
+          EVOLUTION_KEY_ID: ${{ secrets.EVOLUTION_KEY_ID }}
+          EVOLUTION_SECRET: ${{ secrets.EVOLUTION_SECRET }}
+          EVOLUTION_BASE_URL: ${{ secrets.EVOLUTION_BASE_URL }}
+        run: rye run python examples/streaming_examples.py
 
-      - name: Run token management examples
+      - name: Run token management examples (Unix)
+        if: runner.os != 'Windows'
         env:
           EVOLUTION_KEY_ID: ${{ secrets.EVOLUTION_KEY_ID }}
           EVOLUTION_SECRET: ${{ secrets.EVOLUTION_SECRET }}
           EVOLUTION_BASE_URL: ${{ secrets.EVOLUTION_BASE_URL }}
         run: make run-tokens
+
+      - name: Run token management examples (Windows)
+        if: runner.os == 'Windows'
+        env:
+          EVOLUTION_KEY_ID: ${{ secrets.EVOLUTION_KEY_ID }}
+          EVOLUTION_SECRET: ${{ secrets.EVOLUTION_SECRET }}
+          EVOLUTION_BASE_URL: ${{ secrets.EVOLUTION_BASE_URL }}
+        run: rye run python examples/token_management.py
 
-      - name: Run foundation models examples
+      - name: Run foundation models examples (Unix)
+        if: runner.os != 'Windows'
+        env:
+          EVOLUTION_KEY_ID: ${{ secrets.EVOLUTION_KEY_ID }}
+          EVOLUTION_SECRET: ${{ secrets.EVOLUTION_SECRET }}
+          EVOLUTION_BASE_URL: ${{ secrets.EVOLUTION_BASE_URL }}
+          EVOLUTION_PROJECT_ID: ${{ secrets.EVOLUTION_PROJECT_ID }}
+        run: make run-foundation-models
+
+      - name: Run foundation models examples (Windows)
+        if: runner.os == 'Windows'
         env:
           EVOLUTION_KEY_ID: ${{ secrets.EVOLUTION_KEY_ID }}
           EVOLUTION_SECRET: ${{ secrets.EVOLUTION_SECRET }}
           EVOLUTION_BASE_URL: ${{ secrets.EVOLUTION_BASE_URL }}
           EVOLUTION_PROJECT_ID: ${{ secrets.EVOLUTION_PROJECT_ID }}
-        run: make run-foundation-models
+        run: rye run python examples/foundation_models_example.py