Инструкция по деплою и правила разработкиа

Содержание

Общие принципы
Инструкции для фронтенда
Инструкции для бэкенда
Тестовые стенды (Staging)
Проверка перед деплоем

Общие принципы

Все конфигурации должны управляться через переменные окружения (.env файлы)
Переопределение конфигурации доступно через config.override.json (только в режиме разработки)
Запрещено использование сторонних CDN для любых ресурсов (включая шрифты, скрипты, стили)
Весь код должен следовать принятым соглашениям о стиле кодирования

Настройка окружения

Переменные окружения

Все конфигурации приложения должны быть вынесены в .env файлы:

.env - базовые настройки, общие для всех окружений
.env.development - настройки для разработки
.env.production - настройки для продакшена

Пример структуры .env файла:

VITE_API_URL=https://api-id.АОНК.ru/
VITE_APP_NAME=АОНК ID

Переопределение конфигурации

В процессе разработки можно переопределить настройки без изменения исходного кода, используя файл config.override.json. Этот файл должен иметь следующую структуру:

{
  "config": {
    "apiUrl": "http://localhost:8000/",
    "appName": "АОНК ID (локальная разработка)"
  }
}

Важно: Механизм переопределения работает только в режиме разработки. В продакшн-среде он отключен для безопасности.

Персистентные папки

Персистентные папки - это директории, которые сохраняются между обновлениями приложения и не очищаются при повторном развертывании.

Персистентные папки в проекте создаются и обозначаются в Dockerfile с помощью директивы VOLUME. Пример из бэкенд-проекта:

# Создание персистентной директории uploads
RUN mkdir -p /var/www/aonk-id/runtime/uploads
VOLUME /var/www/aonk-id/runtime/uploads

# Создание персистентной директории drivers
RUN mkdir -p /var/www/aonk-id/runtime/drivers
VOLUME /var/www/aonk-id/runtime/drivers

Чтобы создать новую персистентную папку:

Создайте директорию в корне проекта
Добавьте путь к этой директории в файл .gitignore (чтобы избежать коммита содержимого)

Добавьте следующие строки в contrib/Dockerfile:

# Создание персистентной директории
RUN mkdir -p /var/www/aonk-id/my-persistent-dir
VOLUME /var/www/aonk-id/my-persistent-dir

Директива VOLUME в Dockerfile гарантирует, что содержимое указанной директории будет сохраняться между перезапусками контейнера и обновлениями приложения.

Важно: Данные в томах (VOLUME) сохраняются даже при удалении контейнера, но могут быть удалены при выполнении команды docker volume prune. Убедитесь, что у вас настроено резервное копирование важных данных.

Инструкции для фронтенда

Структура проекта (Frontend)

frontend/
├── dist/               # Результат сборки (очищается при каждой сборке)
├── public/             # Статические файлы
│   └── config.override.json  # Файл переопределения конфигурации
├── src/                # Исходный код приложения
│   ├── config/         # Конфигурация приложения
│   │   ├── env.config.js      # Базовая конфигурация
│   │   ├── configRewrite.js   # Механизм переопределения
│   │   └── index.js           # Экспорт конфигурации
│   ├── components/     # Компоненты Vue
│   ├── plugins/        # Плагины Vue
│   ├── router/         # Маршрутизация
│   ├── stores/         # Хранилища Pinia
│   └── styles/         # Стили приложения
├── node_modules/       # Зависимости (очищаются при сборке)
├── contrib/            # Файлы для развертывания
│   ├── Dockerfile      # Dockerfile для сборки образа
│   └── aonk-id-frontend.nginx.conf  # Конфигурация Nginx
├── debian/             # Файлы для сборки Debian-пакета
│   ├── control         # Метаданные пакета
│   ├── aonk-id-frontend-bin.install  # Список файлов для установки
│   └── aonk-id-frontend-bin.dir      # Список создаваемых директорий
├── Makefile            # Скрипты сборки
└── build.sh            # Скрипт создания Debian-пакета

