Integration Package Overview

@vef-framework-react/integration (v2.10.0, first released with framework v2.12.0 on 2026‑07‑17) is the frontend console for the VEF server's integration engine — the subsystem that talks to external vendor systems through scripted adapters behind stable, schema-validated contracts.

When to Use

• Your VEF server runs the integration engine and you want its full management UI — including the script debugging console — by mounting six components on routes.
• You are building integration-adjacent screens (e.g. a business page that picks a contract) and want the typed API hooks (useContractApi, useOpsApi, …), directories (useSystemDirectory, useContractDirectory), and presentation components instead of raw RPC calls.

Domain model

The engine's domains map one-to-one onto the package's permission groups and pages:

Domain	Resource	What it is	Page
Contract	integration/contract	A standard operation: input/output JSON Schemas every provider adapter must honor	IntegrationContractPage
System	integration/system	One external system instance: base URL, outbound/inbound auth, optional direct data source, envelope scripts, retry policy	IntegrationSystemPage
Adapter	integration/adapter	One system-to-contract binding in one direction: a script translating between the system's wire format and the contract's models	IntegrationAdapterPage
Route	integration/route	A rule mapping a route key (tenant, branch, hospital area) to the system serving a contract	IntegrationRoutePage
Code map	integration/code_map (+ integration/code_set catalog)	Per-system bidirectional value translation of one code set between the canonical model and the external system's coding	IntegrationCodeMapPage
Log	integration/log	The recorded invocations with masked, size-capped captures	Console → 调用日志
Ops	integration/ops (+ sys/monitor stats)	Dry runs, connection probes, routing diagnosis, per-node statistics	IntegrationConsolePage

An outbound call flows host → contract → route → system → adapter script → vendor; an inbound delivery flows vendor → system (inbound auth) → adapter script → dispatch → business handler.

:::info Unreleased: the code-map domain The whole code-map domain — IntegrationCodeMapPage, useCodeMapApi, useCodeSetApi, the codeMap permission group, and the codes.* script completions — was added after v2.12.0 (commits b403919, 6ec1938) and ships with the next release. Everything else on this page is released. :::

The console workbench design

The v2.12.0 cycle redesigned all integration pages around a console workbench layout (commits bdcd65f, b0cb7b1; the approval package adopted the same pattern in 17830fd):

• Full-height screens, inner scrolling. Pages fill the viewport; panels split the remaining height and scroll internally (tables scroll their own body; the dry-run request/result cards are side-by-side grid cells that stack in narrow viewports). Tabbed consoles use FlexTabs so each pane owns its height.
• Drawer forms with top labels. Create/update forms open as wide drawers (responsive widths, 100vw on the smallest breakpoint) with vertical label layout — standalone inputs wrapped in the shared Labeled component — grouped into titled sections (FormSection) whose header switch alone tells which optional capabilities a record has.

Editor niceties

Several editing surfaces carry engine-aware assistance:

• Script completions mirrored from the runtime (c56d318, aligned in 094a9c6). Every script editor (adapter scripts, envelope request/response scripts, outbound/inbound auth scripts, the dry-run console) offers completions for exactly the bindings and capability libraries the Go runtime installs on that surface — input, request, system, http, sql, codes, dispatch, errors, plus the engine baseline (console, crypto, cache, dayjs, BigNumber, fxp, radashi, z, URL, URLSearchParams). The catalogs live in ScriptDoc constants you can reuse in your own editors.
• Hoverable script docs (ef47059). Each script field's label carries a help icon (ScriptDocLabel); hovering opens the surface's contract summary and full binding/library listing — rendered from the same completion catalog, so the popover and the autocomplete can never drift apart.
• Scheme-aware auth parameter editor (ac4f860). A system's outbound/inbound auth form renders dedicated inputs for schemes with a fixed parameter set (http_basic username/password, bearer token, signature app id/secret, inbound ip whitelist), a free name→value pair list only where parameter names are user-defined (header, query, script, unknown custom schemes), and nothing for none. Sensitive values are stored encrypted and masked back as ****** — resubmitting the mask keeps the stored secret. Switching schemes prunes parameters left over from the previous scheme (67dfda1).
• Contract labels (a261401, 8314fbc). Contracts carry host-owned labels (edited inline with the shared LabelsEditor, validated inline), the contract list filters by them, and useContractDirectory(search) accepts label filters — so a business-side picker can offer only the contracts tagged for its scene.
• JSON Schema keyword completions (c826041). The contract form's input/output schema editors complete JSON Schema draft 2020‑12 keywords as object keys, with per-keyword documentation.
• Wire-trace body highlighting (c826041). Captured HTTP exchange bodies are auto-detected: JSON bodies re-indent and highlight, XML highlights verbatim, anything else falls back to a plain block — in both the invocation log detail and the dry-run trace.
• Code map editing against the host catalog (b403919, 6ec1938 — unreleased). Adapter scripts translate values with codes.toExternal / codes.toCanonical; the code-map form picks the code set from the host's registered catalog (integration/code_set.list_code_sets, auto-filling the name) with manual free-text fallback when the host registers no enumerable catalog, and the entries editor shows the canonical codes of the selected set as a reference line.

Mounting the pages

No provider is required — mount each page directly on a route. The playground uses /sys/integration-*:

// routes/sys/integration-system/route.tsx
import { createFileRoute } from "@tanstack/react-router";
import { IntegrationSystemPage } from "@vef-framework-react/integration";

export const Route = createFileRoute("/_layout/sys/integration-system")({
  component: () => <IntegrationSystemPage />
});

Recommended order in a menu mirrors the dependency chain: contracts → systems → adapters → routes → code maps → console. See Pages for each page's permissions and endpoints, and the API Reference for the full export tables.

Permission model

INTEGRATION_PERMISSIONS mirrors the backend codes verbatim: standard query/create/update/delete per CRUD domain (contract, system, adapter, route, codeMap), a read-only log.query, and four operational codes (ops.dry_run, ops.dry_run_inbound, ops.test_connection, ops.diagnose_routes). The host code-set catalog endpoints reuse codeMap.query — the catalog exists solely to support the mapping editor. Every page accepts a permissions override; see Permissions.