Структура репозитория плагина

Этот документ описывает структуру репозитория плагина для YCLIENTS.

Общая структура

Корневой директорией репозитория является директория с названием плагина. В зависимости от типа плагина, корневая директория может содержать:

Только директорию frontend/ (для плагинов, работающих только на стороне клиента).
Только директорию backend/ (для плагинов, работающих только на стороне сервера).
Обе директории frontend/ и backend/ (для плагинов, требующих работу как на клиенте, так и на сервере).

Пример структуры для плагина с фронтендом:

plugin-name/              # Корневая директория плагина
├── frontend/             # Директория фронтенд части плагина
│   ├── apps/             # Приложения плагина
│   ├── docs/             # Документация проекта
│   ├── dist/             # Собранные артефакты
│   ├── node_modules/     # Зависимости npm
│   ├── packages/         # Локальные пакеты
│   ├── tools/            # Инструменты разработки
│   ├── .eslintrc.js      # Конфигурация ESLint
│   ├── .gitignore        # Игнорируемые git файлы
│   ├── .prettierrc       # Конфигурация Prettier
│   ├── contract.json     # Контракт плагина
│   ├── package.json      # Зависимости и скрипты npm
│   ├── package-lock.json # Фиксированные версии зависимостей
│   └── README.md         # Основная документация
└── backend/              # Директория бэкенд части плагина (если требуется)
    └── ...               # Структура бэкенд части

Описание директорий и файлов

Директории

`apps/`

Основная директория с приложениями плагина. Каждое приложение представляет собой отдельный пакет плагина, который может быть встроен в различные части системы YCLIENTS. Каждое приложение имеет свою собственную структуру:

package.json — зависимости и конфигурация приложения.
src/ — исходный код приложения.
index.html — точка входа для приложения.
tsconfig.json — конфигурация TypeScript для приложения.
vite.config.mts — конфигурация сборки Vite.

Примеры приложений:

color-picker-erp-settings — настройки плагина в ERP.
color-picker-erp-timetable — интеграция с расписанием в ERP.
color-picker-widget-timetable — интеграция с расписанием в виджетах.

`docs/`

Содержит всю документацию проекта, включая:

Описание процесса CI/CD.
Руководства по разработке.
API документацию.
Документацию по развертыванию.

`dist/`

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

`packages/`

Содержит локальные пакеты, используемые в проекте. Каждый пакет может иметь свою собственную конфигурацию и зависимости.

Доступные пакеты:

api/ — HTTP клиент и API утилиты.
utils/ — общие утилиты и системы событий.

`tools/`

Содержит инструменты и скрипты для разработки, сборки и тестирования плагина.

Доступные инструменты:

vite/ — конфигурация сборки Vite.
typescript/ — конфигурация TypeScript.

Конфигурационные файлы

`.eslintrc.js`

Конфигурация ESLint для статического анализа кода. Определяет правила линтинга и форматирования.

`.prettierrc`

Конфигурация Prettier для автоматического форматирования кода. Обеспечивает единообразный стиль кода.

`contract.json`

Определяет контракт плагина, который заполняется разработчиком плагина. Контракт содержит список пакетов (packages), которые представляют собой отдельные приложения плагина, и метаданные плагина.

Структура контракта:

packages — объект, содержащий конфигурацию для каждого пакета плагина.
- package-name — уникальное имя пакета, соответствующее директории в apps/
- application — тип приложения, в которое встраивается пакет:
  - "erp" — для встраивания в ERP систему YCLIENTS.
  - "widget" — для встраивания в виджеты YCLIENTS.
- areas — список зон интеграции в интерфейсе (массив строк):
  - ["root"] — основная область приложения.
  - ["plugin-settings"] — область настроек плагина.
  - ["erp-visit-modal-client-details"] — область деталей клиента в модальном окне посещения ERP.
plugin-slug — уникальный идентификатор плагина в системе YCLIENTS.

Пример реального контракта:

{
  "packages": {
    "color-picker-erp-settings": {
      "application": "erp",
      "areas": ["plugin-settings"]
    },
    "color-picker-erp-timetable": {
      "application": "erp",
      "areas": ["root"]
    },
    "widget-masters-promo": {
      "application": "widget",
      "areas": ["root"]
    },
    "client-loyalty-card": {
      "application": "erp",
      "areas": ["erp-visit-modal-client-details"]
    },
    "timetable-record-client-name": {
      "application": "erp",
      "areas": ["erp-timetable-controls", "erp-timetable-record-client-name"]
    }
  },
  "plugin-slug": "color-picker-slug"
}

Важные замечания:

Каждый пакет в packages должен соответствовать директории в apps/
Имена пакетов должны быть уникальными в рамках плагина.
Типы приложений (application) определяют, где будет работать пакет.
Зоны (areas) определяют одну или несколько точек интеграции в интерфейсе YCLIENTS для каждого пакета.
plugin-slug должен быть уникальным среди всех плагинов в системе.
Контракт является обязательным документом для публикации плагина.

`package.json`

Основной файл конфигурации npm, содержащий:

Зависимости проекта.
Скрипты для разработки и сборки.
Метаданные проекта.
Версионирование.

Структура приложения в `apps/`

Каждое приложение в директории apps/ имеет следующую структуру:

app-name/
├── src/
│   ├── components/       # Vue компоненты
│   ├── types/           # TypeScript типы
│   ├── app.vue          # Корневой компонент приложения
│   ├── host.ts          # Точка входа для хоста
│   ├── index.ts         # Основная точка входа
│   └── plugin.ts        # Конфигурация плагина
├── index.html           # HTML шаблон
├── package.json         # Зависимости приложения
├── tsconfig.json        # Конфигурация TypeScript
└── vite.config.mts      # Конфигурация сборки

Правила работы с репозиторием

Структура кода
- Соблюдать модульную структуру.
- Следовать принципам чистой архитектуры.
- Использовать типизацию TypeScript.
- Поддерживать документацию в актуальном состоянии.
- Разделять код на frontend и backend части в соответствующих директориях.
- Создавать только необходимые директории (frontend и/или backend) в зависимости от типа плагина.
- Каждое приложение в apps/ должно быть самодостаточным.
Версионирование
- Следовать семантическому версионированию.
- Обновлять версию в package.json
- Создавать теги для релизов.
Зависимости
- Фиксировать версии зависимостей в package-lock.json
- Регулярно обновлять зависимости.
- Проверять совместимость при обновлении.
Документация
- Поддерживать актуальность README.md.
- Документировать все значимые изменения.
- Следовать стандартам документации.
Сборка и тестирование
- Использовать скрипты из package.json
- Следовать процессу CI/CD.
- Поддерживать тестовое покрытие.

Безопасность

Конфиденциальные данные
- Не хранить секреты в репозитории.
- Использовать переменные окружения.
- Следовать политике безопасности.
Зависимости
- Регулярно проверять уязвимости.
- Использовать только проверенные пакеты.
- Следить за обновлениями безопасности.