Регламент разработки сервисов платформы (Технический стандарт)

1. Общие положения и философия

Данный регламент описывает процесс разработки, взаимодействия с кодом и развертывания для всех проектов, входящих в экосистему платформы.

1. Регламент обязателен для всех команд разработки (включая архитектора).
2. Цель: стандартизация цикла разработки, обеспечение предсказуемости релизов и минимизация рисков при ручном деплое.
3. Основной принцип: Мы работаем в парадигме Trunk-Based Development с элементами Git Flow, адаптированными под Mercurial. Это значит, что ветка default (аналог main/master) всегда должна находиться в состоянии, готовом к релизу.

2. Система контроля версий (Mercurial)

Несмотря на то, что мы используем Mercurial, терминология близка к Git для упрощения понимания. Мы отказываемся от модели "одна ветка для всего". Вводится жесткая структура.

2.1. Структура веток

• default (Главная ветка): Священна. В ней находится код, соответствующий текущему релизу на PROD (Production) или код, прошедший полное тестирование в среде DEV. Сюда мержатся только завершенные фичи.
• feature/{TASK_ID}-short-desc (Ветки задач): Создаются для разработки новой функциональности или баг-фикса.
• hotfix (Ветки исправлений): Создаются срочно для исправления критических багов на PROD, минуя долгий цикл DEV. Создается от тега последнего релиза.
• bugfix/{TASK_ID}-short_name: Для исправления багов в default на DEV перед релизом.

2.2. Правила именования

Ветки должны начинаться с идентификатора задачи из системы трекинга OpenProject.

• Правильно: feature/APP-123_add-stock-report
• Неправильно: new_fix, test_branch, my_changes

2.3. Правила работы с ветками, процесс коммитов и слияний (Merge)

1. Запрещено лить коммиты напрямую в default без Pull Request (PR) / Merge Request (MR) (кроме срочных фиксов архитектора).
2. Разработчик создает ветку feature/ от актуального default. Каждый разработчик работает в своей feature-ветке.
3. После завершения работы создается Pull Request (запрос на слияние) архитектору.
4. Слияние в default производит архитектор после проверки кода (Code Review).

3. Управление задачами (OpenProject)

3.1. Связь с репозиторием (Компенсация отсутствия интеграции)

Так как интеграции нет, вводится строгое правило нейминга коммитов:

Каждый коммит (или Merge Commit) обязан содержать идентификатор задачи из OpenProject в квадратных скобках.

