承兑平台在线文档

Appearance

数据模型设计 ​

**本文引用的文件** - [决策变更清单.md](file://决策变更清单.md) - [待确认决策清单.md](file://待确认决策清单.md) - [承兑平台产品方案文档.md](file://承兑平台产品方案文档.md) - [综合审查报告.md](file://综合审查报告.md)

目录 ​

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

简介 ​

本文件围绕“承兑平台”的数据模型设计展开，结合决策变更清单与产品方案文档中的数据相关条款，系统梳理核心数据实体、实体关系、数据字典、主键/外键与索引设计、约束与验证规则、业务规则与数据完整性、数据访问模式与缓存策略、性能与容量规划、数据生命周期与归档策略、数据迁移与版本管理、数据安全与隐私要求等。旨在为数据库设计、API与服务实现提供可落地的数据蓝图。

项目结构 ​

  • 仓库包含产品方案、决策变更、待确认决策、综合审查报告以及原型文件等，为数据模型设计提供了充分的业务背景与约束条件。
  • 数据模型设计以“订单、用户（商户/交易员）、汇率、风控规则、钱包与资金流水”为核心，围绕“做市商+撮合平台”的价差盈利模型构建。
mermaid
graph TB
subgraph "业务域"
Orders["订单域<br/>入金/出金/批量"]
Users["用户域<br/>商户/交易员/代理/介绍人"]
Rates["汇率与费率域<br/>基准/偏移/加点/手续费"]
Risk["风控域<br/>KYC/限额/反欺诈/旅行规则"]
Wallet["钱包域<br/>地址/链上交互/多签"]
Notify["通知域<br/>站内信/短信/邮件/Webhook"]
end
subgraph "数据存储"
DB["数据库(中心化)"]
Cache["缓存(Redis)"]
Chain["链上节点/钱包"]
end
Orders --> DB
Users --> DB
Rates --> DB
Risk --> DB
Wallet --> Chain
DB --> Cache
DB --> Orders
DB --> Users
DB --> Rates
DB --> Risk
DB --> Wallet
DB --> Notify

章节来源

  • [承兑平台产品方案文档.md:1-800](file://承兑平台产品方案文档.md#L1-L800)

核心组件 ​

  • 订单中心：入金/出金/批量订单、状态机、指派与异常处理。
  • 账户中心：商户账户、交易员账户、冻结余额管理、资金流水。
  • 费率引擎：基准报价、交易员偏移、商户加点、手续费与点差计算。
  • 风控中心：KYC/限额/反欺诈/旅行规则/制裁名单。
  • 钱包中心：地址管理、链上交互、冷热钱包、多签管理。
  • 通知中心：站内信、短信/邮件、Webhook。

章节来源

  • [承兑平台产品方案文档.md:295-495](file://承兑平台产品方案文档.md#L295-L495)

架构总览 ​

  • 数据流：终端用户→商户→平台→交易员，平台内部以USDT记账，不直接持有法币。
  • 资金流：入金锁定交易员USDT，出金锁定商户USDT，风控审核通过后释放。
  • 技术栈：PostgreSQL + Redis；链上节点/钱包服务；短信/邮件/通知服务；Webhook回调。
mermaid
graph LR
U["终端用户"] --> M["商户(外汇平台)"]
M --> P["承兑平台"]
P --> T["交易员"]
P --> D["数据库"]
P --> L["链上钱包服务"]
P --> N["通知服务"]
D --> C["缓存(Redis)"]
L --> D
N --> M
N --> U

章节来源

  • [承兑平台产品方案文档.md:497-595](file://承兑平台产品方案文档.md#L497-L595)

详细组件分析 ​

订单实体设计 ​

  • 实体：订单（入金/出金/批量）、订单状态、订单指派记录。
  • 关键属性：订单ID（幂等）、类型、状态、金额、汇率、手续费、创建/更新时间、指派/完成/取消时间。
  • 约束与规则：
    • 幂等性：商户侧订单ID幂等，重复请求返回相同结果。
    • 指派规则：交易员余额充足、在线、未超接单量。
    • 超时处理：阶梯超时（用户确认→交易员确认），超时自动释放并重新指派。
    • 批量出金：支持Excel模板导入，批次释放需考虑汇率波动与U池锁定安全边际。
  • 索引建议：
    • 订单ID（唯一）
    • 商户ID/交易员ID/状态/创建时间
    • 汇率/手续费字段建立二级索引以支持查询与报表
  • 业务规则：
    • 入金：USDT从交易员冻结余额划转至商户账户，平台留存差额。
    • 出金：USDT从商户冻结余额划转至交易员账户，风控审核通过后释放。
mermaid
erDiagram
ORDER {
uuid id PK
string merchant_order_id UK
enum type
enum status
decimal amount_usdt
decimal amount_cny
decimal exchange_rate
decimal fee_usdt
uuid merchant_id FK
uuid trader_id FK
uuid batch_id FK
timestamp created_at
timestamp updated_at
}
MERCHANT {
uuid id PK
string name
string account_no
decimal balance_usdt
decimal frozen_balance_usdt
enum status
}
TRADER {
uuid id PK
string real_name
string id_card_no
string bank_account_no
decimal balance_usdt
decimal frozen_balance_usdt
enum status
}
BATCH_OUT {
uuid id PK
int total_count
int success_count
enum status
timestamp settle_at
}
ORDER }|--|| MERCHANT : "属于"
ORDER }|--|| TRADER : "指派/完成"
ORDER }|--|| BATCH_OUT : "属于"

图表来源

  • [承兑平台产品方案文档.md:1718-1746](file://承兑平台产品方案文档.md#L1718-L1746)

章节来源

  • [承兑平台产品方案文档.md:156-295](file://承兑平台产品方案文档.md#L156-L295)
  • [决策变更清单.md:67-105](file://决策变更清单.md#L67-L105)

用户实体设计 ​

  • 实体：商户、交易员、代理、介绍人。
  • 关键属性：主体信息、账户余额、冻结余额、状态、KYC/KYB信息、收款账户、接单限额、等级/分润比例。
  • 约束与规则：
    • 交易员需预存保证金（可配置），绑定有效收款账户，通过风控审核。
    • 商户可配置专属费率、交易员点差、加点上限。
    • 代理/介绍人无资金操作，仅统计与返佣。
  • 索引建议：
    • 用户ID（唯一）
    • 身份证/银行卡号（唯一性约束）
    • 商户/交易员等级/状态
  • 业务规则：
    • 交易员收益=买卖价差+补助，平台通过点差与手续费抽成。
    • 商户加点用于调节流动性，不得超过上限。
mermaid
erDiagram
MERCHANT {
uuid id PK
string name
string legal_entity_no
decimal balance_usdt
decimal frozen_balance_usdt
enum status
}
TRADER {
uuid id PK
string real_name
string id_card_no UK
string bank_account_no
decimal balance_usdt
decimal frozen_balance_usdt
enum status
enum level
}
AGENT {
uuid id PK
string name
decimal commission_ratio
}
INTRODUCER {
uuid id PK
string name
decimal reward_ratio
}

图表来源

  • [承兑平台产品方案文档.md:83-143](file://承兑平台产品方案文档.md#L83-L143)

章节来源

  • [承兑平台产品方案文档.md:83-143](file://承兑平台产品方案文档.md#L83-L143)
  • [决策变更清单.md:13-36](file://决策变更清单.md#L13-L36)

汇率与费率实体设计 ​

  • 实体：基准报价、交易员偏移、商户加点、手续费规则、点差分级。
  • 关键属性：基准bid/ask、交易员bid/ask偏移、商户入金加点/出金减点、手续费率、分级阈值。
  • 约束与规则：
    • 价格关系：对外ask > 交易员ask > 交易员bid > 对外bid。
    • 商户加点上限（默认1%，超0.5%提醒）。
    • 报价偏离仅告警，不自动干预。
  • 索引建议：
    • 基准报价时间戳
    • 商户ID/交易员等级
  • 业务规则：
    • 汇率查询返回含商户加点后的最终汇率；不提供独立纯基准汇率接口。
    • 费率变更立即生效，仅对新订单有效。
mermaid
erDiagram
RATE_BASE {
uuid id PK
decimal bid
decimal ask
timestamp updated_at
}
TRADER_OFFSET {
uuid id PK
uuid trader_level
decimal bid_offset
decimal ask_offset
}
MERCHANT_MARKUP {
uuid id PK
uuid merchant_id FK
decimal inbound_markup
decimal outbound_discount
decimal max_markup
}
FEE_RULE {
uuid id PK
enum category
decimal rate_percent
decimal fixed_usdt
}

图表来源

  • [承兑平台产品方案文档.md:346-461](file://承兑平台产品方案文档.md#L346-L461)
  • [决策变更清单.md:46-62](file://决策变更清单.md#L46-L62)

章节来源

  • [承兑平台产品方案文档.md:346-461](file://承兑平台产品方案文档.md#L346-L461)
  • [决策变更清单.md:46-62](file://决策变更清单.md#L46-L62)

风控规则实体设计 ​

  • 实体：KYC/限额/反欺诈/旅行规则/制裁名单。
  • 关键属性：用户画像、风险等级、限额阈值、反欺诈规则、旅行规则字段、制裁名单匹配结果。
  • 约束与规则：
    • V1采用OFAC SDN List本地匹配。
    • 旅行规则V1实现数据采集框架，记录发收方信息。
    • 单卡风控：24h收款人上限、可配置释放间隔、同地区优先。
  • 索引建议：
    • 身份证/银行卡号/国家/地区
    • 风控规则ID/阈值
  • 业务规则：
    • 报价偏离仅告警；U池锁定105%+锁定期间冻结商户提现；挂起超4h告警。
mermaid
erDiagram
KYC_PROFILE {
uuid id PK
uuid user_id FK
string id_card_no
string face_photo_url
enum risk_level
}
RISK_LIMIT {
uuid id PK
uuid role_type
decimal daily_max
decimal monthly_max
}
TRAVEL_RULE {
uuid id PK
uuid order_id FK
json sender_info
json receiver_info
}
SANCTIONS_LIST {
uuid id PK
string entity_name
string entity_type
string list_type
}

图表来源

  • [综合审查报告.md:173-247](file://综合审查报告.md#L173-L247)
  • [决策变更清单.md:142-164](file://决策变更清单.md#L142-L164)

章节来源

  • [综合审查报告.md:173-247](file://综合审查报告.md#L173-L247)
  • [决策变更清单.md:142-164](file://决策变更清单.md#L142-L164)

钱包与资金流水实体设计 ​

  • 实体：钱包地址、链上交互、内部划转、提现审核。
  • 关键属性：链类型（TRC20/ERC20/BEP20）、地址、链上状态、内部余额、冻结余额、提现申请与审核。
  • 约束与规则：
    • 独立地址（HD Wallet），每用户每链独立地址，无需Memo。
    • 热钱包日常周转，冷钱包多签大额储备。
    • 冷热分离、多签管理、限额与归集策略。
  • 索引建议：
    • 地址/链类型/用户ID
    • 提现申请状态/审核时间
  • 业务规则：
    • 充值确认链上确认后更新数据库余额；提现审核通过后链上转账。
mermaid
erDiagram
WALLET_ADDRESS {
uuid id PK
uuid user_id FK
string chain_type
string address
enum status
}
CHAIN_TXN {
uuid id PK
string tx_hash
string chain_type
string from_address
string to_address
decimal amount_usdt
int confirmations
timestamp confirmed_at
}
INTERNAL_TRANSFER {
uuid id PK
uuid from_user_id FK
uuid to_user_id FK
decimal amount_usdt
enum direction
timestamp created_at
}
WITHDRAW_APPLY {
uuid id PK
uuid user_id FK
decimal amount_usdt
enum status
timestamp reviewed_at
}

图表来源

  • [承兑平台产品方案文档.md:485-495](file://承兑平台产品方案文档.md#L485-L495)
  • [决策变更清单.md:109-118](file://决策变更清单.md#L109-L118)

章节来源

  • [承兑平台产品方案文档.md:485-495](file://承兑平台产品方案文档.md#L485-L495)
  • [决策变更清单.md:109-118](file://决策变更清单.md#L109-L118)

数据字典（核心字段） ​

  • 订单
    • 字段：id、merchant_order_id（幂等）、type、status、amount_usdt、amount_cny、exchange_rate、fee_usdt、merchant_id、trader_id、batch_id、created_at、updated_at
    • 约束：唯一索引（merchant_order_id），外键（merchant_id、trader_id、batch_id）
  • 用户
    • 字段：id、real_name、id_card_no（唯一）、bank_account_no、balance_usdt、frozen_balance_usdt、status、level
    • 约束：唯一索引（id_card_no），外键（无）
  • 汇率与费率
    • 字段：id、bid、ask、updated_at（基准报价）；trader_level、bid_offset、ask_offset（交易员偏移）；inbound_markup、outbound_discount、max_markup（商户加点）
    • 约束：价格关系约束、加点上限约束
  • 风控
    • 字段：risk_level（KYC）、daily_max/monthly_max（限额）、sender_info/receiver_info（旅行规则）、制裁名单字段
    • 约束：匹配阈值与规则
  • 钱包
    • 字段：chain_type、address、tx_hash、confirmations、confirmed_at（链上交易）
    • 约束：链类型与地址唯一性

章节来源

  • [承兑平台产品方案文档.md:1718-1746](file://承兑平台产品方案文档.md#L1718-L1746)
  • [承兑平台产品方案文档.md:346-461](file://承兑平台产品方案文档.md#L346-L461)
  • [综合审查报告.md:173-247](file://综合审查报告.md#L173-L247)

数据访问模式与缓存策略 ​

  • 订单查询：按商户ID/交易员ID/状态/时间范围分页查询；热点订单可缓存。
  • 账户余额：高频读取，Redis缓存可用/冻结余额，数据库落盘；写操作采用分布式锁。
  • 汇率与费率：基准报价定期刷新，Redis缓存bid/ask；商户加点按商户ID缓存。
  • 钱包：链上交易监听写入数据库，地址余额定期归集；提现申请状态变更写入通知队列。
  • 缓存策略：
    • 读多写少：订单、汇率、用户基础信息缓存；写少读多：交易员等级、手续费规则。
    • 缓存失效：订单状态变更、余额变更、费率变更触发失效。

章节来源

  • [承兑平台产品方案文档.md:1829-1859](file://承兑平台产品方案文档.md#L1829-L1859)

数据流与处理逻辑 ​

  • 入金流程：商户下单→平台锁定交易员USDT→交易员确认收款→平台内部划转→商户入金完成。
  • 出金流程：商户下单→锁定商户USDT→平台指派交易员→交易员转账→上传凭证→风控审核→释放USDT→回调商户。
  • 异常处理：超时自动释放、争议仲裁、挂起超时告警、单卡风控友好策略。
mermaid
flowchart TD
Start(["开始"]) --> CreateOrder["创建订单"]
CreateOrder --> AssignTrader["指派交易员"]
AssignTrader --> LockFund["锁定资金"]
LockFund --> ConfirmCNY["交易员确认收款/转账"]
ConfirmCNY --> InternalTransfer["平台内部USDT划转"]
InternalTransfer --> ReleaseFund["释放资金"]
ReleaseFund --> NotifyMerchant["回调商户"]
NotifyMerchant --> End(["结束"])
CreateOrder --> Timeout{"超时?"}
Timeout --> |是| AutoRelease["自动释放并重新指派"]
AutoRelease --> End
Timeout --> |否| ConfirmCNY

图表来源

  • [承兑平台产品方案文档.md:156-295](file://承兑平台产品方案文档.md#L156-L295)

章节来源

  • [承兑平台产品方案文档.md:156-295](file://承兑平台产品方案文档.md#L156-L295)

数据完整性与约束 ​

  • 主键/外键：订单、用户、钱包、批次等实体建立主外键关系。
  • 唯一性：商户订单ID、交易员身份证号、钱包地址（链+地址）。
  • 业务完整性：价格关系、加点上限、冻结余额与可用余额联动、链上确认与数据库状态一致。
  • 一致性：T+1结算批次号+数据库事务+乐观锁，确保幂等性。

章节来源

  • [综合审查报告.md:109-129](file://综合审查报告.md#L109-L129)
  • [决策变更清单.md:119-126](file://决策变更清单.md#L119-L126)

性能与容量规划 ​

  • 查询热点：订单状态、用户余额、汇率缓存命中率。
  • 写入热点：订单创建、资金冻结/释放、链上交易确认。
  • 容量：按月订单量与峰值QPS估算，数据库读写分离、缓存分层、异步通知。
  • 索引：复合索引（商户ID+状态+时间）、（交易员ID+状态+时间）、（链类型+地址）。

章节来源

  • [综合审查报告.md:589-587](file://综合审查报告.md#L589-L587)

数据生命周期、保留与归档 ​

  • 订单：完成/取消后保留30天，批量出金批次完成后保留90天。
  • 账户与KYC：永久保留，按合规要求销毁或匿名化。
  • 链上交易：保留历史哈希与确认记录，按合规要求归档。
  • 日志与审计：操作日志保留180天，支持对账与追溯。

章节来源

  • [综合审查报告.md:660-673](file://综合审查报告.md#L660-L673)

数据迁移路径、版本管理与API演进 ​

  • 数据迁移：地址方案从共享地址迁移到独立地址，需批量生成HD Wallet地址并迁移历史充值记录。
  • API版本：/api/v1 → /api/v2（破坏性变更需兼容期），Header版本与URL版本并行。
  • 版本策略：破坏性变更需提前30天公告，兼容变更滚动发布。

章节来源

  • [综合审查报告.md:549-557](file://综合审查报告.md#L549-L557)
  • [决策变更清单.md:200-209](file://决策变更清单.md#L200-L209)

数据安全与隐私 ​

  • 数据安全：敏感字段加密存储（身份证号、银行卡号）、传输加密（TLS）、访问鉴权（商户/交易员令牌）。
  • 隐私保护：遵循PDPO/GDPR，提供数据访问与删除权；旅行规则数据最小化采集。
  • 合规：KYC/AML/制裁名单筛查、SAR/STR上报流程、税务合规章节。

章节来源

  • [综合审查报告.md:173-247](file://综合审查报告.md#L173-L247)
  • [决策变更清单.md:142-164](file://决策变更清单.md#L142-L164)

依赖分析 ​

  • 组件耦合：
    • 订单中心依赖费率引擎与风控中心。
    • 账户中心依赖钱包中心与通知中心。
    • 钱包中心依赖链上节点与多签服务。
  • 外部依赖：
    • 链上节点（QuickNode/Alchemy）、短信/邮件服务、合规服务（制裁名单、AML）。
  • 循环依赖规避：通过领域事件与异步解耦，避免直接循环调用。
mermaid
graph TB
Orders["订单中心"] --> Rates["费率引擎"]
Orders --> Risk["风控中心"]
Accounts["账户中心"] --> Wallet["钱包中心"]
Accounts --> Notify["通知中心"]
Wallet --> Chain["链上节点"]
Risk --> Compliance["合规服务"]

图表来源

  • [承兑平台产品方案文档.md:295-495](file://承兑平台产品方案文档.md#L295-L495)

章节来源

  • [承兑平台产品方案文档.md:295-495](file://承兑平台产品方案文档.md#L295-L495)

性能考量 ​

  • 读写分离：热点读取走缓存，写入走数据库；批量结算使用事务+乐观锁。
  • 异步化：Webhook回调、通知、链上监听采用消息队列。
  • 监控与告警：订单超时、链上确认延迟、风控阈值触发、结算批次异常。
  • 资源规划：数据库连接池、缓存容量、链上节点并发限制。

章节来源

  • [综合审查报告.md:109-129](file://综合审查报告.md#L109-L129)

故障排查指南 ​

  • 订单卡住：检查指派锁、冻结余额、状态机；查看链上确认记录。
  • 出金异常：核查交易员凭证、风控审核结果、U池锁定与释放。
  • 汇率异常：核对基准报价来源、偏移与加点配置、缓存一致性。
  • 钱包问题：检查链上交易哈希、确认数、归集阈值与多签状态。

章节来源

  • [综合审查报告.md:250-298](file://综合审查报告.md#L250-L298)

结论 ​

本数据模型以“价差盈利+撮合平台”为核心，围绕订单、用户、汇率、风控、钱包与通知六大域构建。通过幂等订单ID、冻结余额与内部USDT划转、独立地址方案、风控与合规框架，确保业务闭环与合规安全。建议在开发前完成数据库DDL与索引设计、缓存策略与异步化改造，并制定数据迁移与版本演进方案。

附录 ​

  • API参考（仅路径与字段说明）
    • GET /api/v1/exchange-rate：返回当前bid/ask（不含偏移）
    • GET /api/v1/balance：返回可用余额、冻结余额、总余额
    • GET /api/v1/transactions：返回充值、出金、手续费等明细
    • GET /api/v1/orders：支持时间/状态/类型筛选，分页

章节来源

  • [承兑平台产品方案文档.md:1829-1859](file://承兑平台产品方案文档.md#L1829-L1859)
  • [决策变更清单.md:200-209](file://决策变更清单.md#L200-L209)