Модули

Данный документ описывает принципы работы модульной архитектуры Ultralight CRM и правила разработки модулей.

Обзор модульной архитектуры

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

Преимущества модульной архитектуры

• Гибкость — возможность добавлять/удалять функциональность по требованию
• Изоляция — модули работают независимо друг от друга
• Простота развертывания — модули можно устанавливать и обновлять отдельно
• Безопасность — ограничение доступа модулей к ядру системы
• Поддержка сообщества — возможность разработки сторонними разработчиками

Структура модуля

Каждый модуль представляет собой отдельную директорию в папке modules/ и имеет следующую структуру:

modules/
└── [ModuleName]/
    ├── init.php            # Точка входа для установки
    ├── remove.php          # Точка входа для удаления
    ├── info.json           # Метаданные модуля
    ├── web.php             # Маршруты модуля
    ├── client/             # Клиентские скрипты
    │   ├── module.js
    │   └── styles.css
    ├── Services/           # Бизнес-логика
    │   └── ModuleService.php
    ├── views/              # Шаблоны представления
    │   └── index.blade.php
    └── database/           # Миграции и сидеры
        ├── migrations/
        └── seeders/

Обязательные файлы

info.json

Файл метаданных модуля в формате JSON:

{
    "module-id": "ModuleName",
    "name": "Название модуля",
    "version": "1.0.0",
    "description": "Описание модуля",
    "author": "Имя автора",
    "license": "Тип лицензии",
    "dependencies": [
        "ДругойМодуль"
    ]
}

init.php

Точка входа для установки модуля. Должна содержать функцию установки:

<?php

use App\Services\Modules\Api\CrmModulesInfo;

function initModule() {
    // Регистрация сущностей
    // Создание миграций
    // Инициализация данных
    // Подключение маршрутов
    
    return true; // Успешная установка
}

remove.php

Точка входа для удаления модуля:

<?php

function removeModule() {
    // Удаление миграций
    // Очистка данных
    // Отключение маршрутов
    
    return true; // Успешное удаление
}

web.php

Файл маршрутов модуля:

<?php

use Illuminate\Support\Facades\Route;

Route::prefix('module/[ModuleName]')->group(function () {
    Route::get('/', '[Controller]@index')->name('[module].index');
    Route::get('/create', '[Controller]@create')->name('[module].create');
    Route::post('/store', '[Controller]@store')->name('[module].store');
});

API для разработчиков модулей

CrmModulesInfo

Центральный интерфейс для работы с модулями:

// Получить список всех модулей
CrmModulesInfo::getModulesList();

// Получить информацию о модуле
CrmModulesInfo::getModuleInfo('ModuleName');

// Получить версию ядра
CrmModulesInfo::getCoreVersion();

// Получить версию модуля
CrmModulesInfo::getInstalledModuleVersion('ModuleName');

CrmEntityApi

API для работы с сущностями из модулей:

Регистрация нового типа сущности

$entityId = CrmEntityApi::newEntityType('Project', 'App\\Models\\Project')
    ->addField('name', 'CHAR', 128)
    ->addField('status', 'CHAR', 32)
    ->addField('deadline', 'DATE')
    ->register();

Создание экземпляра сущности

$project = CrmEntityApi::create('Project')
    ->set('name', 'Новый проект')
    ->set('status', 'active')
    ->set('deadline', '2025-12-31')
    ->execute();

Поиск сущностей

$projects = CrmEntityApi::find('Project', [
    'FILTER' => [['status', '=', 'active']]
]);

Обновление сущности

CrmEntityApi::update($project, 'status', 'completed');

Жизненный цикл модуля

1. Установка модуля

Установка выполняется через административный интерфейс или API:

1. Проверка совместимости с ядром
2. Проверка зависимостей
3. Выполнение init.php
4. Регистрация модуля в системе
5. Применение миграций
6. Инициализация данных

2. Работа модуля

После установки модуль:

• Доступен через свои маршруты
• Имеет доступ к API ядра
• Может взаимодействовать с другими модулями
• Отображается в интерфейсе

3. Обновление модуля

Обновление выполняется по следующему алгоритму:

1. Загрузка новой версии
2. Проверка совместимости
3. Резервное копирование данных
4. Выполнение миграций обновления
5. Обновление метаданных
6. Перезагрузка модуля

4. Удаление модуля

Удаление выполняется в следующем порядке:

