OSS 实例、文件浏览与图片预览

从开发套件管理工作区存储实例、浏览文件和预览图片，并从 Hosted Service 环境绑定打开对应实例。

开发套件的「对象存储」是独立的 OSS 管理应用。这里的实例指工作区逻辑存储空间 Profile，不要求先绑定 Hosted Service；底层 Bucket 和云存储密钥由平台管理。

从实例列表打开文件

打开工作区的开发套件 → 对象存储，查看当前工作区有权访问的实例。
点击实例名称或「打开实例」，查看状态、单文件大小上限及更新时间。
在文件列表按 key 前缀筛选，使用上一页、下一页浏览，每页最多展示 50 条。文件列表由存储端分页，不先下载全部文件。
点击文件的「详情 / 预览」，读取大小、Content-Type、ETag，并对图片加载临时签名 GET。

空实例和空筛选结果是正常结果。权限拒绝、实例不可用和读取失败会显示错误，不解释为空列表。非 ACTIVE 实例可查看生命周期元数据，不能浏览或申请文件访问。

从 Hosted Service 找到绑定实例

进入后端项目的「环境」页面，选择环境的「资源绑定」，再点击对应绑定的「打开实例」。平台根据 Provider 登记的管理应用关联，查找当前 Runtime 的实际应用版本和页面声明，打开对应 Profile。

这里展示的是环境当前配置绑定，不证明运行中的部署已采用这一修订。同一 Profile 可以绑定多个环境或项目，实例详情展示该空间中的文件，不能据此断言文件都由当前服务上传。未绑定服务的实例同样出现在 OSS 独立应用中。

Provider 未登记管理入口、应用未安装、停用或当前版本缺少详情页面时，平台明确提示原因。页面链接使用当前环境和工作区的应用目录，不使用固定域名、安装 ID 或全局最新版补齐。

权限与图片 URL

OSS 管理采用工作区级资源权限。Owner 根据平台验证的用户身份，实时核验当前工作区访问权和 Profile 的工作区归属。前缀只用于筛选，不是门店、客户或项目的权限边界。业务系统的附件归属和终端用户授权仍由业务后端负责。

Hosted 环境绑定查询继续受项目所有者或工作区管理权限约束；能看到绑定不等于获准读取文件。应用会话、同包 Module 调用和 Object Storage Owner 的资源校验分别执行。

图片预览默认申请 300 秒签名 URL，到期后可点击「重新获取预览地址」。每次新申请都校验当前权限，已经签发的链接仍可使用至到期。前端仅获得签名 URL，不获得 Profile Token 或存储密钥；URL 不作为永久文件引用。

图片只作为图片解码展示，不在应用页面内执行 HTML 文档。对于不支持图片预览的文件，仍可查看元数据。

长期业务接入仍遵循对象存储与签名上传指南：后端先生成 key，上传核验后保存 key，展示时重新签名。

管理 API 与 Module 方法

以下是 Object Storage Owner 的用户授权管理 API。平台应用通过标准 SDK、App Gateway 和同包 workspace-object-storage Module 调用；浏览器不直接携带 Profile Token 请求这些接口。原 Hosted Service capability 接口保持独立的绑定 Token 合同。

HTTP 路径	Module 方法	用途
`GET /api/object-storage/profiles`	`listObjectStorageProfiles`	当前工作区实例列表
`GET /api/object-storage/profiles/{profileRef}`	`getObjectStorageProfile`	指定实例详情
`GET /api/object-storage/profiles/{profileRef}/objects`	`listObjectStorageObjects`	分页列文件
`POST /api/object-storage/profiles/{profileRef}/objects/head`	`getObjectStorageObjectMetadata`	文件元数据
`POST /api/object-storage/profiles/{profileRef}/download-requests`	`prepareObjectStorageDownloadRequest`	临时签名 GET

profileRef 从真实实例列表或环境绑定取得，key 从该 Profile 的文件列表取得。不能编造标识，也不能把底层物理前缀拼进 key。

分页方法参数为 profileRef 和可选 prefix、pageSize、cursor。pageSize 默认 50，允许 1 到 200；prefix 允许空值及以 / 结尾的目录前缀。后续请求原样提交 nextCursor，更换前缀后清空游标。

{
  "contractVersion": "1.0.0",
  "items": [
    {
      "key": "images/example.png",
      "size": 117,
      "lastModified": "2026-11-11T00:00:00Z",
      "eTag": null
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

上述是 CModel 的 data，不是完整响应。管理 API 的成功和业务失败均采用 HTTP 200，顶层保持 contractVersion、errorCode、data 三字段；SDK 返回成功的 data，业务错误保留其错误码。

元数据方法接收 profileRef、key，返回 contractVersion、key、size、contentType、eTag。下载申请接收 profileRef、key，以及可选 expiresInSeconds（默认 300，范围 60 到 3600），返回 contractVersion: "1.1.0"、method: "GET"、url、headers、expiresAt。签名请求必须按返回的 URL 与 headers 原样使用。

直接调用两个 POST 管理 API 时，JSON body 使用 contractVersion: "1.0.0"；Module 负责填充该固定合同字段。

管理入口关联与页面声明

Provider 的 configJson 可通过 managementUi 关联管理应用：

{
  "contractVersion": "1.0.0",
  "managementUi": {
    "applicationResourceLocator": "source-environment/developer-bundle/PLATFORM_APPLICATION/storage-console",
    "profilePageKey": "profile-detail",
    "profileParameter": "profileRef"
  }
}

其中 Locator 是结构示例，实际值必须来自该环境的权威应用目录。Owner 只按该登记关联导航，不按某个 Provider 名称或编号编写分支。关联不授予访问权。

OSS 应用使用已有作者配置 7.3.0 的 pages 声明 profile-list 与 profile-detail，详情页面模板为 /index.html?profileRef={profileRef}。Manager 读取当前 Runtime 中实际资源的精确版本及该版本页面，再通过已有 target 链接协议打开。详见页面声明与链接发现。

管理功能随开发套件 Bundle 正常整包升级生效，不需要改造或重新部署已有业务 Hosted Service。已有 Profile、key、上传和下载合同继续有效。