refactor(model):优化分账相关模型结构体字段类型

- 将 ApplyBindReqData 中 Attachments 字段类型改为 []*ApplyBindAttachment- 新增 ApplyBindAttachment 结构体统一附件信息定义
- 将 ApplyLedgerMerReqData 中 Attachments 字段类型改为 []*ApplyBindAttachment- 将 ApplyLedgerReceiver 中 AttachList 字段类型改为 []*ApplyBindAttachment- 将 PreorderResponse 中 ReqData 字段指针化避免拷贝
- 将 ReqData 中 AccRespFields 字段指针化提升性能
- 将 QueryLedgerMerResponse 中 BindRelations 字段类型改为 []*BindRelation
- 调整字段注释格式增强可读性- 统一结构体字段命名风格提高一致性

README.md

@@ -19,7 +19,7 @@ lklsdk/
 
 ```bash
 # 将SDK引入到您的项目中
-go get -u github.com/black1552/lkl_sdk/lklsdk
+go get -u github.com/black1552/lkl_sdk
 ```
 
 ## 快速开始
@@ -33,22 +33,21 @@ import (
 	"github.com/gogf/gf/v2/os/gctx"
 )
 
-// 创建配置
-config := &lklsdk.Config{
-	AppID:        "your_app_id",        // 拉卡拉分配的AppID
-	TermNo:       "your_term_no",       // 终端号
-	MerchantNo:   "your_merchant_no",   // 商户号
-	SettleMerNo:  "your_settle_mer_no", // 结算商户号
-	SettleTermNo: "your_settle_term_no", // 结算终端号
-	AccountType:  "WECHAT",              // 账户类型，如WECHAT、ALIPAY等
-	TransType:    "71",                  // 交易类型
-	Version:      "3.0",                 // API版本
-	NotifyURL:    "your_notify_url",     // 回调URL
-	SerialNo:     "your_mch_api_key",    // 商户API密钥
-}
+// 创建配置JSON字符串
+cfgJson := `{
+	"public_key": "your_public_key",        // 公钥字符串
+	"private_key": "your_private_key",      // 私钥字符串
+	"app_id": "your_app_id",                // lakala应用ID
+	"serial_no": "your_serial_no",          // 序列号
+	"sub_app_id": "your_sub_app_id",        // 子应用ID 微信AppId
+	"version": "3.0",                       // lakala版本号
+	"account_type": "WECHAT",               // 账户类型
+	"trans_type": "71",                     // 交易类型
+	"notify_url": "your_notify_url"         // 回调地址
+}`
 
 // 初始化SDK（使用泛型指定响应类型）
-sdk := lklsdk.NewSDK[model.ResponseType](gctx.New(), config)
+sdk := lklsdk.NewSDK[model.ResponseType](gctx.New(), cfgJson)
 ```
 
 ## 功能模块
@@ -57,7 +56,7 @@ sdk := lklsdk.NewSDK[model.ResponseType](gctx.New(), config)
 
 ```go
 // 初始化特定响应类型的SDK
