21 KiB
21 KiB
支付管理API
**本文引用的文件** - [viewsh-module-pay-api 包说明](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/package-info.java) - [支付模块 API 常量](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/enums/ApiConstants.java) - [支付订单 API 接口](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/order/PayOrderApi.java) - [退款 API 接口](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/refund/PayRefundApi.java) - [转账 API 接口](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/transfer/PayTransferApi.java) - [钱包 API 接口](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/wallet/PayWalletApi.java) - [支付订单创建请求 DTO](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/order/dto/PayOrderCreateReqDTO.java) - [支付订单响应 DTO](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/order/dto/PayOrderRespDTO.java) - [退款订单创建请求 DTO](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/refund/dto/PayRefundCreateReqDTO.java) - [退款订单响应 DTO](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/refund/dto/PayRefundRespDTO.java) - [转账订单创建请求 DTO](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/transfer/dto/PayTransferCreateReqDTO.java) - [转账订单创建响应 DTO](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/transfer/dto/PayTransferCreateRespDTO.java) - [转账订单响应 DTO](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/transfer/dto/PayTransferRespDTO.java) - [钱包充值请求 DTO](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/wallet/dto/PayWalletAddBalanceReqDTO.java) - [钱包响应 DTO](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/wallet/dto/PayWalletRespDTO.java) - [支付通知 DTO：订单](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/notify/dto/PayOrderNotifyReqDTO.java) - [支付通知 DTO：退款](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/notify/dto/PayRefundNotifyReqDTO.java) - [支付通知 DTO：转账](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/notify/dto/PayTransferNotifyReqDTO.java)目录
简介
本文件为支付管理模块的 API 接口文档，覆盖支付订单管理、退款处理、转账管理、钱包管理等核心能力，并补充支付结果通知接口与支付渠道集成要点。文档面向开发者与产品/测试人员，提供接口定义、参数说明、调用流程与异常处理建议。
项目结构
支付模块采用“API + Server”分层设计：
- API 层：定义 RPC 接口与 DTO，统一版本前缀与服务名。
- Server 层：实现具体业务逻辑，提供 HTTP 控制器与 RPC 实现。
graph TB
subgraph "支付模块(API)"
A["支付订单 API<br/>PayOrderApi"]
B["退款 API<br/>PayRefundApi"]
C["转账 API<br/>PayTransferApi"]
D["钱包 API<br/>PayWalletApi"]
E["通知 DTO<br/>PayOrderNotifyReqDTO / PayRefundNotifyReqDTO / PayTransferNotifyReqDTO"]
end
subgraph "支付模块(Server)"
S1["支付订单实现"]
S2["退款实现"]
S3["转账实现"]
S4["钱包实现"]
end
A --> S1
B --> S2
C --> S3
D --> S4
E --> S1
E --> S2
E --> S3
图表来源
章节来源
核心组件
- 支付订单管理：创建支付单、查询支付单、价格更新。
- 退款处理：创建退款单、查询退款单。
- 转账管理：创建转账单、查询转账单。
- 钱包管理：获取或创建钱包、钱包余额充值。
- 支付结果通知：订单、退款、转账三类通知 DTO，用于第三方支付平台回调。
章节来源
架构总览
支付模块通过 Feign 客户端暴露 RPC 接口，服务名与前缀统一由 ApiConstants 提供，便于跨服务调用与网关路由。
sequenceDiagram
participant Client as "调用方"
participant PayAPI as "支付API接口"
participant PayImpl as "支付实现"
participant Biz as "业务服务"
Client->>PayAPI : "调用 RPC 接口"
PayAPI->>PayImpl : "转发到实现类"
PayImpl->>Biz : "执行业务逻辑"
Biz-->>PayImpl : "返回结果"
PayImpl-->>PayAPI : "封装通用响应"
PayAPI-->>Client : "返回结果"
图表来源
详细组件分析
支付订单管理
-
接口列表
- 创建支付单：POST /pay/order/create
- 查询支付单：GET /pay/order/get?id={id}
- 更新支付订单价格：PUT /pay/order/update-price?id={id}&payPrice={payPrice}
-
请求参数
- 创建支付单：应用标识、用户 IP、用户编号/类型、商户订单号、商品标题/描述、支付金额（分）、过期时间
- 查询支付单：支付单编号（id）
- 更新价格：支付单编号（id）、新的支付金额（分）
-
响应参数
- 支付单编号、渠道编码、商户订单号、商品标题、支付金额（分）、支付状态、成功时间、渠道用户编号、渠道订单号
-
调用序列图
sequenceDiagram
participant Client as "客户端"
participant API as "PayOrderApi"
participant Impl as "PayOrderApiImpl"
participant OrderSvc as "支付订单服务"
Client->>API : "POST /pay/order/create"
API->>Impl : "createOrder(reqDTO)"
Impl->>OrderSvc : "创建支付单并持久化"
OrderSvc-->>Impl : "返回支付单ID"
Impl-->>API : "CommonResult<Long>"
API-->>Client : "返回支付单ID"
Client->>API : "GET /pay/order/get?id={id}"
API->>Impl : "getOrder(id)"
Impl->>OrderSvc : "查询支付单详情"
OrderSvc-->>Impl : "返回PayOrderRespDTO"
Impl-->>API : "CommonResult<PayOrderRespDTO>"
API-->>Client : "返回支付单详情"
图表来源
章节来源
退款处理
-
接口列表
- 创建退款单：POST /pay/refund/create
- 查询退款单：GET /pay/refund/get?id={id}
-
请求参数
- 创建退款单：应用标识、用户 IP、用户编号/类型、商户订单号、商户退款号、退款原因、退款金额（分）
-
响应参数
- 退款单编号、渠道编码、退款状态、退款金额（分）、商户订单号、商户退款号、成功时间、渠道错误码/错误信息
-
流程图（退款申请 → 审核 → 执行）
flowchart TD
Start(["开始"]) --> Create["创建退款单"]
Create --> Audit{"审核通过？"}
Audit --> |否| Reject["拒绝并记录原因"]
Audit --> |是| Execute["执行退款"]
Execute --> Success["退款成功"]
Reject --> End(["结束"])
Success --> End
图表来源
章节来源
转账管理
-
接口列表
- 创建转账单：POST /pay/transfer/create
- 查询转账单：GET /pay/transfer/get?id={id}
-
请求参数
- 创建转账单：应用标识、用户 IP、用户编号/类型、转账金额（分）、转账摘要等（按 DTO 字段）
-
响应参数
- 转账单编号、渠道编码、转账状态、转账金额（分）、成功时间、渠道错误码/错误信息
-
序列图（余额转账）
sequenceDiagram
participant Client as "客户端"
participant API as "PayTransferApi"
participant Impl as "PayTransferApiImpl"
participant TransferSvc as "转账服务"
Client->>API : "POST /pay/transfer/create"
API->>Impl : "createTransfer(reqDTO)"
Impl->>TransferSvc : "校验余额并发起转账"
TransferSvc-->>Impl : "返回转账单ID与状态"
Impl-->>API : "CommonResult<PayTransferCreateRespDTO>"
API-->>Client : "返回转账结果"
图表来源
章节来源
钱包管理
-
接口列表
- 添加钱包余额：POST /pay/wallet/add-balance
- 获取或创建钱包：GET /pay/wallet/get-or-create?userId={id}&userType={type}
-
请求参数
- 添加余额：用户编号、用户类型、充值金额（分）、业务类型等（按 DTO 字段）
- 获取钱包：用户编号、用户类型
-
响应参数
- 钱包余额、冻结余额、可用余额、创建时间、更新时间等（按 DTO 字段）
-
序列图（充值）
sequenceDiagram
participant Client as "客户端"
participant API as "PayWalletApi"
participant Impl as "PayWalletApiImpl"
participant WalletSvc as "钱包服务"
Client->>API : "POST /pay/wallet/add-balance"
API->>Impl : "addWalletBalance(reqDTO)"
Impl->>WalletSvc : "增加余额并记账"
WalletSvc-->>Impl : "返回充值结果"
Impl-->>API : "CommonResult<Boolean>"
API-->>Client : "返回充值成功/失败"
图表来源
章节来源
支付结果通知
-
通知 DTO
- 订单通知：商户订单号、支付订单编号
- 退款通知：商户订单号、商户退款号、支付退款编号
- 转账通知：商户转账单号、转账订单编号
-
使用场景
- 第三方支付平台回调通知，支付/退款/转账完成后由平台推送至支付模块。
章节来源
依赖关系分析
- 统一前缀与服务名：所有 RPC 接口均使用 ApiConstants.PREFIX 作为前缀，NAME 作为服务名，便于网关与注册中心识别。
- 接口与实现：各 API 接口通过 FeignClient 注解绑定到服务名，实现类负责具体业务处理。
- DTO 规范：请求/响应 DTO 明确字段含义与约束，减少前后端歧义。
graph LR
Api["ApiConstants.PREFIX/NAME"] --> OrderAPI["PayOrderApi"]
Api --> RefundAPI["PayRefundApi"]
Api --> TransferAPI["PayTransferApi"]
Api --> WalletAPI["PayWalletApi"]
OrderAPI --> OrderImpl["PayOrderApiImpl"]
RefundAPI --> RefundImpl["PayRefundApiImpl"]
TransferAPI --> TransferImpl["PayTransferApiImpl"]
WalletAPI --> WalletImpl["PayWalletApiImpl"]
图表来源
章节来源
性能考虑
- DTO 校验前置：请求参数在 API 层即进行校验，减少无效调用进入业务层。
- 统一前缀与服务名：便于缓存、限流与监控策略集中配置。
- 分页查询：建议对退款/转账/钱包流水等列表接口采用分页参数，避免一次性返回大量数据。
- 幂等设计：对外暴露的创建接口需具备幂等能力，结合业务主键（如商户订单号/退款号）去重。
故障排查指南
-
常见错误码
- 参数校验失败：检查请求 DTO 字段是否为空、格式是否正确、范围是否合法。
- 服务不可达：确认服务名与前缀一致，网关路由配置正确。
- 业务异常：根据响应中的渠道错误码/错误信息定位第三方平台问题。
-
排查步骤
- 确认请求路径与方法是否匹配接口定义。
- 校验请求参数是否满足 DTO 约束。
- 查看服务日志与链路追踪，定位具体实现类与业务服务。
- 对于退款/转账，确认状态机流转是否符合预期。
结论
支付管理模块通过清晰的 RPC 接口与 DTO 规范，提供了支付订单、退款、转账与钱包的完整能力，并配套通知 DTO 支持第三方平台回调。建议在接入时严格遵循参数约束与调用流程，结合幂等与可观测性设计，确保支付流程稳定可靠。
附录
-
接口调用示例（示意）
- 创建支付单
- 方法：POST
- 路径：/pay/order/create
- 请求体：应用标识、用户IP、用户编号/类型、商户订单号、商品标题/描述、支付金额（分）、过期时间
- 返回：支付单ID
- 查询支付单
- 方法：GET
- 路径：/pay/order/get?id={id}
- 返回：支付单详情
- 创建退款单
- 方法：POST
- 路径：/pay/refund/create
- 请求体：应用标识、用户IP、用户编号/类型、商户订单号、商户退款号、退款原因、退款金额（分）
- 返回：退款单ID
- 查询退款单
- 方法：GET
- 路径：/pay/refund/get?id={id}
- 返回：退款单详情
- 创建转账单
- 方法：POST
- 路径：/pay/transfer/create
- 请求体：应用标识、用户IP、用户编号/类型、转账金额（分）、摘要等
- 返回：转账单ID与状态
- 查询转账单
- 方法：GET
- 路径：/pay/transfer/get?id={id}
- 返回：转账单详情
- 钱包充值
- 方法：POST
- 路径：/pay/wallet/add-balance
- 请求体：用户编号、用户类型、充值金额（分）、业务类型等
- 返回：充值成功/失败
- 获取或创建钱包
- 方法：GET
- 路径：/pay/wallet/get-or-create?userId={id}&userType={type}
- 返回：钱包信息
- 创建支付单
-
支付安全与风控要点（建议）
- 参数签名与防重放：对关键请求增加签名与时间戳校验。
- 限额与白名单：对单笔/单日限额与白名单进行校验。
- 回调验签：第三方回调需验证签名与参数一致性。
- 日志与审计：记录关键操作与异常，便于审计与回溯。