Хост PgDocuments

Обзор

Хост PgDocuments предоставляет набор сервисов для управления информационными объектами (документами) в системе MorphCluster. Основная функциональность включает:

• Управление структурой типов документов (DocKind) — свойства, статусы, действия, права доступа
• Работа с документами — создание, чтение, обновление, удаление
• Импорт/экспорт метаданных и данных в XML/JSON
• Генерация и синхронизация таблиц документов в PostgreSQL
• Выполнение бизнес-логики через функции и действия

---

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

Клиенты (ServiceNats)

Клиенты не описываются в данной документации, но они используются сервисами для межсервисного взаимодействия:

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

---

Основные сервисы

1. DockindStructure

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

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

События:

• onChanged — генерируется при любом изменении структуры типа документа

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

Метод	Описание
getInfo({ docKind })	Получить базовую информацию о типе документа (ID, описание)
setMain({ oldDocKind, newDocKind, description, parentId })	Обновить основную информацию (только описание и родительскую папку)
getStatuses({ docKind, docKindId })	Получить список статусов (событий) типа документа
setStatuses({ docKind, deleteIds, statuses, newOrder })	Обновить статусы: удалить, изменить, добавить, переупорядочить
getProps({ docKind, docKindId })	Получить список свойств типа документа
setProps({ docKind, props, deleteIds })	Обновить свойства: удалить, изменить, добавить
setProperty({ docKindId, property })	Внутренний метод для сохранения одного свойства с его статусными масками и ссылками
getFunctions({ docKind, docKindId })	Получить функции, привязанные к типу документа
setFunctions({ docKind, funcs, deleteIds })	Обновить функции (DB или CSP) с их привязкой к статусам и свойствам
setActions({ docKind, deleteIds, actions })	Обновить действия (переходы между статусами)
setNames({ docKind, names })	Обновить правила именования документов
setPermissions({ docKind, roles, deleteRoleIds })	Установить права доступа для ролей (создание, видимость/редактирование статусов и свойств)
getIdByName({ docKind })	Получить ID типа документа по имени
getNameById({ docKindId })	Получить имя типа документа по ID
updateDockindNames({ dockindId })	Отложенное обновление описаний всех документов типа
createDbFunction({ schema, name })	Создать пустую PL/pgSQL-функцию, если она не существует

---

2. Documents

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

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

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

Метод	Описание
getInfo({ documentId })	Получить основную информацию о документе (тип, статус, дата, создатель)
getDescr({ documentId })	Получить описание документа (сгенерированное по правилам именования)
getValues({ dockind, documentId, propNames })	Получить значения указанных свойств документа (поддерживает простые и ссылочные поля)
setValues({ dockind, documentId, values })	Установить значения свойств документа в рамках транзакции
insertRefs({ dockind, documentId, propName, values })	Добавить ссылки на другие документы в множественное ссылочное поле
deleteRefs({ dockind, documentId, propName, values })	Удалить указанные ссылки из множественного ссылочного поля
checkNull({ dockind, documentId })	Проверить, заполнены ли обязательные для текущего статуса поля

---

3. DocumentLists

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

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

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

Метод	Описание
listIdByProps({ dockind, values, statuses, notStatuses, count })	Найти ID документов по значениям свойств (AND-условия)
listPropsByProps({ dockind, props, filter, statuses, notStatuses, count })	Выбрать документы с указанными полями для вывода
listByUniqueFields({ dockind, values })	Найти документы по уникальным полям (автоматически определяются по конфигурации)
getUniqueCollisions({ dockind, documentId })	Найти документы с конфликтами по уникальным полям (исключая переданный ID)

---

4. DocumentFuncs

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

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

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

Метод	Описание
processStatus({ dockind, documentId, statusName, params, session, postprocess })	Выполнить все функции, привязанные к указанному статусу (pre- или post-process)
processProperty({ dockind, documentId, propName, session })	Выполнить функции, привязанные к изменению свойства
processAnykindFuncs({ dockind, documentId, params, session })	Выполнить глобальные (anykind) функции для документа
runFunc({ func, dockind, documentId, params, session, trxId })	Выполнить конкретную функцию (DB или CSP)

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

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

