Feature: Bulk Employee Management via CSV Import/Export

[jorikfon]

Feature: Bulk Employee Management via CSV Import/Export

Description

English Description

This feature implements comprehensive bulk employee management capabilities through CSV file import and export functionality, enabling administrators to efficiently manage large numbers of employees in the MikoPBX system.

Current Implementation Overview

• ✅ Individual employee creation and editing via web interface
• ✅ RESTful API v3 for employee management (CRUD operations)
• ✅ Basic employee data structure with extensions, forwarding, and mobile numbers
• ❌ No bulk import capability from CSV files
• ❌ No bulk export functionality to CSV
• ❌ No template generation for CSV structure
• ❌ No duplicate handling strategies for imports

Proposed Changes/Solution

1. CSV Import Functionality

• Implement POST /pbxcore/api/v3/employees:import endpoint
• Support multiple import strategies:
  • skip_duplicates - Skip existing employees
  • update_existing - Update existing employee data
  • fail_on_duplicate - Reject import if duplicates found
• Preview mode to validate data before actual import
• Confirmation step after preview
• Automatic dependency resolution for related entities

2. CSV Export Functionality

• Implement POST /pbxcore/api/v3/employees:export endpoint
• Support multiple export formats:
  • minimal - Basic employee data only
  • standard - Common fields including extensions
  • full - Complete employee data with all settings
• Filtering options by number range or other criteria
• Direct download of generated CSV file

3. CSV Template Generation

• Implement GET /pbxcore/api/v3/employees:template endpoint
• Generate downloadable CSV templates with headers
• Support same format options as export (minimal/standard/full)
• Include example data row for reference

4. Web Interface Integration

• New "Bulk Upload" page at /admin-cabinet/extensions/bulkupload
• Drag-and-drop CSV upload with Resumable.js
• Real-time preview of import data
• Progress tracking for large imports
• Export button on employee list page

5. Background Processing

• WorkerBulkEmployees for async processing of large files
• Progress updates via WebSocket/SSE
• Error handling and rollback capabilities

Benefits

• Dramatically reduced time for initial system setup
• Easy migration from other PBX systems
• Simplified employee data backup and restore
• Batch updates for organizational changes
• Template-based standardized data entry
• Improved data consistency across the system

Technical Implementation Details

• ImportCSVAction class for processing CSV imports
• ExportCSVAction class for generating CSV exports
• DependencyResolver for managing related entities
• Support for UTF-8 encoded CSV files
• Validation of required fields and data formats
• Transaction-based imports with rollback on errors

---

Русское описание

Эта функция реализует комплексные возможности массового управления сотрудниками через функциональность импорта и экспорта CSV файлов, позволяя администраторам эффективно управлять большим количеством сотрудников в системе MikoPBX.

Обзор текущей реализации

• ✅ Индивидуальное создание и редактирование сотрудников через веб-интерфейс
• ✅ RESTful API v3 для управления сотрудниками (CRUD операции)
• ✅ Базовая структура данных сотрудника с внутренними номерами, переадресацией и мобильными номерами
• ❌ Отсутствует возможность массового импорта из CSV файлов
• ❌ Отсутствует функциональность массового экспорта в CSV
• ❌ Отсутствует генерация шаблонов для структуры CSV
• ❌ Отсутствуют стратегии обработки дубликатов при импорте

Предлагаемые изменения/решение

1. Функциональность импорта CSV

• Реализация endpoint POST /pbxcore/api/v3/employees:import
• Поддержка нескольких стратегий импорта:
  • skip_duplicates - Пропускать существующих сотрудников
  • update_existing - Обновлять данные существующих сотрудников
  • fail_on_duplicate - Отклонять импорт при обнаружении дубликатов
• Режим предпросмотра для валидации данных перед импортом
• Шаг подтверждения после предпросмотра
• Автоматическое разрешение зависимостей для связанных сущностей

2. Функциональность экспорта CSV

• Реализация endpoint POST /pbxcore/api/v3/employees:export
• Поддержка нескольких форматов экспорта:
  • minimal - Только базовые данные сотрудников
  • standard - Общие поля включая внутренние номера
  • full - Полные данные сотрудников со всеми настройками
• Опции фильтрации по диапазону номеров или другим критериям
• Прямая загрузка сгенерированного CSV файла

3. Генерация шаблонов CSV

• Реализация endpoint GET /pbxcore/api/v3/employees:template
• Генерация загружаемых CSV шаблонов с заголовками
• Поддержка тех же форматов, что и экспорт (minimal/standard/full)
• Включение примера строки данных для справки

4. Интеграция с веб-интерфейсом

• Новая страница "Массовая загрузка" по адресу /admin-cabinet/extensions/bulkupload
• Загрузка CSV методом drag-and-drop с Resumable.js
• Предпросмотр данных импорта в реальном времени
• Отслеживание прогресса для больших импортов
• Кнопка экспорта на странице списка сотрудников

5. Фоновая обработка

• WorkerBulkEmployees для асинхронной обработки больших файлов
• Обновления прогресса через WebSocket/SSE
• Обработка ошибок и возможности отката

Преимущества

• Значительное сокращение времени начальной настройки системы
• Простая миграция с других АТС систем
• Упрощенное резервное копирование и восстановление данных сотрудников
• Пакетные обновления при организационных изменениях
• Стандартизированный ввод данных на основе шаблонов
• Улучшенная согласованность данных в системе

Технические детали реализации

• Класс ImportCSVAction для обработки импорта CSV
• Класс ExportCSVAction для генерации экспорта CSV
• DependencyResolver для управления связанными сущностями
• Поддержка CSV файлов в кодировке UTF-8
• Валидация обязательных полей и форматов данных
• Импорт на основе транзакций с откатом при ошибках

---

Labels

• feature
• enhancement
• api
• ui
• core

Milestone

• 2025.1.0

Related Files (Implementation in Progress)

• src/PBXCoreREST/Lib/Employees/ImportCSVAction.php - CSV import processing
• src/PBXCoreREST/Lib/Employees/ExportCSVAction.php - CSV export generation
• src/PBXCoreREST/Lib/Employees/GetDefaultAction.php - Default values for new employees
• src/PBXCoreREST/Lib/Employees/DependencyResolver.php - Dependency management
• src/PBXCoreREST/Workers/WorkerBulkEmployees.php - Background processing
• src/AdminCabinet/Views/Extensions/bulkupload.volt - Web interface
• sites/admin-cabinet/assets/js/src/Extensions/extensions-bulk-upload.js - Frontend logic