---
title: Module Console UI
description: 为精确 Module Release 发布回执绑定的 console_ui_esm 制品。
---

Module 可以把运维 UI 作为不可变 `console_ui_esm` 制品交付。UI 属于 Module
Release，不属于 Console 仓库；只有 Console 校验已连接 System Receipt 和全部
制品 Binding 后才会加载。

## 合约形态

`ModuleManifest.console` 包含 `ConsoleSurface` 声明。每个源码声明持有
`name`、`label`、`route`、`presentation`、可选 `icon`、所需 Capability 与可选
Navigation。可执行 UI 通过 `ConsoleSurfacePresentation::Esm { entry }` 指定 ESM
Entry；这个源码形态没有 `area` 字段。

Framework 从这些可执行声明生成制品中的
`ConsoleModuleManifest.surfaces` 列表。每个生成的 `ConsoleModuleSurface` 使用
`id`、`path`、`label`、由 Route 推导的 `ConsoleModuleSurface.area`、所需
Capability、可选 Icon 与可选 Navigation。不要把生成的 Presentation 字段反向
写入 `ModuleManifest.console`。

`ModuleManifest.console_slots` 与 `ModuleManifest.console_contributions` 是独立的
Extension 声明；它们不是 `ConsoleSurface` 内的 Context 字段，也不是生成的
`ConsoleModuleSurface` 成员。

同一 Module Release 携带一个 `ConsoleUiArtifact`，其中包含：

- `console_ui_esm` 格式；
- 制品 Locator 与 SHA-256 摘要；
- 生成的 `lenso.console-module.v1` Presentation Manifest；
- 相互独立的 `hostApi` 与 `consoleUi` 兼容范围；
- 具名 ESM Entry 与可选 Style Asset，全部绑定摘要；
- 与所属 Module Release 一致的不可变 Provenance。

Entry 缺失、摘要不匹配、协议范围不兼容、Surface 未声明，或制品属于其他
Module Release 时，Console 会拒绝加载。

## 运行时 API

Entry 使用 `@lenso/console-module-api` 的 framework-neutral Manifest 与强类型
Host Operation。React Surface 使用 `@lenso/console-ui` 的 Adapter、Surface
Root、共享组件与强类型 StyleX Slot。Console 注入不可变 Slot Context；Module
UI 不导入 Console 内部实现。

Host API 提供导航、Locale、当前 Actor、System Context 与同源 Surface
Gateway 调用。Surface 必须能呈现四种对象状态：

- `connected`：正常操作可用；
- `unavailable`：显示服务端原因和重试入口；
- `incompatible`：指出合约或制品不匹配；
- `unmanaged`：说明没有 Management Binding 覆盖该对象。

## Business API 调用

从 Module 已提交的 OpenAPI 合约生成 Client。Surface 通过 Surface Gateway
调用该 Client；不得自行构造 Service Base URL，也不得附加 Service 凭据。

每个请求都受已连接应用的 Surface Grant 限制：

- Console Actor 与可选 Tenant；
- Module 身份和 Module Release 摘要；
- UI 制品摘要；
- Business API Contract 摘要；
- 精确允许的 Operation ID。

任一 Binding 变化时 Gateway 都会 fail closed。浏览器直连 Service 不属于支持
模型。

## 打包循环

1. 构建 ESM Bundle 与生成的 Presentation Manifest。
2. 计算 JavaScript 和每个 Style Asset 的摘要。
3. 把制品附加到同一不可变 Module Release。
4. 运行所属仓库的 Module Release 与 Console 制品检查。
5. 组合选择该精确 Release 的新 `lenso.app.json` 修订。
6. 连接该精确拓扑，并在真实浏览器中校验 Surface。

操作设计参见 [Business API 与 Console Surface](/docs/zh/admin-surfaces)；System
Binding 与浏览器权限参见 [Lenso Console](/docs/zh/runtime-console)。