文档生成

2026-05-11 11:59:36 +08:00
parent 98ff88d5c3
commit b6d21b81e3
4 changed files with 174 additions and 57 deletions
--- a/internal/model/dto/agent_open_api_dto.go
+++ b/internal/model/dto/agent_open_api_dto.go
@@ -66,8 +66,8 @@ type AgentOpenAPIPackageItem struct {
 	SeriesName      string `json:"series_name" description:"套餐系列名称"`
 	PackageType     string `json:"package_type" description:"套餐类型 (formal:正式套餐, addon:附加套餐)"`
 	PackageTypeName string `json:"package_type_name" description:"套餐类型名称（中文）"`
-	CostPrice       int64  `json:"cost_price" description:"成本价(分)"`
-	RetailPrice     int64  `json:"retail_price" description:"生效零售价(分)"`
+	CostPrice       int64  `json:"cost_price" description:"套餐结算价(分)"`
+	RetailPrice     int64  `json:"retail_price" description:"套餐销售价(分)"`
 	TotalFlowMB     int64  `json:"total_flow_mb" description:"总流量(MB)"`
 	ValidDays       int    `json:"valid_days" description:"有效天数"`
 }
--- a/internal/routes/open.go
+++ b/internal/routes/open.go
@@ -11,61 +11,122 @@ import (
 // RegisterOpenAPIRoutes 注册代理开放接口路由
 func RegisterOpenAPIRoutes(router fiber.Router, handler *openapiHandler.Handler, doc *openapi.Generator, basePath string) {
 	const tag = "代理开放接口"
-	const authDescription = "认证 Header：X-Agent-Account、X-Agent-Password、X-Agent-Timestamp、X-Agent-Nonce、X-Agent-Sign。签名算法为 hex(HMAC-SHA256(password, sign_payload))。所有启用代理账号默认可调用，不需要开放接口账号授权表。"
+	const authDescription = `认证方式：
+1. 每个请求必须携带 Header：X-Agent-Account、X-Agent-Password、X-Agent-Timestamp、X-Agent-Nonce、X-Agent-Sign。
+2. X-Agent-Timestamp 支持 Unix 秒、Unix 毫秒或 RFC3339 时间，服务端允许 5 分钟时间误差。
+3. X-Agent-Nonce 为随机串，同一账号在 5 分钟内不可重复。
+4. 签名原文按 7 行拼接，行尾使用 \n，最后一行后不追加换行：
+METHOD
+PATH
+canonical_query
+body_sha256
+timestamp
+nonce
+account
+5. METHOD 使用大写 HTTP 方法；PATH 只取请求路径，例如 /api/open/v1/cards/status，不包含域名和 query。
+6. canonical_query 为 query 参数规范化结果：排除 sign 字段，参数名升序；同名多值按值升序；key 和 value 使用 URL QueryEscape 编码后用 key=value 拼接，多个参数用 & 连接；无 query 时为空字符串。
+7. body_sha256 为原始请求 body 字节的 SHA256 小写十六进制值；GET 或空 body 使用空字符串的 SHA256；POST JSON 请求必须用最终发送的 body 字符串计算，签名和请求发送的 body 必须完全一致。
+8. X-Agent-Sign = hex(HMAC-SHA256(password, sign_payload))，password 为 X-Agent-Password 的原始值，结果使用小写十六进制。
+
+Node.js 签名示例：
+
+` + "```javascript\n" + `const crypto = require("crypto");
+
+function queryEscape(value) {
+  return new URLSearchParams({ v: String(value) }).toString().slice(2);
+}
+
+function canonicalQuery(params) {
+  return Object.entries(params || {})
+    .filter(([key]) => key.toLowerCase() !== "sign")
+    .flatMap(([key, value]) => {
+      const values = Array.isArray(value) ? value : [value];
+      return values.sort().map((item) => [key, item]);
+    })
+    .sort(([aKey, aValue], [bKey, bValue]) => {
+      if (aKey === bKey) return String(aValue).localeCompare(String(bValue));
+      return aKey.localeCompare(bKey);
+    })
+    .map(([key, value]) => queryEscape(key) + "=" + queryEscape(value))
+    .join("&");
+}
+
+function buildAgentSign({ method, path, query, body, timestamp, nonce, account, password }) {
+  const bodyText = body || "";
+  const bodyHash = crypto.createHash("sha256").update(bodyText).digest("hex");
+  const signPayload = [
+    method.toUpperCase(),
+    path,
+    canonicalQuery(query),
+    bodyHash,
+    timestamp,
+    nonce,
+    account,
+  ].join("\n");
+  return crypto.createHmac("sha256", password).update(signPayload).digest("hex");
+}
+` + "```"

 	Register(router, doc, basePath, "GET", "/cards/traffic", handler.GetCardTraffic, RouteSpec{
-		Summary:     "查询单卡流量",
-		Description: authDescription + "\n\n按 card_no 查询代理权限范围内单卡的当前生效套餐、待生效套餐和真实业务口径流量。不返回虚流量、倍率、停机阈值等内部字段。",
-		Input:       new(dto.AgentOpenAPICardQueryRequest),
-		Output:      new(dto.AgentOpenAPICardTrafficResponse),
-		Tags:        []string{tag},
-		Auth:        true,
+		Summary:        "查询单卡流量",
+		Description:    authDescription + "\n\n按 card_no 查询单卡流量、当前套餐和待生效套餐。card_no 支持 ICCID、虚拟号、MSISDN。",
+		Input:          new(dto.AgentOpenAPICardQueryRequest),
+		Output:         new(dto.AgentOpenAPICardTrafficResponse),
+		Tags:           []string{tag},
+		Auth:           true,
+		SecurityScheme: openapi.SecuritySchemeAgentOpenAPI,
 	})
 	Register(router, doc, basePath, "GET", "/cards/status", handler.GetCardStatus, RouteSpec{
-		Summary:     "查询单卡状态",
-		Description: authDescription + "\n\n按 card_no 查询代理权限范围内单卡状态，network_status=1 返回正常，network_status=0 返回停机和停机原因。",
-		Input:       new(dto.AgentOpenAPICardQueryRequest),
-		Output:      new(dto.AgentOpenAPICardStatusResponse),
-		Tags:        []string{tag},
-		Auth:        true,
+		Summary:        "查询单卡状态",
+		Description:    authDescription + "\n\n按 card_no 查询单卡状态，返回正常或停机以及停机原因。",
+		Input:          new(dto.AgentOpenAPICardQueryRequest),
+		Output:         new(dto.AgentOpenAPICardStatusResponse),
+		Tags:           []string{tag},
+		Auth:           true,
+		SecurityScheme: openapi.SecuritySchemeAgentOpenAPI,
 	})
 	Register(router, doc, basePath, "GET", "/cards/realname-status", handler.GetRealnameStatus, RouteSpec{
-		Summary:     "查询单卡实名状态",
-		Description: authDescription + "\n\n按 card_no 查询代理权限范围内单卡实名状态。",
-		Input:       new(dto.AgentOpenAPICardQueryRequest),
-		Output:      new(dto.AgentOpenAPIRealnameStatusResponse),
-		Tags:        []string{tag},
-		Auth:        true,
+		Summary:        "查询单卡实名状态",
+		Description:    authDescription + "\n\n按 card_no 查询单卡实名状态。",
+		Input:          new(dto.AgentOpenAPICardQueryRequest),
+		Output:         new(dto.AgentOpenAPIRealnameStatusResponse),
+		Tags:           []string{tag},
+		Auth:           true,
+		SecurityScheme: openapi.SecuritySchemeAgentOpenAPI,
 	})
 	Register(router, doc, basePath, "GET", "/packages", handler.ListPackages, RouteSpec{
-		Summary:     "查询代理套餐列表",
-		Description: authDescription + "\n\n分页查询当前代理已分配、启用、上架且非赠送的可购买套餐，返回代理生效零售价。",
-		Input:       new(dto.AgentOpenAPIPackageListRequest),
-		Output:      new(dto.AgentOpenAPIPackageItem),
-		Tags:        []string{tag},
-		Auth:        true,
+		Summary:        "查询套餐列表",
+		Description:    authDescription + "\n\n分页查询当前账号可购买的套餐，返回套餐基础信息和价格。",
+		Input:          new(dto.AgentOpenAPIPackageListRequest),
+		Output:         new(dto.AgentOpenAPIPackageItem),
+		Tags:           []string{tag},
+		Auth:           true,
+		SecurityScheme: openapi.SecuritySchemeAgentOpenAPI,
 	})
 	Register(router, doc, basePath, "POST", "/wallet/package-orders", handler.CreateWalletPackageOrders, RouteSpec{
-		Summary:     "钱包套餐购买",
-		Description: authDescription + "\n\n使用代理预充值主钱包为多张卡购买同一个套餐编码。每张卡独立下单，允许部分成功。",
-		Input:       new(dto.AgentOpenAPIWalletPackageOrderRequest),
-		Output:      new(dto.AgentOpenAPIWalletPackageOrderResponse),
-		Tags:        []string{tag},
-		Auth:        true,
+		Summary:        "钱包套餐购买",
+		Description:    authDescription + "\n\n使用预充值钱包为多张卡购买同一个套餐编码。每张卡独立下单，允许部分成功。",
+		Input:          new(dto.AgentOpenAPIWalletPackageOrderRequest),
+		Output:         new(dto.AgentOpenAPIWalletPackageOrderResponse),
+		Tags:           []string{tag},
+		Auth:           true,
+		SecurityScheme: openapi.SecuritySchemeAgentOpenAPI,
 	})
 	Register(router, doc, basePath, "GET", "/wallet/balance", handler.GetWalletBalance, RouteSpec{
-		Summary:     "查询预充值钱包余额",
-		Description: authDescription + "\n\n查询当前代理预充值主钱包余额。主钱包不存在时返回 0。",
-		Output:      new(dto.AgentOpenAPIWalletBalanceResponse),
-		Tags:        []string{tag},
-		Auth:        true,
+		Summary:        "查询预充值钱包余额",
+		Description:    authDescription + "\n\n查询当前账号预充值钱包余额。未开通钱包时返回 0。",
+		Output:         new(dto.AgentOpenAPIWalletBalanceResponse),
+		Tags:           []string{tag},
+		Auth:           true,
+		SecurityScheme: openapi.SecuritySchemeAgentOpenAPI,
 	})
 	Register(router, doc, basePath, "GET", "/wallet/transactions", handler.ListWalletTransactions, RouteSpec{
-		Summary:     "查询预充值钱包流水",
-		Description: authDescription + "\n\n分页查询当前代理预充值主钱包流水，字段与后台主钱包流水接口保持一致。",
-		Input:       new(dto.AgentOpenAPIWalletTransactionListRequest),
-		Output:      new(dto.MainWalletTransactionItem),
-		Tags:        []string{tag},
-		Auth:        true,
+		Summary:        "查询预充值钱包流水",
+		Description:    authDescription + "\n\n分页查询当前账号预充值钱包流水。",
+		Input:          new(dto.AgentOpenAPIWalletTransactionListRequest),
+		Output:         new(dto.MainWalletTransactionItem),
+		Tags:           []string{tag},
+		Auth:           true,
+		SecurityScheme: openapi.SecuritySchemeAgentOpenAPI,
 	})
 }
--- a/internal/routes/registry.go
+++ b/internal/routes/registry.go
@@ -17,14 +17,15 @@ type FileUploadField struct {

 // RouteSpec 定义接口文档元数据
 type RouteSpec struct {
-	Summary     string            // 简短摘要（中文，一行）
-	Description string            // 详细说明，支持 Markdown 语法（可选）
-	Input       interface{}       // 请求参数结构体 (Query/Path/Body)
-	Body        interface{}       // 显式 JSON 请求体（用于 DELETE 等方法，库不自动生成 requestBody 的场景）
-	Output      interface{}       // 响应参数结构体
-	Tags        []string          // 分类标签
-	Auth        bool              // 是否需要认证图标 (预留)
-	FileUploads []FileUploadField // 文件上传字段列表（设置此字段时请求类型为 multipart/form-data）
+	Summary        string            // 简短摘要（中文，一行）
+	Description    string            // 详细说明，支持 Markdown 语法（可选）
+	Input          interface{}       // 请求参数结构体 (Query/Path/Body)
+	Body           interface{}       // 显式 JSON 请求体（用于 DELETE 等方法，库不自动生成 requestBody 的场景）
+	Output         interface{}       // 响应参数结构体
+	Tags           []string          // 分类标签
+	Auth           bool              // 是否需要认证响应和认证标记
+	SecurityScheme string            // OpenAPI 认证方案，空值表示 BearerAuth
+	FileUploads    []FileUploadField // 文件上传字段列表（设置此字段时请求类型为 multipart/form-data）
 }

 // pathParamRegex 用于匹配 Fiber 的路径参数格式 /:param
@@ -55,7 +56,7 @@ func Register(router fiber.Router, doc *openapi.Generator, basePath, method, pat
 			}
 			doc.AddMultipartOperation(method, openapiPath, spec.Summary, spec.Description, spec.Input, spec.Output, spec.Auth, fileFields, spec.Tags...)
 		} else {
-			doc.AddOperation(method, openapiPath, spec.Summary, spec.Description, spec.Input, spec.Body, spec.Output, spec.Auth, spec.Tags...)
+			doc.AddOperationWithSecurity(method, openapiPath, spec.Summary, spec.Description, spec.Input, spec.Body, spec.Output, spec.Auth, spec.SecurityScheme, spec.Tags...)
 		}
 	}
 }