Руководство пользователя и администратора

О документе

Документ предназначен для специалистов, которые впервые работают с Платформой А4: проектирование объектов данных, связей, статусных процессов и пользовательского интерфейса.

1. Назначение и область применения

Платформа А4 — комплекс программных компонентов для быстрого конструирования высокопроизводительных бизнес-приложений. Прикладной специалист задаёт шаблонные типы объектов, схемы данных (поля, типы, ограничения) и статусные переходы через интерфейс конфигурации, опираясь на общие паттерны платформы: получение и изменение данных, кэширование, индексация, журналирование.

Руководство описывает работу настройщика решения. Не входят: развёртывание ОС и СУБД, сетевая инфраструктура, выдача сертификатов — по отдельным регламентам организации.

2. Термины и сокращения

2.1. Словарь Zoo (условные имена сущностей)

Внутренние кодовые имена часто совпадают с короткими обозначениями Zoo. В типовом приложении на базе платформы (пример — репозиторий sdesk) разделы CMS сопоставлены с Zoo:

3. Доступ к платформе и роли

• Получите URL, учётную запись и способ входа у администратора.
• Уточните среду (разработка / тест / продуктив) и набор ролей (эксплуатация / проектирование).
• Для работы с метамоделью откройте раздел конструктора (имя зависит от поставки).
• Для операционной работы используйте клиентский фронтенд или технический интерфейс — по задаче.

4. Объекты данных и схемы

Каждый шаблонный тип объекта опирается на древовидную или иерархическую структуру связей в общем случае. Схема данных описывает поля: типы, свойства, ограничения; всё задаётся через интерфейс. Новое свойство можно добавить без миграции классической реляционной схемы, если платформа хранит часть атрибутов в JSON или вычисляет их динамически; при необходимости поля индексируются в СУБД или кэшируются на бэкенде для производительности.

4.1. Практические шаги настройщика

1. Создайте или выберите шаблонный тип объекта (предметная сущность).
2. Опишите схему данных: системные имена полей, типы, обязательность, значения по умолчанию.
3. Укажите способ хранения чувствительных к нагрузке полей (колонка / JSON / вычисление) по рекомендации архитектора.
4. Включите индексацию для полей, участвующих в поиске и фильтрации.
5. Проверьте валидацию и тестовые выборки во встроенном техническом интерфейсе.

5. Связи между объектами

Связи выражают принадлежность и иерархию: родитель–потомок, ссылки на справочники, при необходимости — дополнительные таблицы связей. В предметных моделях вроде УМБ-АСТК встречаются связи категорий вещей, вещей с местами и организациями, исполнителей друг с другом; при проектировании важно избегать циклов в графе и договариваться о каскадном поведении при удалении.

1. Зафиксируйте кардинальность и направление связи на диаграмме.
2. Создайте связь в конструкторе; для многие-ко-многим предусмотрите связующую сущность, если платформа требует.
3. Настройте отображение на формах (вложенные списки, подбор из справочника).
4. Проверьте сценарии удаления и переноса записей.

6. Статусная модель и процессы

Встроенная статусная модель задаёт допустимые переходы между состояниями объекта, действие, которое выполняет переход, и атрибуты действий. На её основе описываются бизнес-процессы жизненного цикла записей (согласования, этапы исполнения, отмена). В примере УМБ-АСТК у плана заказов используется шкала статусов (черновик, согласование, утверждение, выполнение и т.д.) — перенесите аналогичную логику в свою предметную область.

6.1. Минимальный чек-лист процесса

• Начальное состояние и событие создания записи.
• Промежуточные статусы и роли, которые могут инициировать переход.
• Условия перехода (по полям записи или внешним признакам).
• Финальные статусы; обработка отката или корзины — по бизнес-правилам.

7. Интерфейсы: технический и клиентский фронтенд

Технический фронтенд платформы предназначен для быстрой работы с объектами шаблонных типов: поиск, редактирование, просмотр свойств и связей — удобнее, чем прямой доступ к БД, и пригоден для продуктовой поддержки со стороны бэкенда. Клиентский фронтенд на Angular собирает пользовательские экраны из настроенных компонентов; он ориентирован на легковесность и работу на слабых рабочих местах.

• Для отладки модели и данных используйте технический интерфейс.
• Для конечных пользователей настройте клиентские формы, списки и навигацию.
• Согласуйте видимость полей и кнопок с ролями и статусами процесса.

8. API, интеграции и опциональные сервисы

На основе схем данных платформа формирует готовый API для объектов шаблонных типов; при необходимости добавляются произвольные эндпоинты и обогащение ответов. По заявленным характеристикам типовые задержки — порядка единиц–десятков миллисекунд для тяжёлых запросов (фактические цифры зависят от стенда и нагрузки).

