Регламент разработки сервисов (Актуальное состояние, As-Is)

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

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

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

2.1. Работа с ветками

  • Основная ветка: default — является единственной постоянной веткой. В неё выполняется слияние всех изменений.
  • Правила создания веток: Формальных правил нет. Разработчик может создать отдельную ветку (через hg branch) по своему усмотрению, если планирует вести долгую разработку или эксперимент.
  • Слияние: После завершения работы ветка сливается обратно в default через hg merge. Слияние выполняет архитектор после код-ревью.
  • Прямые коммиты: Разрешены прямые коммиты (без создания веток) непосредственно в default для небольших фиксов и правок.

2.2. Именование коммитов

  • Строгих правил по форматированию сообщений коммитов нет, кроме как необходимость указывать суть изменения и по английски.

2.3. Релизный процесс и теги

  • Релизы на боевом окружении (PROD) фиксируются с помощью тегов (Mercurial Tags).
  • Теги проставляются вручную в репозитории. Правила именования тегов формально не закреплены (используется удобный для архитектора формат, обычно содержащий номер версии).
  • Релизный цикл (регулярность выкаток) не регламентирован — решение принимает архитектор под текущие бизнес-задачи.

3. Среда разработки (CodeServer)

3.1. Доступ к проектам

  • Каждый разработчик работает в персональном экземпляре VS Code, развернутом на серверах компании (CodeServer).
  • Все разработчики имеют доступ (чтение) ко всем проектам платформы в рамках окружения DEV. Это сделано для возможности просмотра реализации смежных сервисов.

3.2. Деплой на окружения

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

4. Типовая архитектура проектов

4.1. Организация работы

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

4.2. Старые проекты

  • Архитектура: Монолит. Backend и фронтенд-часть генерируются на стороне сервера, разрабатывается на PHP с использованием собственного фреймворка компании BMC IO Framework.
  • Базы данных: используют одновременно MySQL и MongoDB.
  • Разрешается копирование участков кода между проектами.

4.3. Новые проекты

  • Архитектура: Разделение на Backend и Frontend.
    • Backend: разрабатывается на PHP с использованием собственного фреймворка компании BMC IO Framework.
    • Frontend: разрабатывается на Vue 3, однако точка входа в приложение генерируется на стороне сервера.
  • База данных: используется только MySQL (MongoDB в новых проектах не применяется).
  • Варианты сборки Frontend:
    • Самостоятельное приложение (сборка через Webpack).
    • Микрофронтенд (для встраивания в десктопное хост-приложение и мобильное хост-приложение) — сборка осуществляется через Webpack Module Federation.

4.4. Кеширование

  • Для всех проектов в качестве системы кеширования используется Memcached.
  • Правила именования ключей и стратегия инвалидации жестко не регламентированы и определяются разработчиком конкретного проекта.

5. Хост-приложения и микрофронтенды

5.1. Точки входа

Существует два основных хост-приложения, в которые могут интегрироваться микрофронтенды:

  • Десктоп хост-приложение.
  • Мобильное хост-приложение.

5.2. Взаимодействие

  • Микрофронтенды разрабатываются как изолированные модули.
  • Коммуникация между микрофронтендами и хостом осуществляется через стандартные механизмы Module Federation (exposes/remotes) или через глобальный объект окна (window), если это требуется.
  • Регламент по управлению состояниями (Vuex) между хостом и микрофронтендами описан в документации по фреймворку IO Framework v7.

6. Базы данных (Управление изменениями)

6.1. MySQL

  • Изменения структуры БД (миграции) выполняются разработчиками.
  • Средство управления миграциями — внутренний инструментарий PHP-фреймворка.
  • Автоматического прогона миграций при деплое нет. Архитектор или разработчик выполняет миграции вручную на целевом окружении в момент выкатки релиза.

6.2. MongoDB

  • Используется только в режиме поддержки легаси-функционала в старых проектах.
  • Изменение схемы (структуры документов) MongoDB происходит ad-hoc, путем правки кода сохранения данных; отдельной системы миграций для MongoDB не предусмотрено.

7. Процедура выкатки на PROD (Действующий процесс)

  1. Разработчик завершает работу над задачей в своей ветке или в default.
  2. Разработчик уведомляет архитектора о готовности изменений (устно или в мессенджере).
  3. Архитектор проверяет код (визуально) и принимает решение о включении изменений в релиз.
  4. Архитектор вручную подготавливает сборку (если требуется, запускает npm run build).
  5. Архитектор вручную переносит файлы (через FTP/SSH/rsync) на боевой сервер.
  6. Архитектор запускает миграции БД (если есть) вручную на PROD.
  7. Архитектор ставит тег в репозитории Mercurial, чтобы зафиксировать состояние кода.

8. Действующие правила по качеству кода

  • Формальные инструменты статического анализа (PHPStan, Psalm, ESLint с жесткими правилами) в обязательном порядке не используются. Проверка качества лежит на совести разработчика и архитектора в ходе ревью.
  • Требований к покрытию кода тестами нет. Тесты пишутся по желанию разработчика или если это прямо указано в техническом задании.

Приложение А. Типовые действия разработчика

Начало работы над задачей:

  1. Перейти в папку проекта в CodeServer.
  2. Выполнить hg pull -u (обновить текущую ветку default).
  3. При необходимости создать ветку: hg branch my-feature-name (название произвольное).
  4. Начать разработку.

Завершение задачи (если задача не требует внимания архитектора):

  1. Выполнить коммит: hg commit -m "описание изменений".
  2. Выполнить hg push (влить в репозиторий).

Завершение задачи (требуется выкатка на PROD):

  1. Убедиться, что изменения слиты в default.
  2. Написать архитектору в чат: "Проект Х, задача Y, готово к релизу".
  3. Дождаться, пока архитектор выполнит деплой.