📚 课程目录第2章支付核心概念

2. 支付核心概念：订单、交易、渠道、商户、用户、支付网关

在构建支付聚合系统之前，必须统一团队对六大核心概念的认知。这些概念是支付领域模型的基石，也是后续 API 契约设计的直接对象。概念混淆会导致接口语义不一致、状态机混乱、对账失败等严重问题。

2.1 六大核心概念定义与职责

概念	定义	生命周期特征	聚合系统中的角色
订单 (Order)	商户业务系统的交易凭证，描述“谁买了什么、多少钱”。	创建 → 支付中 → 已支付/已取消	聚合接口的入口载体，携带业务上下文。
交易 (Transaction)	支付系统内部的资金流转记录，描述“资金从哪到哪、通过什么方式”。	待支付 → 处理中 → 成功/失败/退款	支付网关的核心处理单元，与渠道一一对应。
渠道 (Channel)	具体的支付方式提供方，如支付、支付宝、银联、银行卡收单。	可用/不可用/维护中	聚合系统的下游适配目标，负责与外部网关通信。
商户 (Merchant)	接入支付系统的业务主体，拥有独立的费率、结算周期和密钥。	启用/停用/冻结	聚合系统的租户边界，隔离配置与资金。
用户 (User)	发起支付行为的自然人，在系统中通常以用户 ID 或 OpenID 标识。	匿名/已注册/已绑定	支付请求的发起者，风控与对账的基本粒度。
支付网关 (Payment Gateway)	连接商户系统与支付渠道的中间层服务，负责协议转换、路由、安全与状态同步。	无状态服务，持续运行	聚合系统的核心引擎，对外暴露统一接口。

领域建模提示： 在 Go 项目中，建议将 Order 和 Transaction 设计为独立的聚合根。订单聚合根管理业务状态，交易聚合根管理资金状态。二者通过 OrderID 关联，但生命周期解耦。

2.2 核心概念关系：从订单到支付网关的流转

下图展示了用户发起支付后，六大概念之间的协作关系与数据流向。这是理解聚合接口契约设计的基础。

2.3 订单与交易：一对多的核心关系

在支付聚合系统中，一个订单可以对应多笔交易。这是最常见的认知误区。典型场景包括：

组合支付： 用户使用支付 + 余额支付完成一笔订单，产生两笔交易。
支付失败重试： 第一次交易失败后，系统自动切换到备用渠道发起第二笔交易。
部分退款： 原交易成功后，退款操作会产生一笔新的负向交易。

  契约设计原则： 订单接口返回的 order_status 是业务视角的最终状态；交易接口返回的 transaction_status 是资金视角的实时状态。聚合系统必须维护二者的映射关系，不能混用。

2.4 支付网关：聚合系统的核心枢纽

支付网关在六大概念中承担“胶水层”角色，其核心职责包括：

职责	说明	Go 实现关注点
协议转换	将商户系统的统一请求转换为各渠道的专有协议（XML/JSON/Proto）。	使用 `interface{}` 定义渠道适配器，避免硬编码。
智能路由	根据金额、渠道可用性、费率、风控规则选择最优渠道。	策略模式 + 可配置路由表，支持热加载。
安全加固	签名验签、敏感信息加密、防重放攻击。	统一在网关层处理，业务层不感知密钥。
状态同步	处理异步回调、轮询、对账，确保交易最终一致。	使用消息队列解耦回调处理，避免阻塞。
幂等保障	防止重复支付、重复退款。	基于 `transaction_id` 或 `idempotent_key` 实现去重。

2.5 概念在 API 契约中的映射

在 Go 接口定义中，六大概念对应不同的数据结构与端点：

// 订单请求体
type CreateOrderRequest struct {
    MerchantID  string          `json:"merchant_id" validate:"required"`
    UserID      string          `json:"user_id" validate:"required"`
    OrderAmount int64           `json:"order_amount" validate:"required,gt=0"` // 单位：分
    Currency    string          `json:"currency" default:"CNY"`
    Description string          `json:"description"`
    // 交易相关字段在订单层不出现
}

// 交易请求体
type CreateTransactionRequest struct {
    OrderID     string `json:"order_id" validate:"required"`
    ChannelCode string `json:"channel_code" validate:"required"` // 由网关路由决定
    Amount      int64  `json:"amount" validate:"required,gt=0"`
    IdempotentKey string `json:"idempotent_key" validate:"required"`
}

// 支付网关统一响应
type PaymentResponse struct {
    GatewayCode     string `json:"gateway_code"`     // 网关内部码
    TransactionID   string `json:"transaction_id"`
    ChannelRespCode string `json:"channel_resp_code"` // 渠道原始返回码
    ChannelRespMsg  string `json:"channel_resp_msg"`
    PayURL          string `json:"pay_url,omitempty"` // 跳转支付链接
}

常见错误： 将渠道特有的字段（如的 open_id、支付宝的 buyer_id）直接放在订单接口中。正确做法是在交易层通过扩展字段 extras map[string]interface{} 透传，网关层负责解析和校验。

2.6 概念关系总结

下图从分层视角展示六大概念在支付聚合系统中的位置与依赖关系：

分层原则： 业务层只关心订单和用户上下文；资金层只关心交易和渠道的清算结果；网关层作为桥梁，负责双向翻译和状态同步。这种分层在 Go 项目中对应清晰的包结构：internal/order、internal/gateway、internal/transaction。