接口设计规范

**本文档引用的文件** - [承兑平台产品方案文档.md](file://承兑平台产品方案文档.md) - [决策变更清单.md](file://决策变更清单.md) - [待确认决策清单.md](file://待确认决策清单.md) - [文档/Readme.md](file://文档/Readme.md) - [任务和测试过程/Readme.md](file://任务和测试过程/Readme.md) - [AI沟通记录/2026-06-05-Chat.md](file://AI沟通记录/2026-06-05-Chat.md) - [Axure老的项目原型/【App】交易员/files/登录/data.js](file://Axure老的项目原型/【App】交易员/files/登录/data.js) - [Axure老的项目原型/【App】交易员/files/我的/data.js](file://Axure老的项目原型/【App】交易员/files/我的/data.js) - [Axure老的项目原型/【App】交易员/files/客户订单/data.js](file://Axure老的项目原型/【App】交易员/files/客户订单/data.js)

引言

本接口设计规范面向承兑平台的对外API设计，旨在为商户端、交易员端、运营后台等角色提供统一、安全、可扩展的接口标准。文档基于项目需求分析，明确了系统对外接口的设计原则、命名规范、参数约定，解释了RESTful API设计模式、请求响应格式、错误码定义、版本控制策略，并提供了接口文档模板、Swagger规范、Postman集合的使用指导。

项目结构

承兑平台采用前后端分离架构，前端通过Axure原型展示交互流程，后端提供RESTful API供前端调用。项目文档包含产品方案、决策清单、任务清单等，支撑接口设计的业务背景与约束。

mermaid

graph TB
subgraph "前端"
UI[用户界面]
Router[路由]
end
subgraph "后端"
API[API服务器]
Auth[认证服务]
DB[(数据库)]
end
UI --> API
API --> Auth
API --> DB

图表来源

[承兑平台产品方案文档.md:299-331](file://承兑平台产品方案文档.md#L299-L331)

章节来源

[承兑平台产品方案文档.md:1-100](file://承兑平台产品方案文档.md#L1-L100)
[文档/Readme.md:1-3](file://文档/Readme.md#L1-L3)

核心组件

订单中心：负责入金/出金订单的创建、指派、锁定、确认、完成、取消等全流程管理。
账户中心：提供商户/交易员的注册、USDT充值提现、余额查询、资金流水等功能。
费率引擎：实现两套报价体系（对外报价与交易员结算价）与三层级配置（平台基准、交易员偏移、商户加点）。
钱包中心：管理充值地址、链上交互、内部划转、提现审核、冷热钱包等。
通知中心：提供站内信、短信、邮件、Webhook等通知能力。
数据报表中心：提供实时交易数据、财务统计、交易员绩效、商户分析等报表。

章节来源

[承兑平台产品方案文档.md:333-329](file://承兑平台产品方案文档.md#L333-L329)

架构概览

承兑平台采用分层混合托管的资金模型，结合中心化数据库与链上钱包，实现毫秒级内部划转与链上充值提现的分离。系统通过API网关统一接入，前端通过Axure原型进行交互设计，后端提供RESTful API。

mermaid

graph TB
subgraph "前端应用"
Merchant[商户端]
Trader[交易员端]
Admin[运营后台]
end
subgraph "API网关"
Gateway[API网关]
end
subgraph "业务中台"
Order[订单中心]
Account[账户中心]
Rate[费率引擎]
Risk[风控中心]
Notify[通知中心]
end
subgraph "基础设施"
DB[(数据库)]
Wallet[钱包服务]
Cache[(缓存)]
MQ[(消息队列)]
end
Merchant --> Gateway
Trader --> Gateway
Admin --> Gateway
Gateway --> Order
Gateway --> Account
Gateway --> Rate
Gateway --> Risk
Gateway --> Notify
Order --> DB
Account --> DB
Rate --> DB
Risk --> DB
Notify --> DB
Order --> Wallet
Account --> Wallet
Order --> Cache
Account --> Cache
Order --> MQ
Account --> MQ

图表来源

[承兑平台产品方案文档.md:299-331](file://承兑平台产品方案文档.md#L299-L331)

详细组件分析

订单中心接口设计

订单中心提供入金/出金订单的完整生命周期管理，支持批量出金、指派调度、异常订单处理等功能。

mermaid

classDiagram
class OrderController {
+createOrder(orderRequest) OrderResponse
+assignOrder(orderId) AssignResponse
+lockOrder(orderId) LockResponse
+confirmOrder(orderId) ConfirmResponse
+completeOrder(orderId) CompleteResponse
+cancelOrder(orderId) CancelResponse
+batchOutOrder(batchRequest) BatchResponse
}
class OrderService {
+processOrder(order) Order
+calculateRate(order) RateCalculation
+releaseLock(order) void
+notifyOrderStatus(order) void
}
class OrderRepository {
+save(order) Order
+findById(id) Order
+findByCriteria(criteria) Order[]
+updateStatus(orderId, status) void
}
OrderController --> OrderService : "调用"
OrderService --> OrderRepository : "持久化"

图表来源

[承兑平台产品方案文档.md:335-344](file://承兑平台产品方案文档.md#L335-L344)

章节来源

[承兑平台产品方案文档.md:335-344](file://承兑平台产品方案文档.md#L335-L344)

账户中心接口设计

账户中心提供商户与交易员的账户管理、充值提现、余额查询、资金流水等功能。

mermaid

classDiagram
class AccountController {
+registerAccount(registerRequest) RegisterResponse
+depositUSDT(depositRequest) DepositResponse
+withdrawUSDT(withdrawRequest) WithdrawResponse
+getBalance(accountId) BalanceResponse
+getTransactionHistory(query) TransactionListResponse
}
class AccountService {
+validateKYC(user) boolean
+checkRiskLevel(user) RiskLevel
+processDeposit(transaction) Transaction
+processWithdraw(transaction) Transaction
+updateBalance(accountId, amount) void
}
class AccountRepository {
+save(account) Account
+findById(id) Account
+findByUserId(userId) Account
+findTransactionsByCriteria(criteria) Transaction[]
}
AccountController --> AccountService : "调用"
AccountService --> AccountRepository : "持久化"

图表来源

[承兑平台产品方案文档.md:485-494](file://承兑平台产品方案文档.md#L485-L494)

章节来源

[承兑平台产品方案文档.md:485-494](file://承兑平台产品方案文档.md#L485-L494)

费率引擎接口设计

费率引擎实现两套报价体系与三层级配置，支持基准报价、交易员偏移、商户加点等配置。

mermaid

classDiagram
class RateController {
+getExchangeRate() ExchangeRateResponse
+getConfiguredRate() ConfiguredRateResponse
+setPlatformBidAsk(bidAskRequest) BidAskResponse
+setTraderOffset(offsetRequest) OffsetResponse
+setMerchantSpread(spreadRequest) SpreadResponse
}
class RateService {
+calculateBidAsk(platformConfig) BidAsk
+applyTraderOffset(traderConfig, baseRate) BidAsk
+applyMerchantSpread(merchantConfig, traderRate) FinalRate
+validateRateConstraints(rate) boolean
}
class RateRepository {
+savePlatformConfig(config) PlatformConfig
+saveTraderConfig(config) TraderConfig
+saveMerchantConfig(config) MerchantConfig
+findLatestPlatformConfig() PlatformConfig
}
RateController --> RateService : "调用"
RateService --> RateRepository : "持久化"

图表来源

[承兑平台产品方案文档.md:346-377](file://承兑平台产品方案文档.md#L346-L377)

章节来源

[承兑平台产品方案文档.md:346-377](file://承兑平台产品方案文档.md#L346-L377)

钱包中心接口设计

钱包中心管理充值地址、链上交互、内部划转、提现审核、冷热钱包等。

mermaid

classDiagram
class WalletController {
+generateDepositAddress(addressRequest) AddressResponse
+listenChainConfirmation(address) void
+internalTransfer(transferRequest) TransferResponse
+approveWithdraw(withdrawId) ApproveResponse
+getHotWalletBalance() BalanceResponse
+getColdWalletBalance() BalanceResponse
}
class WalletService {
+generateUniqueAddress(userId, chain) Address
+monitorChain(confirmCallback) void
+executeInternalTransfer(transfer) void
+executeWithdraw(withdraw) void
+rebalanceHotWallet() void
}
class WalletRepository {
+saveAddress(address) Address
+findByUserId(userId) Address[]
+findHotWallet() Wallet
+findColdWallet() Wallet
}
WalletController --> WalletService : "调用"
WalletService --> WalletRepository : "持久化"

图表来源

[承兑平台产品方案文档.md:485-494](file://承兑平台产品方案文档.md#L485-L494)

章节来源

[承兑平台产品方案文档.md:485-494](file://承兑平台产品方案文档.md#L485-L494)

依赖分析

系统采用模块化设计，各组件通过API进行解耦，依赖关系清晰：

mermaid

graph LR
OrderCenter[订单中心] --> AccountCenter[账户中心]
OrderCenter --> RateEngine[费率引擎]
OrderCenter --> WalletCenter[钱包中心]
AccountCenter --> WalletCenter
RateEngine --> Database[(数据库)]
OrderCenter --> Database
AccountCenter --> Database
WalletCenter --> Database
WalletCenter --> Blockchain[区块链节点]

图表来源

[承兑平台产品方案文档.md:299-331](file://承兑平台产品方案文档.md#L299-L331)

章节来源

[承兑平台产品方案文档.md:299-331](file://承兑平台产品方案文档.md#L299-L331)

性能考虑

缓存策略：使用Redis缓存热点数据（汇率、地址、配置），减少数据库压力
异步处理：订单状态变更、通知发送采用消息队列异步处理
数据库优化：合理设计索引，分表分库处理大流量
CDN加速：静态资源通过CDN分发，提升访问速度

故障排除指南

接口超时：检查数据库连接池配置，优化慢查询SQL
并发冲突：使用分布式锁防止重复下单，实现幂等性设计
链上交互失败：监控区块链节点状态，实现重试机制
缓存雪崩：设置合理的缓存过期时间，使用分布式锁更新缓存

章节来源

[决策变更清单.md:127-133](file://决策变更清单.md#L127-L133)

结论

本接口设计规范为承兑平台提供了完整的API设计标准，涵盖了从订单管理到账户服务、从费率配置到钱包交互的全业务流程。通过标准化的接口设计、严格的错误处理、完善的性能优化策略，确保系统能够稳定、安全、高效地支撑业务发展。

附录

接口设计原则

一致性：统一的请求响应格式，保持接口风格一致
可扩展性：预留扩展字段，支持未来功能扩展
安全性：实现身份认证、权限控制、数据加密
可靠性：实现幂等性、重试机制、错误恢复

命名规范

HTTP方法：GET（查询）、POST（创建）、PUT（更新）、DELETE（删除）
URL命名：使用名词复数形式，如 /api/v1/orders
参数命名：使用驼峰命名法，如 orderId、userId
状态码：遵循HTTP标准状态码语义

参数约定

必填参数：在接口文档中标注required字段
参数验证：实现参数类型、长度、格式验证
默认值：为可选参数设置合理的默认值
参数范围：对数值型参数设置合理的取值范围

请求响应格式

请求体：JSON格式，UTF-8编码
响应体：统一的响应结构，包含状态码、消息、数据体
时间格式：ISO 8601标准格式
分页参数：page（页码）、pageSize（每页条数）

错误码定义

通用错误码：1000-1999（系统级别错误）
业务错误码：2000-2999（业务逻辑错误）
参数错误码：3000-3999（参数验证错误）
权限错误码：4000-4999（权限相关错误）

版本控制策略

版本号：/api/v{version}/形式
向后兼容：新增接口不破坏现有接口
弃用策略：提供过渡期，提前通知接口变更
文档更新：每次版本升级同步更新API文档

接口文档模板

markdown

# 接口名称

## 请求地址
`POST /api/v1/orders`

## 请求头
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| Content-Type | string | 是 | application/json |
| Authorization | string | 是 | Bearer token |

## 请求参数
| 参数名 | 类型 | 必填 | 描述 | 示例 |
|--------|------|------|------|------|
| orderId | string | 是 | 订单ID | 123456789 |
| amount | number | 是 | 金额 | 1000.00 |

## 响应参数
| 参数名 | 类型 | 必填 | 描述 | 示例 |
|--------|------|------|------|------|
| code | number | 是 | 状态码 | 200 |
| message | string | 是 | 响应消息 | success |
| data | object | 否 | 响应数据 | {} |

## 状态码
- 200: 请求成功
- 400: 参数错误
- 401: 未授权
- 500: 系统错误

Swagger规范

基本信息：项目名称、版本、描述、联系信息
安全定义：API Key、Bearer Token等认证方式
标签分类：按功能模块组织接口文档
示例请求：提供完整的请求示例
响应示例：提供标准的响应示例

Postman集合

环境配置：开发、测试、生产环境变量
集合结构：按模块组织请求集合
前置脚本：实现签名、时间戳等预处理
测试脚本：验证响应状态、数据格式
导入导出：支持JSON格式导入导出

接口调用示例

商户下单：商户通过API发起入金/出金订单
交易员接单：交易员通过App接收订单通知
资金划转：系统自动执行USDT内部划转
状态通知：通过Webhook通知商户订单状态变化

参数校验规则

必填校验：检查必需参数是否存在
类型校验：验证参数数据类型是否正确
范围校验：检查数值是否在允许范围内
格式校验：验证字符串格式是否符合要求
业务校验：检查业务逻辑是否成立

权限控制机制

角色权限：区分商户、交易员、运营管理员权限
接口权限：基于角色控制接口访问权限
数据权限：限制用户只能访问自己的数据
操作权限：控制用户对数据的操作权限

接口安全性设计

传输安全：HTTPS加密传输，防止数据泄露
身份认证：JWT Token认证，支持多设备登录
权限控制：RBAC权限模型，细粒度权限控制
数据加密：敏感数据加密存储，传输过程加密
防重放：时间戳+随机数防重放攻击
限流策略：IP维度限流，防止恶意刷单

限流策略

令牌桶算法：平滑限流，支持突发流量
滑动窗口：精确控制请求频率
分布式限流：基于Redis实现分布式限流
动态限流：根据系统负载动态调整限流阈值

缓存机制

多级缓存：本地缓存+分布式缓存+数据库缓存
缓存策略：LRU淘汰，热点数据优先缓存
缓存更新：写时更新，读时失效
缓存穿透：布隆过滤器+空值缓存
缓存雪崩：随机过期时间，分布式锁更新

监控指标

接口指标：QPS、响应时间、错误率
系统指标：CPU、内存、磁盘、网络
业务指标：订单量、成交额、用户活跃度
告警指标：异常阈值、SLA指标、容量预警
日志指标：访问日志、错误日志、审计日志

章节来源

[决策变更清单.md:107-163](file://决策变更清单.md#L107-L163)
[待确认决策清单.md:280-322](file://待确认决策清单.md#L280-L322)

接口设计规范 ​

目录 ​

引言 ​

项目结构 ​

核心组件 ​

架构概览 ​

详细组件分析 ​

订单中心接口设计 ​

账户中心接口设计 ​

费率引擎接口设计 ​

钱包中心接口设计 ​

依赖分析 ​

性能考虑 ​

故障排除指南 ​

结论 ​

附录 ​

接口设计原则 ​

命名规范 ​

参数约定 ​

请求响应格式 ​

错误码定义 ​

版本控制策略 ​

接口文档模板 ​

Swagger规范 ​

Postman集合 ​

接口调用示例 ​

参数校验规则 ​

权限控制机制 ​

接口安全性设计 ​

限流策略 ​

缓存机制 ​

监控指标 ​

接口设计规范

目录

引言

项目结构

核心组件

架构概览

详细组件分析

订单中心接口设计

账户中心接口设计

费率引擎接口设计

钱包中心接口设计

依赖分析

性能考虑

故障排除指南

结论

附录

接口设计原则

命名规范

参数约定

请求响应格式

错误码定义

版本控制策略

接口文档模板

Swagger规范

Postman集合

接口调用示例

参数校验规则

权限控制机制

接口安全性设计

限流策略

缓存机制

监控指标