platforms/docs/操作日志_用户端APP_充值查询与幂等_20260911.md

# 充值查询与幂等接口开发记录

操作时间：2026-09-11
操作类型：扩展、修复
影响模块：共用客户端钱包充值接口。

## 操作前后

原充值接口只有创建和Mock确认，客户端无法查询本人充值记录或恢复未知结果。创建时遇到重复请求号直接返回旧记录，没有核对本次金额与渠道；重复提交不同金额可能得到旧金额支付参数。

现在以请求号唯一约束配合`ON CONFLICT DO NOTHING`，重复时核对主体类型、主体标识、金额和渠道。同请求同参数返回同充值单；金额、渠道或归属不一致返回2411“充值请求已存在，请保持原金额和支付方式”。不通过异常插入破坏外层事务，不创建重复充值记录。原返回字段保持兼容，真实渠道响应增加`recharge_identity`、`recharge_no`、`recharge_status`。

新增本人充值记录、单条结果及按原请求号恢复查询。钱包入账状态与支付单状态分别返回，缺少支付单时不推测已经支付。所有读取限定主体类型及身份，不返回钱包内部主键、操作者、密钥或支付调起参数。

## 接口契约

相对路径基于`/heqi/client/v1/user`，现有服务端客户端也复用同一能力。

| 方法与路径 | 参数 | 返回与边界 |
| --- | --- | --- |
| POST wallet/recharges | 既有amount、channel、request_no、pay_type等 | 同请求号重试必须保持金额和渠道，冲突2411 |
| GET wallet/recharges | 可选cursor，服务端返回的正整数游标 | items最多50条，next_cursor为空表示无后续页 |
| GET wallet/recharges/:identity | 公开充值标识 | 本人充值字段，可选payment_status、expires_at |
| GET wallet/recharge-requests/:request | 原始request_no | 网络结果未知时恢复本人充值记录，不修改状态 |

充值字段：identity、recharge_no、recharge_status、amount（整数分）、channel、created_at、completed_at。`recharge_status=23`才是已入账，不能仅凭支付客户端返回成功宣称到账。原图10至5000元不是已确认的服务端业务规则，本轮没有改写现有限额配置或凭空发布充值协议。

## 核心文件

- `backend/api/internal/logic/common/client_wallet.go`：CreateRecharge冲突处理及响应补充；ConfirmMockRecharge补齐主体类型过滤。
- `backend/api/internal/logic/common/recharge_query.go`：GetRecharge、ListRecharges及白名单投影rechargePublic。
- `backend/api/internal/routers/client.go`：增加三个读取路由，旧接口保留。
- `backend/api/internal/logic/common/recharge_remote_test.go`：显式开启的远程事务回滚测试。

## 验证和风险

`HEQI_REMOTE_RECHARGE_TEST=1`远程测试通过（16.17秒）：独立用户与零余额钱包，创建同参重试、修改金额/渠道冲突、按请求号恢复、跨主体类型拒绝、Mock重复确认仅入账一次、只生成一笔流水。完成后整体回滚，确认测试充值单和钱包均不存在；没有实际调用微信/支付宝，也没有修改已有账户资金。普通测试默认跳过远程用例。

本轮无数据库结构变更，不启动本机PostgreSQL或Redis。真实渠道返回可能未知，客户端应保留原请求号查询；本轮不修改支付SDK的渠道重试逻辑，不宣称渠道侧恰好一次请求已得到完整验证。

图38充值页面及完整渠道交互仍未完成，本轮提供其必需的结果查询和幂等保证，不能据此把图38计为完成或改变全量17张部分实现、41张无对应完整页、0张严格通过的状态。

后端全量go test、go vet和API构建通过。新API进程42452监听12426；实际授权账户读取充值记录返回成功及1条既有记录，未知请求号返回业务码1112。SDK错误响应仍使用HTTP200包装业务码，客户端必须读取code，不能单靠HTTP状态判断存在或成功。本轮实测只读，没有创建真实充值单或发送真实支付请求。