EntityTable

Общее описание

Класс EntityTable является финальным классом для работы с сущностями CRM-системы Ultralight CRM. Он отвечает за выполнение основных операций над сущностями: создание, чтение, обновление и удаление (CRUD).

Основная информация

• Полный путь: App\Models\EntityTable
• Класс-родитель: Model (Laravel Eloquent)
• Модификатор: final (не может быть унаследован)
• Назначение: Интерфейс для работы с экземплярами сущностей

Назначение

Класс EntityTable предназначен для:

• Получения сущностей по фильтру
• Создания новых экземпляров сущностей
• Реализации бизнес-логики доступа к сущностям
• Интеграции с системой управления правами доступа
• Обеспечения безопасности при работе с данными

Методы

getEntities(array $filter, bool $dnCheckRights = false): array

Функция позволяет получить сущности, применяя фильтр для выборки.

Параметры:

• $filter — фильтр, с помощью которого формируется выборка сущностей
• $dnCheckRights — флаг, указывающий, нужно ли проверять права доступа (необязательный, по умолчанию false)

Возвращает: Массив инициализированных сущностей, соответствующих фильтру

Формат фильтра:

[
    "ENTITY_TYPE_ID" => 1, // идентификатор типа сущностей
    "LIMIT" => 5, // количество сущностей, которое будет получено
    "ORDER_BY" => ["column", "ASC|DESC"], // сортировка
    "PAGINATE" => 20, // пагинация (при использовании LIMIT игнорируется)
    "FILTER" => [ // массив фильтрации по полям
        ["FIELD_NAME", "=", "FIELD_VALUE"], // операторы: =, <, >, !=, <=, >=
        ["FIELD_NAME", "<", "FIELD_VALUE"],
        ["FIELD_NAME", "!=", "FIELD_VALUE"]
    ]
]

Пример использования:

// Получение пользователей с лимитом
$users = EntityTable::getEntities([
    'ENTITY_TYPE_ID' => 1,
    'LIMIT' => 10
]);

// Получение проектов с фильтрацией и сортировкой
$projects = EntityTable::getEntities([
    'ENTITY_TYPE_ID' => 5,
    'FILTER' => [['status', '=', 'active']],
    'ORDER_BY' => ['created_at', 'DESC']
]);

// Получение клиентов с пагинацией
$clients = EntityTable::getEntities([
    'ENTITY_TYPE_ID' => 3,
    'PAGINATE' => 20
]);

getEntitiesEx(string $entityTypeName, array $filter, bool $dnCheckRights = false)

Аналог getEntities, но принимает имя типа сущности вместо идентификатора.

Параметры:

• $entityTypeName — имя типа сущности
• $filter — фильтр для выборки
• $dnCheckRights — флаг проверки прав доступа (необязательный)

Возвращает: Массив инициализированных сущностей

Пример использования:

// Получение проектов по имени типа
$projects = EntityTable::getEntitiesEx('Project', [
    'FILTER' => [['status', '=', 'active']]
]);

// Получение клиентов с пагинацией
$clients = EntityTable::getEntitiesEx('Client', [
    'PAGINATE' => 15
]);

createEntity(int $entityTypeId, array $fields)

Функция создает новый экземпляр сущности и возвращает созданную сущность.

Параметры:

• $entityTypeId — идентификатор типа сущности
• $fields — массив значений полей экземпляра сущности в виде [«имя поля» => «значение», …]

Возвращает: Инициализированный экземпляр сущности

Пример использования:

// Создание нового пользователя
$user = EntityTable::createEntity(1, [
    'name' => 'Иван Иванов',
    'email' => 'ivan@example.com',
    'password' => bcrypt('secret')
]);

// Создание нового проекта
$project = EntityTable::createEntity(5, [
    'name' => 'Новый проект',
    'status' => 'active',
    'deadline' => '2025-12-31'
]);

Практическое использование

Базовые операции

Получение сущностей

// Простое получение всех пользователей
$users = EntityTable::getEntities([
    'ENTITY_TYPE_ID' => 1
]);

// Получение с фильтрацией
$activeUsers = EntityTable::getEntities([
    'ENTITY_TYPE_ID' => 1,
    'FILTER' => [['status', '=', 'active']]
]);

// Получение с сортировкой
$sortedProjects = EntityTable::getEntities([
    'ENTITY_TYPE_ID' => 5,
    'ORDER_BY' => ['priority', 'DESC']
]);

// Получение с лимитом
$recentClients = EntityTable::getEntities([
    'ENTITY_TYPE_ID' => 3,
    'ORDER_BY' => ['created_at', 'DESC'],
    'LIMIT' => 5
]);

Пагинация

// Получение клиентов с пагинацией
$pagedClients = EntityTable::getEntities([
    'ENTITY_TYPE_ID' => 3,
    'PAGINATE' => 10
]);

// Результат включает метаданные пагинации
echo $pagedClients['meta']['current_page'];
echo $pagedClients['meta']['last_page'];
echo $pagedClients['meta']['total'];

echo $pagedClients['links']['first'];
echo $pagedClients['links']['prev'];
echo $pagedClients['links']['next'];
echo $pagedClients['links']['last'];

Сложные фильтры

// Фильтрация по нескольким условиям
$filteredProjects = EntityTable::getEntities([
    'ENTITY_TYPE_ID' => 5,
    'FILTER' => [
        ['status', '=', 'active'],
        ['priority', '>', 5],
        ['budget', '<=', 10000]
    ],
    'ORDER_BY' => ['deadline', 'ASC']
]);

