feat(account): 新增账户管理标志类型定义

- 在 consts/account.go 中新增 MgtFlag 类型及其常量定义 - 将 model/balanceQuery.go 中的 MgtFlag 字段类型从 string 改为 consts.MgtFlag - 更新 README.md 中的目录结构，新增 merchant.go 和 uploadFile.go 文件说明 - 在 README.md 示例代码中使用 consts 包中的常量替换硬编码字符串 - 添加详细的错误处理说明及多个新功能使用示例到 README.md - 引入 github.com/google/uuid 依赖包并更新 go.mod 文件 - 在示例代码中增加对支付类型、管理标志等字段的具体常量引用
2025-10-11 10:25:41 +08:00
parent 38b8d577cc
commit 7974b4d570
4 changed files with 310 additions and 10 deletions
@@ -12,7 +12,9 @@ lklsdk/
 ├── trade.go            # 交易相关功能
 ├── account.go          # 账户相关功能
 ├── merge_pre.go        # 主扫合单交易功能
-└── sdk.go        # SDK主入口
+├── sdk.go              # SDK主入口
+├── merchant.go         # 商户相关功能
+└── uploadFile.go       # 文件上传相关功能
 ```

 ## 安装
@@ -30,6 +32,7 @@ go get -u github.com/black1552/lkl_sdk
 import (
 	"github.com/black1552/lkl_sdk/lklsdk"
 	"github.com/black1552/lkl_sdk/model"
+	"github.com/black1552/lkl_sdk/consts"
 	"github.com/gogf/gf/v2/os/gctx"
 )

@@ -122,7 +125,7 @@ applyLedgerReq := &model.ApplyLedgerMerReqData{
 	SplitLowestRatio:     3.51,                                 // 最低分账比例
 	SplitEntrustFileName: "授权委托书.pdf",                     // 授权委托书文件名
 	SplitEntrustFilePath: "path",                              // 授权委托书文件路径
-	SplitRange:           "ALL",                               // 分账范围（ALL全部交易分账，MARK标记交易分账）
+	SplitRange:           consts.SPLIT_RANGE_ALL,                               // 分账范围（ALL全部交易分账，MARK标记交易分账）
 	RetUrl:               "notifyUrl.com",                     // 回调URL
 }

@@ -181,7 +184,7 @@ splitLedgerReq := &model.OrderSplitLedgerReqData{
 	OutSeparateNo: "",              // 商户分账指令流水号
 	TotalAmt:      "",              // 分账总金额，单位为分
 	LklOrgNo:      "",              // 拉卡拉机构编号
-	CalType:       "",              // 分账计算类型（0-按金额，1-按比例）
+	CalType:       consts.CAL_TYPE_AMOUNT,              // 分账计算类型（0-按金额，1-按比例）
 	NotifyUrl:     "",              // 回调地址
 	RecvDatas:     recvDatas,        // 分账接收方数据
 }
@@ -242,8 +245,8 @@ balanceQueryReq := &model.BalanceQueryReqData{
 	MerchantNo: config.MerchantNo,
 	OrgNo:      "",    // 机构号
 	PayNo:      "",    // 支付单号
-	PayType:    "",    // 支付类型
-	MgtFlag:    "",    // 管理标志
+	PayType:    consts.PAY_TYPE_CARD,    // 支付类型（CARD-卡支付，COUPON-优惠券支付，DISCOUNT-折扣支付，POINT-积分支付，MIX-混合支付）
+	MgtFlag:    consts.MGT_FLAG_NO,    // 管理标志（NO-普通交易，YES-管理交易）
 }

 // 调用接口
@@ -282,6 +285,295 @@ if !resp.SuccessOrFail() {
 // 使用resp获取返回的数据
 ```

