# 支付宝押金冻结订单解冻运维手册

> 用于处理 `shop_freeze_order` 表中客户押金冻结订单的解冻操作

---

## 一、背景

当客户需要退还押金时，需要调用支付宝 `alipay.fund.auth.order.unfreeze` 接口解冻资金。

### 相关参数（订单ID=29909）
| 参数 | 值 |
|------|-----|
| 授权号 auth_no | `2026041610002001650571764471` |
| 商户冻结订单号 out_order_no | `2044685513146597377` |
| 冻结金额 | `200.00` 元 |

---

## 二、文件位置

```
src/test/java/com/gxwebsoft/test/UnfreezeToolTest.java
```

---

## 三、修改配置（针对不同订单）

在 `UnfreezeToolTest.java` 中修改以下常量：

```java
private static final String AUTH_NO = "2026041610002001650571764471";  // 支付宝授权号
private static final String OUT_ORDER_NO = "2044685513146597377";      // 商户冻结订单号
private static final BigDecimal AMOUNT = new BigDecimal("200.00");    // 解冻金额
```

---

## 四、执行命令

### 方式一：指定测试方法（推荐）
```bash
cd /Users/gxwebsoft/JAVA/yunxinwei-java
./mvnw test -Dtest=UnfreezeToolTest#fixAndUnfreeze
```

### 方式二：运行整个测试类
```bash
./mvnw test -Dtest=UnfreezeToolTest
```

---

## 五、执行前检查

### 1. 确保 Redis 已启动
```bash
redis-cli ping
# 如果返回 PONG，说明已启动
# 如果报错，执行：
redis-server --daemonize yes
```

### 2. 确保数据库连接正常
检查 `application.yml` 中的数据库配置

### 3. 验证订单信息
执行前先确认：
- 订单确实存在且状态为冻结
- 授权号 auth_no 正确
- 解冻金额与冻结金额一致

---

## 六、执行流程

程序会自动执行以下步骤：

1. **查找冻结订单** — 根据 `out_order_no` 查询 `shop_freeze_order` 表
2. **修复 auth_no** — 如果数据库中 auth_no 为空，补充授权号
3. **查找关联订单** — 根据 `freeze_order_no` 查询关联的业务订单
4. **修复订单关联** — 修复订单与冻结订单的关联关系
5. **调用支付宝解冻接口** — 使用 `alipay.fund.auth.order.unfreeze` API
6. **更新数据库状态** — 将 `status` 更新为 `UNFREEZE`

---

## 七、执行成功示例

```
========================================
押金修复 & 解冻工具
========================================

[1] 查找冻结订单...
✅ 找到冻结订单: id=29909
   out_order_no: 2044685513146597377
   status: FREEZE
   auth_no: 2026041610002001650571764471

[2] 修复 auth_no...
✅ auth_no 已修复: 2026041610002001650571764471

[3] 查找关联订单...
✅ 找到关联订单: id=29908
   order_no: 2026041622609876
   is_freeze: true
   freeze_order_no: 2044685513146597377

[5] 调用支付宝解冻接口...
----------------------------------------
支付宝返回：
{
    "code": "10000",
    "msg": "Success",
    "amount": "200.00",
    "authNo": "2026041610002001650571764471",
    "outOrderNo": "2044685513146597377",
    "operationId": "202605111341118651865",
    "unfreezeTime": "2026-05-11 13:41:11"
}
----------------------------------------

🎉 解冻成功！
   解冻金额: 200.00
   授权号: 2026041610002001650571764471
   订单号: 2044685513146597377

[6] 更新数据库状态...
✅ 数据库已更新

⏰ 资金将在1-7个工作日内退回客户农业银行储蓄卡
```

---

## 八、常见错误处理

| 错误码 | 含义 | 处理方式 |
|--------|------|----------|
| `isv.invalid-alipay-root-cert-sn` | 根证书序列号不匹配 | 使用 Java SDK 的 `certificateExecute()` 方法 |
| `ACQ.TRADE_NOT_EXIST` | 交易不存在 | 检查 auth_no 是否正确 |
| `isv.auth_no_error` | 授权号错误 | 核对 auth_no 值 |
| `isv.amount_error` | 金额不匹配 | 确保解冻金额 <= 冻结金额 |

---

## 九、技术要点

- 使用 **Java SDK** 的证书模式（`DefaultAlipayClient`）
- 使用 `certificateExecute()` 方法而非普通 `execute()`
- 从数据库 `sys_setting` 表读取商户配置（tenant_id=6）
- 使用雪花ID生成 `out_request_no`

---

## 十、相关文件

| 文件 | 说明 |
|------|------|
| `src/test/java/.../UnfreezeToolTest.java` | 解冻工具类 |
| `src/main/resources/cert/` | 支付宝证书目录 |
| `shop_freeze_order` | 冻结订单表 |
| `order` | 业务订单表 |
| `sys_setting` | 系统配置表（支付宝密钥） |

---

*文档创建时间: 2026-05-11*
*最后更新: 2026-05-11*