Интеграции: библиотеки для MySQL, PostgreSQL, MSSQL; очистка и пакетирование данных; логирование и режим отладки; ML-модуль для нечёткого сопоставления записей при перекрёстных интеграциях с несколькими мастер-системами.

8.1. Опциональные компоненты

• Мессенджеры: e-mail, Telegram-бот в закрытом контуре.
• CDN для писем, документов и изображений.
• Модуль GPT / AI-ассистенты.
• BI и работа с большими объёмами данных (порядка ~1 ТБ по описанию платформы).

9. Практические сценарии

9.1. Категория вещи и экземпляр

1. Опишите иерархию категорий вещей (справочник понятий: класс → тип → модель).
2. Задайте набор свойств для категории (единицы измерения, внешние идентификаторы и т.д.).
3. Создайте экземпляр вещи с количеством и связями (принадлежность месту, организации, составная часть другой вещи).
4. Проверьте выборку дерева категорий и фильтрацию вещей в списке.

9.2. Заказ, задание и план

1. Введите минимальный квант работы — задание (что сделать и с чем связано).
2. Соберите заказ из заданий; назначьте исполнителя, срок и место выполнения.
3. Сформируйте план как список заказов с привязкой к структуре (филиал, объекты и т.п.).
4. Настройте статусную линейку плана (черновик → согласование → утверждение → выполнение).

9.3. Исполнители и доступ пользователей

1. Опишите типы исполнителей (юрлицо, филиал, бригада, мастер и т.д.) и иерархию линков.
2. Создайте пользователей системы; отделите учётную запись от физического исполнителя, если исполнитель не входит в систему.
3. Назначьте роли, уровни ролей и зоны ответственности (доступные исполнители).
4. Проверьте матрицу доступа на тестовых учётных записях.

10. Частые вопросы и типовые ошибки

11. Приложения

11.1. История версий документа

Приложение А. Фрагмент структуры «УМБ-АСТК» (пример)

Структура сущностей и БД А4.

1. Задачи

Задание (task) или операция — что (task.job) с чем (task.thing) нужно сделать, минимальный квант дела.

Заказ (order) — набор заданий, с указанием в т.ч. кому (order.assignee), когда (order.deadline) и где (order.place) делать.

Возможно, вместо отдельных task и order можно сделать древовидную структуру задач, задачи-подзадачи, где у каждой задачи есть parent_id, и это позволит не заводить по большей части дублирующих друг друга отдельных task и order.

Тип работ (task_job_types) — {ТО-1, ТО-2, ТО-3, Аварийная заявка, ТО АСУПГ, Монтаж АСУПГ}.

По факту в АСТК все задания в заказе всегда одного типа. На будущее можем предусмотреть и типы tasks. Но пока в заказе все задания имеют один тип работ, и сам заказ имеет тот же тип работ.

План (plan) — список заказов. Имеет привязку к структуре (филиалу, РЭС и т.д.).

plan_status = {-10=корзина, 0=черновик, 10=на согласовании, 20=на утверждении, 30=утверждён, 90=выполнен}

Тип плана (plan_type) — СТК ГРП, ТО АСУПГ и т.д.

Нормативы (norms) — список нормативов (нормативное время выполнения работ, ч; нормативное время до объекта выполнения работ, ч).

Значения нормативов по типам работ (norm_values) — … Также значения нормативов могут прописываться в свойствах категорий, структур и пр.

2. Вещи

Вещь (thing, или asset) — ТМЦ, перемещаемая. Это инструменты, датчики, материалы, расходники.

2.1. Категории вещей

Категории вещей (thing_categories, cat) — полудревовидная структура информационных понятий (а не реальных вещей):

Пример: СИ, манометры технические, датчик давления, ДМ1-0,6Мпа-1,5.

Свойства категорий вещей (thing_cat_props) — дополнительные поля для категорий вещей: code, title, format (внешний айди в системе А3; тип давления, единица измерения давления, точность измерения давления).

format = {int, float, string, list}, для list берётся из справочника.

Списки свойств категорий вещей (thing_cat_prop_lists) — словари, списки значений для некоторых свойств вещей: prop_code, value, sort (тип давления = {высокое, среднее, низкое}, единица измерения давления = {кПа, МПа}).

Свойства конкретных категорий вещей (thing_cat_prop_links) — набор свойств, которые имеют вещи из данной категории: cat_id, prop_code (датчик давления = {тип давления, единица измерения давления, точность измерения давления}).

cat_id = "*" здесь будет означать свойства для всех категорий. Тут нужно понять, потребуется ли более сложное наследование списков свойств, например, не для всех вещей, а для каких-то надкатегорий. Можно явно прописывать в категории особого «парента» prop_model — категорию, из которой данная категория будет брать набор свойств. Иначе у каждой модели каждого датчика придётся прописывать список свойств отдельно.