Добавление файлов и папок в сборку

При добавлении новых файлов и папок в проект, необходимо учитывать два аспекта:

Включение файлов в сборку Vite:
- Все исходные файлы должны размещаться в директории src/
- Статические файлы (изображения, шрифты и т.д.) должны размещаться в директории public/
- Vite автоматически включит эти файлы в результирующую сборку (директория dist/)
Включение файлов в установочный пакет:
- Для определения файлов, которые должны быть установлены на сервер, используется файл debian/aonk-id-frontend-bin.install
- Каждая строка в этом файле содержит два элемента: исходный путь и путь назначения
Пример содержимого файла aonk-id-frontend-bin.install:
```
package.json /var/www/aonk-id
package-lock.json /var/www/aonk-id
dist/* /var/www/aonk-id/public
```

Если вам необходимо добавить новые файлы или директории в установочный пакет:

Добавьте новую строку в файл debian/aonk-id-frontend-bin.install, указав исходный путь и путь назначения
```
my-config-file.json /var/www/aonk-id/configs
```
Убедитесь, что указанный каталог назначения существует или создайте его, добавив путь в файл debian/aonk-id-frontend-bin.dir:
```
/var/www/aonk-id/configs
```

Управление состоянием

Для управления состоянием приложения используется Pinia. При добавлении нового хранилища:

Создайте файл в директории src/stores/
Используйте defineStore для определения хранилища
Импортируйте конфигурацию из @/config, если требуется доступ к настройкам

Пример:

import { defineStore } from 'pinia'
import config from '@/config'

export const useAuthStore = defineStore('auth', {
  state: () => ({
    user: null,
    apiUrl: config.apiUrl
  }),
  actions: {
    // ...
  }
})

Сборка и деплой фронтенда

Установка зависимостей:
```
yarn install
```
Запуск в режиме разработки:
```
yarn dev
```
Сборка для продакшена:
```
yarn build
```
Создание Debian-пакета:
```
./build.sh
```

Инструкции для бэкенда

Структура проекта (Backend)

backend/
├── config/             # Конфигурация приложения
│   ├── env.config.js   # Базовая конфигурация
│   └── configRewrite.js # Механизм переопределения
├── controllers/        # Контроллеры
├── models/             # Модели данных
├── routes/             # Маршруты API
├── middleware/         # Промежуточное ПО
├── helpers/            # Вспомогательные функции
├── drivers/            # Драйверы (персистентная папка)
├── uploads/            # Загруженные файлы (персистентная папка)
├── contrib/            # Файлы для развертывания
│   └── Dockerfile      # Dockerfile для сборки образа
├── debian/             # Файлы для сборки Debian-пакета
│   ├── control         # Метаданные пакета
│   └── aonk-id-backend-bin.install  # Список файлов для установки
├── Makefile            # Скрипты сборки
└── build.sh            # Скрипт создания Debian-пакета

Добавление файлов и папок в сборку (Backend)

Для включения файлов в установочный пакет бэкенда, используется файл debian/aonk-id-backend-bin.install. Каждая строка в файле определяет исходный путь и путь назначения:

package.json /var/www/aonk-id/runtime
package-lock.json /var/www/aonk-id/runtime
config /var/www/aonk-id/runtime
controllers /var/www/aonk-id/runtime
emails /var/www/aonk-id/runtime
helpers /var/www/aonk-id/runtime
middleware /var/www/aonk-id/runtime
models /var/www/aonk-id/runtime
readme /var/www/aonk-id/runtime
node_modules /var/www/aonk-id/runtime
routes /var/www/aonk-id/runtime
seeders /var/www/aonk-id/runtime
index.js /var/www/aonk-id/runtime
config.override.json /var/www/aonk-id/runtime
contrib/aonk-id.service /lib/systemd/system
contrib/aonk-id /etc/default

Работа с базой данных

Для работы с базой данных в проекте используется Sequelize ORM:

