Genarrative/server-rs/crates/platform-oss/README.md

platform-oss 平台适配 package 说明

日期：2026-04-20

1. package 职责

platform-oss 是 OSS 平台适配 package，后续负责：

1. OSS 直传签名、STS、上传策略适配
2. 对象上传、下载、签名 URL 与 cdn_url 解析适配
3. 对象元数据、标签与内容 hash 适配
4. 供 module-assets、module-custom-world 等模块复用的对象存储基础设施能力

2. 当前阶段说明

当前提交已落地最小可用 OSS 基础设施：

1. PostObject 浏览器直传签名
2. 旧 /generated-* 公开前缀到 OSS object_key 的兼容映射
3. 私有对象短期签名读 URL
4. 私有对象 HEAD Object 探测
5. 服务端 PutObject 上传 helper
6. x-oss-meta-* 元数据归一化与大小限制校验
7. content-type、content-length-range、success_action_status policy 条件生成

当前仍未落地的内容：

1. STS 真实临时授权下发
2. multipart 分片上传
3. 内容 hash 自动计算与标签写入

补充说明：

1. 当前产品口径为服务器上传 AI 生成资源、Web 端只负责读取。
2. 因此 STS 不作为默认上传主链，api-server 只暴露禁用式 contract，避免浏览器拿到 OSS 写权限。
3. 服务端生成资源应优先复用 OssClient::put_object，上传成功后再走对象确认链路写入 asset_object。 4. 读签名和 HEAD Object 的入参必须直接传 object_key，不要把 bucket 名拼进路径；例如 generated-square-hole-assets/.../image.png 才是正确入参，xushi-dev/... 这类前缀不属于 object_key。 5. OSS V4 x-oss-date 必须固定为 yyyyMMdd'T'HHmmss'Z'，不能依赖 time::Time::to_string()；后者在小时小于 10 时可能输出非补零时间，导致签名格式错误。

3. 边界约束

1. platform-oss 只承接对象存储平台适配，不承接业务实体状态与业务规则。
2. 资产状态与对象绑定最终由业务模块和 apps/spacetime-module 管理，前端接口由 apps/api-server 暴露。
3. 不允许把 OSS SDK、签名逻辑和 URL 策略重新散落到多个业务模块里各自实现。