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。