✨ Добавить основу PHPMax SDK

.github/pull_request_template.md

@@ -1,19 +1,31 @@
 ## Описание
-Кратко, что делает этот PR. Например, добавляет новый метод, исправляет баг, улучшает документацию.
+
+Кратко, что делает этот PR для PHPMax: переносит PyMax parity, исправляет
+payload/runtime behavior, обновляет документацию или tooling.
 
 ## Тип изменений
+
 - [ ] Исправление бага
 - [ ] Новая функциональность
 - [ ] Улучшение документации
 - [ ] Рефакторинг
+- [ ] Parity-перенос из PyMax
 
 ## Связанные задачи / Issue
+
 Ссылка на issue, если есть: #
 
 ## Тестирование
-Покажите пример кода, который проверяет изменения:
 
-```python
-import pymax
+- [ ] `just pre-publish-check`
+- [ ] Если менялись protocol/model/payload слои, обновлены parity fixtures.
+- [ ] Если менялись исходники, документация обновлена или явно проверена.
+- [ ] Если менялся release/runtime surface, проверен `just release-zip`.
+
+Пример PHP-кода для проверки behavior, если нужен:
+
+```php
+<?php
 
-# пример использования нового функционала
+require __DIR__ . '/autoload.php';
+```

.github/workflows/publish.yml

@@ -1,4 +1,4 @@
-name: Publish
+name: Release ZIP
 
 on:
   release:
@@ -13,52 +13,47 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
-  package:
-    name: Build package
+  release-zip:
+    name: Build PHPMax release ZIP
     runs-on: ubuntu-latest
 
+    permissions:
+      contents: write
+
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
 
-      - name: Install uv
-        uses: astral-sh/setup-uv@v8.1.0
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
         with:
-          enable-cache: true
-
-      - name: Build package distributions
-        run: uv build
-
-      - name: Validate package distributions
-        run: uv run twine check dist/*
-
-      - name: Upload package distributions
+          php-version: "7.4"
+          extensions: json, openssl, zip, pdo_sqlite
+          coverage: none
+          tools: composer:v2
+
+      - name: Install just
+        uses: extractions/setup-just@v3
+
+      - name: Run PHPMax pre-publish gate
+        run: just pre-publish-check
+
+      - name: Build release ZIP
+        shell: bash
+        run: |
+          just release-zip
+          archive="dist/phpmax-${GITHUB_REF_NAME//\//-}.zip"
+          cp dist/phpmax-dev.zip "$archive"
+          echo "archive=$archive" >> "$GITHUB_ENV"
+
+      - name: Upload release ZIP artifact
         uses: actions/upload-artifact@v4
         with:
-          name: package-distributions
-          path: dist/
-
-  publish:
-    name: Publish to PyPI
-    runs-on: ubuntu-latest
-    needs: [package]
+          name: phpmax-release-zip
+          path: ${{ env.archive }}
 
-    environment:
-      name: pypi
-
-    permissions:
-      contents: read
-      id-token: write
-
-    steps:
-      - name: Download package distributions
-        uses: actions/download-artifact@v4
+      - name: Attach ZIP to GitHub Release
+        if: github.event_name == 'release'
+        uses: softprops/action-gh-release@v2
         with:
-          name: package-distributions
-          path: dist/
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v8.1.0
-
-      - name: Publish package to PyPI
-        run: uv publish
+          files: ${{ env.archive }}

.github/workflows/tests.yml

@@ -14,8 +14,38 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  lint:
-    name: Lint
+  phpmax:
+    name: PHPMax / PHP ${{ matrix.php-version }}
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        php-version: ["7.4", "8.3"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php-version }}
+          extensions: json, openssl, zip, pdo_sqlite
+          coverage: none
+          tools: composer:v2
+
+      - name: Install just
+        uses: extractions/setup-just@v3
+
+      - name: Run PHPMax pre-publish gate
+        run: just pre-publish-check
+
+      - name: Verify release manifest
+        run: just release-check
+
+  python-lint:
+    name: Python Reference / Lint
     runs-on: ubuntu-latest
 
     steps:
@@ -36,8 +66,8 @@ jobs:
       - name: Run Ruff linting
         run: uv run ruff check .
 
-  tests:
-    name: Tests / Python ${{ matrix.python-version }}
+  python-tests:
+    name: Python Reference / Python ${{ matrix.python-version }}
     runs-on: ubuntu-latest
 
     strategy:
@@ -63,4 +93,4 @@ jobs:
           uv run pytest \
             --cov=src/pymax \
             --cov-report=term-missing:skip-covered \
-            --cov-report=markdown-append:$GITHUB_STEP_SUMMARY
+            --cov-report=markdown-append:$GITHUB_STEP_SUMMARY

.mailmap

@@ -0,0 +1,2 @@
+Varyag Nord <124573691+varyagnord@users.noreply.github.com> <varyagnord@example.com>
+Maksim Mazein <148742019+murzein@users.noreply.github.com>

AGENTS.md

@@ -0,0 +1,84 @@
+# AGENTS.md
+
+## Главная цель
+
+Мы превращаем Python-библиотеку PyMax в PHP-библиотеку PHPMax для PHP 7.4+.
+Цель не в механическом переписывании файлов, а в аккуратном переносе поведения,
+протоколов, payload-контрактов и developer experience с учетом ограничений PHP
+и shared hosting.
+
+## Обязательные правила работы
+
+- Перед любыми существенными изменениями читать `docs/phpmax/README.md`,
+  `docs/phpmax/roadmap.md`, `docs/phpmax/architecture.md` и
+  `docs/phpmax/upstream-sync.md`.
+- Для стандартных проверок использовать `just`. Перед публикацией запускать
+  `just pre-publish-check`; для быстрой диагностики - `just doctor`.
+- `src/pymax` считать reference-реализацией и источником правды. Не менять
+  Python-код без отдельной причины: он нужен для сверки с upstream PyMax.
+- PHP-код должен оставаться совместимым с PHP 7.4: не использовать native enum,
+  union types, attributes, constructor property promotion, `match`, fibers и
+  другие возможности PHP 8+.
+- Основной runtime проектировать под shared hosting: короткие CLI/cron-запуски,
+  bounded execution, явное закрытие соединений, сохранение session/sync.
+- Realtime-события в первой версии поддерживаются best-effort, через
+  ограниченные по времени `runFor()`/poll-циклы.
+- Безопасность важнее удобства: токены не логировать, session-файлы держать вне
+  webroot, использовать atomic write/file locks, давать понятные ошибки прав.
+- Архитектуру держать слоистой: public client, app runtime, services, protocol,
+  transport, models/hydration, session store. Не смешивать сетевой код,
+  сериализацию и domain helpers.
+- Для UI/документации всегда искать наиболее понятное решение. Помнить о
+  законах Хика и Фиттса: меньше лишних выборов, очевидные действия, короткий
+  путь к нужному сценарию.
+- Документацию вести автоматически вместе с кодом. Если изменились исходники,
+  перед публикацией обязательно оценить, нужно ли обновить docs. Если изменение
+  косметическое и docs менять не нужно, явно зафиксировать, что docs были
+  просмотрены и оставлены без изменений.
+- `GEMINI.md` должен быть точной копией `AGENTS.md`. При изменении одного файла
+  обязательно синхронизировать второй и проверять `cmp AGENTS.md GEMINI.md`.
+
+## Обязательная проверка upstream PyMax
+
+Перед началом каждого крупного этапа реализации и минимум раз в 7 дней во время
+активной разработки нужно проверять, вышла ли новая версия основного Python
+дистрибутива PyMax.
+
+Порядок:
+
+1. Проверить GitHub upstream `MaxApiTeam/PyMax` и опубликованный Python-пакет
+   `maxapi-python`.
+2. Сравнить текущую reference-версию в репозитории с upstream.
+3. Проанализировать diff: opcodes, payloads, auth, session/sync, protocol,
+   events, domain models, uploads, docs/release notes.
+4. Принять решение: переносить изменение сейчас, отложить, или игнорировать как
+   Python-only.
+5. Записать результат в `docs/phpmax/upstream-sync.md`.
+
+Если есть новая версия с изменениями protocol/auth/session/security, нельзя
+начинать новый этап PHP-реализации, пока не решено, как эти изменения повлияют
+на PHPMax.
+
+## Основные якоря плана
+
+- Staged parity: проектируем полный parity, реализуем этапами.
+- Python reference остается рядом для будущего upstream merge.
+- Composer-пакет PHPMax живет отдельным PSR-4 namespace `PHPMax\\`.
+- TCP transport является приоритетом первой версии.
+- WebSocket/QR `WebClient` переносится после TCP core как optional layer.
+- Модели переносятся через явный hydration/serialization слой, а не ручной
+  парсинг в каждом сервисе.
+- Uploads и event dispatch считаются зонами повышенного риска и требуют
+  отдельных parity-тестов.
+
+## Проверки перед завершением задачи
+
+- `git status --short` просмотрен.
+- Если менялись инструкции, `AGENTS.md` и `GEMINI.md` идентичны.
+- Если менялись docs, структура ссылок в `docs/phpmax/README.md` актуальна.
+- Если менялись исходники, принято решение по документации: docs обновлены или
+  осознанно не изменены как ненужные для данного изменения.
+- Если менялся PHP-код, добавлены или обновлены PHPUnit/parity-тесты.
+- Если менялся protocol/payload/model слой, сверены fixtures с Python reference.
+- Перед публикацией выполнен `just pre-publish-check` либо явно указано, почему
+  он не мог быть выполнен.

GEMINI.md

@@ -0,0 +1,84 @@
+# AGENTS.md
+
+## Главная цель
+
+Мы превращаем Python-библиотеку PyMax в PHP-библиотеку PHPMax для PHP 7.4+.
+Цель не в механическом переписывании файлов, а в аккуратном переносе поведения,
+протоколов, payload-контрактов и developer experience с учетом ограничений PHP
+и shared hosting.
+
+## Обязательные правила работы
+
+- Перед любыми существенными изменениями читать `docs/phpmax/README.md`,
+  `docs/phpmax/roadmap.md`, `docs/phpmax/architecture.md` и
+  `docs/phpmax/upstream-sync.md`.
+- Для стандартных проверок использовать `just`. Перед публикацией запускать
+  `just pre-publish-check`; для быстрой диагностики - `just doctor`.
+- `src/pymax` считать reference-реализацией и источником правды. Не менять
+  Python-код без отдельной причины: он нужен для сверки с upstream PyMax.
+- PHP-код должен оставаться совместимым с PHP 7.4: не использовать native enum,
+  union types, attributes, constructor property promotion, `match`, fibers и
+  другие возможности PHP 8+.
+- Основной runtime проектировать под shared hosting: короткие CLI/cron-запуски,
+  bounded execution, явное закрытие соединений, сохранение session/sync.
+- Realtime-события в первой версии поддерживаются best-effort, через
+  ограниченные по времени `runFor()`/poll-циклы.
+- Безопасность важнее удобства: токены не логировать, session-файлы держать вне
+  webroot, использовать atomic write/file locks, давать понятные ошибки прав.
+- Архитектуру держать слоистой: public client, app runtime, services, protocol,
+  transport, models/hydration, session store. Не смешивать сетевой код,
+  сериализацию и domain helpers.
+- Для UI/документации всегда искать наиболее понятное решение. Помнить о
+  законах Хика и Фиттса: меньше лишних выборов, очевидные действия, короткий
+  путь к нужному сценарию.
+- Документацию вести автоматически вместе с кодом. Если изменились исходники,
+  перед публикацией обязательно оценить, нужно ли обновить docs. Если изменение
+  косметическое и docs менять не нужно, явно зафиксировать, что docs были
+  просмотрены и оставлены без изменений.
+- `GEMINI.md` должен быть точной копией `AGENTS.md`. При изменении одного файла
+  обязательно синхронизировать второй и проверять `cmp AGENTS.md GEMINI.md`.
+
+## Обязательная проверка upstream PyMax
+
+Перед началом каждого крупного этапа реализации и минимум раз в 7 дней во время
+активной разработки нужно проверять, вышла ли новая версия основного Python
+дистрибутива PyMax.
+
+Порядок:
+
+1. Проверить GitHub upstream `MaxApiTeam/PyMax` и опубликованный Python-пакет
+   `maxapi-python`.
+2. Сравнить текущую reference-версию в репозитории с upstream.
+3. Проанализировать diff: opcodes, payloads, auth, session/sync, protocol,
+   events, domain models, uploads, docs/release notes.
+4. Принять решение: переносить изменение сейчас, отложить, или игнорировать как
+   Python-only.
+5. Записать результат в `docs/phpmax/upstream-sync.md`.
+
+Если есть новая версия с изменениями protocol/auth/session/security, нельзя
+начинать новый этап PHP-реализации, пока не решено, как эти изменения повлияют
+на PHPMax.
+
+## Основные якоря плана
+
+- Staged parity: проектируем полный parity, реализуем этапами.
+- Python reference остается рядом для будущего upstream merge.
+- Composer-пакет PHPMax живет отдельным PSR-4 namespace `PHPMax\\`.
+- TCP transport является приоритетом первой версии.
+- WebSocket/QR `WebClient` переносится после TCP core как optional layer.
+- Модели переносятся через явный hydration/serialization слой, а не ручной
+  парсинг в каждом сервисе.
+- Uploads и event dispatch считаются зонами повышенного риска и требуют
+  отдельных parity-тестов.
+
+## Проверки перед завершением задачи
+
+- `git status --short` просмотрен.
+- Если менялись инструкции, `AGENTS.md` и `GEMINI.md` идентичны.
+- Если менялись docs, структура ссылок в `docs/phpmax/README.md` актуальна.
+- Если менялись исходники, принято решение по документации: docs обновлены или
+  осознанно не изменены как ненужные для данного изменения.
+- Если менялся PHP-код, добавлены или обновлены PHPUnit/parity-тесты.
+- Если менялся protocol/payload/model слой, сверены fixtures с Python reference.
+- Перед публикацией выполнен `just pre-publish-check` либо явно указано, почему
+  он не мог быть выполнен.