Skip to content

Self-service — catalogs and runtime overrides

Goal: operators and administrators can add new cloud endpoints, sites / factories, cabinet variants, and adjust line parameters without code changes and without a service restart.

Related docs: ARCHITECTURE.ru.md §17, API_REFERENCE.md, ROLLOUT.md.

Architecture

Three configuration layers merge at runtime:

  1. Base edge-service.yaml — shipping defaults, read once at start.
  2. Overrides in the config table with prefix l2.override. — everything the admin / operator changes over REST.
  3. Catalogs hosted on the factory server — fleet-wide lists of cloud endpoints, sites and cabinet variants.

Precedence: base YAML → runtime overrides → explicit catalog selection. The last step wins for fields set on both sides.

Factory-side catalogs

Hosted on the factory server, exposed as three REST resources under /api/v1/catalog/.

Resource Key fields
cloud-endpoints id (snake_case), displayName/displayNameRu, baseUrl (ends /), isProduction, active
sites code (2-16 chars, uppercased), name/nameRu, region, timezone, factoryServerHost, contact, active
variants code, name/nameRu, requiresUps, requiresPlcCabinet, colorHex, active

Reads are public so edge devices can populate dropdowns without credentials. Writes require the ADMIN or MANAGER JWT role.

REST

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

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

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

Validation:

  • cloud_endpoints.id matches ^[a-z0-9_\-]{2,64}$.
  • baseUrl starts with http(s):// and ends with /.
  • sites.code and line_variants.code match ^[A-Za-z0-9_\-]{2,16}$.

Edge-side runtime overrides

Stored in the existing config table under keys prefixed l2.override.. Served by ConfigOverridesService.

GET    /api/v1/config                  # snapshot of current overrides
PUT    /api/v1/config                  # { set: {…}, unset: [...], actor }
DELETE /api/v1/config                  # drop all overrides
POST   /api/v1/config/reload           # re-read DB, re-apply drivers

Key convention:

Key Value
line.variant Variant code (DRY / WET / custom)
line.site Site code
line.plcVisualisationUrl Iframe URL for the PLC HMI
cloud.endpointId A cloud_endpoints.id
scanners JSON array of ScannerConfig
printers JSON array of PrinterConfig
plcs JSON array of PlcConfig
batchAccounting.enabled true / false

POST /config/reload after updating scanners / printers / plcs atomically rebuilds the corresponding managers without restarting the JVM. All other keys take effect on the next boot.

Device metadata catalog

/api/v1/catalog/scanners, /catalog/printers, /catalog/plc-protocols expose the per-model parameter schema so the UI can render typed forms dynamically. Adding a new printer driver requires nothing but a new entry in DeviceCatalogService — no frontend change is needed.

UI

Management dashboard — Catalogs

New /catalogs page under the Settings navigation group. Three tabs:

  • Cloud — CRUD cloud endpoints (picker fallback for all terminals).
  • Sites — CRUD sites / factories.
  • Variants — CRUD cabinet variants (DRY / WET / HYBRID / …).

Changes propagate to every terminal on its next poll (60s by default).

Operator terminal — L2 Settings → Other

Three sections inside the "Other" tab:

  1. Line parameters — Cabinet variant and Site dropdowns populated from the factory catalogs, plus PLC visualisation URL text input.
  2. Cloud integration — cloud endpoint picker from cloud_endpoints.
  3. Configuration overrides — live table of every l2.override.* key in the config table, with per-key delete, Reload, and Clear all buttons.

Edits are sent to PUT /api/v1/config as soon as an input loses focus, so values survive restarts automatically.

Playbooks

Onboard a new factory

  1. Sign in to the management dashboard with the ADMIN role.
  2. Catalogs → Sites → Add site.
  3. Fill code, name, nameRu, timezone, factoryServerHost (optional).
  4. Save.
  5. On each cabinet at the new site: Terminal → L2 Settings → Other → Site → pick the code → click Reload. The choice is persisted in l2.override.line.site.
  6. Optionally mass-push the override via POST /api/v1/devices/{id}/config.

Add a new cloud environment (e.g. a staging subdomain)

  1. Catalogs → Cloud → Add with a unique id, baseUrl ending in /api/v1/, and isProduction flag.
  2. Pickers on every terminal refresh automatically.

Introduce a new cabinet variant (e.g. HYBRID)

  1. Catalogs → Variants → Add, set requiresUps / requiresPlcCabinet.
  2. Fleet filters and the terminal's variant dropdown will show it.

Change the scanner list on a live line

  1. Terminal → L2 Settings → Scanners, edit rows, Save.
  2. PUT /api/v1/scanners rebuilds the ScannerManager on the spot and persists the whole list to l2.override.scanners — so the change survives a reboot.
  3. To reset to the YAML defaults: L2 Settings → Other → Clear all.

Audit trail

  • Catalog mutations are recorded in the factory server audit_log table (actor, action, entity_type, entity_id, timestamp).
  • Edge-side override updates are logged by ConfigOverridesService at INFO level (Config override updated: <key> by <actor>) and forwarded to the events journal (SYSTEM category) when EventService is wired.

Last updated: April 2026.