Руководство разработчика модулей TropaTT

+-----------------------------------------------------------------------------------+
|                                 TropaTT Core                                      |
|                                                                                   |
|   +-------------------+       +--------------------+       +------------------+   |
|   |   FrontController |       |    PositionRegistry|       |   HookManager    |   |
|   |   (Web & REST)    |       |  (UI Slots Engine) |       |  (Event Bus)     |   |
|   +---------+---------+       +---------+----------+       +--------+---------+   |
|             |                           |                           |             |
+-------------|---------------------------|---------------------------|-------------+
              |                           |                           |
              v                           v                           v
+-----------------------------------------------------------------------------------+
|                             PluginManager Runtime                                 |
|                                                                                   |
|  +--------------------+   +-----------------------+   +------------------------+  |
|  | ModuleCodeValidator|   | ModuleCircuitBreaker  |   | ModuleMigrationRunner  |  |
|  +--------------------+   +-----------------------+   +------------------------+  |
|                                                                                   |
|  +--------------------+   +-----------------------+   +------------------------+  |
|  | ModuleAssetManager |   |  ModuleCronScheduler  |   |  ModuleJobDispatcher   |  |
|  +--------------------+   +-----------------------+   +------------------------+  |
+-------------------------------------+---------------------------------------------+
                                      |
                                      v
+-----------------------------------------------------------------------------------+
|                        Сторонний Модуль (Vendor / Extension)                      |
|                                                                                   |
|  +---------------+  +--------------------------+  +----------------------------+  |
|  | manifest.json |  | ServiceProvider.php      |  | Controllers & Models       |  |
|  +---------------+  +--------------------------+  +----------------------------+  |
|  +---------------+  +--------------------------+  +----------------------------+  |
|  | migrations/*.sql | assets/ (css, js)       |  | templates/ (*.twig / *.php)|  |
|  +---------------+  +--------------------------+  +----------------------------+  |
+-----------------------------------------------------------------------------------+

modules/acme.telegram-notifier/
├── manifest.json                      # Декларативный манифест модуля (обязателен)
├── README.md                          # Описание и инструкция для пользователей
├── api/                               # Серверная логика API и бэкенда
│   ├── TelegramNotifierServiceProvider.php  # ServiceProvider модуля
│   ├── config/
│   │   └── routes.php                 # Маршруты REST API
│   ├── controller/
│   │   └── ApiTelegramController.php  # API-контроллер
│   ├── service/
│   │   ├── TelegramService.php        # Бизнес-логика отправки
│   │   └── TelegramQueue.php          # Очередь
│   ├── hook/
│   │   └── StatusHook.php             # Слушатели хуков ядра
│   ├── cron/
│   │   └── QueueWorkerHandler.php     # Обработчик cron
│   └── migrations/                    # SQL-миграции базы данных
│       ├── 001_create_tables.sql
│       └── 001_create_tables_rollback.sql
└── web/                               # Веб-интерфейс и пользовательские слоты
    ├── config/
    │   └── routes.php                 # Маршруты веб-страниц CRM
    ├── controller/
    │   └── WebSettingsController.php  # Контроллер веб-страницы
    ├── position/
    │   └── TaskSidebarPanel.php       # Рендерер UI-слота в сайдбаре задачи
    ├── template/
    │   └── page/
    │       └── settings.php           # Шаблон страницы настроек
    ├── language/                      # Локализация интерфейса
    │   ├── ru-ru.php
    │   └── en-us.php
    └── assets/                        # Статические ресурсы
        ├── css/
        │   └── widget.css
        └── js/
            └── widget.js

{
  "name": "acme.telegram-notifier",
  "version": "1.0.0",
  "vendor": "acme",
  "author": "Anton Barinov",
  "author_url": "https://github.com/Anton-Barinov",
  "title": "Telegram Уведомления",
  "description": "Мгновенная отправка уведомлений о смене статусов и комментариях в Telegram",
  "category": "integration",
  "license": "MIT",
  "core_version": ">=1.0.0",
  "dependencies": [],
  "require_permissions": [
    "tasks.read"
  ],
  "service_provider": "Module\\Acme\\TelegramNotifier\\TelegramNotifierServiceProvider",
  "api_routes": "api/config/routes.php",
  "web_routes": "web/config/routes.php",
  "migrations": "api/migrations/",
  "config_defaults": {
    "telegram_bot_token": "",
    "telegram_default_chat_id": "",
    "notify_on_status_change": 1
  },
  "menu_items": [
    {
      "route": "module-telegram-settings",
      "label": "Настройки Telegram",
      "icon": "<i class=\"bi bi-telegram\"></i>",
      "permission": "acme.telegram.manage",
      "parent": null
    }
  ],
  "assets": {
    "css": [
      "web/assets/css/widget.css"
    ],
    "js_routes": {
      "task-detail": "web/assets/js/widget.js"
    },
    "css_routes": {
      "task-detail": "web/assets/css/widget.css"
    }
  },
  "positions": {
    "task.detail.sidebar": [
      {
        "renderer": "Module\\Acme\\TelegramNotifier\\Position\\TaskSidebarPanel::render",
        "priority": 15,
        "key": "telegram_notifier"
      }
    ]
  },
  "hooks": {}
}

<?php
declare(strict_types=1);

namespace Module\Acme\TelegramNotifier;

use Api\System\Library\Container;
use Api\System\Library\Hook\HookManager;
use Api\System\Library\Module\AbstractModuleServiceProvider;
use Api\System\Library\Module\ModuleEvents;
use Api\System\Library\Module\ScheduledTask;
use Module\Acme\TelegramNotifier\Service\TelegramService;
use Module\Acme\TelegramNotifier\Cron\QueueWorkerHandler;

final class TelegramNotifierServiceProvider extends AbstractModuleServiceProvider
{
    public function register(Container $container): void
    {
        // Регистрация сервиса как singleton в DI-контейнере ядра
        $container->singleton(TelegramService::class, static function (Container $c): TelegramService {
            $pdo = $c->get(\PDO::class);
            return new TelegramService($pdo);
        });
    }

    public function boot(Container $container): void
    {
        /** @var HookManager $hooks */
        $hooks = $container->get('hook.manager');

        // Подписка на событие смены статуса задачи с приоритетом 100
        $hooks->register(ModuleEvents::TASK_STATUS_CHANGED, function (array &$context): void {
            $telegram = $this->container->get(TelegramService::class);
            $telegram->onStatusChanged($context);
        }, 100);
    }

    public function getPermissions(): array
    {
        return [
            'acme.telegram.view',
            'acme.telegram.manage',
        ];
    }

    public function getMenuItems(): array
    {
        return [
            [
                'route' => 'module-telegram-settings',
                'label' => 'Telegram Бот',
                'icon' => '<i class="bi bi-telegram"></i>',
                'permission' => 'acme.telegram.manage',
                'parent' => null,
            ],
        ];
    }

    public function getScheduledTasks(): array
    {
        return [
            new ScheduledTask(
                moduleName: 'acme.telegram-notifier',
                taskName: 'flush_telegram_queue',
                schedule: '*/2 * * * *',
                handlerClass: QueueWorkerHandler::class,
                handlerMethod: 'run'
            ),
        ];
    }
}