Модели данных размещаются в директории models/
Миграции размещаются в директории migrations/
Сидеры для заполнения тестовыми данными - в директории seeders/

Пример создания миграции:

npx sequelize-cli migration:generate --name create-users-table

Запуск миграций:

npx sequelize-cli db:migrate

Персистентные папки (Backend)

На бэкенде определены следующие персистентные директории:

/var/www/aonk-id/runtime/uploads - для загруженных файлов
/var/www/aonk-id/runtime/drivers - для драйверов

Сборка и деплой бэкенда

Установка зависимостей:
```
npm install
```
Запуск в режиме разработки:
```
npm run dev
```
Создание Debian-пакета:
```
./build.sh
```

Тестовые стенды (Staging)

Создание и обновление стендов

Для работы с тестовыми стендами используется механизм веток. Каждая ветка формата stand/название автоматически создает или обновляет соответствующий тестовый стенд:

Создайте новую ветку с префиксом stand/:
```
git checkout -b stand/feature-name
```
Внесите необходимые изменения и закоммитьте их:
```
git add .
git commit -m "Описание изменений"
```
Отправьте ветку в удаленный репозиторий:
```
git push origin stand/feature-name
```

После пуша изменений в ветку stand/feature-name, система CI/CD автоматически развернет или обновит тестовый стенд с соответствующим именем.

Чистая установка стенда

Для полной очистки тестового стенда (включая базу данных и персистентные файлы) необходимо выполнить коммит с ключевым словом CleanStand в сообщении:

git commit --allow-empty -m "CleanStand: полная очистка тестового стенда"
git push origin stand/feature-name

Важно: Используйте эту операцию с осторожностью, так как она приведет к потере всех данных на тестовом стенде.

Взаимодействие фронтенда и бэкенда

API-интерфейсы

Взаимодействие между фронтендом и бэкендом осуществляется через REST API.

На бэкенде API-маршруты определяются в директории routes/
На фронтенде для работы с API используется axios

Аутентификация и авторизация

Для авторизации используется механизм JWT-токенов:

Фронтенд отправляет учетные данные пользователя на бэкенд
Бэкенд проверяет учетные данные и выдает JWT-токен
Фронтенд сохраняет токен и использует его для последующих запросов

Проверка перед деплоем

Перед деплоем в продакшн-среду необходимо выполнить следующие проверки:

Убедиться, что все тесты проходят успешно
Проверить сборку на наличие предупреждений или ошибок
Проверить работоспособность основных функций приложения
Удостовериться, что все переменные окружения для продакшн-среды корректно настроены

Правила разработки

Обязательные требования

Конфигурации через переменные окружения
- Все настройки, зависящие от окружения, должны быть определены через .env файлы
- Доступ к переменным должен осуществляться через объект конфигурации, а не напрямую через import.meta.env или process.env
Механизм переопределения конфигурации
- Каждый проект должен поддерживать переопределение конфигурации через config.override.json
- Логика загрузки переопределений должна работать только в режиме разработки
Запрет на использование сторонних CDN
- Все ресурсы (шрифты, скрипты, стили) должны быть локальными
- Шрифты должны размещаться в директории проекта, а не загружаться через Google Fonts или другие CDN
- Все библиотеки должны быть установлены через npm/yarn
Безопасность
- Не хранить секреты и ключи в исходном коде
- Не включать учетные данные в репозиторий
- Использовать HTTPS для всех внешних запросов

Лучшие практики

Код
- Следовать принятому стилю кодирования
- Писать тесты для критически важного функционала
- Использовать типизацию где это возможно
Производительность
- Минимизировать количество и размер внешних зависимостей
- Оптимизировать изображения и другие медиа-ресурсы
- Использовать ленивую загрузку для тяжелых компонентов
Доступность
- Обеспечивать доступность интерфейса (WCAG)
- Поддерживать корректное отображение на различных устройствах
- Учитывать особенности разных браузеров