draft

backend/internal/channel/interface.go

@@ -0,0 +1,231 @@
+package channel
+
+import (
+	"context"
+	"time"
+
+	"pay-bridge/internal/model"
+)
+
+// PaymentChannel 支付渠道统一接口，所有渠道适配器必须实现此接口
+type PaymentChannel interface {
+	// Code 返回渠道编码，如 "HEEPAY"
+	Code() string
+
+	// CreateOrder 统一下单，返回支付凭证
+	CreateOrder(ctx context.Context, req *CreateOrderReq) (*CreateOrderResp, error)
+
+	// QueryOrder 查询订单状态
+	QueryOrder(ctx context.Context, req *QueryOrderReq) (*QueryOrderResp, error)
+
+	// CloseOrder 关闭订单
+	CloseOrder(ctx context.Context, req *CloseOrderReq) error
+
+	// Refund 发起退款
+	Refund(ctx context.Context, req *RefundReq) (*RefundResp, error)
+
+	// QueryRefund 查询退款状态
+	QueryRefund(ctx context.Context, req *QueryRefundReq) (*QueryRefundResp, error)
+
+	// ExtractTradeNo 从上游回调 body 中提取平台交易号（用于回调路由，在验签前调用）
+	ExtractTradeNo(rawBody []byte) (string, error)
+
+	// VerifyNotify 验证上游回调签名，返回解析后的通知数据
+	VerifyNotify(ctx context.Context, rawBody []byte, headers map[string]string) (*NotifyData, error)
+
+	// ProfitSharing 发起分账（渠道不支持时返回 ErrNotSupported）
+	ProfitSharing(ctx context.Context, req *ProfitSharingReq) (*ProfitSharingResp, error)
+
+	// RollbackProfitSharing 回退分账（退款场景使用）
+	RollbackProfitSharing(ctx context.Context, req *RollbackSharingReq) error
+
+	// DownloadBill 下载对账账单
+	DownloadBill(ctx context.Context, req *DownloadBillReq) (*BillData, error)
+
+	// UploadFile 上传文件，返回 file_id（进件图片/视频上传）
+	UploadFile(ctx context.Context, req *UploadFileReq) (*UploadFileResp, error)
+
+	// MerchantApply 商户进件
+	MerchantApply(ctx context.Context, req *MerchantApplyReq) (*MerchantApplyResp, error)
+
+	// QueryMerchantStatus 查询商户审核状态
+	QueryMerchantStatus(ctx context.Context, channelMerchantID string) (*MerchantStatusResp, error)
+}
+
+// URLs 渠道网关地址（由配置文件注入，与商户无关）
+type URLs struct {
+	PayURL      string // 支付网关
+	MerchantURL string // 进件网关
+}
+
+// ChannelFactory 渠道工厂函数类型
+type ChannelFactory func(config *model.ChannelConfig, urls URLs) PaymentChannel
+
+// --- 请求/响应类型 ---
+
+// CreateOrderReq 下单请求
+type CreateOrderReq struct {
+	AppID           string
+	TradeNo         string
+	MerchantOrderNo string
+	PayMethod       model.PayMethod
+	Amount          int64          // 分
+	Subject         string
+	NotifyURL       string
+	ExpireTime      time.Time
+	Extra           map[string]any // 支付方式特有参数（openid 等）
+}
+
+// CreateOrderResp 下单响应
+type CreateOrderResp struct {
+	ChannelTradeNo string
+	PayCredential  map[string]any // 支付凭证，各方式格式不同
+	RawResponse    []byte
+}
+
+// QueryOrderReq 查询订单请求
+type QueryOrderReq struct {
+	TradeNo        string
+	ChannelTradeNo string
+}
+
+// QueryOrderResp 查询订单响应
+type QueryOrderResp struct {
+	TradeNo        string
+	ChannelTradeNo string
+	Status         model.TradeStatus
+	Amount         int64
+	PayTime        *time.Time
+}
+
+// CloseOrderReq 关闭订单请求
+type CloseOrderReq struct {
+	TradeNo        string
+	ChannelTradeNo string
+}
+
+// RefundReq 退款请求
+type RefundReq struct {
+	TradeNo        string
+	ChannelTradeNo string
+	RefundNo       string
+	RefundAmount   int64
+	TotalAmount    int64
+	Reason         string
+	NotifyURL      string
+}
+
+// RefundResp 退款响应
+type RefundResp struct {
+	RefundNo        string
+	ChannelRefundNo string
+	Status          model.RefundStatus
+}
+
+// QueryRefundReq 查询退款请求
+type QueryRefundReq struct {
+	RefundNo        string
+	ChannelRefundNo string
+}
+
+// QueryRefundResp 查询退款响应
+type QueryRefundResp struct {
+	RefundNo        string
+	ChannelRefundNo string
+	Status          model.RefundStatus
+	RefundAmount    int64
+	RefundTime      *time.Time
+}
+
+// NotifyData 上游回调解析结果
+type NotifyData struct {
+	TradeNo        string
+	ChannelTradeNo string
+	Status         model.TradeStatus
+	Amount         int64
+	PayTime        *time.Time
+	NotifyType     model.NotifyType
+	RefundNo       string
+	RefundStatus   model.RefundStatus
+	RefundAmount   int64
+	RawData        []byte
+}
+
+// ProfitSharingReq 分账请求
+type ProfitSharingReq struct {
+	TradeNo           string
+	ChannelTradeNo    string
+	SharingNo         string
+	ReceiverMerchantID string
+	Amount            int64
+}
+
+// ProfitSharingResp 分账响应
+type ProfitSharingResp struct {
+	SharingNo        string
+	ChannelSharingNo string
+}
+
+// RollbackSharingReq 回退分账请求
+type RollbackSharingReq struct {
+	SharingNo        string
+	ChannelSharingNo string
+	TradeNo          string
+}
+
+// DownloadBillReq 下载账单请求
+type DownloadBillReq struct {
+	BillDate string // YYYY-MM-DD
+}
+
+// BillData 账单数据
+type BillData struct {
+	Records     []BillRecord
+	TotalAmount int64
+}
+
+// BillRecord 账单记录
+type BillRecord struct {
+	TradeNo        string // 平台交易号（渠道账单中携带时填充）
+	ChannelBillNo  string // 渠道账单流水号
+	ChannelTradeNo string
+	Amount         int64
+	Status         string
+	TradeTime      time.Time
+}
+
+// UploadFileReq 文件上传请求
+type UploadFileReq struct {
+	FileContent   []byte // 原始文件二进制内容
+	FileName      string // 文件名（须含扩展名，如 license.jpg）
+	FileMediaType string // 文件类型编码（01=营业执照 等）
+}
+
+// UploadFileResp 文件上传响应
+type UploadFileResp struct {
+	FileID string // 上传成功后返回，供进件接口使用
+}
+
+// MerchantApplyReq 商户进件请求（customer.enter.enterprise.apply）
+type MerchantApplyReq struct {
+	MerchantID string
+	// BizContent 为完整的 biz_content JSON 对象，按照 001 文档结构直接传入
+	// 包含 base_info / settlement_info / subject_info / identity_info / contact_info /
+	// business_info 等顶层字段
+	BizContent map[string]any
+}
+
+// MerchantApplyResp 商户进件响应
+type MerchantApplyResp struct {
+	RequestNo         string // 汇元返回的申请流水号，用于后续查询/修改
+	ChannelMerchantID string
+	AuditStatus       string
+}
+
+// MerchantStatusResp 商户状态响应
+type MerchantStatusResp struct {
+	ChannelMerchantID string
+	Status            string
+	RejectReason      string
+	FailReason        string
+}