# 声明应用能力

通过 module 或 interface target 声明平台应用可调用的最小方法范围。

平台应用的授权不是“登录后可以调用全部平台接口”。每个版本必须声明需要的能力；已启用的精确 Bundle 安装、当前成员权限和该版本声明共同把调用范围限制在当前工作区、当前安装、当前用户和安装锁定的不可变版本上。

## `methodDefinitions`

在 `baijimu.platform-application.json` 中，随 Bundle 安装的平台应用必须通过
`methodDefinitions` 使用结构化 `target` 声明精确 Module 资源或可替换接口，以及允许的方法：

```json
[
  {
    "target": {
      "type": "module",
      "bundleId": "workspace-core",
      "moduleId": "2108"
    },
    "methods": [
      "listWorkspaceMembers"
    ]
  }
]
```

- `target.type` 只能是 `module` 或 `interface`。
- 固定依赖使用 `module`；`bundleId + moduleId` 必须来自当前 Bundle 或显式依赖闭包的模块目录，不得根据显示名称自行构造。
- 只有可替换能力使用 `interface`；`name` 必须在 `manifest.interfaceBindings` 中绑定到 模块领域引用。
- 每一项必须声明一个非空 `target` 和非空 `methods`。
- `methods` 必须是非空数组。
- 方法名按原始大小写保存并精确匹配。
- 不接受原始 `service`、具体 `businessId` 或 service/method 通配符。

版本创建协议不接受以下旧字段：

- `services`
- `serviceId`
- `businessId`
- `runtimeBusinessId`
- `serviceRef`
- `runtimeServiceId`

## 最小权限原则

只声明当前版本实际调用的方法。不要使用通配权限代替梳理接口，也不要因为后续“可能用到”就提前加入管理、删除或导出类方法。

当新版本扩大能力范围时：

1. 创建新的平台应用版本。
2. 更新并创建新的 Bundle 版本。
3. 预览升级，核对新增的跨 Bundle 方法清单并由安装用户明确确认。
4. 升级目标工作区 Bundle 安装。
5. 验证未声明方法和未安装依赖仍被拒绝。

## 只声明 Runtime 模块能力

平台应用不提供通用平台 HTTP 代理，也不能用 Manifest `httpGrants` 直接访问
`bundle-service`、`project-service`、`workflow-engine` 等平台内部服务。需要暴露的新
能力必须先定义为 Runtime 模块方法并创建不可变模块版本，再由平台应用版本声明该方法。

能力声明负责“允许调用什么”，Bundle 安装负责“该工作区安装了哪一版产品”，工作区权限负责“当前用户能调用什么”，运行态网关负责核验本次请求是否同时符合这些边界。平台应用不维护独立的用户 consent 状态。

页面运行时把与 `methodDefinitions` 一致的结构化 `target`、`method` 和 `params` 发送给 App Gateway，
但不发送具体 `businessId` 或安装态调用凭据。module target 仍是稳定逻辑身份，不是运行时服务身份。
请求格式见
[调用模块方法](/development/bundle-development/platform-application-development/module-method-calls/)。