Пакет @morphcluster/carabi

Документация сервисов хоста PgDocuments

Обзор

ПХост PgDocuments предоставляет клиентские обёртки, хелперы и утилиты для работы с базой данных, документами, справочниками и миграциями.

Клиенты удалённых сервисов

Все клиенты предоставляют методы, соответствующие удалённым запросам:

• OraLongTransactions - клиент для упработы с двлинными транзакциями Oracle-адаптера. (см. хост Postgres).
• OraQueries - клиент для выполнения обычных (без транзакций) запросов в стиле Oracle.
• PgQueryPool - клиент для работы с прямым пулом PostgreSQL (если используется режим pg).
• Documents - низкоуровневая работа с информационными объектами (документами) бв систезме MorphCluster. Основная функциональность включалидацииет:
  и
  проверки
  • Управ.
  • DocumentLists - расширленныие запструктуросый стиписков документов с(DocKind) фильтрацией по статусам.
  • DockindStructure - работа со структурой информационных объектов (типы,— свойства, статусы, действия, права).

  ---

  Утилиты SQL

  SqlQuery

  Назначение: пдострупа

• Рабоениета сложных SQL-запросов программным способом. Поддерживает SELECT, FROM, JOIN, WHERE, ORDER BY, LIMIT/OFFSET.

  const q = new SqlQuery()
    .select(['u.id', 'u.name'])
    .from('users', 'u')
    .leftJoin('orders', 'o', new WhereCondition('simple', 'u.id = o.user_id'))
    .orderBy('u.name');
  
  const sql = q.build({ pretty: true });
  

  Подробнее в отдельном документе

  ами

  SqlModify

  Назначение: упрощает— создание запросов INSERT и UPDATE.

  const mod = new SqlModify('users');
  mod.set('name', 'varchar2', 'Alice');
  mod.set('age', 'number', 30);
  mod.setId('id', 'number', 123);
  const { sql, params } = mod.getUpdateQuery();
  

  Мечтоды:

  рт

  Метод	Описание
  set(column, type, value)	Задать значение, обновление, удаление Импорт/эксполонки
  setId(column, type, value)	Зметадатьнных и данных в XML/JSON Генерация и синхронизация таблиц документификатор записи
  getInsertQuery()	Возвращает {sql, params} для INSERT ... RETURNING
  getUpdateQuery()	Возвращает {sql, params} для UPDATE

  Параметры формируются в видеPostgreSQL

{ name, type, value }, совместимом с QueriesHelper.

Сервисы-помошники

QueriesHelper

универсальный сервис-помощник для в

• Выполнения запросов ке баизне данныхс-логики через функции и действия

Структура сервисов

Клиентыбр (ServiceNats)

Клиенты не описываются в данныой документадаптерции, (oraно они исполи pg). Являеьзуются псервисами для медпжсервисночтительным спгособом взаимодействия:

• Eventer — отправка событий, БД управление пользовательскими соединениями
• SysProcesses — управленикле фоновыми бизнес-процессадми

Основныхе сервисах.

Подробнее смотрите в отдельном разделе

ы

OLTHelper1. DockindStructure

УОтветственность: Упраревший, сейчас его замленил QueriesHelper. Класс-помощник для упрощённой работы с длинными транзакциями (OraLongTransactions).

Не является сервисом, это обычный класс, который нужно создавать вручную.

Конструктурой типов документов (DocKind): статусы, свойства, функции, действия, права доступа, правила именования.

new OLTHelper(oltServiceInstance, workspace, oltId?, log, options?)