function (array &$context): void

namespace Api\System\Library\Module;

final class ModuleEvents
{
    // Жизненный цикл задач (TaskController)
    public const TASK_CREATED          = 'task.created';
    public const TASK_UPDATED          = 'task.updated';
    public const TASK_STATUS_CHANGED   = 'task.status_changed';
    public const TASK_ASSIGNEE_CHANGED = 'task.assignee_changed';
    public const TASK_DELETED          = 'task.deleted';

    // Жизненный цикл проектов (ProjectController)
    public const PROJECT_CREATED       = 'project.created';
    public const PROJECT_UPDATED       = 'project.updated';
    public const PROJECT_DELETED       = 'project.deleted';

    // Жизненный цикл пользователей (UserController)
    public const USER_CREATED          = 'user.created';
    public const USER_UPDATED          = 'user.updated';
    public const USER_DELETED          = 'user.deleted';

    // Жизненный цикл рабочих циклов / спринтов (WorkCycleController)
    public const CYCLE_CREATED         = 'cycle.created';
    public const CYCLE_STARTED         = 'cycle.started';
    public const CYCLE_COMPLETED       = 'cycle.completed';
    public const CYCLE_REOPENED        = 'cycle.reopened';
    public const CYCLE_ARCHIVED        = 'cycle.archived';
    public const CYCLE_DELETED         = 'cycle.deleted';

    // CRM записи (клиенты, контрагенты, контакты, компании, организации)
    public const CLIENT_CREATED        = 'client.created';
    public const CLIENT_UPDATED        = 'client.updated';
    public const CLIENT_DELETED        = 'client.deleted';
    public const COUNTERPARTY_CREATED  = 'counterparty.created';
    public const COUNTERPARTY_UPDATED  = 'counterparty.updated';
    public const COUNTERPARTY_DELETED  = 'counterparty.deleted';
    public const CONTACT_CREATED       = 'contact.created';
    public const CONTACT_UPDATED       = 'contact.updated';
    public const CONTACT_DELETED       = 'contact.deleted';
    public const COMPANY_CREATED       = 'company.created';
    public const COMPANY_UPDATED       = 'company.updated';
    public const COMPANY_DELETED       = 'company.deleted';
    public const ORGANIZATION_CREATED  = 'organization.created';
    public const ORGANIZATION_UPDATED  = 'organization.updated';
    public const ORGANIZATION_DELETED  = 'organization.deleted';

