完善七牛回调验签与重试策略文档

docs/common/reports/qiniu_callback_validation_2026-02-28.md

@@ -0,0 +1,27 @@
+# 七牛直传与回调验签验证记录（2026-02-28）
+
+对应 issue：`#13 [P1][T10] 七牛云直传配置与回调验签`
+
+## 验证项
+
+1. 上传凭证配置
+- `QINIU_CALLBACK_URL/QINIU_CALLBACK_BODY/QINIU_CALLBACK_BODY_TYPE` 已接入配置读取。
+- token 生成时 callback 策略可注入 putPolicy。
+
+2. 回调验签
+- 七牛回调签名校验方法：`VerifyCallbackSignature`
+- 验证通过：合法签名请求返回 200。
+- 验证失败：非法签名请求返回 401。
+
+3. 失败重试策略
+- 回调处理约定：
+  - `401/400`：非重试型错误（验签失败、参数错误）
+  - `503`：可重试型错误（业务临时故障）
+
+## 测试命令
+
+```bash
+go test ./internal/common/qiniu/service -v
+go test ./internal/common/qiniu/handler -v
+go test ./...
+```

docs/common/upload_qiniu.md

@@ -6,6 +6,10 @@
 
 - 已完成登录并拿到 `session_key`（见：`docs/common/auth.md`）
 - 已配置 `.env` 中的七牛参数（见：`.env.example`）
+  - 若需要上传成功回调，请额外配置：
+    - `QINIU_CALLBACK_URL`（例如：`https://api.example.com/api/v1/common/upload/qiniu/callback`）
+    - `QINIU_CALLBACK_BODY`
+    - `QINIU_CALLBACK_BODY_TYPE`
 
 ## 接口
 
@@ -74,3 +78,30 @@ curl -X POST 'https://upload.qiniup.com' \
 
 七牛成功时会返回 JSON（字段可能因配置不同略有差异），其中一般会包含 `key/hash`。
 
+---
+
+## 上传回调（服务端）
+
+当配置了 `QINIU_CALLBACK_URL` 后，后端签发的 putPolicy 会包含 callback 参数。七牛上传成功后会回调：
+
+`POST /api/v1/common/upload/qiniu/callback`
+
+说明：
+- 该接口无需登录（由七牛服务端调用）。
+- 服务端会校验 `Authorization: QBox ...` 签名。
+- 验签失败返回 `401`，直接拒绝。
+- 当业务处理发生临时异常时可返回 `503`，利用七牛回调重试机制重试。
+
+默认回调体（可通过 `QINIU_CALLBACK_BODY` 调整）：
+
+```txt
+key=$(key)&hash=$(etag)&fsize=$(fsize)&mimeType=$(mimeType)
+```
+
+### 失败重试策略
+
+- 当前策略：
+  - 验签失败：`401`（不可信请求，不重试）
+  - 参数错误：`400`（请求无效，不重试）
+  - 临时失败：`503`（可重试）
+- 建议在回调处理中保证幂等（例如按 `key` 去重），避免重复消费。