1. Проверка зависимостей
2. Выполнение remove.php
3. Удаление миграций
4. Очистка данных
5. Удаление из реестра модулей

Разработка модуля

Шаг 1: Создание структуры

# Создаем директорию модуля
mkdir modules/MyModule

# Создаем обязательные файлы
touch modules/MyModule/info.json
touch modules/MyModule/init.php
touch modules/MyModule/remove.php
touch modules/MyModule/web.php

Шаг 2: Определение метаданных

// modules/MyModule/info.json
{
    "module-id": "MyModule",
    "name": "Мой модуль",
    "version": "1.0.0",
    "description": "Описание моего модуля",
    "author": "Имя разработчика",
    "license": "MIT",
    "dependencies": []
}

Шаг 3: Реализация установки

// modules/MyModule/init.php
<?php

use App\Services\Modules\Api\CrmEntityApi;

function initModule() {
    try {
        // Регистрируем новый тип сущности
        CrmEntityApi::newEntityType('Task', 'App\\Models\\Task')
            ->addField('title', 'CHAR', 255)
            ->addField('description', 'TEXT')
            ->addField('status', 'CHAR', 20)
            ->addField('priority', 'INTEGER')
            ->register();
            
        return true;
    } catch (Exception $e) {
        return false;
    }
}

Шаг 4: Реализация удаления

// modules/MyModule/remove.php
<?php

function removeModule() {
    try {
        // Удаление миграций и данных будет выполнено автоматически
        // Дополнительная очистка при необходимости
        
        return true;
    } catch (Exception $e) {
        return false;
    }
}

Шаг 5: Добавление маршрутов

// modules/MyModule/web.php
<?php

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\ModuleController;

Route::prefix('module/mymodule')->group(function () {
    Route::get('/', [ModuleController::class, 'index'])->name('mymodule.index');
    Route::get('/tasks', [ModuleController::class, 'tasks'])->name('mymodule.tasks');
    Route::post('/tasks', [ModuleController::class, 'storeTask'])->name('mymodule.storeTask');
});

Шаг 6: Создание контроллера

// app/Http/Controllers/ModuleController.php
<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Services\Modules\Api\CrmEntityApi;

class ModuleController extends Controller
{
    public function index()
    {
        return view('module.mymodule.index');
    }
    
    public function tasks()
    {
        $tasks = CrmEntityApi::find('Task', [
            'ORDER_BY' => ['priority', 'DESC']
        ]);
        
        return view('module.mymodule.tasks', compact('tasks'));
    }
    
    public function storeTask(Request $request)
    {
        $task = CrmEntityApi::create('Task')
            ->set('title', $request->input('title'))
            ->set('description', $request->input('description'))
            ->set('status', 'new')
            ->set('priority', $request->input('priority', 1))
            ->execute();
            
        return redirect()->route('mymodule.tasks');
    }
}

Шаг 7: Создание представлений

{{-- resources/views/module/mymodule/index.blade.php --}}
@extends('app')

@section('content')
<div class="container">
    <h1>Мой модуль</h1>
    <p>Добро пожаловать в мой модуль!</p>
</div>
@endsection

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

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

• Не изменяйте ядро системы
• Валидируйте все входные данные
• Используйте CSRF-защиту
• Экранируйте вывод данных
• Проверяйте права доступа

2. Производительность

• Минимизируйте количество запросов к БД
• Используйте кэширование
• Оптимизируйте маршруты
• Минифицируйте клиентские ресурсы

3. Совместимость

• Соблюдайте версионирование
• Проверяйте совместимость с ядром
• Документируйте зависимости
• Тестируйте на разных версиях

4. Качество кода

• Следуйте PSR-стандартам
• Пишите читаемый код
• Документируйте API
• Покрывайте тестами

Отладка модулей

Инструменты отладки

• /dub — отладочный эндпоинт для просмотра списка модулей
• Логирование через Laravel Log
• Xdebug для PHP
• Browser DevTools для клиентской части

Распространенные проблемы

1. Модуль не устанавливается — проверьте синтаксис init.php
2. Маршруты не работают — проверьте web.php и кэш маршрутов
3. Права доступа — убедитесь в наличии необходимых прав
4. Зависимости — проверьте наличие зависимых модулей

Модульная архитектура Ultralight CRM предоставляет мощные возможности для расширения функциональности системы, сохраняя при этом стабильность и безопасность ядра.