跳到内容
Lenso
简体中文
Esc
导航打开⌘J预览
本页内容

Business API 与 Console Surface

设计强类型 Module Operation,并把 Console UI 绑定到精确生成客户端。

运维工作流使用与其他可信 Client 相同的业务合约。Module 声明 Business API、 发布生成客户端,并在 Module Release 中交付精确 Console Surface。Console 提供 已认证 Actor,并执行已连接应用的 Surface Grant。

从 Business API 开始

围绕业务能力建模 Operation,不要使用 framework-wide Record 抽象。对于 Support Ticket Module,可以定义:

Operation 业务行为
listTickets 返回当前 Actor 与 Tenant 可见的 Ticket。
createTicket 使用调用方提供的 Idempotency Key 创建 Ticket。
updateTicket 对现有 Ticket 执行修订绑定的更新。
closeTicket 通过领域转换关闭 Ticket。

OpenAPI 合约定义输入、输出、错误、Actor、Tenant、Deadline 与 Idempotency 行为。从已提交合约生成 Client,并在所属仓库中检查生成结果。

绑定 Surface

ModuleManifest.console 命名 Surface 与 ESM Entry。Module Release 把该 Entry 绑定到不可变 console_ui_esm 制品。应用组合选择精确 Module Release 与 UI 制品摘要。

Surface Grant 把访问范围缩小到:

  • 一个 Module 身份与 Module Release 摘要;
  • 一个 UI 制品摘要;
  • 一个 Business API Contract 摘要;
  • 一组明确的 Operation ID。

安装或连接 Surface 不会自动授予 Module 中的全部 Operation。

通过 Surface Gateway 调用

生成客户端使用 ConsoleClient.surfaceApi 提供的同源 Surface Gateway。Console Service 先重新检查 Browser Session、Console Actor、可选 Tenant、精确已连接 System 和完整 Surface Grant,再调用目标 Module。

浏览器不会获得目标凭据。它不得调用 Service Base URL、查询 Service Store, 也不得发明未声明的 Operation。

按直接对象状态设计

每个目标只呈现一种状态和直接原因:

  • connected:允许 Surface Grant 包含的操作;
  • unavailable:在安全时保留当前数据,并提供重试;
  • incompatible:指出 Contract、Release 或制品不匹配;
  • unmanaged:说明对象不在当前 Binding 范围内。

不要把这些状态合成为应用总分,也不要静默回退到其他目标。

授权检查清单

  • 在目标 Module 校验 Actor 与 Tenant,不能只依赖浏览器。
  • 更新必须绑定当前业务修订。
  • 可重试写入必须要求 Idempotency Key。
  • 传播调用方 Deadline,并拒绝已过期工作。
  • Surface Operation ID 必须比 Module Contract 更窄。
  • 返回强类型 Problem Response,不包含 Secret 或 Transport Diagnostic。

制品打包参见 Module Console UI;Capability 设计参见 Auth and Capabilities

最后更新于 2026年8月13日

这个页面有帮助吗?