feat: init sms-server-cli SDK

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-05 15:03:55 +08:00
commit 69be4bcb82
11 changed files with 1508 additions and 0 deletions
@@ -0,0 +1,272 @@
+# sms-server-cli
+
+短信服务 Go SDK，用于对接 [sms-server](https://gitea.s1f.ren/shiran/sms-server) 的 HTTP API。
+
+```
+模块路径: gitea.s1f.ren/shiran/sms-server-cli
+Go 版本: 1.21+
+```
+
+## 安装
+
+```bash
+go get gitea.s1f.ren/shiran/sms-server-cli
+```
+
+## 快速开始
+
+### 使用 ServiceToken（服务端对服务端）
+
+```go
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+
+	smscli "gitea.s1f.ren/shiran/sms-server-cli"
+)
+
+func main() {
+	client := smscli.NewServiceClient("https://sms.example.com", "your-service-token")
+
+	ctx := context.Background()
+
+	// 创建签名
+	sig, err := client.CreateSignature(ctx, smscli.CreateSignatureReq{
+		Title:         "我的应用",
+		ApplicantName: "张三",
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Printf("签名 ID: %d\n", sig.ID)
+
+	// 批量发送短信
+	resp, err := client.SendBatch(ctx, smscli.SendBatchReq{
+		SignatureID: sig.ID,
+		TemplateID:  1,
+		Params:      map[string]string{"code": "123456"},
+		Phones:      []string{"13800138000"},
+	})
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Printf("消息 ID: %s, 计费条数: %d\n", resp.MsgID, resp.FeeCount)
+}
+```
+
+### 使用 UserToken（用户令牌）
+
+```go
+client := smscli.NewUserTokenClient("https://sms.example.com", "your-user-token")
+
+resp, err := client.SendBatch(ctx, smscli.SendBatchReq{
+	SignatureID: 1,
+	TemplateID:  2,
+	Params:      map[string]string{"code": "654321"},
+	Phones:      []string{"13900139000"},
+})
+```
+
+## 认证方式
+
+| 方式 | 构造函数 | Header | 适用场景 |
+|------|---------|--------|---------|
+| ServiceAuth | `NewServiceClient(baseURL, token)` | `Authorization: ServiceToken <token>` | 服务端对服务端调用 |
+| BearerAuth | `NewBearerClient(baseURL, token)` | `Authorization: Bearer <token>` | 已登录用户调用 |
+| UserTokenAuth | `NewUserTokenClient(baseURL, token)` | `Authorization: UserToken <token>` | 用户令牌调用 |
+
+## 枚举值
+
+### ReviewStatus（审核状态）
+
+| 常量 | 值 | 说明 |
+|------|---|------|
+| `ReviewStatusDraft` | 0 | 草稿 |
+| `ReviewStatusReviewing` | 1 | 审核中 |
+| `ReviewStatusApproved` | 2 | 已通过 |
+| `ReviewStatusRejected` | 3 | 已驳回 |
+
+### QuotaType（额度类型）
+
+| 常量 | 值 | 说明 |
+|------|---|------|
+| `QuotaTypeLongTerm` | 1 | 长期额度 |
+| `QuotaTypeShortTerm` | 2 | 短期额度 |
+| `QuotaTypeCycle` | 3 | 周期额度 |
+
+### SendStatus（发送状态）
+
+| 常量 | 值 | 说明 |
+|------|---|------|
+| `SendStatusPending` | 0 | 待发送 |
+| `SendStatusSubmitted` | 1 | 已提交 |
+| `SendStatusSuccess` | 2 | 发送成功 |
+| `SendStatusFailed` | 3 | 发送失败 |
+| `SendStatusRejected` | 4 | 已拒绝 |
+
+### AuthType（认证类型）
+
+| 常量 | 值 | 说明 |
+|------|---|------|
+| `AuthTypeAuthToken` | 1 | 登录令牌 |
+| `AuthTypeServiceToken` | 2 | 服务令牌 |
+| `AuthTypeUserToken` | 3 | 用户令牌 |
+
+## API 参考
+
+### 签名管理（Signature）
+
+#### 用户接口
+
+| 方法 | 说明 |
+|------|------|
+| `CreateSignature(ctx, req)` | 创建签名 |
+| `ListSignatures(ctx, query)` | 获取签名列表 |
+| `GetSignature(ctx, id)` | 获取签名详情 |
+| `UpdateSignature(ctx, id, req)` | 更新签名 |
+| `DeleteSignature(ctx, id)` | 删除签名 |
+| `SubmitSignature(ctx, id)` | 提交签名审核 |
+
+#### 管理员接口
+
+| 方法 | 说明 |
+|------|------|
+| `AdminListSignatures(ctx, query)` | 获取签名列表（支持 UserID/Status 筛选） |
+| `AdminGetSignature(ctx, id)` | 获取签名详情 |
+| `AdminCreateSignature(ctx, req)` | 创建签名（可指定用户） |
+| `AdminUpdateSignature(ctx, id, req)` | 更新签名 |
+| `AdminDeleteSignature(ctx, id)` | 删除签名 |
+| `AdminSubmitSignature(ctx, id)` | 提交签名审核 |
+| `ApproveSignature(ctx, id)` | 审核通过签名 |
+| `RejectSignature(ctx, id, req)` | 驳回签名 |
+
+### 模板管理（Template）
+
+#### 用户接口
+
+| 方法 | 说明 |
+|------|------|
+| `CreateTemplate(ctx, req)` | 创建模板 |
+| `ListTemplates(ctx, query)` | 获取模板列表 |
+| `GetTemplate(ctx, id)` | 获取模板详情 |
+| `UpdateTemplate(ctx, id, req)` | 更新模板 |
+| `DeleteTemplate(ctx, id)` | 删除模板 |
+| `SubmitTemplate(ctx, id)` | 提交模板审核 |
+| `ListRecommendedTemplates(ctx, query)` | 获取推荐模板列表 |
+
+#### 管理员接口
+
+| 方法 | 说明 |
+|------|------|
+| `AdminListTemplates(ctx, query)` | 获取模板列表（支持 UserID/Status 筛选） |
+| `AdminListRecommendedTemplates(ctx, query)` | 获取推荐模板列表 |
+| `AdminGetTemplate(ctx, id)` | 获取模板详情 |
+| `AdminCreateTemplate(ctx, req)` | 创建模板（可指定用户） |
+| `AdminUpdateTemplate(ctx, id, req)` | 更新模板 |
+| `AdminDeleteTemplate(ctx, id)` | 删除模板 |
+| `AdminSubmitTemplate(ctx, id)` | 提交模板审核 |
+| `ApproveTemplate(ctx, id)` | 审核通过模板 |
+| `RejectTemplate(ctx, id, req)` | 驳回模板 |
+| `CreateRecommendedTemplate(ctx, req)` | 创建推荐模板 |
+| `UpdateRecommendedTemplate(ctx, id, req)` | 更新推荐模板 |
+| `DeleteRecommendedTemplate(ctx, id)` | 删除推荐模板 |
+
+### 用户令牌管理（Token）
+
+#### 用户接口
+
+| 方法 | 说明 |
+|------|------|
+| `CreateUserToken(ctx, req)` | 创建令牌 |
+| `ListUserTokens(ctx, query)` | 获取令牌列表 |
+| `GetUserToken(ctx, id)` | 获取令牌详情 |
+| `UpdateUserToken(ctx, id, req)` | 更新令牌 |
+| `DeleteUserToken(ctx, id)` | 删除令牌 |
+| `ToggleUserToken(ctx, id)` | 切换令牌启用/禁用 |
+
+#### 管理员接口
+
+| 方法 | 说明 |
+|------|------|
+| `AdminListUserTokens(ctx, query)` | 获取令牌列表（支持 UserID/Status 筛选） |
+| `AdminGetUserToken(ctx, id)` | 获取令牌详情 |
+| `AdminCreateUserToken(ctx, req)` | 创建令牌（可指定用户） |
+| `AdminUpdateUserToken(ctx, id, req)` | 更新令牌 |
+| `AdminDeleteUserToken(ctx, id)` | 删除令牌 |
+| `AdminToggleUserToken(ctx, id)` | 切换令牌启用/禁用 |
+
+### 额度管理（Quota）
+
+#### 用户接口
+
+| 方法 | 说明 |
+|------|------|
+| `ListQuotas(ctx, query)` | 获取额度列表 |
+| `GetQuotaSummary(ctx)` | 获取额度汇总 |
+
+#### 管理员接口
+
+| 方法 | 说明 |
+|------|------|
+| `AdminListQuotas(ctx, query)` | 获取额度列表（支持 UserID 筛选） |
+| `AdminGetQuotaSummary(ctx, userID)` | 获取指定用户的额度汇总 |
+| `CreateQuota(ctx, req)` | 创建额度 |
+| `UpdateQuota(ctx, id, req)` | 更新额度 |
+| `DeleteQuota(ctx, id)` | 删除额度 |
+
+### 发送管理（Send）
+
+#### 用户接口
+
+| 方法 | 说明 |
+|------|------|
+| `SendBatch(ctx, req)` | 批量发送（相同内容，多号码） |
+| `SendMulti(ctx, req)` | 个性化群发（不同参数，多号码） |
+| `ListSendRecords(ctx, query)` | 获取发送记录列表 |
+| `GetSendStatus(ctx, msgID)` | 查询发送状态 |
+
+#### 管理员接口
+
+| 方法 | 说明 |
+|------|------|
+| `AdminListSendRecords(ctx, query)` | 获取发送记录列表（支持 UserID 筛选） |
+| `AdminGetSendStatus(ctx, msgID)` | 查询发送状态 |
+
+### 适配器管理（Adapter）
+
+#### 管理员接口
+
+| 方法 | 说明 |
+|------|------|
+| `GetAdapterBalance(ctx)` | 查询适配器余额 |
+
+## 响应结构
+
+所有 API 的 HTTP 响应统一为以下 JSON 结构：
+
+```json
+{
+  "code": 0,
+  "msg": "success",
+  "data": { }
+}
+```
+
+SDK 会自动处理响应解析，`code != 0` 时返回包含 `msg` 的 error。
+
+分页列表接口返回 `PaginationResult[T]`：
+
+```json
+{
+  "list": [],
+  "total": 100,
+  "page": 1
+}
+```
+
+## License
+
+MIT