BMS/bms-back/docs/oss-bill-storage.md

应收账单 OSS 存储

新生成的应收账单导出 Excel 上传到 lionqueen Bucket。 生产路径为 bms/prod/ar/bill/yyyy/MM/dd/<uuid>.xlsx，本地、测试路径为 bms/test/ar/bill/yyyy/MM/dd/<uuid>.xlsx。数据库 ar_bill_export.storage_key 保存包含完整对象路径的 oss://lionqueen/...，不需要数据库变更。 生产环境启动需启用 prod Profile，可通过 OSS_PATH_PREFIX 覆盖目录前缀 （不以 / 开头或结尾）。同 Bucket 下的目录划分用于区分文件，权限隔离仍需配置 RAM 策略。

部署配置

在后端进程环境变量中填写完整密钥，然后重启后端：

OSS_ACCESS_KEY_ID=<完整 AccessKey ID>
OSS_ACCESS_KEY_SECRET=<完整 AccessKey Secret>

默认配置位于 bms-admin/src/main/resources/application.yml：

oss:
  endpoint: ${OSS_ENDPOINT:https://oss.lionquexpress.com}
  bucket: ${OSS_BUCKET:lionqueen}
  path-prefix: ${OSS_PATH_PREFIX:bms/test}
  cname: ${OSS_CNAME:true}
  access-key-id: ${OSS_ACCESS_KEY_ID:}
  access-key-secret: ${OSS_ACCESS_KEY_SECRET:}

也可以通过外部 Spring 配置文件填写这些配置。 oss.lionquexpress.com 按 OSS 自定义域名使用，需在 OSS 控制台已绑定到 lionqueen，且 HTTPS 证书可用。若这个域名仅用于 CDN 分发，请设置 OSS_ENDPOINT 为 Bucket 所在地域的 OSS Endpoint，并设置 OSS_CNAME=false。 密钥需要目标 Bucket 下对应对象的上传、读取、删除权限。

生成和下载

• 流式生成系统临时文件，计算大小和 SHA-256，上传成功后才更新导出状态为 SUCCESS。
• 上传时显式设置对象 ACL 为 private，下载继续使用原有账单下载接口及权限校验，后端流式读取 OSS。
• 生成或上传失败走原有 FAILED 状态处理；正常和异常路径都会尝试清理临时文件。
• 任务已超时或被其他流程结束、成功状态更新返回 0 时，删除该次上传的 OSS 对象。
• OSS 上传与数据库状态更新不属于同一事务；数据库更新异常可能留下未关联的 OSS 对象，需运维核对处理。
• 历史 /profile/... 账单仍从原本地目录下载，本次不迁移历史文件。
• 已有 oss://lionqueen/bms/ar/bill/... 文件仍按数据库中记录的路径读取，下载和删除不重新添加环境前缀。
• 普通附件、头像、导入文件及导出模板维持现有存储方式。

SDK 自定义域名与客户端配置参考：阿里云 OSS Java SDK 文档。