4.5 GO SDK

# Standard SDK - 数字营销开放接口SDK

这个目录包含了数字营销开放接口的标准SDK实现，提供完整的API调用、加密解密、日期工具等功能。

## 功能特性

- **API请求处理**: 完整的数字营销开放接口调用流程
- **加密解密**: RSA加密/解密和签名/验签（支持PKCS#8和PKCS#1格式）
- **AES加密**: AES加密/解密（ECB模式）
- **日期工具**: 位掩码解析工具类（月份、周、日期）
- **配置管理**: 支持配置文件和环境变量
- **错误处理**: 中文错误提示，便于调试
- **测试覆盖**: 完整的单元测试和覆盖率报告

## 目录结构

### 核心SDK文件
- `allinpay_shopoint_standard_sdk.go` - 标准接口SDK主要实现
- `date_utils.go` - 日期位掩码工具函数
- `config_example.go` - 配置加载示例代码

### 示例和测试文件
- `example.go` - 基础功能演示示例
- `examples/demo.go` - 完整的演示程序
- `allinpay_shopoint_standard_sdk_test.go` - SDK单元测试

### 配置文件
- `config.template.json` - 配置模板
- `config.test.json` - 测试配置

## 快速开始

### 下载SDK

[点击下载](https://dms.shopoint.cn/openapis/sdk/go.zip)

### 1. 基本配置

```go
package main

import (
    "encoding/json"
    "fmt"
    "log"
    "allinpay-shopoint-sdk-go/standard-sdk"
)

func main() {
    // 创建SDK实例
    sdk := standardsdk.NewAllinpayShopointStandardSDK()
    
    // 配置SDK参数
    sdk.OpenAPIsEndpoint = "https://dms-api-test.shopoint.cn/shopoint-openapis-web/apis/v3"
    sdk.OpenAPIsAppID = "YOUR_APP_ID"
    sdk.OpenAPIsPublicKey = `-----BEGIN PUBLIC KEY-----
SHOPOINT_PUBLIC_KEY_CONTENT_HERE
-----END PUBLIC KEY-----`
    sdk.CallerPrivateKey = `-----BEGIN PRIVATE KEY-----
CALLER_PRIVATE_KEY_CONTENT_HERE
-----END PRIVATE KEY-----`
    
    // 可选：设置调试模式
    sdk.DebugEnabled = true
}
```

### 2. 使用配置文件

1. 复制配置模板：

```bash
cp config.template.json config.test.json
```

2. 编辑配置文件，填入真实配置

3. 使用配置文件：

```go
// 从配置文件加载
config, err := standardsdk.LoadConfigFromFile("config.test.json")
if err != nil {
    log.Fatalf("加载配置失败: %v", err)
}

sdk := standardsdk.NewAllinpayShopointStandardSDK()
config.ApplyConfig(sdk)
```

### 3. 发送API请求

```go
// 示例：会员查询接口
method := "allinpay.shopoint.memberService.memberQuery"

// 构建业务请求参数
bizParams := map[string]interface{}{
    "idType":   "1",
    "memberId": "13681694175",
}

bizContent, err := json.Marshal(bizParams)
if err != nil {
    log.Fatalf("Failed to marshal biz content: %v", err)
}

// 发送请求
result, err := sdk.SendRequest(method, string(bizContent), "1.0")
if err != nil {
    log.Fatalf("Failed to send request: %v", err)
}

fmt.Printf("Result: %s\n", result)
```

### 4. 使用日期工具

```go
dateUtils := &standardsdk.DateUtils{}

// 解析月份位掩码 (7 = 111二进制 = 1、2、3月)
months, err := dateUtils.GetMonthsInt(7)
if err != nil {
    log.Printf("Failed to get months: %v", err)
} else {
    fmt.Printf("Months: %v\n", months) // 输出: [1 2 3]
}

// 解析周位掩码 (5 = 101二进制 = 周一、周三)
weeks, err := dateUtils.GetWeeksInt(5)
if err != nil {
    log.Printf("Failed to get weeks: %v", err)
} else {
    fmt.Printf("Weeks: %v\n", weeks) // 输出: [1 3]
}

// 解析日期位掩码 (15 = 1111二进制 = 1、2、3、4日)
dates, err := dateUtils.GetDatesInt(15)
if err != nil {
    log.Printf("Failed to get dates: %v", err)
} else {
    fmt.Printf("Dates: %v\n", dates) // 输出: [1 2 3 4]
}
```

## 运行示例

### 基础功能测试

```bash
cd standard-sdk
go run allinpay_shopoint_standard_sdk.go date_utils.go config_example.go example.go
```

### 完整演示程序

```bash
cd standard-sdk/examples
go run demo.go
```

### 运行测试

```bash
cd standard-sdk
go test -v
```

### 生成测试覆盖率报告

```bash
cd standard-sdk
go test -coverprofile=coverage.out
go tool cover -html=coverage.out -o coverage.html
```

## API方法

### AllinpayShopointStandardSDK 结构体方法

- `NewAllinpayShopointStandardSDK()` - 创建新的SDK实例
- `SendRequest(method, bizContent, version string)` - 发送业务接口请求
- `RSAPrivateSign(data, privateKey string)` - 私钥签名
- `RSAPublicVerify(data, sign, publicKey string)` - 公钥验签
- `RSAPublicEncrypt(data, publicKey string)` - 公钥加密
- `RSAPrivateDecrypt(data, privateKey string)` - 私钥解密
- `AESEncrypt(data string, key []byte)` - AES加密
- `AESDecrypt(data string, key []byte)` - AES解密

### DateUtils 工具类方法

- `GetMonthsInt(month int)` - 解析月份位掩码
- `GetDatesInt(date int)` - 解析日期位掩码  
- `GetWeeksInt(week int)` - 解析周位掩码

## 日期工具业务场景示例

```go
dateUtils := &standardsdk.DateUtils{}

// 工作日配置 (周一到周五)
workdays := 1 + 2 + 4 + 8 + 16 // 31
weeks, _ := dateUtils.GetWeeksInt(workdays)
fmt.Printf("工作日: %v\n", weeks) // 输出: [1 2 3 4 5]

// 季度末月份配置 (3,6,9,12月)
quarterEnd := 4 + 32 + 256 + 2048 // 2340
months, _ := dateUtils.GetMonthsInt(quarterEnd)
fmt.Printf("季度末: %v\n", months) // 输出: [3 6 9 12]

// 月初配置 (1-15日)
monthStart := (1 << 15) - 1 // 32767
dates, _ := dateUtils.GetDatesInt(monthStart)
fmt.Printf("月初: %v\n", dates) // 输出: [1 2 3 4 5 6 7 8 9 10 11 12 13 14 15]
```

## 配置要求

### 系统要求
- Go版本：1.19+
- 操作系统：支持Windows、macOS、Linux

### 密钥要求
- 密钥长度：2048位及以上
- 密钥格式：PKCS#8 (推荐) 或 PKCS#1
- 签名算法：RSA-PKCS1v15 + SHA256

### 必需配置
- `OpenAPIsEndpoint`: 数字营销接口地址
- `OpenAPIsAppID`: 数字营销分配的AppID
- `OpenAPIsPublicKey`: 数字营销分配的RSA公钥
- `CallerPrivateKey`: 对接方的RSA私钥
- `DebugEnabled`: 调试模式开关（可选）

## 安全注意事项

⚠️ **重要安全提醒**

1. **私钥保护**: 私钥信息极其敏感，请勿在代码中硬编码或提交到版本控制系统
2. **环境变量**: 建议使用环境变量或安全的配置文件管理敏感信息
3. **权限控制**: 确保只有授权人员能够访问私钥文件
4. **定期轮换**: 定期更换密钥以提高安全性

### 推荐的配置方式

#### 方法1: 使用环境变量 (推荐)

```bash
# 设置环境变量
export SHOPOINT_API_ENDPOINT="https://your-api-endpoint"
export SHOPOINT_APP_ID="your_app_id"
export SHOPOINT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----
shopoint_public_key_content
-----END PUBLIC KEY-----"
export CALLER_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
caller_private_key_content
-----END PRIVATE KEY-----"
export SHOPOINT_DEBUG="true"
```

#### 方法2: 使用配置文件

1. 复制 `config.template.json` 为 `config.test.json`
2. 填入真实的配置信息
3. 使用 `config_example.go` 中的方法加载配置

## 注意事项

1. 请确保密钥格式正确，支持PKCS#8和PKCS#1格式
2. 调试模式会输出详细的请求和响应日志
3. 所有的加密和签名都使用RSA-PKCS1v15和SHA256算法
4. AES加密使用ECB模式，128位密钥
5. 请求会自动进行签名和验签，确保数据安全

## 错误处理

SDK中的所有方法都会返回适当的错误信息，请务必检查错误并进行相应处理。

```go
result, err := sdk.SendRequest(method, bizContent, version)
if err != nil {
    log.Printf("Request failed: %v", err)
    return
}
```