.. include:: <isonum.txt>

Интеграционные хранилища и операции (API v2)
============================================

В платформе Пересвет есть базовая поддержка исторических данных (historian) и
иерархической модели (LDAP). Для интеграции со “внешними” реляционными данными
(справочники, планы, календари и т.п.) добавлен механизм *интеграционных хранилищ*
и *операций*.

Ключевая идея: значения “интеграционного” тега берутся/пишутся не в
автоматически создаваемую таблицу historian, а через *параметризованный запрос*,
описанный в LDAP как операция.

Включение/выключение v2
-----------------------

Функциональность v2 является опциональной и может не запускаться в некоторых
сборках/конфигурациях.

- Для монолитного приложения ``one_app`` используется переменная окружения:

  - ``PRS_ENABLE_V2=1`` (или ``true/yes/on``) — включить v2 API и v2 model_crud.
  - если переменная не задана — работает только v1.

- Для MCP сервера ``mcp_peresvet``:

  - ``MCP_PERESVET_ENABLE_V2=1`` включает MCP-инструменты для ``/v2``.
  - если не задано — берётся значение ``PRS_ENABLE_V2``.

Тип хранилища integrational
---------------------------

Для ``prsDataStorage`` тип хранилища задаётся атрибутом:

- ``prsEntityTypeCode = 2`` — *integrational* (PostgreSQL).

Операции в LDAP
---------------

Под узлом конкретного хранилища данных (``<dataStorage>``) в LDAP хранится:

- ``cn=system``.
- Внутри ``cn=system`` узел ``cn=operations`` со списком операций.
- Для каждой операции есть узел ``cn=<operationCn>`` (``objectClass=prsDatastorageOperation``) с атрибутами:

  - ``prsEntityTypeCode``: ``0`` (GET) или ``1`` (SET).
  - ``prsJsonConfigString`` с JSON-свойствами операции:

    - ``query`` — текст запроса (строго параметризованный, ``:param``).
    - ``prsTimeOutMs`` — таймаут выполнения/вычислений.
    - ``prsMaxRows`` — лимит строк для GET.
    - ``prsVersion`` — версия операции.

  - Дочерние узлы параметров ``cn=<paramName>`` (``objectClass=prsDatastorageOperationParameter``), где:

    - ``prsJsonConfigString`` — JSON с настройками параметра (например ``required/default/type``).

Интеграционные теги
-------------------

Привязка тега к хранилищу описывается узлом ``prsDatastorageTagData`` под
``cn=system/cn=tags``.

Для интеграционного тега:

- ``prsEntityTypeCode = 2``
- в ``prsJsonConfigString`` указываются ссылки на операции и маппинг параметров:

.. code-block:: json

  {
    "get": {
      "operationCn": "oee.downtimeReasons.interval.v1",
      "params": {
        "start": "$.start",
        "finish": "$.finish"
      }
    },
    "set": {
      "operationCn": "oee.downtimeReasons.set.v1",
      "params": {
        "code": "$.point.y.code"
      }
    }
  }

JSONata выражения допускаются только **в значениях параметров**.

Контракт результата GET
-----------------------

GET-операция обязана возвращать колонки (или поля результата):

- ``y``, ``x``, ``q``

Сервис интеграционного хранилища преобразует результат в стандартный ответ
``data/get``:

.. code-block:: json

  {
    "data": [
      {
        "tagId": "<tagId>",
        "data": [["<y1>", "<x1>", "<q1>"], ["<y2>", "<x2>", "<q2>"]]
      }
    ]
  }

API v2 для dataStorages
-----------------------

В v2 добавлены поля для операций:

- ``operations`` в ``create/update``
- ``getLinkedOperations`` в ``read``
- ``unlinkOperations`` в ``update``

Эндпоинты:

- ``GET /v2/dataStorages`` — чтение (включая операции по флагу)
- ``POST /v2/dataStorages`` — создание (включая операции)
- ``PUT /v2/dataStorages`` — обновление (включая операции)

Примечание про GET-параметры
----------------------------

Начиная с текущей версии рекомендуется передавать параметры GET-запросов
как обычные query-параметры (``id``, ``base``, ``scope``, ``filter`` и т.д.),
а не через ``q=<json>``.