XC_VM/docs/ru/guides/dev-workflow.md

# Рабочий процесс разработки

Как настроить проект локально, выполнить проверку качества и развернуть код на сервере разработки.

---

## Локальная настройка

**Предпосылки:** PHP **8.1** ( коды кодовой базы `php: 8.1.33`; более новые версии не поддерживаются) и Composer доступны локально.

Зафиксированное значение `src/vendor/` равно **только для производства**, поэтому инструменты разработки (PHPStan,
phpc) отсутствуют в дереве. Установите их один раз из зафиксированной блокировки:

```bash
make dev-tools          # = cd src && composer install
```

Это добавит пакеты `require-dev` в пакеты `src/vendor/`. **Никогда не совершайте их** —
зарегистрированный поставщик должен оставаться доступным только для производства (`composer install --no-dev`).
`.gitignore` не допускает попадания пакетов разработчика в `git add`, а CI-шлюз
(`check-vendor-prod-only`) завершается сбоем сборки, если она когда-либо была зафиксирована.

## Проверка качества

Запустите их до того, как push — CI запустит тот же набор:

|Команда|Проверки|
| --- | --- |
| `make phpstan` |Статический анализ по сравнению с зафиксированным базовым уровнем (сбой происходит только при появлении НОВЫХ проблем)|
| `make cs` |Стиль кода — импорт/гигиена пространства имен (phpcs + Slevomat)|
| `make cs-fix` |Примените исправления стиля на месте|
| `make gates` |PSR-4 регрессионные параметры (ниже)|
| `php tools/.bin/phpunit.phar -c tests/phpunit.xml.dist` |Модульные тесты — смотрите [Настройка PHPUnit](phpunit-phar.md)|

для `make phpstan` и `make cs` нужны инструменты разработчика — сначала запустите `make dev-tools`.

Базовый уровень PHPStan имеет значение `build/phpstan-baseline.neon` — он замораживает все *ранее существовавшие*
проблемы, так что только **новое** из них не проходят CI. Если вы намеренно измените уровень или примете пакет
найдя, восстановите его с помощью `make phpstan-baseline` и зафиксируйте результат. Не восстанавливайте его
просто чтобы заглушить настоящую новую ошибку — исправьте код.

`make gates` связывает трех охранников:

- **проверка-процедура-использование** — процедурные файлы / файлы просмотра импортируют каждый перенесенный класс, который они используют (PHP импорт является позиционным, поэтому `use` должен предшествовать использованию).;
- **проверить-lb-архив** — сборка балансировщика нагрузки исключает привилегированный код (контроллеры администратора/реселлера, домен пользователя/устройства, команды установки/root) — смотрите [Система сборки (MAIN vs LB)](../builds/build_system.md) для определения границы исключения;
- **проверка-только для поставщика-продукта** — ни один пакет `require-dev` не зафиксирован в соответствии с `src/vendor/`.

## Развертывание кода в VDS через SFTP

Для ежедневной разработки мы рекомендуем [расширение SFTP](https://marketplace.visualstudio.com/items?itemName=Natizyskunk.sftp) для VS Code — редактировать локально, автоматически загружать при сохранении.

### Установка

Создать `.vscode/sftp.json`:

```json
[
    {
        "name": "My Dev VDS",
        "host": "YOUR_VDS_IP",
        "protocol": "sftp",
        "port": 22,
        "username": "root",
        "remotePath": "/home/xc_vm",
        "useTempFile": false,
        "uploadOnSave": true,
        "openSsh": false,
        "watcher": {
            "files": "**/*",
            "autoUpload": false,
            "autoDelete": true
        },
        "ignore": [
            ".vscode",
            ".git",
            ".gitattributes",
            ".gitignore",
            "update",
            "*pycache/",
            "*.gitkeep",
            "bin/",
            "config/",
            "tmp/"
        ],
        "context": "./src/",
        "profiles": {}
    },
    {
        "name": "My Dev VDS Tests",
        "host": "YOUR_VDS_IP",
        "protocol": "sftp",
        "port": 22,
        "username": "root",
        "remotePath": "/home/xc_vm/tests",
        "useTempFile": false,
        "uploadOnSave": true,
        "openSsh": false,
        "watcher": {
            "files": "**/*",
            "autoUpload": false,
            "autoDelete": true
        },
        "ignore": [
            ".vscode",
            ".git",
            ".gitattributes",
            ".gitignore",
            "tmp/",
            ".cache/"
        ],
        "context": "./tests/",
        "profiles": {}
    }
]
```

### Основные настройки

- **`context: "./src/"`** — сопоставляет локальное `src/` с удаленным `/home/xc_vm/`
- **`context: "./tests/"`** — сопоставляет локальное `tests/` с удаленным `/home/xc_vm/tests/`
- **`uploadOnSave: true`** — каждое сочетание клавиш Ctrl+S мгновенно переносит файл в VDS
- **`ignore`** — защищает файлы, зависящие от сервера. (`bin/`, `config/`, `tmp/`)

> ⚠️ **`watcher.autoDelete: true`** — локальное удаление файла приводит к его удалению и на VDS. Удобный
> для поддержания синхронизации дерева, но неправильно удаленный локальный файл (или неправильное переименование) приведет к удалению
> удаленное копирование. Сохраняйте список `ignore` неизменным или установите для него значение `false`, если вы не хотите, чтобы наблюдатель
> для распространения удалений.

> **Безопасность:** Используйте SSH-ключи вместо пароля. Каталог `.vscode/` находится в каталоге `.gitignore`, поэтому учетные данные не попадут в git.

### Как синхронизировать папку с тестами

1. Добавьте вторую запись SFTP с `context: "./tests/"` и `remotePath: "/home/xc_vm/tests"`.
2. Сохраняйте файлы под `tests/` локально.
3. Расширение загрузит их отдельно из `src/` в `/home/xc_vm/tests`.
4. Это необходимо, поскольку тесты хранятся за пределами `src/` и не будут загружены из основной записи.

### Рабочий процесс

1. Откройте проект в VS Code
2. Отредактируйте любой файл в разделе `src/`
3. Если вы добавляете тест, отредактируйте файл в разделе `tests/`
4. Сохранить — соответствующая запись SFTP загружает файл в VDS
5. Запустите соответствующий тест на VDS
6. Фиксация в git как обычно

## Связанные файлы

|Файл|Роль|
| --- | --- |
| `.vscode/sftp.json` |Локальный → Конфигурация синхронизации VDS (gitignored)|
| `Makefile` |`make dev-tools`, `make phpstan`, `make cs`, `make gates`|
| `src/composer.json` |Зависимости + PSR-4 автозагрузка|