API: Функциональные модули

Только portal_admin. Базовый путь: /api/v1/modules.

См. также: Функциональные модули (.portalmod).

GET /modules

Список установленных модулей.

GET /api/v1/modules
Authorization: Bearer …

Ответ — массив объектов с полями moduleKey, version, title, installedAt, installedBy.

GET /modules/templates

Список шаблонов портала для wizard в админке (Helpdesk, Comms и др.).

GET /api/v1/modules/templates
Authorization: Bearer …

В каждом шаблоне — блок catalog со статусом korport.ru и числом доступных модулей (с учётом лицензии).

GET /modules/catalog/status

Статус каталога korport.ru и счётчики модулей по шаблонам.

GET /api/v1/modules/catalog/status
Authorization: Bearer …

POST /modules/install-template

Установка шаблона с korport.ru одной кнопкой (без загрузки файла).

POST /api/v1/modules/install-template
Content-Type: application/json
Authorization: Bearer …

{ "templateId": "helpdesk" }

templateId	Шаблон
helpdesk	Helpdesk (1 модуль: korport.helpdesk)
comms	Новости и объявления (3 модуля)

Платные модули каталога требуют entitlement в license token (modules в ключе). Бесплатные (demo.* / isFree) — всегда доступны. В режиме trial (kind=trial, обычно modules: ["*"]) платные модули каталога доступны для оценки. После активации ключа через Настройки → Продукт и лицензия или portal-cli license activate entitlement применяются сразу (без перезапуска API).

Продуктовые модули korport.* устанавливаются только с korport.ru при entitlement в license token. Ручная загрузка .portalmod для них заблокирована.

POST /modules/install

Установка или обновление модуля из ZIP-архива .portalmod.

POST /api/v1/modules/install?installDependencies=true
Content-Type: multipart/form-data
Authorization: Bearer …

package=@korport.helpdesk.portalmod

Параметр	Описание
installDependencies	true (по умолчанию) — auto-install зависимостей из requires

Зависимости ищутся в порядке:

1. Каталог deps/ внутри загружаемого ZIP
2. Локальный каталог MODULE_CATALOG_PATH (catalog.json + пакеты)
3. Удалённый MODULE_CATALOG_URL / RemoteCatalogUrl (опционально)

Ограничение	Значение
Максимальный размер	50 МБ
Формат	ZIP с module.json в корне

Ответ при успехе

{
  "moduleKey": "demo.tasks",
  "version": "1.0.0",
  "skipped": false,
  "upgraded": false,
  "resourceMap": {
    "nodes.tasks": "550e8400-e29b-41d4-a716-446655440000",
    "lists.tasks.id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
  },
  "log": [
    "Установлен пакет packages/ticket-portal.portalpart",
    "Создан узел helpdesk",
    "Создан список it-tickets"
  ],
  "dependenciesInstalled": []
}

Поле	Описание
skipped	true — модуль той же версии уже установлен, изменений нет
upgraded	true — обновление с более ранней версии
resourceMap	Карта символьных ключей → UUID созданных ресурсов
log	Журнал шагов установки

Ошибки

Код	Причина
409	Не выполнены зависимости из requires
400	Невалидный ZIP, отсутствует module.json, превышен размер
403	Нет роли portal_admin

GET /modules/{key}/resources

Карта ресурсов установленного модуля — для отладки и интеграций.

GET /api/v1/modules/demo.tasks/resources

{
  "moduleKey": "demo.tasks",
  "version": "1.0.0",
  "resourceMap": {
    "nodes.demo": "…",
    "nodes.tasks": "…",
    "lists.tasks.id": "…"
  },
  "installLog": ["…"]
}

Ключ {key} — значение id из module.json (напр. demo.tasks).

Установка через UI

Админка → Модули — загрузка файла .portalmod, просмотр журнала и установленных версий. Эквивалент POST /modules/install.

Зависимости между модулями

Если в module.json указано:

"requires": ["demo.address-book@>=1.0.0"]

API проверит наличие установленного модуля demo.address-book с подходящей версией до начала установки. Ресурсы зависимого модуля доступны в $ref как modules.demo.address-book.lists.employees.id.

Повторная установка и обновление

• Та же версия — ответ со skipped: true, ресурсы не пересоздаются.
• Новая версия — обновление записи модуля; если есть provisioner, вызывается UpgradeAsync(fromVersion).
• Откат версии через API не поддерживается — только установка более новой версии.