    // Таксономия и конфигурационные сущности
    public const TAG_CREATED           = 'tag.created';
    public const TAG_UPDATED           = 'tag.updated';
    public const TAG_DELETED           = 'tag.deleted';
    public const STATUS_CREATED        = 'status.created';
    public const STATUS_UPDATED        = 'status.updated';
    public const STATUS_DELETED        = 'status.deleted';
    public const PRIORITY_CREATED      = 'priority.created';
    public const PRIORITY_UPDATED      = 'priority.updated';
    public const PRIORITY_DELETED      = 'priority.deleted';
    public const CUSTOM_FIELD_CREATED  = 'custom_field.created';
    public const CUSTOM_FIELD_UPDATED  = 'custom_field.updated';
    public const CUSTOM_FIELD_DELETED  = 'custom_field.deleted';

    // Коллаборация, файлы и чат
    public const COMMENT_ADDED         = 'comment.added';
    public const FILE_UPLOADED         = 'file.uploaded';
    public const CHAT_MESSAGE_CREATED  = 'chat.message_created';
    public const CHAT_MESSAGE_UPDATED  = 'chat.message_updated';
    public const CHAT_MESSAGE_DELETED  = 'chat.message_deleted';

    // Рендеринг интерфейса ядра (Web\Core\Controller)
    public const RENDER_BEFORE         = 'render.before';
    public const RENDER_AFTER          = 'render.after';
}

"positions": {
  "task.detail.sidebar": [
    {
      "renderer": "Module\\Acme\\TelegramNotifier\\Position\\TaskSidebarPanel::render",
      "priority": 10,
      "key": "telegram_panel"
    }
  ]
}

<?php
declare(strict_types=1);

namespace Module\Acme\TelegramNotifier\Position;

final class TaskSidebarPanel
{
    public static function render(array $context): string
    {
        $taskPublicId = trim((string)($context['task_public_id'] ?? ''));
        if ($taskPublicId === '') {
            return '';
        }

        $safePublicId = htmlspecialchars($taskPublicId, ENT_QUOTES, 'UTF-8');

        return '<div class="crm-card mb-3" data-task-public-id="' . $safePublicId . '">'
            . '<div class="crm-side-card-head">'
            . '<h2 class="h6 mb-0"><i class="bi bi-telegram text-primary me-1"></i> Telegram Уведомления</h2>'
            . '</div>'
            . '<div class="p-3 small">'
            . '<p class="text-muted mb-2">Уведомления по задаче отправляются в привязанный чат.</p>'
            . '</div>'
            . '</div>';
    }
}

<?php
// web/language/ru-ru.php
return [
    'module_telegram_settings' => [
        'title' => 'Настройки Telegram-бота',
        'bot_token' => 'Токен бота',
        'save' => 'Сохранить',
    ],
];

<?php
declare(strict_types=1);

use Module\Acme\TelegramNotifier\Controller\ApiTelegramController;

return [
    [
        'methods'    => ['GET'],
        'route'      => '/settings', // Преобразуется в /_module/acme.telegram-notifier/settings
        'controller' => ApiTelegramController::class,
        'action'     => 'getSettings',
        'auth'       => true,
    ],
    [
        'methods'    => ['POST'],
        'route'      => '/test-message', // Преобразуется в /_module/acme.telegram-notifier/test-message
        'controller' => ApiTelegramController::class,
        'action'     => 'sendTest',
        'auth'       => true,
    ],
];

<?php
declare(strict_types=1);

namespace Module\Acme\TelegramNotifier\Controller;

use Api\System\Library\Container;
use Api\System\Library\Http\JsonResponse;

final class ApiTelegramController
{
    public function __construct(private readonly Container $container) {}

    public function getSettings(array $params = []): JsonResponse
    {
        return JsonResponse::success('TELEGRAM_SETTINGS', 'OK', [
            'bot_configured' => true,
        ]);
    }

    public function sendTest(array $params = []): JsonResponse
    {
        $raw = file_get_contents('php://input');
        $body = json_decode($raw ?: '{}', true) ?: [];

        $chatId = trim((string)($body['chat_id'] ?? ''));
        if ($chatId === '') {
            return JsonResponse::error('INVALID_PARAM', 'chat_id is required', 400);
        }

        return JsonResponse::success('SENT', 'Test message dispatched');
    }
}