---

5. DocCardValues

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

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

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

Метод	Описание
getValDisplay({ documentId, propName })	Получить отображаемое значение поля (например, имя справочника вместо ID)
getValues({ documentId, propName })	Получить массив значений простого поля
setValues({ cardId, documentId, propName, value/values })	Установить значения простого поля в рамках карточной транзакции
getRefs({ documentId, propName })	Получить список связанных документов для ссылочного поля
setRefs({ cardId, documentId, propName, refDocumentIds })	Заменить весь список связанных документов
clearRefs({ cardId, documentId, propName })	Очистить ссылочное поле
insertRefs({ cardId, documentId, propName, refDocumentIds })	Добавить ссылки в множественное поле
deleteRefs({ cardId, documentId, propName, refDocumentIds })	Удалить указанные ссылки
createRefDoc({ cardId, documentId, propName, parentId })	Создать новый документ, привязанный к ссылочному полю
deleteRefDocs({ cardId, documentId, propName, refDocumentIds })	Удалить связанные документы (полное удаление)
commit({ cardId })	Зафиксировать транзакцию карточки (проверка обязательных полей и уникальности)
rollback({ cardId })	Откатить транзакцию карточки

---

6. DocCardActions

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

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

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

Метод	Описание
runActions({ dockind, documentIds, actionId, actParams, cardId, session })	Выполнить действие над одним или несколькими документами
runAction({ dockind, documentId, action, actParams, cardId, session })	Внутренний метод выполнения одного действия (проверка статуса, смена статуса, вызов функций)
runGlobalAction({ action, actParams, cardId, session })	Выполнить глобальное действие (без привязки к документу)
create({ dockind, parentId, classifPropId, classifId, session })	Создать новый документ с опциональным родителем и классификатором
deleteDocs({ dockind, documentIds, session })	Пометить документы как удалённые и запустить фоновую очистку
processDelete({ dockind, documentId, session })	Отложенная постобработка удаления (вызов функций статуса "deleted", физическое удаление)

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

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

---

7. DocTables

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

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

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

Метод	Описание
recreate({ docKind })	Полностью пересоздать таблицу, представление и процедуру синхронизации для типа, затем синхронизировать все данные
recreateStruct({ docKind })	Пересоздать только структуру таблицы (без представления и данных)
recreateView({ docKind })	Пересоздать представление для типа документа (объединяет основную таблицу и словари)
recreateAll({})	Пересоздать структуры для всех типов документов (последовательно)
createSyncProcedure({ dockind })	Сгенерировать PL/pgSQL-процедуру синхронизации для типа
documentSync({ docKind, documentId })	Синхронизировать один документ с его таблицей
documentSyncKind({ docKind })	Синхронизировать все документы указанного типа (пакетная обработка)

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

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

---

8. DockindImporter

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

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

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

Метод	Описание
importXml({ root, vocabs, types })	Импорт структуры из XML (словари + типы документов)
importJson({ root, data })	Импорт структуры из JSON

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

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

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

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

---

9. DockindExporter

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

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

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

Метод	Описание
exportJson({ dockind })	Экспортировать полную структуру типа документа в JSON

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

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

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

---

10. DocDataImporter

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

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

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

Метод	Описание
importXml({ dataXml, uniqueProps })	Импортировать данные документов из XML

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

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

Правила слияния:

• 0 — значение не меняется
• 2 — добавление новых значений в множество
• 3 — перезапись значения
• 4 — стирание значения

---

Вспомогательные модули

db-functions.mjs

Содержит определения SQL-функций для csp_documents (схема CSP-документов). Эти функции используются сервисами для работы с базой данных:

• get_all_dockinds — получить все типы документов
• get_document_info — получить информацию о документе
• get_dockind_id_by_name / get_dockind_name_by_id — преобразование ID/имени
• get_dockind_props — свойства типа документа
• get_dockind_prop_events — статусные маски свойств
• get_document_values / get_document_refs — чтение значений и ссылок
• и другие

DocFunctionsInstaller

Наследуется от DbFunctionsInstaller и устанавливает функции из db-functions.mjs при старте сервиса.