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

Этот документ описывает структуру репозитория плагина для 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      # Конфигурация сборки

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

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

Рекомендации по разработке

1. Начало работы

   npm install        # Установка зависимостей
   npm run dev       # Запуск в режиме разработки
   npm run build     # Сборка проекта
   npm run test      # Запуск тестов

2. Добавление новых зависимостей

   npm install <package> --save        # Для production зависимостей
   npm install <package> --save-dev    # Для development зависимостей

3. Создание нового приложения
   • Создать новую директорию в apps/
   • Добавить конфигурацию в contract.json
   • Настроить package.json, tsconfig.json и vite.config.mts
   • Создать базовую структуру src/
4. Обновление документации
   • Обновлять соответствующие файлы в docs/
   • Следовать формату Markdown.
   • Проверять корректность ссылок.
5. Работа с TypeScript
   • Использовать строгую типизацию.
   • Следовать рекомендациям из tsconfig.json
   • Документировать типы и интерфейсы.

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

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

Поддержка

При возникновении вопросов или проблем:

1. Проверить документацию в docs/
2. Обратиться к команде разработки.
3. Создать issue в репозитории.
4. Следовать процессу code review.