收银台
受众：开发者 / 运维 摘要：Core Cashier 通用收银台底座，负责支付订单、渠道编排、回调、对账、补偿和支付报价。
Cashier 是中性支付订单底座。业务模块只登记自己的支付场景和成功 / 退款处理器，支付渠道能力由 Payment Starter 提供，平台商户和开放支付能力由 聚合支付平台 承接。
能力范围
| 能力 | 说明 |
|---|---|
| 支付订单 | 用 scene 区分商城、开放平台套餐、视频内容、表单提交等消费方 |
| 支付提交 | 用户侧按订单号提交支付，调用 Payment Provider |
| 支付报价 | 创建、刷新、取消 quote，锁定支付资产、金额、汇率和过期时间 |
| 回调处理 | 统一验签、幂等、交易流水、回调日志和成功处理器调用 |
| 对账补偿 | 查询渠道结果、补偿 pending 订单、记录失败原因 |
| CSV 导出 | 订单、交易和回调日志按筛选条件导出排障快照 |
Cashier 不承担业务订单状态、商户结算批次、权益激活策略或营销优惠计算。
API 路径
| API | 说明 |
|---|---|
GET /api/v1/cashier/payment-orders/{outTradeNo} | 当前用户查询支付单 |
POST /api/v1/cashier/payment-orders/{outTradeNo}/pay | 提交支付，需携带 quote |
POST /api/v1/cashier/payment-orders/{outTradeNo}/sync | 同步本地支付结果 |
POST /api/v1/cashier/payment-orders/{outTradeNo}/quotes | 创建支付报价 |
GET /api/v1/cashier/payment-orders/{outTradeNo}/quotes/active | 查询 active quote |
POST /api/v1/cashier/payment-orders/{outTradeNo}/quotes/{quoteNo}/refresh | 刷新 quote |
POST /api/v1/cashier/payment-orders/{outTradeNo}/quotes/{quoteNo}/cancel | 取消 quote |
GET /api/v1/cashier/payment-methods | 查询当前可用支付方式 |
GET /api/v1/cashier/web3/payment-options | 查询 Web3 支付选项 |
GET /api/v1/admin/cashier/payment-orders | 后台支付订单查询 |
GET /api/v1/admin/cashier/payment-transactions | 后台交易流水查询 |
GET /api/v1/admin/cashier/payment-callback-logs | 后台回调日志查询 |
POST /api/v1/admin/cashier/payment-notifies/{provider} | Provider 回调入口 |
POST /api/v1/admin/cashier/payment-compensations | 手动补偿支付单 |
POST /api/v1/admin/cashier/payment-reconciliations | 手动对账 |
后台权限前缀为 cashier:payment:*。
数据模型
| 表 | 说明 |
|---|---|
cashier_payment_order | 支付单、业务场景、定价金额、状态和 attributes |
cashier_payment_transaction | 每次支付、同步、回调或补偿形成的交易流水 |
cashier_payment_callback_log | Provider 回调请求、验签和处理结果 |
cashier_payment_quote | 支付报价、支付资产、汇率、过期和消费状态 |
迁移归属：
| 文件 | 说明 |
|---|---|
0000_00_00_031000_core_cashier_create_tables.xml | 支付订单、交易、回调日志和支付报价等基础表 |
0000_00_00_031100_core_cashier_seed_data.xml | 权限、菜单和角色绑定 |
扩展点
| 扩展点 | 用途 |
|---|---|
CashierPaymentOrderSuccessHandler | 按 scene 处理支付成功后的业务激活 |
CashierPaymentOrderRefundHandler | 按 scene 处理退款后的业务回滚 |
CashierPaymentQuoteRatePort | 由 Money 等模块提供支付资产报价 |
CashierWeb3PaymentOptionPort | 由 Money / Web3 提供后台多链代币收款选项 |
CashierOutboxPort | 将支付回调事实投递到 Outbox |
业务模块接入时只保存自己的业务订单和 Cashier 订单号快照，不复制 Cashier 状态机。
支付补偿任务默认名称为 cashier.payment.compensation。Web3 用户端同步后仍未确认成功时，系统会向专用 cashier 队列投递单笔延迟补偿消息；队列消费后如支付单仍为 pending，会按配置继续重投，避免高频支付确认重试占用默认队列。
Web3 多链代币支付
统一收银台的 Web3 支付支持多链多代币，可选范围由后台 Web3 链列表和 Token 列表决定：
GET /api/v1/cashier/web3/payment-options返回后台已启用且开启支付（paymentEnabled）、且解析到平台收款地址的链上代币选项（链名、chainId、代币符号 / 合约 / 精度、收款地址、确认数）。该端口由 Money / Web3 通过CashierWeb3PaymentOptionPort实现，未实现时返回空列表。- 提交支付时携带所选链与代币（
web3ChainName+web3TokenContract/web3TokenKey/web3TokenSymbol）。Cashier 在服务端按选项范围权威匹配并回填收款地址、代币合约、精度和确认数，越界直接拒绝。 - 前端透传的收款地址 / 代币合约不会生效；端口缺省时锁回支付单自身的链上收款快照，收款地址永不由前端决定，确保资金安全。
验证命令
bash
./mvnw -pl spring-open-core/spring-open-core-cashier -am test -DskipITs -DskipFrontend -Dsurefire.failIfNoSpecifiedTests=false
./.ai/scripts/check modules
./.ai/scripts/check migrations
git diff --check