+### 7. 账户提现
+
+```go
+// 初始化特定响应类型的SDK
+sdk := lklsdk.NewSDK[model.WithdrawResponse](gctx.New(), cfgJson)
+
+// 构建请求参数
+withdrawReq := &model.WithdrawReqData{
+	MerchantNo: "your_merchant_no",  // 商户号
+	TermNo:     "your_term_no",      // 终端号
+	OutTradeNo: "your_withdraw_out_trade_no", // 提现商户流水号
+	Amount:     "10000",             // 提现金额，单位为分
+	Currency:   "CNY",               // 货币类型
+	AccountType: "WECHAT",           // 账户类型
+}
+
+// 调用接口
+withdrawResp, err := sdk.Withdraw(withdrawReq)
+if err != nil {
+	log.Printf("账户提现失败: %v\n", err)
+}
+
+// 使用SuccessOrFail方法判断请求是否成功
+if !withdrawResp.SuccessOrFail() {
+	log.Printf("账户提现失败: %s\n", withdrawResp.Msg)
+}
+```
+
+### 8. 商户进件
+
+```go
+// 初始化特定响应类型的SDK
+sdk := lklsdk.NewSDK[model.MerchantApplyResponse](gctx.New(), cfgJson)
+
+// 构建请求参数
+merchantApplyReq := &model.MerchantApplyReqData{
+	// 填写商户进件所需的各项参数
+	MerchantName: "商户名称",
+	ContactName:  "联系人姓名",
+	ContactPhone: "联系电话",
+	// ... 其他必要参数
+}
+
+// 调用接口
+merchantApplyResp, err := sdk.AddMer(merchantApplyReq)
+if err != nil {
+	log.Printf("商户进件失败: %v\n", err)
+}
+
+// 使用SuccessOrFail方法判断请求是否成功
+if !merchantApplyResp.SuccessOrFail() {
+	log.Printf("商户进件失败: %s\n", merchantApplyResp.Msg)
+}
+```
+
+### 9. 商户进件信息查询
+
+```go
+// 初始化特定响应类型的SDK
+sdk := lklsdk.NewSDK[model.QueryMerResponse](gctx.New(), cfgJson)
+
+// 构建请求参数
+queryMerReq := &model.QueryMerRequestData{
+	MerchantNo: "your_merchant_no", // 商户号
+	// ... 其他必要参数
+}
+
+// 调用接口
+queryMerResp, err := sdk.QueryMerchant(queryMerReq)
+if err != nil {
+	log.Printf("商户进件信息查询失败: %v\n", err)
+}
+
+// 使用SuccessOrFail方法判断请求是否成功
+if !queryMerResp.SuccessOrFail() {
+	log.Printf("商户进件信息查询失败: %s\n", queryMerResp.Msg)
+}
+```
+
+### 10. 商户进件信息校验
+
+```go
+// 初始化特定响应类型的SDK
+sdk := lklsdk.NewSDK[model.MerValidateResponse](gctx.New(), cfgJson)
+
+// 构建请求参数
+merValidateReq := &model.MerValidateRequestData{
+	// 填写商户进件校验所需的各项参数
+	MerchantName: "商户名称",
+	// ... 其他必要参数
+}
+
+// 调用接口
+merValidateResp, err := sdk.MerValidate(merValidateReq)
+if err != nil {
+	log.Printf("商户进件信息校验失败: %v\n", err)
+}
+
+// 使用SuccessOrFail方法判断请求是否成功
+if !merValidateResp.SuccessOrFail() {
+	log.Printf("商户进件信息校验失败: %s\n", merValidateResp.Msg)
+}
+```
+
+### 11. 商户进件复议提交
+
+```go
+// 初始化特定响应类型的SDK
+sdk := lklsdk.NewSDK[model.ReConfSubmitResponse](gctx.New(), cfgJson)
+
+// 构建请求参数
+reConfSubmitReq := &model.ReConfSubmitRequestData{
+	// 填写商户进件复议所需的各项参数
+	MerchantNo: "your_merchant_no",
+	// ... 其他必要参数
+}
+
+// 调用接口
+reConfSubmitResp, err := sdk.ReconsiderSubmit(reConfSubmitReq)
+if err != nil {
+	log.Printf("商户进件复议提交失败: %v\n", err)
+}
+
+// 使用SuccessOrFail方法判断请求是否成功
+if !reConfSubmitResp.SuccessOrFail() {
+	log.Printf("商户进件复议提交失败: %s\n", reConfSubmitResp.Msg)
+}
+```
+
+### 12. 聚合预下单
+
+```go
+// 初始化特定响应类型的SDK
+sdk := lklsdk.NewSDK[model.PreorderResponse](gctx.New(), cfgJson)
+
+// 构建请求参数
+preOrderReq := &model.PreorderReqData{
+	MerchantNo:  "your_merchant_no",  // 商户号
+	TermNo:      "your_term_no",      // 终端号
+	OutTradeNo:  "your_out_trade_no", // 商户交易流水号
+	AccountType: "WECHAT",            // 账户类型
+	TransType:   "71",                // 交易类型
+	Amount:      "100",               // 金额，单位为分
+	Subject:     "测试订单",           // 订单标题
+	NotifyUrl:   "https://your-notify-url.com", // 回调地址
+}
+
+// 调用接口
+preOrderResp, err := sdk.PreOrder(preOrderReq)
+if err != nil {
+	log.Printf("聚合预下单失败: %v\n", err)
+}
+
+// 使用SuccessOrFail方法判断请求是否成功
+if !preOrderResp.SuccessOrFail() {
+	log.Printf("聚合预下单失败: %s\n", preOrderResp.Msg)
+}
+```
+
+### 13. 文件上传查询
+
+```go
+// 初始化特定响应类型的SDK
+sdk := lklsdk.NewSDK[model.UploadFileResponse](gctx.New(), cfgJson)
+
+// 构建请求参数
+uploadFileReq := &model.UploadFileReqData{
+	// 填写文件上传查询所需的各项参数
+	// ...
+}
+
+// 调用接口
+uploadFileResp, err := sdk.UploadFileQuery(uploadFileReq)
+if err != nil {
+	log.Printf("文件上传查询失败: %v\n", err)
+}
+
+// 使用SuccessOrFail方法判断请求是否成功
+if !uploadFileResp.SuccessOrFail() {
+	log.Printf("文件上传查询失败: %s\n", uploadFileResp.Msg)
+}
+```
+
+### 14. 分账接收方创建申请
+
+```go
+// 初始化特定响应类型的SDK
+sdk := lklsdk.NewSDK[model.ApplyLedgerReceiverResponse](gctx.New(), cfgJson)
+
+// 构建请求参数
+applyLedgerReceiverReq := &model.ApplyLedgerReceiverReqData{
+	MerchantNo:    "your_merchant_no",  // 商户号
+	TermNo:        "your_term_no",      // 终端号
+	ReceiverType:  "PERSON",            // 接收方类型
+	ReceiverName:  "接收方名称",         // 接收方名称
+	ReceiverNo:    "接收方编号",         // 接收方编号
+	ReceiverAccNo: "接收方账号",         // 接收方账号
+	// ... 其他必要参数
+}
+
+// 调用接口
+applyLedgerReceiverResp, err := sdk.ApplyLedgerReceiver(applyLedgerReceiverReq)
+if err != nil {
+	log.Printf("分账接收方创建申请失败: %v\n", err)
+}
+
+// 使用SuccessOrFail方法判断请求是否成功
+if !applyLedgerReceiverResp.SuccessOrFail() {
+	log.Printf("分账接收方创建申请失败: %s\n", applyLedgerReceiverResp.Msg)
+}
+```
+
+### 15. 分账关系绑定申请
+
+```go
+// 初始化特定响应类型的SDK
+sdk := lklsdk.NewSDK[model.ApplyBindResponse](gctx.New(), cfgJson)
+
+// 构建请求参数
+applyBindReq := &model.ApplyBindReqData{
+	MerchantNo:   "your_merchant_no",  // 商户号
+	TermNo:       "your_term_no",      // 终端号
+	ReceiverType: "PERSON",            // 接收方类型
+	ReceiverNo:   "接收方编号",         // 接收方编号
+	BindType:     "1",                 // 绑定类型
+	// ... 其他必要参数
+}
+
+// 调用接口
+applyBindResp, err := sdk.ApplyBind(applyBindReq)
+if err != nil {
+	log.Printf("分账关系绑定申请失败: %v\n", err)
+}
+
+// 使用SuccessOrFail方法判断请求是否成功
+if !applyBindResp.SuccessOrFail() {
+	log.Printf("分账关系绑定申请失败: %s\n", applyBindResp.Msg)
+}
+```
+
+### 16. 可分账金额查询
+
+```go
+// 初始化特定响应类型的SDK
+sdk := lklsdk.NewSDK[model.SplitBalanceResponse](gctx.New(), cfgJson)
+
+// 构建请求参数
+splitBalanceReq := &model.SplitBalanceReqData{
+	MerchantNo: "your_merchant_no",  // 商户号
+	TermNo:     "your_term_no",      // 终端号
+	// ... 其他必要参数
+}
+
+// 调用接口
+splitBalanceResp, err := sdk.QuerySplitBalance(splitBalanceReq)
+if err != nil {
+	log.Printf("可分账金额查询失败: %v\n", err)
+}
+
+// 使用SuccessOrFail方法判断请求是否成功
+if !splitBalanceResp.SuccessOrFail() {
+	log.Printf("可分账金额查询失败: %s\n", splitBalanceResp.Msg)
+}
+```
+
+## 错误处理
+
+SDK使用两层错误处理机制，请确保同时检查网络错误和业务响应状态：
+
+```go
+// 1. 首先检查网络或SDK层面的错误
+resp, err := sdk.SomeFunction(req)
+if err != nil {
+	log.Printf("调用接口失败: %v\n", err)
+	// 处理网络错误或SDK内部错误
+	return err
+}
+
+// 2. 然后使用SuccessOrFail()方法判断业务响应是否成功
+if !resp.SuccessOrFail() {
+	log.Printf("业务处理失败: %s\n", resp.Msg) // 或resp.RetMsg
+	// 处理业务失败情况
+	return errors.New("业务处理失败")
+}
+
+// 处理成功响应
+// 使用resp获取返回的数据
+```
+
 ## 注意事项

 1. 请妥善保管您的AppID、商户号、密钥等敏感信息
