---
title: Business API 与 Console Surface
description: 设计强类型 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](/docs/zh/console-packages)；Capability 设计参见
[Auth and Capabilities](/docs/zh/auth-capabilities)。