权限与身份

权限分为清单声明、宿主能力和实际调用校验。页面成功打开不代表可以访问登录身份、后台或本地资源。

#按需声明权限

这不是全部权限的枚举。高级能力应查阅匹配版本的公开契约，避免预先申请所有权限。

#读取当前身份

在完整 Manifest 中加入所需权限：

{
  "permissions": ["webview", "identity.read"]
}

WebView 使用 SDK 的身份接口：

const result = await sdk.session.getContext();
if (result.code !== 1) {
  throw new Error(result.message || '无法读取当前身份，请确认登录与授权。');
}

const user = result.data?.user;
const unit = result.data?.unit;
if (!user || !unit) {
  // 展示未登录或未选择单位的状态。
}

身份上下文包含必要的用户、单位标识与名称，不包含 Desktop Token。不要读取宿主 localStorage、复制 userInfo 或缓存登录凭据来绕过接口。

监听身份变化时应更新页面状态并释放旧监听；切换用户或单位后，扩展自己的业务数据也应按业务权限重新加载。

#区分两类后台请求

平台后台通过 sdk.api.call() 调用清单允许的平台命令，由宿主复用当前登录会话。声明中需同时包含命令和正确后缀：

{
  "permissions": ["webview", "http"],
  "contributes": {
    "api": [
      { "command": "Example.List", "suffix": "/sys" }
    ]
  }
}

Example.List 是说明命令声明方式的占位名称，按实际已开放命令替换，不能直接调用。

扩展自有后台通过 sdk.api.request() 等公开传输访问已声明的后端，由扩展发布方负责自身认证。端点由受控部署配置解析，Manifest 不携带环境地址，也不会自动获得 Desktop 的认证头。

这两类请求与扩展本地命令不是同一个接口，不能互相替换。

#处理失败与兼容

按以下顺序排查：目标宿主是否支持该接口、Manifest 是否声明权限、贡献或端点是否完整、登录和单位上下文是否有效、实际返回是否成功。

能力不存在、未授权与后台失败应分别给出提示。不要把所有失败都提示为“请重新登录”，也不要在调用失败后直接回退到 Electron、Node、任意网络地址或其他扩展的数据。

出现“桌面会话同步失败”或身份读取失败时，重点核对 identity.read 和实际承载方式：.mipx 看扩展 Manifest；普通 Web 应用看平台应用授权，不能套用扩展清单。