Самообслуживание (self-service) — каталоги и переопределения¶

Цель — администраторы и операторы могут добавлять новые облачные эндпойнты, площадки, исполнения шкафов и менять конфигурацию линии без правки кода и без перезапуска сервиса.

Связанные документы: ARCHITECTURE.ru.md §17, API_REFERENCE.ru.md, ROLLOUT.ru.md.

Архитектура self-service¶

┌──────────────────────┐                 ┌─────────────────────┐
│  Центральная консоль │◀──REST─────────▶│  Factory server     │
│  (management UI)     │                 │                     │
│                      │                 │  cloud_endpoints    │
│  /catalogs           │                 │  sites              │
│                      │                 │  line_variants      │
└──────────────────────┘                 └─────────────────────┘
          ▲                                        ▲
          │                                        │ GET  /catalog/*
          │                                        │ (публично)
          │                                        │
          │                                        │
          │                                 ┌──────────────┐
          │                                 │  Edge (L2)   │
          │                                 │              │
          │ PUT /config ──────────────────▶ │  Config      │
          └──────────────────────────────── │  overrides   │
                                            │  (config    ) │
                                            │              │
                                            │  Scanner /   │
                                            │  Printer /   │
                                            │  PLC managers│
                                            └──────────────┘

Три слоя конфигурации объединяются во время работы:

Базовый edge-service.yaml — shipping-defaults, читается при старте.
Переопределения в таблице config (префикс l2.override.) — всё, что админ / оператор изменил через REST.
Справочники с factory-server — общие для всех терминалов списки (облачные эндпойнты, площадки, исполнения).

Приоритет: справочник → переопределение → базовый файл (последний выигрывает для полей, которые заполнены явно в обоих слоях).

Справочники (каталоги)¶

Хранятся на factory-server в трёх таблицах, доступны по REST под префиксом /api/v1/catalog/.

Cloud endpoints (`cloud_endpoints`)¶

Поле	Назначение
`id`	snake_case id (`okto_prod`, `mars_dev_8`)
`displayName`	Английское имя
`displayNameRu`	Русское имя
`baseUrl`	`https://…/api/v1/`
`isProduction`	Маркер боевого окружения (красный бейдж в UI)
`description`	Свободная заметка для администраторов
`active`	Когда `false` — эндпойнт скрыт, но не удалён

Sites (`sites`)¶

Поле	Назначение
`code`	Короткий код (`LUZ`, `NOV`, `KAL` …)
`name` / `nameRu`	Человекочитаемые имена
`region`	Регион / страна
`timezone`	IANA (`Europe/Moscow`)
`factoryServerHost`	Хост локального factory-server на площадке
`contact`	Email / Slack канал для эскалаций
`active`	Скрывает площадку из выпадающих списков

Line variants (`line_variants`)¶

Поле	Назначение
`code`	`DRY`, `WET`, `HYBRID`, …
`requiresUps`	Требует ли исполнение ИБП
`requiresPlcCabinet`	Нужен ли шкаф управления
`colorHex`	Цвет для бейджа в консоли

REST API¶

Чтение (публично)¶

GET /api/v1/catalog/cloud-endpoints
GET /api/v1/catalog/sites
GET /api/v1/catalog/variants

Ответ: ApiResponse<CatalogListing<T>> с полями items[] и updatedAt.

Запись (роль `ADMIN` / `MANAGER`)¶

POST   /api/v1/catalog/cloud-endpoints
DELETE /api/v1/catalog/cloud-endpoints/{id}

POST   /api/v1/catalog/sites
DELETE /api/v1/catalog/sites/{code}

POST   /api/v1/catalog/variants
DELETE /api/v1/catalog/variants/{code}

POST идемпотентен: по id/code делает upsert. Валидация: - cloud_endpoints.id: ^[a-z0-9_\-]{2,64}$, baseUrl должен заканчиваться на /. - sites.code, line_variants.code: ^[A-Za-z0-9_\-]{2,16}$, при сохранении приводится к верхнему регистру.

Переопределения на edge¶

GET    /api/v1/config                  → текущие переопределения
PUT    /api/v1/config                  → { set: {…}, unset: [...], actor }
DELETE /api/v1/config                  → сбросить всё
POST   /api/v1/config/reload           → перечитать из БД и применить

Важные ключи (префикс l2.override. в БД):

Ключ	Тип / пример
`line.variant`	`DRY` / `WET` / custom
`line.site`	`LUZ`, `NOV` …
`line.plcVisualisationUrl`	`https://plc-ui.mars.local/`
`cloud.endpointId`	`mars_prod` — значение из `cloud_endpoints.id`
`scanners`	JSON-строка со списком `ScannerConfig[]`
`printers`	JSON-строка со списком `PrinterConfig[]`
`plcs`	JSON-строка со списком `PlcConfig[]`
`batchAccounting.enabled`	`true` / `false`

POST /api/v1/config/reload после обновления ключей scanners / printers / plcs немедленно переподключает драйверы без перезапуска JVM. Остальные ключи применяются при следующем старте.

UI¶

Центральная консоль → «Каталоги»¶

Новый раздел /catalogs (иконка книги в группе «Настройки»):

Облако — CRUD облачных эндпойнтов (mars_prod, okto_stage и т.д.).
Площадки — CRUD сайтов / фабрик.
Исполнения — CRUD вариантов шкафов (DRY, WET, HYBRID).

Сохранение идёт через POST /api/v1/catalog/…. Правки видны всем терминалам на следующем опросе (каждые 60 с) — без деплоя.

Терминал оператора → «Настройки L2 → Прочее»¶

Вкладка «Прочее» показывает три секции:

Параметры линии — выпадающие списки Исполнение, Площадка и поле URL визуализации ПЛК. Списки наполняются из справочников factory-server.
Облачная интеграция — выбор облачного эндпойнта из cloud_endpoints.
Переопределения конфигурации — таблица текущих ключей с возможностью удалить отдельный ключ, сбросить всё, или перечитать и применить.

Каждое изменение сразу уходит в PUT /api/v1/config, поэтому значение сохранится между перезапусками.

Playbook: добавить новую фабрику¶

Логин в Центральной консоли с ролью ADMIN.
/catalogs → вкладка Площадки → кнопка «Добавить площадку».
Заполнить:
code: 3-4 буквы, уникально (KAL, UFA …);
name / nameRu;
timezone: IANA;
factoryServerHost: hostname локального factory-server, если он есть; иначе оставить пустым (терминалы подключатся к облаку).
Нажать Сохранить.
На каждом новом шкафу: открыть терминал → «Настройки L2 → Прочее» → выбрать только что созданную площадку → «Перечитать». Значение сохранится в config (l2.override.line.site = KAL).
Через POST /api/v1/devices/{id}/config (центральная консоль) можно пушнуть тот же override на все устройства площадки разом.

Playbook: подключить новое облачное окружение¶

/catalogs → Облако → «Добавить».
Указать id (snake_case), baseUrl (обязательно с /api/v1/ в конце), isProduction.
После сохранения на терминалах в «Настройки L2 → Прочее» появится новый пункт в списке «Облачный эндпойнт». Выбор пишется в l2.override.cloud.endpointId.

Playbook: добавить новое исполнение (например, `HYBRID`)¶

/catalogs → Исполнения → «Добавить».
code = HYBRID, задать requiresUps / requiresPlcCabinet, цвет для бейджа.
После сохранения код появится:
в фильтрах парка устройств (центральная консоль);
в выпадающем списке «Исполнение шкафа» на терминалах (вкладка «Прочее»).

Playbook: сменить список сканеров на работающей линии¶

Открыть «Настройки L2 → Сканеры», отредактировать список, нажать «Сохранить».
PUT /api/v1/scanners на edge сразу же:
пересоздаёт ScannerManager с новыми настройками;
сохраняет JSON в config.l2.override.scanners — поэтому после перезагрузки терминала список останется прежним.
Если нужно «вернуться к заводским» — «Настройки L2 → Прочее → Сбросить всё»: переопределения удаляются, конфиг из edge-service.yaml снова становится источником истины.

Аудит¶

Все изменения через POST /api/v1/catalog/* пишутся в таблицу audit_log factory-server (actor, action, entity_type, entity_id, timestamp).
Все изменения через PUT /api/v1/config на edge логируются ConfigOverridesService (INFO: "Config override updated: key by actor") и попадают в журнал событий events при подключённом EventService с категорией SYSTEM.

Дата обновления: апрель 2026.