/**
# Расширения (Extensions)

Расширения представляют собой отдельные сервисы предоставляющие дополнительные возможности для пользователей. Сервис
может предоставлять несколько расширений одновременно.

Для координации взаимодействия используется сервис менеджер расширений (Extension Manager). Для предоставления своих функций в систему сервис должен
зарегистрироваться на контроллере.

*/
syntax = "proto3";

option go_package = "git.perx.ru/perxis/perxis-go/proto/extensions;extensions";

package extensions;

import "references/references.proto";

// Target - определяет как открывать результат выполнения действия в пользовательском интерфейсе
enum Target {
  DEFAULT = 0; // По умолчанию (если нет других условий, то MODAL)
  MODAL = 1; // Открывать в модальном окне
  WIDE = 2;  // Открывать в широком модальном окне
  MAIN = 4;  // Открывать в главной рабочей области (часть без меню)
  DRAWER = 5; // Открывать в боковой панели
  NOTIFICATION = 6; // Открывать виде всплывающего уведомлении
  BLANK = 7; // Открывать в новой вкладке
  NONE = 100; // Не отображать результат
}


/**
Action описывает как коллекцию в системе с предустановленными действиями, так и возможные дальнейшие действия после
получения ответа  (см. `ActionResponse.next`)

Если поле `request` присутствует, но не все требуемые поля заполнены, то значения для них берутся из текущих значений.

Коллекция: space_actions (Пространство/Действия)
Действия сохраненные в коллекции не содержат поля `request`. Значение заполняется текущими значениями.

Пользовательские действия добавляются при установке расширений или при
настройке в системную коллекции `Пространство/Действия` (system_actions). Расширения самостоятельно контролирует создание необходимых
им действий в коллекции.

Интерфейс загружает пользовательские действия и отображает их в интерфейсе соответствующим образом.
*/
message Action {
  // Kind описывает c какой сущность системы связано действие и что требуется передать в качестве параметров
  // Интерфейс загружает пользовательские действия и отображает их в интерфейсе в зависимости от ActionType.
  enum Kind {
    DEFAULT = 0; // Действие не отображается в интерфейсе и может использоваться для выполнения дополнительных запросов (см. `ActionResponse.next`) или напрямую из сторонних приложений.
    SPACE = 1; // Действие связано с пространством (требуется передача space_id). Отображается в меню "Действия".
    ENVIRONMENT = 2; // Действие связано с окружением (требуется передача space_id, env_id). Отображается в меню "Действия".
    COLLECTION = 3; // Действие связано с коллекцией (требуется передача space_id, env_id, collection_id). Отображается на экране списка записей.
    ITEM = 4; // Действие связано с записью (требуется передача space_id, env_id, collection_id, item_id). Отображается на экране редактирования записи.
    ITEMS = 5; // Действие связано с несколькими записями (требуется передача space_id, env_id, collection_id, item_ids). Отображается на экране списка записей.
    REVISION = 6; // Действие связано с ревизией записи (требуется передача space_id, env_id, collection_id, item_id, rev_id). На данный момент не используется.
    CREATE = 7; // Действие создание записи (требуется передача space_id, env_id, collection_id).
  }

  // DEPRECATED: Используйте `action` в формате URI
  string extension = 10000; // Расширение

  // Идентификатор действия (в формате URI)
  // Варианты использования:
  // - пустой - никаких действий не выполняется
  // - `action_id` - простое действие (если установлено значение `extension`, то оно используется)
  // - `grpc:///extension_id/action_id` - полное действие с указанием расширения
  // - `https://host/path` - действие по HTTP(S)
  // - `ui:///path` - действие в интерфейсе
  // - `/path` - действие в интерфейсе - DEPRECATED: Используйте `ui:///path`
  //
  // Пример: `https://example.com/api/v1/action` - будет выполнен запрос HTTP по указанному URL.
  // Сервер может вернуть ответ в формате JSON или HTML/MD. Дальнейшие действия определяется оп заголовку ответа
  // `Content-Type`:
  // - `application/json` - ответ в формате JSON. Структура ответа соответствует `ActionResponse` и интерпретируется
  // тем же способом что и ответ от GRPC.
  // - `text/html` - ответ в формате HTML. Интерфейс отображает ответ в виде сообщения в IFrame
  // - `text/markdown` - ответ в формате MD. Интерфейс отображает ответ в виде сообщения.
  //
  // Переменные `:var` заменяются на текуще значение в пользовательском интерфейсе
  // Перечень переменных для подстановки:
  // - :spaceId
  // - :envId
  // - :colId
  // - :itemId
  //
  // Пример: `ui:///spaces/:spaceId/envs/:envId/cols/:colId` - будет выполнено действие в интерфейсе.
  string action = 10100;
  Target target = 10110; // как должен отображаться результат действия
  string parent = 10120; // Идентификатор родительского действия (для отображения в меню)
  string name = 10200; // Название действия для отображения в интерфейсе (пункт меню, кнопка).
  string description = 10210; // Описание действия для отображения в интерфейсе
  string icon = 10220; // Название иконки для отображения действия в интерфейсе
  content.references.Reference image = 10230; // Изображение для отображения в действия в интерфейсе
  repeated string groups = 10240; // Группы отображения действия в интерфейсе
  Kind kind = 10300; // Указывает область действия (где отображается действие)
  repeated string classes = 10310; // Классы данных к которым применимо действие (название коллекций или специальных групп в рамках которых данное действие применимо)
  // Для `CREATE` действуют следующие правила:
  // - Для создание записей в коллекции применимы действия которые содержат в classes название коллекции
  // - Для создания записей в виджетах которые допускают создание записей (Block/BlockList) применимы действия которые содержат:
  //   - в classes хотя бы одно значение из classes виджета
  //   - если у виджета не указан classes, тогда названия коллекций которые могут быть использованы для создания элементов в поле (allowed_collections)
  repeated content.references.Reference refs = 10320; // Ссылки на записи используемые для выполнения действия (назначение ссылок зависит от действия и расширения)

  // Коллекция для сохранения параметрами действия. Если параметр указан, то при выполнении действия будет открываться
  // форма создания записи в указанной коллекции
  string params_collection = 10330;

  ActionRequest request = 10400; // Параметры запроса (используется в случае `ActionResponse.next`)

  // DEPRECATED: Используйте `action` вместо `navigation_route`
  bool navigation_action = 10500; // Флаг указывающий что действие переносить пользователя в другую часть интерфейса, а не отправляет запрос на сервер

  // navigation_route - Строка шаблон для перехода в интерфейсе
  // При указании полного адреса (http(s)://xyz), URL открывается в новом окне браузера
  // Относительный адрес в пользовательском интерфейсе переносит пользователя в соответствующий раздел без перезагрузки приложения
  //
  // Переменные `:var` заменяются на текуще значение в пользовательском интерфейсе (Пример: `/spaces/:spaceId/envs/:envId/cols/:colId`)
  // Перечень переменных для подстановки:
  // - :spaceId
  // - :envId
  // - :colId
  // - :itemId
  //
  // DEPRECATED: Используйте `action`
  string navigation_route = 10510;

  // Параметр указывающий что действие выполняется автоматически
  // Если указано, то действие выполняется автоматически каждый раз при загрузке приложения
  bool autorun = 10520;

  // Параметр указывающий что действие требует подтверждения пользователя
  // Перед выполнением действия пользователю отображается информация о действии и кнопки подтверждения/отмены
  bool confirm = 10530;

  enum View {
    DEFAULT_VIEW = 0; // Отображать в интерфейсе по умолчанию
    HIDDEN_VIEW = 1; // Не отображать в интерфейсе
    MAIN_MENU_VIEW = 2; // Отображать в главном меню
    MAIN_MENU_BOTTOM_VIEW = 3; // Отображать в главном меню внизу
  }

  View view = 10540; // Отображение действия в интерфейсе
  int32 order = 10550; // Порядок отображения действия в интерфейсе (Для пунктов меню)
}

