# feedback-go-sdk

**Repository Path**: bsxbl/feedback-go-sdk

## Basic Information

- **Project Name**: feedback-go-sdk
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-27
- **Last Updated**: 2026-01-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# feedback-go-sdk

纯 Go 版本的 Feedback SDK，用于用户反馈和激活管理。

[![Gitee](https://gitee.com/bsxbl/feedback-go-sdk/badge/star.svg?theme=white)](https://gitee.com/bsxbl/feedback-go-sdk)

## 安装

```bash
go get gitee.com/bsxbl/feedback-go-sdk
```

或者指定版本：

```bash
go get gitee.com/bsxbl/feedback-go-sdk@v0.1.0
```

或者使用本地路径（开发时）：

```bash
go mod edit -replace gitee.com/bsxbl/feedback-go-sdk=./feedback-go-sdk
go get gitee.com/bsxbl/feedback-go-sdk
```

## 快速开始

### 基本示例

```go
package main

import (
	"fmt"
	"log"

	"gitee.com/bsxbl/feedback-go-sdk"
)

func main() {
	// 初始化客户端
	client, err := feedback.NewClient(feedback.InitOptions{
		BaseURL:         "http://localhost:8080",
		SoftwareID:      1,
		Version:         "1.0.0",
		MachineCodePath: "./machine-codes",
		TimeoutMs:       30000, // 可选，默认 30000
	})
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}

	// 检查是否可用
	if !client.Enabled() {
		fmt.Println("SDK is disabled, some features may not work")
		return
	}

	// 获取机器码
	machineCode := client.MachineCode()
	fmt.Printf("Machine Code: %s\n", machineCode)

	// 提交反馈
	feedbackResult, err := client.Feedback(feedback.FeedbackPayload{
		Content: "This is a test feedback",
		Email:   "user@example.com", // 可选
	})
	if err != nil {
		log.Printf("Feedback error: %v", err)
	} else {
		fmt.Printf("Feedback result: %+v\n", feedbackResult)
	}

	// 激活软件
	activateResult, err := client.Activate(feedback.ActivationRequest{
		Code: "your-activation-code",
	})
	if err != nil {
		log.Printf("Activate error: %v", err)
	} else {
		fmt.Printf("Activation result: %+v\n", activateResult)
	}

	// 检查激活状态
	checkResult, err := client.Check()
	if err != nil {
		log.Printf("Check error: %v", err)
	} else {
		if checkResult.Expired {
			fmt.Printf("License expired: %s\n", checkResult.Reason)
		} else {
			fmt.Printf("License valid until: %s\n", checkResult.ExpireAt)
		}
	}
}
```

## API 参考

### `NewClient(options InitOptions) (*Client, error)`

初始化 Feedback 客户端。

**参数：**

- `options.BaseURL` (string): 服务器基础 URL
- `options.SoftwareID` (uint): 软件 ID
- `options.Version` (string): 软件版本号
- `options.MachineCodePath` (string): 机器码存放目录路径
- `options.TimeoutMs` (int, 可选): 请求超时时间（毫秒），默认 30000

**返回值：**

返回一个 `*Client` 实例和错误。即使初始化失败，也不会返回错误，而是返回 `enabled=false` 的客户端。

### `Client`

#### 方法

##### `Enabled() bool`

返回 SDK 是否可用。

##### `MachineCode() string`

返回机器码。

##### `Feedback(payload FeedbackPayload) (*FeedbackResult, error)`

提交用户反馈。

**参数：**

- `payload.Content` (string): 反馈内容（必填）
- `payload.Email` (string): 邮箱地址（可选）

**返回值：**

```go
type FeedbackResult struct {
    Success bool   // 是否成功
    ID      *uint  // 反馈 ID
    Error   string // 错误信息
}
```

##### `Activate(request ActivationRequest) (*ActivationResult, error)`

激活软件。

**参数：**

- `request.Code` (string): 激活码

**返回值：**

```go
type ActivationResult struct {
    Success  bool   // 是否成功
    ExpireAt string // 过期时间
    Error    string // 错误信息
}
```

##### `Check() (*ActivationCheckResponse, error)`

检查激活状态。

**重要：** 如果调用失败（网络错误或服务器返回非 2xx），SDK 会直接返回 `expired: true`，而不是返回错误。这确保了在无法联系服务端时，默认按"授权已到期"处理。

**返回值：**

```go
type ActivationCheckResponse struct {
    Expired   bool    // 是否过期
    Activated *bool   // 是否已激活
    ExpireAt  string // 过期时间
    Reason    string // 错误原因
}
```

## 错误处理

SDK 采用"安全降级"策略：

1. **初始化失败**：不会返回错误，而是返回 `enabled=false` 的客户端
2. **方法调用**：当 `enabled=false` 时，所有方法都会返回失败结果，而不是返回错误
3. **激活检查失败**：`Check` 方法在失败时会返回 `expired: true`，确保在无法联系服务端时默认按"授权已到期"处理

## 机器码

SDK 会自动生成和管理机器码：

- 机器码存储在 `MachineCodePath` 指定的目录中
- 机器码文件名即为机器码本身（32 位字符串）
- 如果目录中已存在机器码文件，SDK 会复用；否则会生成新的机器码
- 机器码生成规则：系统用户名的 MD5 前 16 位 + UUID 后 16 位

## 类型定义

所有类型都可以从包中导入：

```go
import "gitee.com/bsxbl/feedback-go-sdk"

// 使用类型
var options feedback.InitOptions
var result feedback.FeedbackResult
```

## 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

## 发布

- **快速部署**: 参考 [DEPLOY.md](DEPLOY.md)
- **发布指南**: 参考 [PUBLISHING.md](PUBLISHING.md)
- **快速开始**: 参考 [QUICK_START.md](QUICK_START.md)

## 仓库信息

- **Gitee 仓库**: https://gitee.com/bsxbl/feedback-go-sdk
- **模块路径**: `gitee.com/bsxbl/feedback-go-sdk`

**注意**：使用 Gitee 作为 Go 模块源时，需要配置 GOPROXY：

```bash
go env -w GOPROXY=https://goproxy.cn,direct
go env -w GOSUMDB=sum.golang.google.cn
```