文档生成

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...)
 		}
 	}
 }
--- a/pkg/openapi/generator.go
+++ b/pkg/openapi/generator.go
@@ -17,6 +17,17 @@ type Generator struct {
 	Reflector *openapi3.Reflector
 }

+// SecuritySchemeAgentOpenAPI 表示代理开放接口 Header 签名认证方案
+const SecuritySchemeAgentOpenAPI = "agent_open_api"
+
+const (
+	agentOpenAPIAccountSecurityName   = "AgentOpenAPIAccount"
+	agentOpenAPIPasswordSecurityName  = "AgentOpenAPIPassword"
+	agentOpenAPITimestampSecurityName = "AgentOpenAPITimestamp"
+	agentOpenAPINonceSecurityName     = "AgentOpenAPINonce"
+	agentOpenAPISignSecurityName      = "AgentOpenAPISign"
+)
+
 // NewGenerator 创建一个新的生成器实例
 func NewGenerator(title, version string) *Generator {
 	reflector := openapi3.Reflector{}
@@ -30,6 +41,7 @@ func NewGenerator(title, version string) *Generator {

 	g := &Generator{Reflector: &reflector}
 	g.addBearerAuth()
+	g.addAgentOpenAPIAuth()
 	return g
 }

@@ -50,6 +62,31 @@ func (g *Generator) addBearerAuth() {
 	g.addErrorResponseSchema()
 }

+// addAgentOpenAPIAuth 添加代理开放接口 Header 签名认证定义
+func (g *Generator) addAgentOpenAPIAuth() {
+	g.addAPIKeyHeaderAuth(agentOpenAPIAccountSecurityName, "X-Agent-Account", "代理账号用户名或手机号")
+	g.addAPIKeyHeaderAuth(agentOpenAPIPasswordSecurityName, "X-Agent-Password", "代理账号登录密码")
+	g.addAPIKeyHeaderAuth(agentOpenAPITimestampSecurityName, "X-Agent-Timestamp", "Unix 秒、Unix 毫秒或 RFC3339 时间")
+	g.addAPIKeyHeaderAuth(agentOpenAPINonceSecurityName, "X-Agent-Nonce", "随机串，同一账号在 5 分钟内不可重复")
+	g.addAPIKeyHeaderAuth(agentOpenAPISignSecurityName, "X-Agent-Sign", "请求签名")
+}
+
+// addAPIKeyHeaderAuth 添加一个 Header 类型的 API Key 认证定义
+func (g *Generator) addAPIKeyHeaderAuth(name, header, description string) {
+	g.Reflector.Spec.ComponentsEns().SecuritySchemesEns().WithMapOfSecuritySchemeOrRefValuesItem(
+		name,
+		openapi3.SecuritySchemeOrRef{
+			SecurityScheme: &openapi3.SecurityScheme{
+				APIKeySecurityScheme: &openapi3.APIKeySecurityScheme{
+					Name:        header,
+					In:          openapi3.APIKeySecuritySchemeInHeader,
+					Description: &description,
+				},
+			},
+		},
+	)
+}
+
 // addErrorResponseSchema 添加错误响应 Schema 定义
 func (g *Generator) addErrorResponseSchema() {
 	objectType := openapi3.SchemaType("object")
@@ -121,6 +158,11 @@ type FileUploadField struct {
 //   - tags: 标签列表
 //   - requiresAuth: 是否需要认证
 func (g *Generator) AddOperation(method, path, summary, description string, input interface{}, body interface{}, output interface{}, requiresAuth bool, tags ...string) {
+	g.AddOperationWithSecurity(method, path, summary, description, input, body, output, requiresAuth, "", tags...)
+}
+
+// AddOperationWithSecurity 添加操作并支持指定 OpenAPI 认证方案
+func (g *Generator) AddOperationWithSecurity(method, path, summary, description string, input interface{}, body interface{}, output interface{}, requiresAuth bool, securityScheme string, tags ...string) {
 	op := openapi3.Operation{
 		Summary: &summary,
 		Tags:    tags,
@@ -138,7 +180,7 @@ func (g *Generator) AddOperation(method, path, summary, description string, inpu
 		}
 	}

-	// u663eu5f0fu4f20u5165u7684 JSON bodyuff0cu7528u4e8e DELETE u7b49u65b9u6cd5u4e0du81eau52a8u751fu6210 requestBody u7684u573au666f
+	// 显式传入的 JSON body，用于 DELETE 等方法不自动生成 requestBody 的场景
 	if body != nil {
 		tempOp := openapi3.Operation{}
 		if err := g.Reflector.SetRequest(&tempOp, body, "POST"); err != nil {
@@ -157,7 +199,7 @@ func (g *Generator) AddOperation(method, path, summary, description string, inpu

 	// 添加认证要求
 	if requiresAuth {
-		g.addSecurityRequirement(&op)
+		g.addSecurityRequirement(&op, securityScheme)
 	}

 	// 添加标准错误响应
@@ -251,7 +293,7 @@ func (g *Generator) AddMultipartOperation(method, path, summary, description str
 	}

 	if requiresAuth {
-		g.addSecurityRequirement(&op)
+		g.addSecurityRequirement(&op, "")
 	}

 	g.addStandardErrorResponses(&op, requiresAuth)
@@ -398,7 +440,20 @@ func (g *Generator) setEnvelopeResponse(op *openapi3.Operation, output interface
 }

 // addSecurityRequirement 为操作添加认证要求
-func (g *Generator) addSecurityRequirement(op *openapi3.Operation) {
+func (g *Generator) addSecurityRequirement(op *openapi3.Operation, securityScheme string) {
+	if securityScheme == SecuritySchemeAgentOpenAPI {
+		op.Security = []map[string][]string{
+			{
+				agentOpenAPIAccountSecurityName:   {},
+				agentOpenAPIPasswordSecurityName:  {},
+				agentOpenAPITimestampSecurityName: {},
+				agentOpenAPINonceSecurityName:     {},
+				agentOpenAPISignSecurityName:      {},
+			},
+		}
+		return
+	}
+
 	op.Security = []map[string][]string{
 		{"BearerAuth": {}},
 	}