// ActionRequest - запрос на выполнение действия к расширению (или менеджеру расширений)
message ActionRequest {
  string extension = 1000;
  string action = 10100;
  string space_id = 10500;
  string env_id = 10510;
  string collection_id = 10520;
  string item_id = 10530;
  repeated string item_ids = 10540;

  // Идентификатор локали в пространстве: поле может использоваться расширением, если действие возможно выполнить на разных локалях 
  string locale_id = 11050;

  // Поля к которым применимо действие. В случае если действие выполняется из списка записей, содержит перечень
  // полей которые пользователь выбрал для отображения в интерфейсе.
  repeated string fields = 10550;

  map<string,string> metadata = 11000;

  // Ссылки на записи используемые для выполнения действия (назначение ссылок зависит от действия и расширения)
  repeated content.references.Reference refs = 11010;

  // Ссылка на документ с параметрами выполнения Action.
  // Чтобы при выполнении действия открывалась форма параметров, необходимо указать `Action.params_collection`
  content.references.Reference params = 11020;

  // Параметры запроса пользователя
  message UserPreferences {
    string timezone = 1000; // Timezone в формате IANA. Пример: "Europe/Moscow", "America/New_York" https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
    string locale = 1020; // Текущая локаль пользователя в UI
    string theme = 1030; // Текущая тема пользователя в UI
    string agent = 1040; // Браузера или приложение пользователя
  }

  UserPreferences user = 11030;
}