---
id: 013
title: 支付宝真付接入（信封购买）
status: closed
labels: [payment, p1, breaking-change]
assignee: team-lead
closed_at: 2026-04-23
created_at: 2026-04-23
---

# #013 支付宝真付接入

## 背景

当前 `xq envelope buy --mock` 假付（paid=1 不扣钱）。v0.5.0 目标接入真付，这是 xiangqin 商业闭环的第一步。

**有历史代码**：M3 时代做过支付宝集成（`src/xiangqin/payment/alipay.py` 211 行），M4 砍曝光时一起砍掉。git commit `6d142b4` 之前能找回。

## 方案

### 支付宝开放平台接入

- App ID: vault `alipay/openapi-app/2021000104691762`（已有）
- 商户应用证书 + 私钥：vault `alipay-kongxuanpin` credential（已有 app_id / app_private_key / alipay_public_key 三个字段）
- 支付方式：PC 网站支付（电脑打开链接扫码）/ 当面付（二维码）/ Wap 支付
- **xq CLI 触发路径**：
  1. `xq envelope buy --count 10`
  2. 服务端创建 order + 调 alipay.trade.precreate → 返回二维码 URL
  3. CLI 打印 ASCII 二维码（qrcode 库，之前砍掉了要加回来）
  4. 用户支付宝扫码支付
  5. 支付宝异步回调 `/webhook/alipay` → 服务端验签 + 更新 order + 加信封余量
  6. CLI 轮询 order 状态 / 或 push 通知

### 对账

- 每日从支付宝拉交易流水 → 和本地 order 表对齐
- 缺失 / 异常 → 告警（加到 M7 业务级告警）

### 退款

- `xq envelope refund <order_id>` 调 alipay.trade.refund
- 72h 内允许全额退；超期拒绝
- 信封余量相应扣减

## 依赖

- vault.json 里 alipay credential 已声明（M3 保留下来的）
- restore 旧 alipay.py：git show 6d142b4:src/xiangqin/payment/alipay.py 出来复用
- 补 `cryptography` 依赖（M4 一起砍了要加回）

## 工作量

- restore + 适配新 schema（envelope_orders 代替 exposure_orders）：2 天
- webhook 验签 + 幂等性：1 天
- 对账脚本：1 天
- CLI 端二维码 + 轮询：1 天
- 测试 + 上线：1-2 天

**单人全职 5-8 天**。

## 不做

- **不自建支付**（资金通道 + 合规不碰）
- 不存用户银行卡信息（支付宝托管）
- 不支持分期 / 花呗（信封单价 ¥1，无意义）

## 相关

- P1-1 of blueprint
- 依赖 issue #020（退款）后续
