# 应收账单 OSS 存储

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

## 部署配置

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

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

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

```yaml
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 文档](https://www.alibabacloud.com/help/en/oss/developer-reference/oss-java-sdk/)。

## 毛利分析报表

产品、订单两个维度的导出也使用上述 OSS 配置。生产文件路径为
`bms/prod/report/profit/yyyy/MM/dd/<uuid>.xlsx`，本地和测试为
`bms/test/report/profit/yyyy/MM/dd/<uuid>.xlsx`。
导出保持同步：临时 Excel 生成并上传成功后更新导出日志，再由前端发起下载。
下载继续校验当前用户及原接口权限；历史本地文件名仍从原 download 目录读取。
上传失败标记导出失败并清理临时文件，状态更新返回 0 时删除此次上传的 OSS 对象。