# 阿里云 OSS 直传：获取上传凭证

用途：小程序/前端把文件直接上传到阿里云 OSS，后端只负责签发上传凭证，减少带宽与压力。

## 前置条件

- 已完成登录并拿到 `session_key`（见：`docs/common/auth.md`）
- 已配置 `.env` 中的 OSS 参数（见：`.env.example`）
  - 若需要上传成功回调，请额外配置：
    - `OSS_CALLBACK_URL`（例如：`https://api.example.com/api/v1/common/upload/oss/callback`）
    - `OSS_CALLBACK_BODY`
    - `OSS_CALLBACK_BODY_TYPE`

## 接口

`POST /api/v1/common/upload/oss/token`

Header：

```
Authorization: Bearer <session_key>
Content-Type: application/json
```

请求体（可选）：

```json
{
  "filename": "avatar.png"
}
```

说明：
- `filename` 仅用于提取文件后缀（例如 `.png`），以便后端生成带后缀的 `key`；不传也可以。

成功响应示例（OSS PostObject 凭证）：

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "key": "uploads/mp_1/user_123/20251231/ab12cd34....png",
    "upload_url": "https://bucket.oss-cn-beijing.aliyuncs.com",
    "cdn_domain": "https://bucket.oss-cn-beijing.aliyuncs.com",
    "oss_access_key_id": "LTAI5t...",
    "oss_policy": "base64...",
    "oss_signature": "sig..."
  }
}
```

字段说明：
- `key`：后端生成的对象 key，上传时必须使用该 key
- `upload_url`：OSS PostObject 上传地址
- `cdn_domain`：CDN 访问域名，可用 `cdn_domain + "/" + key` 拼出访问 URL
- `oss_access_key_id`：OSS AccessKeyId
- `oss_policy`：Base64 编码的 Policy
- `oss_signature`：HMAC-SHA1 签名

## 使用示例（curl 直传）

1) 先请求凭证：

```bash
curl -X POST 'http://127.0.0.1:8080/api/v1/common/upload/oss/token' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer wx-session-key' \
  -d '{"filename":"avatar.png"}'
```

2) 再把文件直传 OSS（multipart/form-data）：

```bash
curl -X POST '<upload_url>' \
  -F "key=<上一步返回的 key>" \
  -F "policy=<oss_policy>" \
  -F "OSSAccessKeyId=<oss_access_key_id>" \
  -F "Signature=<oss_signature>" \
  -F "file=@./avatar.png"
```

OSS 成功时返回 HTTP 204（无 body）。

---

## 上传回调（服务端）

当配置了 `OSS_CALLBACK_URL` 后，上传成功后会回调：

`POST /api/v1/common/upload/oss/callback`

说明：
- 该接口无需登录（由 OSS 服务端调用）。
- 服务端会校验 `Authorization` 签名。
- 验签失败返回 `401`，直接拒绝。
- 当业务处理发生临时异常时可返回 `503`，利用回调重试机制重试。

默认回调体（可通过 `OSS_CALLBACK_BODY` 调整）：

```txt
key=$(key)&hash=$(etag)&fsize=$(fsize)&mimeType=$(mimeType)
```

### 失败重试策略

- 当前策略：
  - 验签失败：`401`（不可信请求，不重试）
  - 参数错误：`400`（请求无效，不重试）
  - 临时失败：`503`（可重试）
- 建议在回调处理中保证幂等（例如按 `key` 去重），避免重复消费。