// Поиск по диапазону дат
$dateFrom = '2025-01-01';
$dateTo = '2025-12-31';
$projectsInYear = EntityTable::getEntities([
    'ENTITY_TYPE_ID' => 5,
    'FILTER' => [
        ['created_at', '>=', $dateFrom],
        ['created_at', '<=', $dateTo]
    ]
]);

Создание сущностей

// Создание пользователя с полной информацией
$user = EntityTable::createEntity(1, [
    'name' => 'Петр Петров',
    'email' => 'petr@example.com',
    'password' => bcrypt('password123'),
    'appeal' => 'Уважаемый',
    'primary_email' => 'petr@company.com',
    'primary_phone' => '+79991234567',
    'post' => 'Менеджер'
]);

// Создание проекта с деталями
$project = EntityTable::createEntity(5, [
    'name' => 'Разработка CRM',
    'description' => 'Создание новой CRM-системы',
    'status' => 'in_progress',
    'priority' => 10,
    'budget' => 50000,
    'deadline' => '2025-12-31',
    'created_at' => now()
]);

// Создание клиента
$client = EntityTable::createEntity(3, [
    'name' => 'ООО Рога и Копыта',
    'contact_person' => 'Иван Иванов',
    'phone' => '+79887654321',
    'email' => 'info@rogaikopyota.ru',
    'address' => 'г. Москва, ул. Ленина, д. 1',
    'status' => 'active'
]);

Механизм работы

Проверка прав доступа

Система проверяет права доступа при каждом обращении:

1. При получении сущностей — проверяется доступ к типу сущности
2. При создании сущностей — проверяется право на запись для типа
3. При инициализации — проверяется доступ к конкретной сущности

Алгоритм проверки:

$accessRight = CrmAuthorization::getAccess($entityTypeId, $entityId);
if ($accessRight == 0 || $accessRight == 1 || $dnCheckRights) {
    // Разрешить доступ
} else {
    throw new Exception("Access denied: $accessRight");
}

Обработка фильтров

Система преобразует фильтры в SQL-запросы:

// Фильтр
'FILTER' => [['status', '=', 'active'], ['priority', '>', 5]]

// Преобразуется в
$query->where('status', '=', 'active')->where('priority', '>', 5);

Пагинация

При использовании пагинации возвращается структура с данными и метаданными:

return [
    'data' => $entities,
    'meta' => [
        'current_page' => $results->currentPage(),
        'per_page' => $results->perPage(),
        'total' => $results->total(),
        'last_page' => $results->lastPage()
    ],
    'links' => [
        'first' => $results->url(1),
        'last' => $results->url($results->lastPage()),
        'prev' => $results->previousPageUrl(),
        'next' => $results->nextPageUrl(),
    ]
];

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

Проверка входных данных

Система выполняет строгую проверку входных данных:

1. Обязательные параметры — ENTITY_TYPE_ID должен быть указан
2. Проверка существования типа — через EntityTypes::checkEntityTypeExists()
3. Проверка полей — при создании, через EntityTypes::checkFieldExists()
4. Проверка прав доступа — через CrmAuthorization::getAccess()

Обработка ошибок

Система выбрасывает исключения при ошибках:

• InvalidArgumentException — при отсутствии обязательных параметров
• RuntimeException — при ошибках выполнения
• Exception — при ошибках доступа

Примеры обработки:

try {
    $entities = EntityTable::getEntities([
        'ENTITY_TYPE_ID' => 999, // несуществующий тип
        'LIMIT' => 5
    ]);
} catch (Exception $e) {
    echo 'Ошибка: ' . $e->getMessage();
}

try {
    $entity = EntityTable::createEntity(1, [
        'invalid_field' => 'value' // несуществующее поле
    ]);
} catch (Exception $e) {
    echo 'Ошибка: ' . $e->getMessage();
}

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

Оптимизация запросов

Система оптимизирует запросы к базе данных:

1. Использование индексов — для полей, используемых в фильтрации
2. Пагинация — для больших наборов данных
3. Лимиты — для ограничения количества результатов
4. Эффективные JOIN’ы — при необходимости

Кэширование

Для улучшения производительности рекомендуется использовать кэширование:

// Кэширование результатов на 5 минут
$users = Cache::remember('active_users', 300, function () {
    return EntityTable::getEntities([
        'ENTITY_TYPE_ID' => 1,
        'FILTER' => [['status', '=', 'active']]
    ]);
});

Рекомендации по использованию

1. Всегда используйте фильтры — даже при получении одной сущности
2. Используйте пагинацию — для списков с большим количеством элементов
3. Проверяйте ошибки — оборачивайте вызовы в try-catch
4. Используйте getEntitiesEx — когда знаете имя типа, но не знаете идентификатор
5. Документируйте фильтры — ведите реестр используемых фильтров

Заключение

Класс EntityTable является ключевым компонентом системы Ultralight CRM, обеспечивающим централизованный доступ ко всем сущностям. Он реализует полный набор операций CRUD, интегрирован с системой управления правами доступа и обеспечивает безопасность при работе с данными. Благодаря гибкому механизму фильтрации и поддержке пагинации, класс эффективно работает как с небольшими, так и с большими объемами данных.