# wechat_transfer_authorization — 微信「免确认转账」授权

> 模型 `app/models/wallet.py` · 仓库 `app/repositories/wallet.py` · 接口 [wallet-withdraw](../api/wallet-withdraw.md)(打款时用)、绑定 [wallet-bind-wechat](../api/wallet-bind-wechat.md) · [← 索引](./README.md) · [总览](./OVERVIEW.md)

微信商家转账的**免确认收款授权**。用户授权一次后,后续提现可走 `transfer_with_authorization` 免逐笔在微信里确认、直接到账;未授权则走确认模式(每笔都要用户在微信点确认)。**一个用户一行**(`user_id` 主键)。

**状态机**:
```
(无) ──申请 / 首单转账顺带申请──▶ pending(微信 WAIT_USER_CONFIRM,待用户在微信确认授权)
pending ──用户确认授权──▶ active(微信 TAKING_EFFECT,此后转账免确认)
pending / active ──用户在微信关 / 商户解除 / 风控──▶ closed(终态,需重新开启,下次提现自动回退确认模式重授权)
```

## 用在哪 / 增删改查
- **C(插入)**:`_ensure_pending_auth_no` —— 用户首次提现走"方式一(转账顺带申请授权)",或显式 `apply_transfer_auth`(开启免确认)时,建一行 `pending`(生成 `out_authorization_no`)。
- **U(更新)**:
  - `sync_transfer_auth`(仅 `pending` 时查微信):用户确认后 `TAKING_EFFECT` → `active` + 回填 `authorization_id`;超期未确认 `CLOSED` → `closed`。
  - `_refresh_active_auth`:免确认转账失败后回查,微信侧已失效 → `closed`。
  - `close_transfer_auth`(用户解除授权)→ `closed`。
  - `closed` 后重新开启:换新 `out_authorization_no`、清 `authorization_id`、回到 `pending`。
- **D**:无(重开是改回 pending,不删行)。
- **R**:`execute_withdraw_transfer` 打款前读它决定走免确认还是确认模式。

## 字段
| 列 | 类型 | 约束 / 默认 | 说明(取值 / join) |
|---|---|---|---|
| `user_id` | Integer | **PK + FK→user.id** | 用户(一用户一行) |
| `openid` | String(64) | NOT NULL | 微信 openid 快照(= `user.wechat_openid`,换绑时刷新) |
| `out_authorization_no` | String(64) | UNIQUE, index, NOT NULL | **我方生成**的授权单号(查授权/发起授权用);重开时换新值 |
| `authorization_id` | String(64) | nullable | **微信** active 后返回的授权号;免确认转账(`transfer_with_authorization`)必传 |
| `state` | String(16) | NOT NULL, default `pending` | 取值:`pending`(待用户确认)/ `active`(已生效可免确认)/ `closed`(已关闭需重开) |
| `created_at` | DateTime(tz) | server_default now() | |
| `updated_at` | DateTime(tz) | server_default now(), onupdate now() | |

## 关系 / Join Key
- `user_id` → `user.id`(一对一)。
- 逻辑配合 `withdraw_order`:打款时按本表 `state=='active' && authorization_id` 决定免确认 vs 确认模式(无 id 直连,按 `user_id` 关联)。
- `openid` 是 `user.wechat_openid` 的快照(冗余,避免打款时再查 user)。

## 索引与约束
- PK `user_id`;UNIQUE+index `out_authorization_no`。

## 注意
- `out_authorization_no`(我方)与 `authorization_id`(微信)是**两个不同的号**,别混:前者贯穿整个授权生命周期,后者只在生效后才有。
- 未配 `WXPAY_AUTH_NOTIFY_URL`(未启用免确认)时本表不参与,提现退化为原确认模式。