-sdk := lklsdk.NewSDK[model.MergePreorderResponse](gctx.New(), config)
+sdk := lklsdk.NewSDK[model.MergePreorderResponse](gctx.New(), cfgJson)
 
 // 准备拆单信息
 outSplitInfo := []*model.OutSplitInfo{
@@ -110,7 +109,7 @@ if !mergePreorderResp.SuccessOrFail() {
 
 ```go
 // 初始化特定响应类型的SDK
-sdk := lklsdk.NewSDK[model.ApplyLedgerMerResponse](gctx.New(), config)
+sdk := lklsdk.NewSDK[model.ApplyLedgerMerResponse](gctx.New(), cfgJson)
 
 // 构建请求参数
 applyLedgerReq := &model.ApplyLedgerMerReqData{
@@ -143,7 +142,7 @@ if !expectResp.SuccessOrFail() {
 
 ```go
 // 初始化特定响应类型的SDK
-sdk := lklsdk.NewSDK[model.TradeQueryResponse](gctx.New(), config)
+sdk := lklsdk.NewSDK[model.TradeQueryResponse](gctx.New(), cfgJson)
 
 // 构建请求参数
 tradeQueryReq := &model.TradeQueryReqData{
@@ -168,7 +167,7 @@ if !tradeQueryResp.SuccessOrFail() {
 
 ```go
 // 初始化特定响应类型的SDK
-sdk := lklsdk.NewSDK[model.OrderSplitLedgerResponse](gctx.New(), config)
+sdk := lklsdk.NewSDK[model.OrderSplitLedgerResponse](gctx.New(), cfgJson)
 
 // 准备分账接收方数据
 var recvDatas []*model.OrderSplitLedgerRecvDatas
@@ -199,11 +198,44 @@ if !splitLedgerResp.SuccessOrFail() {
 }
 ```
 
-### 5. 账户余额查询
+### 5. 退款
 
 ```go
 // 初始化特定响应类型的SDK
-sdk := lklsdk.NewSDK[model.BalanceQueryResponse](gctx.New(), config)
+sdk := lklsdk.NewSDK[model.RefundResponse](gctx.New(), cfgJson)
+
+// 构建请求参数
+refundReq := &model.RefundReqData{
+	MerchantNo: "your_merchant_no",  // 商户号
+	TermNo:     "your_term_no",      // 终端号
+	OutTradeNo: "original_out_trade_no", // 原商户交易流水号
+	OutRefundNo: "your_refund_out_trade_no", // 退款商户流水号
+	RefundAmount: "100",  // 退款金额，单位为分
+	TotalAmount: "100",   // 原交易总金额，单位为分
+	RefundReason: "退款原因", // 退款原因
+	NotifyUrl: "https://your-notify-url.com", // 回调地址
+}
+
+// 调用接口
+refundResp, err := sdk.Refound(refundReq)
+if err != nil {
+	log.Printf("退款失败: %v\n", err)
+}
+
+// 使用SuccessOrFail方法判断请求是否成功
+if !refundResp.SuccessOrFail() {
+	log.Printf("退款失败: %s\n", refundResp.Msg)
+}
+
+// 处理成功响应
+// 可以从refundResp.RespData中获取退款结果数据
+```
+
+### 6. 账户余额查询
+
+```go
+// 初始化特定响应类型的SDK
+sdk := lklsdk.NewSDK[model.BalanceQueryResponse](gctx.New(), cfgJson)
 
 // 构建请求参数
 balanceQueryReq := &model.BalanceQueryReqData{

lklsdk/client.go

@@ -16,22 +16,20 @@ import (
 
 	"github.com/black1552/base-common/utils"
 	"github.com/gogf/gf/v2/os/gfile"
+	"github.com/gogf/gf/v2/util/gconv"
 )
 
 // Config 拉卡拉SDK配置
 type Config struct {
-	AppID        string `json:"app_id"`
-	TermNo       string `json:"term_no"`
-	MerchantNo   string `json:"merchant_no"`
-	SettleMerNo  string `json:"settle_merchant_no"`
-	SettleTermNo string `json:"settle_term_no"`
-	AccountType  string `json:"account_type"`
-	TransType    string `json:"trans_type"`
-	Version      string `json:"version"`
-	NotifyURL    string `json:"notify_url"`
-	PublicKey    string `json:"public_key"`
-	PrivateKey   string `json:"private_key"`
-	SerialNo     string `json:"serial_no"`
+	PublicKey   string `json:"public_key" dc:"公钥字符串"`
+	PrivateKey  string `json:"private_key" dc:"私钥字符串"`
+	AppId       string `json:"app_id" dc:"lakala应用ID"`
+	SerialNo    string `json:"serial_no" dc:"序列号"`
+	SubAppId    string `json:"sub_app_id" dc:"子应用ID 微信AppId"`
+	Version     string `json:"version" dc:"lakala版本号"`
+	AccountType string `json:"account_type" dc:"账户类型"`
+	TransType   string `json:"trans_type" dc:"交易类型"`
+	NotifyUrl   string `json:"notify_url" dc:"回调地址"`
 }
 
 // Client 拉卡拉SDK客户端
@@ -42,7 +40,12 @@ type Client[T any] struct {
 }
 
 // NewClient 创建拉卡拉SDK客户端
-func NewClient[T any](ctx context.Context, config *Config) *Client[T] {
+func NewClient[T any](ctx context.Context, cfgJson string) *Client[T] {
+	var config *Config
+	err := gconv.Struct(cfgJson, &config)
+	if err != nil {
+		return nil
+	}
 	return &Client[T]{
 		config: config,
 		ctx:    ctx,
@@ -65,7 +68,7 @@ func (c *Client[T]) generateSign(request []byte) (string, error) {
 	timestamp := fmt.Sprintf("%d", time.Now().Unix())
 
 	// 构建待签名报文
-	signData := fmt.Sprintf("%s\n%s\n%s\n%s\n%s\n", c.config.AppID, c.config.SerialNo, timestamp, nonceStr, string(request))
+	signData := fmt.Sprintf("%s\n%s\n%s\n%s\n%s\n", c.config.AppId, c.config.SerialNo, timestamp, nonceStr, string(request))
 
 	// 计算签名
 	hashed := sha256.Sum256([]byte(signData))
@@ -82,7 +85,7 @@ func (c *Client[T]) generateSign(request []byte) (string, error) {
 
 	// 构建Authorization头
 	authorization := fmt.Sprintf("LKLAPI-SHA256withRSA appid=\"%s\",serial_no=\"%s\",timestamp=\"%s\",nonce_str=\"%s\",signature=\"%s\"",
-		c.config.AppID, c.config.SerialNo, timestamp, nonceStr, signatureBase64)
+		c.config.AppId, c.config.SerialNo, timestamp, nonceStr, signatureBase64)
 	return authorization, nil
 }
 

lklsdk/sdk.go

@@ -17,8 +17,8 @@ type SDK[T any] struct {
 }
 
 // NewSDK 创建拉卡拉SDK实例
-func NewSDK[T any](ctx context.Context, config *Config) *SDK[T] {
-	client := NewClient[T](ctx, config)
+func NewSDK[T any](ctx context.Context, cfgJson string) *SDK[T] {
+	client := NewClient[T](ctx, cfgJson)
 	return &SDK[T]{
 		Client:      client,
 		SplitLedger: NewSplitLedgerService(client),

lklsdk/trade.go

@@ -28,7 +28,7 @@ func (t *TradeService[T]) TradeQuery(req *model.TradeQueryReqData) (*T, error) {
 	baseReq := model.TradeQuery{
 		ReqTime:    time.Now().Format("20060102150405"),
 		Version:    "3.0",
-		OutOrgCode: t.client.config.AppID,
+		OutOrgCode: t.client.config.AppId,
 		ReqData:    req,
 	}
 

model/applyBind.go

@@ -15,20 +15,22 @@ type ApplyBindRequest struct {
 // 包含分账关系绑定所需的详细业务参数
 
 type ApplyBindReqData struct {
-	Version         string `json:"version"`         // 接口版本号，必传，长度8，取值说明：1.0
-	OrderNo         string `json:"orderNo"`         // 订单编号，必传，长度32，用于后续跟踪排查问题及核对报文，格式为14位年月日(24小时制)分秒+8位随机数（不重复）
-	OrgCode         string `json:"orgCode"`         // 分账接收方所属机构代码，必传，长度32
-	MerInnerNo      string `json:"merInnerNo"`      // 分账商户内部商户号，必传，长度32，与MerCupNo选传其一，不能都为空
-	MerCupNo        string `json:"merCupNo"`        // 分账商户银联商户号，必传，长度32，与MerInnerNo选传其一，不能都为空
-	ReceiverNo      string `json:"receiverNo"`      // 分账接收方编号，必传，长度32
-	EntrustFileName string `json:"entrustFileName"` // 合作协议附件名称，必传，长度32
-	EntrustFilePath string `json:"entrustFilePath"` // 合作协议附件路径，必传，长度32，通过调用附件上传接口获取
-	RetUrl          string `json:"retUrl"`          // 回调通知地址，必传，长度128，审核通过后通知地址
-	Attachments     []struct {
-		AttachType      string `json:"attachType"`      // 附件类型编码，必传，长度32
-		AttachName      string `json:"attachName"`      // 附件名称，必传，长度32
-		AttachStorePath string `json:"attachStorePath"` // 附件路径，必传，长度128，通过调用附件上传接口获取
-	} `json:"attachments,omitempty"` // 附加资料，可选，集合类型，其他附加资料文件信息
+	Version         string                 `json:"version"`               // 接口版本号，必传，长度8，取值说明：1.0
+	OrderNo         string                 `json:"orderNo"`               // 订单编号，必传，长度32，用于后续跟踪排查问题及核对报文，格式为14位年月日(24小时制)分秒+8位随机数（不重复）
+	OrgCode         string                 `json:"orgCode"`               // 分账接收方所属机构代码，必传，长度32
+	MerInnerNo      string                 `json:"merInnerNo"`            // 分账商户内部商户号，必传，长度32，与MerCupNo选传其一，不能都为空
+	MerCupNo        string                 `json:"merCupNo"`              // 分账商户银联商户号，必传，长度32，与MerInnerNo选传其一，不能都为空
+	ReceiverNo      string                 `json:"receiverNo"`            // 分账接收方编号，必传，长度32
+	EntrustFileName string                 `json:"entrustFileName"`       // 合作协议附件名称，必传，长度32
+	EntrustFilePath string                 `json:"entrustFilePath"`       // 合作协议附件路径，必传，长度32，通过调用附件上传接口获取
+	RetUrl          string                 `json:"retUrl"`                // 回调通知地址，必传，长度128，审核通过后通知地址
+	Attachments     []*ApplyBindAttachment `json:"attachments,omitempty"` // 附加资料，可选，集合类型，其他附加资料文件信息
+}
+
+type ApplyBindAttachment struct {
+	AttachType      string `json:"attachType"`      // 附件类型编码，必传，长度32
+	AttachName      string `json:"attachName"`      // 附件名称，必传，长度32
+	AttachStorePath string `json:"attachStorePath"` // 附件路径，必传，长度128，通过调用附件上传接口获取
 }
 
 // ApplyBindResponse 分账关系绑定响应结构体

model/applyLedgerMer.go

@@ -10,27 +10,23 @@ type ApplyLedgerMerRequest struct {
 
 // ApplyLedgerMerReqData 商户分账业务开通申请请求业务数据结构体
 type ApplyLedgerMerReqData struct {
-	Version              string  `json:"version"`              // 版本号，必传，长度8，取值说明：1.0
-	OrderNo              string  `json:"orderNo"`              // 订单编号，必传，长度32，用于后续处理查询及回调通知消息标识，2014年月日时分秒毫秒组成
-	OrgCode              string  `json:"orgCode"`              // 机构代码，必传，长度12
-	MerInnerNo           string  `json:"merInnerNo"`           // 拉卡拉内部商户号，可选，长度32，拉卡拉内部商户号和银联商户号必须传一个，默认以内部商户号为准
-	MerCupNo             string  `json:"merCupNo"`             // 银联商户号，可选，长度32，拉卡拉内部商户号和银联商户号必须传一个，默认以内部商户号为准
-	ContactMobile        string  `json:"contactMobile"`        // 联系手机号，必传，长度32
-	SplitLowestRatio     float64 `json:"splitLowestRatio"`     // 最低分账比例，必传，长度12，百分比，支持2位精度，取值范围：70-70.50
-	SplitEntrustFileName string  `json:"splitEntrustFileName"` // 分账授权委托书文件名称，必传，长度64，文件格式：pdf
-	SplitEntrustFilePath string  `json:"splitEntrustFilePath"` // 分账授权委托书文件路径，必传，长度64，调用附件上传接口获取
-	SplitRange           string  `json:"splitRange"`           // 分账范围，必传，长度32，取值说明：ALL-全部交易分账(所有交易默认都分账)，MARK-标记交易分账(只有带标记交易才分账，其余交易正常结算)
-	SplitFundSource      string  `json:"splitFundSource"`      // 分账依据，非必传，长度32，取值说明：TRA-交易分账，BAR-金额分账
-	ElecContractId       string  `json:"elecContractId"`       // 电子合同编号，非必传，长度32，收单已签约交易电子合同编号，供审核人员复核使用
-	SplitLaunchMode      string  `json:"splitLaunchMode"`      // 分账发起方式，非必传，长度32，取值说明：AUTO-自动触发分账，POINTTRUE-指定规则分账，MANUAL-手动分账
-	SettleType           string  `json:"settleType"`           // 结算类型，非必传，长度32，取值说明：01-主扫现结，02-复扫现结，03-交易自动结算
-	SplitRuleSource      string  `json:"splitRuleSource"`      // 分账规则来源，条件必传，长度32，取值说明：MER-商户自定规则，PLATFORM-平台分润规则(分润规则必传)
-	RetUrl               string  `json:"retUrl"`               // 回调通知地址，必传，长度128，分账申请结果以异步消息或同步返回的方式通知，如需无线路由处理，也可以通过第三方商户信息查询接口确定结算结果
-	Attachments          []struct {
-		AttachType      string `json:"attachType"`      // 附件类型编码，必传，长度32
-		AttachName      string `json:"attachName"`      // 附件名称，必传，长度32
-		AttachStorePath string `json:"attachStorePath"` // 附件路径，必传，长度128，调用附件上传接口获取
-	} `json:"attachments,omitempty"` // 附加资料，可选，集合，其他需附加的文件信息
+	Version              string                 `json:"version"`               // 版本号，必传，长度8，取值说明：1.0
+	OrderNo              string                 `json:"orderNo"`               // 订单编号，必传，长度32，用于后续处理查询及回调通知消息标识，2014年月日时分秒毫秒组成
+	OrgCode              string                 `json:"orgCode"`               // 机构代码，必传，长度12
+	MerInnerNo           string                 `json:"merInnerNo"`            // 拉卡拉内部商户号，可选，长度32，拉卡拉内部商户号和银联商户号必须传一个，默认以内部商户号为准
+	MerCupNo             string                 `json:"merCupNo"`              // 银联商户号，可选，长度32，拉卡拉内部商户号和银联商户号必须传一个，默认以内部商户号为准
+	ContactMobile        string                 `json:"contactMobile"`         // 联系手机号，必传，长度32
+	SplitLowestRatio     float64                `json:"splitLowestRatio"`      // 最低分账比例，必传，长度12，百分比，支持2位精度，取值范围：70-70.50
+	SplitEntrustFileName string                 `json:"splitEntrustFileName"`  // 分账授权委托书文件名称，必传，长度64，文件格式：pdf
+	SplitEntrustFilePath string                 `json:"splitEntrustFilePath"`  // 分账授权委托书文件路径，必传，长度64，调用附件上传接口获取
+	SplitRange           string                 `json:"splitRange"`            // 分账范围，必传，长度32，取值说明：ALL-全部交易分账(所有交易默认都分账)，MARK-标记交易分账(只有带标记交易才分账，其余交易正常结算)
+	SplitFundSource      string                 `json:"splitFundSource"`       // 分账依据，非必传，长度32，取值说明：TRA-交易分账，BAR-金额分账
+	ElecContractId       string                 `json:"elecContractId"`        // 电子合同编号，非必传，长度32，收单已签约交易电子合同编号，供审核人员复核使用
+	SplitLaunchMode      string                 `json:"splitLaunchMode"`       // 分账发起方式，非必传，长度32，取值说明：AUTO-自动触发分账，POINTTRUE-指定规则分账，MANUAL-手动分账
+	SettleType           string                 `json:"settleType"`            // 结算类型，非必传，长度32，取值说明：01-主扫现结，02-复扫现结，03-交易自动结算
+	SplitRuleSource      string                 `json:"splitRuleSource"`       // 分账规则来源，条件必传，长度32，取值说明：MER-商户自定规则，PLATFORM-平台分润规则(分润规则必传)
+	RetUrl               string                 `json:"retUrl"`                // 回调通知地址，必传，长度128，分账申请结果以异步消息或同步返回的方式通知，如需无线路由处理，也可以通过第三方商户信息查询接口确定结算结果
+	Attachments          []*ApplyBindAttachment `json:"attachments,omitempty"` // 附加资料，可选，集合，其他需附加的文件信息
 }
 
 // ApplyLedgerMerResponse 商户分账业务开通申请响应结构体

model/applyLedgerReceiver.go

@@ -55,14 +55,7 @@ type ApplyLedgerReceiverReqData struct {
 	// 收款账户清算行行号，必传，长度32，取值说明：参照FBI.N信息查询，仅支持对私结算账户
 	AcctClearBankCode string `json:"acctClearBankCode"`
 	// 接收方附件资料，可选，集合
-	AttachList []struct {
-		// 附件名称，可选，长度32
-		AttachName string `json:"attachName"`
-		// 附件路径，可选，长度32，取值说明：（调用进件附件上传接口获取到附件路径）
-		AttachStorePath string `json:"attachStorePath"`
-		// 附件类型编码，可选，长度32
-		AttachType string `json:"attachType"`
-	} `json:"attachList"`
+	AttachList []*ApplyBindAttachment `json:"attachList"`
 	// 提款类型，可选，长度32，取值说明：01：主动提款，03：交易自动结算，不填默认01
 	SettleType string `json:"settleType"`
 }

model/preorder.go

@@ -35,22 +35,21 @@ func NewPreorder(param *PreorderReqData) *Preorder {
 
 // PreorderResponse 预下单响应结构体
 type PreorderResponse struct {
-	Code     string  `json:"code"`      // 响应码，BBS00000表示成功
-	Msg      string  `json:"msg"`       // 响应信息，对响应码的文字描述
-	ReqData  ReqData `json:"resp_data"` // 响应业务数据
-	RespTime string  `json:"resp_time"` // 响应时间
+	Code     string   `json:"code"`      // 响应码，BBS00000表示成功
+	Msg      string   `json:"msg"`       // 响应信息，对响应码的文字描述
+	ReqData  *ReqData `json:"resp_data"` // 响应业务数据
+	RespTime string   `json:"resp_time"` // 响应时间
 }
 
 // ReqData 响应业务数据
 type ReqData struct {
-	MerchantNo       string             `json:"merchant_no"`        // 商户号
-	OutTradeNo       string             `json:"out_trade_no"`       // 外部订单号（商户订单号）
-	TradeNo          string             `json:"trade_no"`           // 交易号，拉卡拉生成的订单号
-	LogNo            string             `json:"log_no"`             // 拉卡拉对账单流水号
-	SettleMerchantNo string             `json:"settle_merchant_no"` // 结算商户号
-	SettleTermNo     string             `json:"settle_term_no"`     // 结算终端号
-	AccRespFields    WxPreorderResponse `json:"acc_resp_fields"`    // 支付通道返回的具体信息
-
+	MerchantNo       string              `json:"merchant_no"`        // 商户号
+	OutTradeNo       string              `json:"out_trade_no"`       // 外部订单号（商户订单号）
+	TradeNo          string              `json:"trade_no"`           // 交易号，拉卡拉生成的订单号
+	LogNo            string              `json:"log_no"`             // 拉卡拉对账单流水号
+	SettleMerchantNo string              `json:"settle_merchant_no"` // 结算商户号
+	SettleTermNo     string              `json:"settle_term_no"`     // 结算终端号
+	AccRespFields    *WxPreorderResponse `json:"acc_resp_fields"`    // 支付通道返回的具体信息
 }
 
 // WxPreorderResponse 支付通道返回的具体信息

model/queryLedgerMer.go

@@ -66,7 +66,7 @@ type QueryLedgerMerRespData struct {
 	// 分账规则来源，取值说明：MER：商户分账规则，PLATFORM：平台分账规则
 	SplitRuleSource string `json:"split_rule_source"`
 	// 已绑定接收方列表
-	BindRelations []BindRelation `json:"bind_relations"`
+	BindRelations []*BindRelation `json:"bind_relations"`
 }
 
 // BindRelation 已绑定接收方信息结构体
@@ -87,4 +87,4 @@ type BindRelation struct {
 // 返回值：true表示成功，false表示失败
 func (resp *QueryLedgerMerResponse) SuccessOrFail() bool {
 	return resp.Code == "000000"
-}
+}