<?php
declare(strict_types=1);

use Module\Acme\TelegramNotifier\Controller\WebSettingsController;

return [
    'module-telegram-settings' => [WebSettingsController::class, 'index'],
];

<?php
declare(strict_types=1);

namespace Module\Acme\TelegramNotifier\Controller;

use Web\System\Core\Controller;

final class WebSettingsController extends Controller
{
    public function index(): void
    {
        $this->render(__DIR__ . '/../template/page/settings.php', [
            'title' => 'Настройки Telegram',
            'route' => 'module-telegram-settings',
        ]);
    }
}

"assets": {
  "css": [
    "web/assets/css/global-badge.css"
  ],
  "css_routes": {
    "task-detail": "web/assets/css/widget.css",
    "module-telegram-settings": "web/assets/css/settings.css"
  },
  "js_routes": {
    "task-detail": "web/assets/js/widget.js"
  }
}

CREATE TABLE IF NOT EXISTS `module_acme_telegram_queue` (
    `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
    `chat_id` VARCHAR(64) NOT NULL,
    `message_text` TEXT NOT NULL,
    `status` ENUM('pending', 'sent', 'failed') NOT NULL DEFAULT 'pending',
    `attempts` INT UNSIGNED NOT NULL DEFAULT 0,
    `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    `sent_at` DATETIME NULL,
    PRIMARY KEY (`id`),
    KEY `idx_status_created` (`status`, `created_at`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

DROP TABLE IF EXISTS `module_acme_telegram_queue`;

new ScheduledTask(
    moduleName: 'acme.telegram-notifier',
    taskName: 'telegram_queue_worker',
    schedule: '*/5 * * * *', // Каждые 5 минут
    handlerClass: QueueWorkerHandler::class,
    handlerMethod: 'run'
)

use Api\System\Library\Module\ModuleJobDispatcher;

$dispatcher = $container->get(ModuleJobDispatcher::class);
$jobId = $dispatcher->dispatch(
    moduleName: 'acme.telegram-notifier',
    jobName: 'send_telegram_http_message',
    payload: [
        'chat_id' => '-100123456789',
        'text' => 'Привет из транзакционной очереди!',
    ],
    delay: 10 // Задержка 10 секунд
);

private array $forbiddenFunctions = [
    'eval', 'exec', 'system', 'shell_exec', 'passthru',
    'popen', 'proc_open', 'pcntl_exec', 'assert',
    'create_function', 'include', 'file_put_contents',
    'unlink', 'rmdir', 'chmod', 'chown',
    'dl', 'ffi',
];

module-acme-telegram-1.0.0.zip
├── manifest.json
├── README.md
├── api/
└── web/

use Api\System\Library\Module\ModuleRemoteInstaller;

$installer = $container->get(ModuleRemoteInstaller::class);

// Установка по HTTPS URL:
$moduleName = $installer->installFromUrl(
    url: 'https://marketplace.tropatt.com/downloads/acme.telegram-notifier-1.0.0.zip',
    verifySignature: true
);

{
  "name": "acme.telegram-notifier",
  "version": "1.0.0",
  "vendor": "acme",
  "author": "Anton Barinov",
  "author_url": "https://github.com/Anton-Barinov",
  "title": "Telegram Notifier",
  "description": "Оповещения в Telegram-чаты при событиях задач TropaTT CRM",
  "category": "integration",
  "license": "MIT",
  "core_version": ">=1.0.0",
  "dependencies": [],
  "require_permissions": ["tasks.read"],
  "service_provider": "Module\\Acme\\TelegramNotifier\\TelegramNotifierServiceProvider",
  "api_routes": "api/config/routes.php",
  "web_routes": "web/config/routes.php",
  "migrations": "api/migrations/",
  "config_defaults": {
    "bot_token": "",
    "chat_id": ""
  },
  "positions": {
    "task.detail.sidebar": [
      {
        "renderer": "Module\\Acme\\TelegramNotifier\\Position\\TaskSidebarPanel::render",
        "priority": 15,
        "key": "telegram_panel"
      }
    ]
  },
  "hooks": {}
}

<?php
declare(strict_types=1);

namespace Module\Acme\TelegramNotifier;

use Api\System\Library\Container;
use Api\System\Library\Module\AbstractModuleServiceProvider;

final class TelegramNotifierServiceProvider extends AbstractModuleServiceProvider
{
    public function register(Container $container): void
    {
        // Регистрация сервисов
    }

    public function boot(Container $container): void
    {
        // Логика инициализации
    }
}