Значения свойств категорий вещей (thing_cat_prop_values) — значения доп. полей для конкретных категорий вещей:

Типы категорий вещей (thing_cat_types) — линейный короткий список, задающий крупномасштабные сегменты категорий. Например: {инструменты, материалы, устройства}.

Уровни категорий вещей (cat_levels) — иерархический список подсегментов категорий, например: {класс, тип, модель}.

slug — транслитерированный в url-пригодный формат name, для user-friendly url. Unique key.

status — status<0 означает удаление. status=-3175 означает, что данная категория удалена, и все запросы к ней следует переадресовать к категории id=3175. status=0 (default) означает, что категория ещё не активирована — например, только что создана и ещё редактируется. status>0 — активная категория; смысл конкретных положительных значений status, если потребуется, можно придумать в процессе создания бизнес-логики.

parent_id — главный парент данной категории. Для неглавных есть таблица линков. Главный нужен для быстрых выборок, когда нам нужно извлечь древовидную структуру, а не детали всех возможных взаимосвязей. Это денормализует структуру, но обеспечивает гибкость при сохранении скорости и удобства древовидности.

Заметка про денормализации (не только эту, но и другие). Консистентность денормализации (одновременная запись линков и parent_id) обеспечивается двумя механиками: логикой сохранения категории и логикой редактирования линков (с обёртками в transaction-rollback), а также, для гарантии, дополнительным скриптом, запускаемым по крону. Также можно сделать триггеры, но это обычно overkill.

Связи категорий вещей (thing_cat_links) — иерархический (parent-child, без siblings) список связей: parent_id, child_id.

Типы связей категорий вещей (thing_cat_link_types) — …

Примеры работы с простыми линками: все потомки (здесь lower = child, upper = parent); все родители, с уровнями отдалённости (lvl). Рисунки — см. исходный документ в репозитории.

Здесь важно, что, несмотря на иерархичность, граф не защищён от внутренних циклов, поэтому вместо рекурсии нужно использовать ограниченный цикл (в данном случае до 100).

2.2. Сами вещи

Вещи (things) — реальные материальные вещи.

Свойства вещей (thing_props) — дополнительные поля для вещей (серийный номер, внешний ID в такой-то системе).

Значения свойств вещей (thing_prop_values) — значения доп. полей для конкретных вещей:

Связи вещей (thing_links) — вещь может принадлежать:

• другой вещи (part_of) — когда она в неё устанавливается, является её частью;
• месту (at_place) — когда находится на этом месте (склад, установка, виртуальный склад) (частичная денормализация, т.к. место иногда можно определить по паренту);
• организации (owned_by).

Поля: entype, entid, link_type.

Типы линков вещей (thing_link_types) — part_of, at_place, owned_by, юридическая принадлежность, финансовая, физическая, транспортировочная и т.д.

Количество/объём (amount) — для недискретных вещей (например, какой-то материал — краска, песок и т.д.) указываем объём. Для целей АСТК, где речь про штучные девайсы, все amount=1. Но на будущее имеем в виду, что в целом бывают и количества, и единицы измерения, и дробление/слияние вещей.

3. Люди

Те, кто выполняет работу: мастера, бригады, организации.

3.1. Структуры

Провайдеры/исполнители (isps) — любые функциональные структуры, кто выполняет какие-либо работы: бригады, филиалы, мастера и т.д.

Типы исполнителей (isp_types) — юрлицо, филиал, РЭС, бригада, рабочий, водитель и т.д. Тип исполнителя определяет бизнес-логику.

Линки исполнителей (isp_links) — принадлежность (человека бригаде, РЭС филиалу).

Типы линков исполнителей (isp_link_types) — …

3.2. Пользователи

Пользователи не обязательно исполнители (например, админы системы). А исполнители не обязательно пользователи (рядовые рабочие бригады могут не иметь доступа в систему).

Пользователи (users) — пользователи системы, имеют в неё доступ. Действия в системе осуществляются от имени пользователя. Авторизуется пользователь. Поля: isp_id, login, psw.

Роли пользователей (user_roles) — бригадир, координатор, администратор и т.д.

Уровни ролей пользователей (user_role_levels) — стажёр, обычный, старший, главный.

Зоны ответственности пользователей (user_isp_zones) — перечень isp, доступных пользователю.

Роли + уровни + зоны позволяют задавать матрицу доступов, достаточную для 99% задач.

3.3. Клиенты

…

4. Места

Места (places) — склады, офисы, стационарные объекты инфраструктуры и пр. В том числе «рабочее место» (объект работ) — объект, на котором могут проводиться работы, туда выезжают бригады.