# 支付管理API

<cite>
**本文引用的文件**
- [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)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件为支付管理模块的 API 接口文档，覆盖支付订单管理、退款处理、转账管理、钱包管理等核心能力，并补充支付结果通知接口与支付渠道集成要点。文档面向开发者与产品/测试人员，提供接口定义、参数说明、调用流程与异常处理建议。

## 项目结构
支付模块采用“API + Server”分层设计：
- API 层：定义 RPC 接口与 DTO，统一版本前缀与服务名。
- Server 层：实现具体业务逻辑，提供 HTTP 控制器与 RPC 实现。

```mermaid
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
```

图表来源
- [支付模块 API 常量](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/enums/ApiConstants.java#L10-L23)
- [支付订单 API 接口](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/order/PayOrderApi.java#L17-L42)
- [退款 API 接口](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/refund/PayRefundApi.java#L18-L33)
- [转账 API 接口](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/transfer/PayTransferApi.java#L19-L34)
- [钱包 API 接口](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/wallet/PayWalletApi.java#L18-L38)

章节来源
- [viewsh-module-pay-api 包说明](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/package-info.java#L1-L10)

## 核心组件
- 支付订单管理：创建支付单、查询支付单、价格更新。
- 退款处理：创建退款单、查询退款单。
- 转账管理：创建转账单、查询转账单。
- 钱包管理：获取或创建钱包、钱包余额充值。
- 支付结果通知：订单、退款、转账三类通知 DTO，用于第三方支付平台回调。

章节来源
- [支付订单 API 接口](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/order/PayOrderApi.java#L17-L42)
- [退款 API 接口](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/refund/PayRefundApi.java#L18-L33)
- [转账 API 接口](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/transfer/PayTransferApi.java#L19-L34)
- [钱包 API 接口](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/wallet/PayWalletApi.java#L18-L38)
- [支付通知 DTO：订单](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/notify/dto/PayOrderNotifyReqDTO.java#L15-L33)
- [支付通知 DTO：退款](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/notify/dto/PayRefundNotifyReqDTO.java#L14-L39)
- [支付通知 DTO：转账](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/notify/dto/PayTransferNotifyReqDTO.java#L14-L33)

## 架构总览
支付模块通过 Feign 客户端暴露 RPC 接口，服务名与前缀统一由 ApiConstants 提供，便于跨服务调用与网关路由。

```mermaid
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 : "返回结果"
```

图表来源
- [支付模块 API 常量](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/enums/ApiConstants.java#L10-L23)
- [支付订单 API 接口](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/order/PayOrderApi.java#L17-L42)
- [退款 API 接口](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/refund/PayRefundApi.java#L18-L33)
- [转账 API 接口](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/transfer/PayTransferApi.java#L19-L34)
- [钱包 API 接口](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/wallet/PayWalletApi.java#L18-L38)

## 详细组件分析

### 支付订单管理
- 接口列表
  - 创建支付单：POST /pay/order/create
  - 查询支付单：GET /pay/order/get?id={id}
  - 更新支付订单价格：PUT /pay/order/update-price?id={id}&payPrice={payPrice}

- 请求参数
  - 创建支付单：应用标识、用户 IP、用户编号/类型、商户订单号、商品标题/描述、支付金额（分）、过期时间
  - 查询支付单：支付单编号（id）
  - 更新价格：支付单编号（id）、新的支付金额（分）

- 响应参数
  - 支付单编号、渠道编码、商户订单号、商品标题、支付金额（分）、支付状态、成功时间、渠道用户编号、渠道订单号

- 调用序列图
```mermaid
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 : "返回支付单详情"
```

图表来源
- [支付订单 API 接口](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/order/PayOrderApi.java#L23-L41)
- [支付订单创建请求 DTO](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/order/dto/PayOrderCreateReqDTO.java#L17-L78)
- [支付订单响应 DTO](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/order/dto/PayOrderRespDTO.java#L14-L68)

章节来源
- [支付订单 API 接口](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/order/PayOrderApi.java#L17-L42)
- [支付订单创建请求 DTO](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/order/dto/PayOrderCreateReqDTO.java#L17-L78)
- [支付订单响应 DTO](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/order/dto/PayOrderRespDTO.java#L14-L68)

### 退款处理
- 接口列表
  - 创建退款单：POST /pay/refund/create
  - 查询退款单：GET /pay/refund/get?id={id}

- 请求参数
  - 创建退款单：应用标识、用户 IP、用户编号/类型、商户订单号、商户退款号、退款原因、退款金额（分）

- 响应参数
  - 退款单编号、渠道编码、退款状态、退款金额（分）、商户订单号、商户退款号、成功时间、渠道错误码/错误信息

- 流程图（退款申请 → 审核 → 执行）
```mermaid
flowchart TD
Start(["开始"]) --> Create["创建退款单"]
Create --> Audit{"审核通过？"}
Audit --> |否| Reject["拒绝并记录原因"]
Audit --> |是| Execute["执行退款"]
Execute --> Success["退款成功"]
Reject --> End(["结束"])
Success --> End
```

图表来源
- [退款 API 接口](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/refund/PayRefundApi.java#L24-L31)
- [退款订单创建请求 DTO](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/refund/dto/PayRefundCreateReqDTO.java#L16-L70)
- [退款订单响应 DTO](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/refund/dto/PayRefundRespDTO.java#L14-L65)

章节来源
- [退款 API 接口](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/refund/PayRefundApi.java#L18-L33)
- [退款订单创建请求 DTO](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/refund/dto/PayRefundCreateReqDTO.java#L16-L70)
- [退款订单响应 DTO](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/refund/dto/PayRefundRespDTO.java#L14-L65)

### 转账管理
- 接口列表
  - 创建转账单：POST /pay/transfer/create
  - 查询转账单：GET /pay/transfer/get?id={id}

- 请求参数
  - 创建转账单：应用标识、用户 IP、用户编号/类型、转账金额（分）、转账摘要等（按 DTO 字段）

- 响应参数
  - 转账单编号、渠道编码、转账状态、转账金额（分）、成功时间、渠道错误码/错误信息

- 序列图（余额转账）
```mermaid
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 : "返回转账结果"
```

图表来源
- [转账 API 接口](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/transfer/PayTransferApi.java#L25-L33)
- [转账订单创建请求 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)

章节来源
- [转账 API 接口](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/transfer/PayTransferApi.java#L19-L34)
- [转账订单创建请求 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)

### 钱包管理
- 接口列表
  - 添加钱包余额：POST /pay/wallet/add-balance
  - 获取或创建钱包：GET /pay/wallet/get-or-create?userId={id}&userType={type}

- 请求参数
  - 添加余额：用户编号、用户类型、充值金额（分）、业务类型等（按 DTO 字段）
  - 获取钱包：用户编号、用户类型

- 响应参数
  - 钱包余额、冻结余额、可用余额、创建时间、更新时间等（按 DTO 字段）

- 序列图（充值）
```mermaid
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 : "返回充值成功/失败"
```

图表来源
- [钱包 API 接口](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/wallet/PayWalletApi.java#L24-L36)
- [钱包充值请求 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)

章节来源
- [钱包 API 接口](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/wallet/PayWalletApi.java#L18-L38)
- [钱包充值请求 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
  - 订单通知：商户订单号、支付订单编号
  - 退款通知：商户订单号、商户退款号、支付退款编号
  - 转账通知：商户转账单号、转账订单编号

- 使用场景
  - 第三方支付平台回调通知，支付/退款/转账完成后由平台推送至支付模块。

章节来源
- [支付通知 DTO：订单](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/notify/dto/PayOrderNotifyReqDTO.java#L15-L33)
- [支付通知 DTO：退款](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/notify/dto/PayRefundNotifyReqDTO.java#L14-L39)
- [支付通知 DTO：转账](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/notify/dto/PayTransferNotifyReqDTO.java#L14-L33)

## 依赖关系分析
- 统一前缀与服务名：所有 RPC 接口均使用 ApiConstants.PREFIX 作为前缀，NAME 作为服务名，便于网关与注册中心识别。
- 接口与实现：各 API 接口通过 FeignClient 注解绑定到服务名，实现类负责具体业务处理。
- DTO 规范：请求/响应 DTO 明确字段含义与约束，减少前后端歧义。

```mermaid
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"]
```

图表来源
- [支付模块 API 常量](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/enums/ApiConstants.java#L10-L23)
- [支付订单 API 接口](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/order/PayOrderApi.java#L17-L42)
- [退款 API 接口](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/refund/PayRefundApi.java#L18-L33)
- [转账 API 接口](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/transfer/PayTransferApi.java#L19-L34)
- [钱包 API 接口](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/api/wallet/PayWalletApi.java#L18-L38)

章节来源
- [支付模块 API 常量](file://viewsh-module-pay/viewsh-module-pay-api/src/main/java/com/viewsh/module/pay/enums/ApiConstants.java#L10-L23)

## 性能考虑
- DTO 校验前置：请求参数在 API 层即进行校验，减少无效调用进入业务层。
- 统一前缀与服务名：便于缓存、限流与监控策略集中配置。
- 分页查询：建议对退款/转账/钱包流水等列表接口采用分页参数，避免一次性返回大量数据。
- 幂等设计：对外暴露的创建接口需具备幂等能力，结合业务主键（如商户订单号/退款号）去重。

## 故障排查指南
- 常见错误码
  - 参数校验失败：检查请求 DTO 字段是否为空、格式是否正确、范围是否合法。
  - 服务不可达：确认服务名与前缀一致，网关路由配置正确。
  - 业务异常：根据响应中的渠道错误码/错误信息定位第三方平台问题。

- 排查步骤
  1) 确认请求路径与方法是否匹配接口定义。
  2) 校验请求参数是否满足 DTO 约束。
  3) 查看服务日志与链路追踪，定位具体实现类与业务服务。
  4) 对于退款/转账，确认状态机流转是否符合预期。

## 结论
支付管理模块通过清晰的 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}
    - 返回：钱包信息

- 支付安全与风控要点（建议）
  - 参数签名与防重放：对关键请求增加签名与时间戳校验。
  - 限额与白名单：对单笔/单日限额与白名单进行校验。
  - 回调验签：第三方回调需验证签名与参数一致性。
  - 日志与审计：记录关键操作与异常，便于审计与回溯。