• Формат: [ProjectPrefix-#TaskID] Comment
• Пример: [WAREHOUSE-123] Fix calculation in receipt service
• Обоснование: Архитектор и разработчики смогут искать историю изменений по ID задачи в логах Mercurial.

3.2. Статусы задач

Связь статуса задачи с ветками:

• In Progress -> Ветка feature/ создана, ведутся коммиты.
• Needs Review -> Создан PR на слияние в default (ожидание архитектора).
• Tested -> Ветка влита в release (тестирование на стейджинге).
• Closed -> Тег на продакшене подтвержден.

4. Архитектура, типы проектов

Регламент различает подходы в зависимости от типа проекта.

Все проекты делятся на 3 типа в рамках репозитория:

1. Монолит (Legacy): Бэк+Фронт на сервере (PHP+Twig на IO Framework). База: MySQL + MongoDB.
2. Современный SPA: Бэк (PHP на IO Framework) + Фронт (Vue3 / Webpack).
3. Микрофронтенд (Module Federation): Бэк (PHP на IO Framework) + Фронт (Vue3, экспортирующий компоненты для Хост-приложения).

4.1. Проекты-монолиты (Старые / PHP+Twig)

• Backend и Frontend рендерятся на сервере.
• Правило: Запрещено использовать современные сборщики (Webpack) внутри старых проектов, чтобы не ломать инфраструктуру. Все изменения CSS/JS должны быть ванильными или через jQuery.

4.2. Современные SPA (Vue 3 + Webpack)

• Бэкенд: PHP (собственный фреймворк компании) — отдает API.
• Фронтенд: Vue 3.
• Сборка: Используется Webpack.
• Конфигурация: Каждый новый проект должен иметь файл .env (не в репозитории!) для разделения окружений (DEV, PROD).

4.3. Микрофронтенды (Module Federation)

• Проекты, которые встраиваются в Хост-приложение (Веб и Flutter WebView).
• Правило: Изолированность. Микрофронтенд не должен знать о состоянии глобального хранилища (Store) хоста, если это не оговорено архитектором. Все коммуникации идут через пропсы или кастомные события.

5. Cреда разработки (CodeServer)

5.1. Доступы

Каждый разработчик имеет доступ ко всем проектам в CodeServer в среде DEV. Это разрешено только для чтения (копирование кода). Запрещено редактировать код чужого проекта без согласования с его владельцем (командой проекта) или архитектором.

5.2. Рабочее окружение (CodeServer)

Каждый сотрудник работает в изолированном контейнере CodeServer на сервере.

1. Доступ: Каждый разработчик имеет доступ на чтение во все проекты в среде DEV.
2. Правило "Copy-Paste" (Копирование кода): Разрешается копировать участки кода между проектами для ускорения работы. Однако, при копировании, разработчик обязан:
   • Адаптировать неймспейсы (namespace) под текущий проект.
   • Убедиться, что копируемый код не тянет за собой зависимости (composer/npm), отсутствующие в целевом проекте (либо добавить их в composer.json).

6. Работа с базами данных (MySQL, MongoDB)

6.1. Старые проекты (MySQL + Mongo)

• Запрещено использование MongoDB для новых фичей.
• MongoDB (для старых проектов): Поскольку использование MongoDB в новых проектах запрещено, поддержка старых коллекций осуществляется только в режиме "чтение". Запись в Mongo для новых фич возможна только с личного разрешения архитектора.

6.2. Новые проекты (Только MySQL)

• Все изменения схемы данных — только через миграции.
• Критично: Запрещено менять структуру БД вручную через консоль на сервере DEV/PROD (исключение только с разрешения архитектора). Только код миграции.

7. Memcached (Кеш)

• Ключи кеша должны иметь префикс проекта.
  • Формат: {PROJECT_NAME}:{ENTITY}:{ID}
  • Пример: crm:user:profile:123
• Инвалидация: При изменении структуры данных или обновлении данных (CRUD) в БД, разработчик обязан предусмотреть инвалидацию (сброс) соответствующего кеша в этом же коммите.

8. Релизный процесс (Процедура деплоя)

8.1. Окружения

• DEV: Среда разработки и тестирования.
• PROD (Боевой): Деплой осуществляется только архитектором платформы вручную.

8.2. Этапы выкатки на Production

1. Архитектор создает ветку release от default.
2. Команда разработки тестирует релиз-ветку на DEV.
3. Архитектор проводит код-ревью всех коммитов в релиз-ветке.
4. Деплой: Архитектор вручную деплоит код из release на PROD.
5. После успешной проверки на проде архитектор ставит тег в репозитории.
6. Архитектор вливает release обратно в default (чтобы синхронизировать баг-фиксы из релиза).

8.3. Hotfix (Аварийный)

1. Создается ветка hotfix от тега текущего релиза.
2. Правка деплоится немедленно (с уведомлением всех команд).
3. После фикса — обязательно вливается в default и в текущую ветку разработки.

8.4. Процедура выпуска (Теги)

Релизный цикл выглядит так:

1. Разработчик завершает фичу, создает PR в default.
2. Архитектор проверяет код и выполняет слияние.
3. Архитектор запускает сборку (Webpack) и тесты на DEV.
4. После подтверждения работоспособности на DEV, архитектор переключается на ветку default, пуллит изменения и ставит тег.
   • Формат тега: v{MAJOR}.{MINOR}.{PATCH}
   • Пример: v2.1.3
5. Архитектор вручную переносит сборки (артефакты) на PROD.

9. Специфика разработки (Микрофронты и Хосты)

9.1. Самостоятельные приложения

Разработка ведется в своей папке. Сборка через npm run build. Результат сборки (дист) идет в репозиторий.

9.2. Микрофронтенды

1. При изменении интерфейса микрофронтенда разработчик обязан обновить версию экспортируемого модуля в package.json (patch версию).
2. Синхронизация: После деплоя микрофронта на прод, разработчик обязан создать задачу в OpenProject для команды, отвечающей за Хост-приложение, чтобы они обновили зависимость (remote entry) в своем хосте.
3. Запрещено ломать API контракты (пропсы) экспортируемых компонентов без обратной совместимости (deprecation cycle).

10. Качество кода и стандарты (CI/CD)

Так как у нас нет автоматизированного пайплайна (CI) на каждый коммит (ввиду специфики Mercurial и ручного деплоя), мы внедряем локальные хуки (Hooks).

1. Pre-commit hook: Перед коммитом должен запускаться линтер для PHP (PHP_CodeSniffer) и для JS (ESLint).
   • Требование: Код должен проходить проверку без критических ошибок (Errors). Ворнинги (Warnings) допускаются, но должны быть исправлены до создания PR.
2. Коммит-сообщения: Строго по шаблону:

[PROJECT_KEY] Тип: Краткое описание

- Подробности изменений
- Ссылка на задачу

Типы: feat, fix, refactor, docs, style.

Перед отправкой запроса на слияние архитектору разработчик обязан проверить:

1. Нет ли var_dump, dd, console.log в коде.
2. Написаны ли миграции для БД (если менялась структура).
3. Добавлены ли логи в ключевые места (использование Logger компании).
4. Обновлена ли документация API (если менялся бэкенд).
5. Проверена работа в нескольких браузерах (если фронт).

11. Обязанности участников

1. Архитектор платформы:
   • Мониторинг архитектурной целостности всех проектов.
   • Единоличное право мержить в default.
   • Единоличное право деплоить на PROD.
   • Контроль за использованием кешей и структур БД.
2. Разработчик (Team Lead проекта):
   • Качество кода в своем проекте.
   • Актуализация документации (README) проекта.
   • Создание миграций для БД и прогон их на DEV перед передачей архитектору.

12. Ответственность

• Разработчик несет ответственность за работоспособность своей фича-ветки.
• Архитектор несет ответственность за целостность ветки default и состояние продакшена в момент деплоя.
• Нарушение регламента (коммит без ID задачи, работа напрямую в default) карается устным предупреждением или блокировкой прав на пуши.

13. Сценарии действий (Памятка разработчика)

Сценарий А: Новая фича в существующем проекте

1. hg pull -u (обновил default).
2. hg branch feature/TASK-567_new_filter.
3. Пишем код.
4. Тестируем локально.
5. hg commit -m "[CRM] feat: add new filter"
6. hg push --new-branch
7. Создаем Merge Request в системе (или пишем Архитектору в чат).

Сценарий Б: Срочный баг на PROD

1. hg pull -u
2. hg branch hotfix/TASK-999_fix_critical
3. Фиксим баг.
4. Архитектор мержит горячую фичу сразу в default без ожидания стандартного релизного цикла (с последующим присвоением тега).

Сценарий В: Создание нового микрофронтенда

1. Согласовать с Архитектором название хоста (путь).
2. Использовать стандартный Webpack конфиг платформы (лежит в репозитории platform-core).
3. В webpack.config.js указать exposes для модулей, которые будут шариться.
4. Важно: Убедиться, что версия vue и vue-router соответствует версии Хост-приложения.

Сценарий Г: Если деплой на прод прошел, но система упала

1. Архитектор откатывает код до предыдущего тега (hg update -r v[old]).
2. Откатывает миграции БД (скрипт отката обязателен для каждой миграции).
3. Ветка release помечается как ABANDONED и удаляется. Баг фиксится в новой hotfix.