const olt = new OLTHelper(this.OraLongTransactions, 'main', null, log, getInfo({ noUser: truedocKind });
await olt.execFunc('PKG_TEST.DO_SOMETHING', { param1: 1 });
const rows = await olt.fetch(olt.result, 100);
await olt.commit();

Ответственность: Низкоуровневая работа с документами — чтение/запись значение: представляет метаданные одного типай, информационногя о объекта (документа).е, Загпружается из БД човерезка CSP_DOCUMENTS.GET_DOCKIND_INFO и свобязанныте запросы.

Конструктор:

new DocumentKind(queriesHelper)

После создания нужно вызвать await docKind.load(log).

Основные свойства (после загрузки):

• name, id, description, tableName
• properties – массив DocProperty
• propEvents – массив DocEventProperty
• statuses – массив объектов {id, name, descr}

Методы:

• getTableName() – имя таблицы БД для этого типа.
• getPropFieldName(prop) – имя колонки для свойства.
• getUniqueProps() – массив уникальных свойств.

Класс DocProperty:

{
  id, name, fieldName, propKind,
  formatBase, formatLogic,
  object, multi, unique,
  fpath, SQL, rule, raw
}

Класс DocEventProperty:

{
  propId, statusId,
  writable, readable, notNull
}

Справочники

VocabsHelper

Назначение: сервис для загрузки и кэширования справочников.

Методы:

При первом запросе загружает справочник асинхронно, последующие вызовы возвращают уже загруженный экземпляр.

Vocab

Назначение: представляет один справочник (простейшая модель).

Конструктор: new Vocab(name, queriesHelper)

Методы:

• load(log) – загружает ID справочника по имени.

Свойства после загрузки: id, name, loaded = true.

Document

Назначение: представляет один экземпляр информационного объекта с кэшированием значений и отслеживанием изменений.

КЗависимонструктори: QueriesHelper, DockindCache

new Document(log, session, docKind, { Documents, QueriesHelper, trxId? })

Основные методы:

Пример:

const doc = new Document(log, session, dockind, { QueriesHelper: this.QueriesHelper, Documents: this.Documents, trxId });
doc.id = 123;
await doc.getValues(['Name', 'Age']);
await doc.setValues({ Name: 'Alice' }); // изменится, но не сохранено
await doc.setValues({ Age: 30 }, false); // ещё измененгие
await doc.commitValues(); // одно сохранение двух полей

DocumentsHelper

Назначение: высокоуровневый сервис для работы с документами. Создаёт документы в множественное ссылочное поле deleteRefs({ dockind, documentId, propName, values }) Удалить указанные ссылки из множественного ссылочного поля checkNull({ dockind, documentId }) Проверить, загружает их по ID, выполнены ли обязательные для текущего статуса поля

3. DocumentLists

Ответственность: пПоиск и выборка списков документов по значениям свойств.

МЗависимости: QueriesHelper, DockindCache, Documents

Основные методы:

4. DocumentFuncs

Ответственность: Выполнение бизнес-функций, привязанных к статурсам и свойствам документов.

Зависимости: QueriesHelper, DockindCache, Documents, GlobalServices, Eventer

Основные методы:

Поддерживаемые типы функций:

• DB — вызов хранимой процедуры PostgreSQL (формат schema.function)
• CSP — вызов метода удалённого сервиса (формат ServiceName.method)

5. DocCardValues

Ответственность: Высокоуровневая работа со значениями документов в контексте карточки (UI-транзакции).

Зависимости: QueriesHelper, DockindCache, Documents, DocumentFuncs, DocumentLists

Основные методы:

6. DocCardActions

Ответственность: Выполнение действий (переходов междующ статусами) с документами.

Зависимости: QueriesHelper, DockindCache, Documents, DocumentFuncs, DocCardValues, SysProcesses, DocumentLists

Основные методы:

Логика действия:

1. Проверка допустимости текущего статуса (FROM_STATUS_IDS)
2. (Опционально) Смена статуса на TO_STATUS_ID с вызовом pre-process функций
3. (Опционально) Вызов функции, привязанной к действию
4. Запуск post-process функций для нового статуса
5. Запуск глобальных (anykind) функций

7. DocTables

Ответственность: Генерация и синхронизация струзктур таблить списокц документов в PostgreSQL для быс фильтрого поиска и отчетов.

Зависимости: QueriesHelper, OraLongTransactions, DockindCache

Основные методы:

Архитектура таблиц:

• Основная таблица: →doc_tables.<dockind>_t DocumentKind— содержит single-свойства
• Дочерние таблицы: doc_tables.<dockind>_t_<prop> — для multi-свойств
• Представление: doc_tables.<dockind>_v — объединяет данные для удобного чтения

8. DockindImporter

Ответственность: Импорт метаданных из XML и JSON в базу данных.

Зависимости: DockindStructure, QueriesHelper, DocumentsHelper, OraLongTransactions

Основные методы:

Внутренние классы:

• XmlImporter — парсинг XML, создание/обновление словарей, типов, статусов, свойств, действий, имён, функций
• JsonImporter — аналогичный функционал для JSON (более современный формат)

Поддерживаемые сущности при импорте (JSON):

• Словари (vocabs)
• Типы документов (name, descr)
• Статусы (statuses с цветами, функциями, правами)
• Свойства (props с типом, мульти, уникальностью, статусными масками, ссылками, правами, функциями)
• Правила именования (names)
• Действия (actions с условиями, переходами, правами, функциями)
• Права доступа (permissions на уровне ролей)

9. DockindExporter

Ответственность: Экспорт метаданных типа документа в JSON.

Зависимости: DockindStructure, QueriesHelper, DocumentsHelper, OraLongTransactions

Основные методы:

Внутренний класс: JsonExporter

Экспортируемые данные:

• Основная информация (name, descr)
• Используемые словари (vocabs со значениями)
• Статусы (statuses с цветами, правами, функциями)
• Свойства (props с типами, параметрами, статусными масками, ссылками, правами, функциями)
• Правила именования (names)
• Действия (actions с условиями, переходами, правами, функциями)

10. DocDataImporter

Ответственность: Импорт данных документов из внешних источников (XML).

Зависимости: QueriesHelper, DocumentsHelper, DockindCache, Documents

Основные методы:

Логика импорта:

1. Парсинг XML, извлечение структуры документов
2. Для каждого документа:
   • Поиск существующего документа по ID эуникзеальнымпляра

     Параметры loadDocList:

     {
       props: ['Name', 'Age'],     // полям д(есля выборки filter: { Name: 'Alice' },  // фильтр
       statuses: ['Active'],       // огруказаны)

   • Еслич найден — применение правил слияния (добавление, перезапись, стирание)
   • Если не найден — создание нового документа
3. Заполнение свойств документа (включая ссылки на подчинённые документы)
4. Установка статуса