@@ -27,6 +27,13 @@ func (at AttType) Ptr() string {
 	return string(at)
 }

+type MgtFlag string
+
+const (
+	MGT_FLAG_AVERAGE   MgtFlag = "01" // 一般账户
+	MGT_FLAG_HOUSEHOLD MgtFlag = "03" // 虚户
+)
+
 type SplitRange string

 const (
@@ -20,6 +20,7 @@ require (
 	github.com/go-logr/stdr v1.2.2 // indirect
 	github.com/go-sql-driver/mysql v1.9.2 // indirect
 	github.com/gogf/gf/contrib/drivers/mysql/v2 v2.9.3 // indirect
+	github.com/google/uuid v1.6.0 // indirect
 	github.com/gorilla/websocket v1.5.3 // indirect
 	github.com/grokify/html-strip-tags-go v0.1.0 // indirect
 	github.com/magiconair/properties v1.8.10 // indirect
@@ -27,7 +27,7 @@ type BalanceQueryReqData struct {
 	// 账号类型（01：收款账户，02：付款账户，03：分账商户账户，04：分账接收方账户，05：充值代付账户，06：结算代付账户）-未上送则默认01，非必传，最大长度32
 	PayType consts.PayType `json:"pay_type"`
 	// 账户标志（01:一般账户;03:虚户）-未上送则默认01，非必传，最大长度32
-	MgtFlag string `json:"mgt_flag"`
+	MgtFlag consts.MgtFlag `json:"mgt_flag"`
 }

 // BalanceQueryResponse 余额查询响应结构体