开放接口完成

2026-05-11 14:26:10 +08:00
parent 02d522564f
commit 93200a9074
6 changed files with 482 additions and 12 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -106,3 +106,4 @@ docs/admin-openapi.yaml
 .omx/state/sessions/omx-1777517489966-oo3g37/hud-state.json
 .omx/state/sessions/omx-1777517489966-oo3g37/notify-hook-state.json
 .omx/state/tmux-extended-keys/private-tmp-tmux-501-default.json
+.aider*
--- a/README.md
+++ b/README.md
@@ -218,6 +218,7 @@ default:
 - **B 端认证系统**：完整的后台和 H5 认证功能，支持基于 Redis 的 Token 管理和双令牌机制（Access Token 24h + Refresh Token 7天）；包含登录、登出、Token 刷新、用户信息查询和密码修改功能；通过用户类型隔离确保后台（SuperAdmin、Platform、Agent）和 H5（Agent、Enterprise）的访问控制；详见 [API 文档](docs/api/auth.md)、[使用指南](docs/auth-usage-guide.md) 和 [架构说明](docs/auth-architecture.md)
 - **生命周期管理**：物联网卡/号卡的开卡、激活、停机、复机、销户
 - **代理商体系**：层级管理和分佣结算，支持差价佣金和一次性佣金两种佣金类型，详见 [套餐与佣金业务模型](docs/commission-package-model.md)
+- **代理开放接口**：新增 `/api/open/v1` 签名接口，代理店铺第三方系统可调用卡流量、卡状态、实名状态、套餐列表、预充值钱包余额/流水和钱包套餐购买能力。详见 [对接说明](docs/agent-open-api/功能总结.md)
 - **批量同步**：卡状态、实名状态、流量使用情况
 - **轮询系统**：IoT 卡实名状态、流量使用、套餐余额的定时轮询检查；支持配置化轮询策略、动态并发控制、告警系统、数据清理和手动触发功能；详见 [轮询系统文档](docs/polling-system/README.md)
 - **套餐系统升级**：完整的套餐生命周期管理，支持主套餐排队激活、加油包绑定主套餐、囤货待实名激活、流量按优先级扣减、自然月/按天有效期计算、日/月/年流量重置、客户端流量查询和套餐流量详单；详见 [套餐系统升级文档](docs/package-system-upgrade/)
--- a/internal/routes/open.go
+++ b/internal/routes/open.go
@@ -13,9 +13,15 @@ func RegisterOpenAPIRoutes(router fiber.Router, handler *openapiHandler.Handler,
 	const tag = "代理开放接口"
 	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，最后一行后不追加换行：
+2. Header 字段说明：
+   - X-Agent-Account：代理账号标识，填写代理登录平台使用的用户名或手机号，例如 agent001；该值由平台开通代理账号时提供，必须与签名原文 account 行完全一致。
+   - X-Agent-Password：代理账号当前登录密码，由代理账号持有人提供；该值同时作为 HMAC-SHA256 签名密钥，密码变更后必须使用新密码签名。
+   - X-Agent-Timestamp：请求发起时间，由调用方生成，支持 Unix 秒、Unix 毫秒或 RFC3339 时间，例如 1715400000、1715400000000 或 2024-05-11T10:00:00+08:00；必须与签名原文 timestamp 行完全一致。
+   - X-Agent-Nonce：请求随机串，由调用方每次请求自行生成，例如 UUID、雪花 ID 或“时间戳+随机数”；不需要平台提前分配，同一账号在 5 分钟内不可重复。
+   - X-Agent-Sign：请求签名，由调用方按下方规则实时计算得到，不是平台分配的固定值；只要 method、path、query、body、timestamp、nonce、account 或 password 任意一个变化，签名都会变化。
+3. X-Agent-Timestamp 超出允许时间窗口会认证失败；客户端服务器时间应保持同步。
+4. X-Agent-Nonce 重复会被判定为重放请求。
+5. 签名原文按 7 行拼接，行尾使用 \n，最后一行后不追加换行：
 METHOD
 PATH
 canonical_query
@@ -23,10 +29,10 @@ 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 的原始值，结果使用小写十六进制。
+6. METHOD 使用大写 HTTP 方法；PATH 只取请求路径，例如 /api/open/v1/cards/status，不包含域名和 query。
+7. canonical_query 为 query 参数规范化结果：排除 sign 字段，参数名升序；同名多值按值升序；key 和 value 使用 URL QueryEscape 编码后用 key=value 拼接，多个参数用 & 连接；无 query 时为空字符串。
+8. body_sha256 为原始请求 body 字节的 SHA256 小写十六进制值；GET 或空 body 使用空字符串的 SHA256；POST JSON 请求必须用最终发送的 body 字符串计算，签名和请求发送的 body 必须完全一致。
+9. X-Agent-Sign = hex(HMAC-SHA256(password, sign_payload))，password 为 X-Agent-Password 的原始值，结果使用小写十六进制。

 Node.js 签名示例：

--- a/pkg/openapi/generator.go
+++ b/pkg/openapi/generator.go
@@ -64,11 +64,11 @@ func (g *Generator) addBearerAuth() {

 // 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", "请求签名")
+	g.addAPIKeyHeaderAuth(agentOpenAPIAccountSecurityName, "X-Agent-Account", "代理账号标识，填写代理登录平台使用的用户名或手机号，例如 agent001。")
+	g.addAPIKeyHeaderAuth(agentOpenAPIPasswordSecurityName, "X-Agent-Password", "代理账号当前登录密码，同时作为 HMAC-SHA256 签名密钥；密码变更后必须使用新密码签名。")
+	g.addAPIKeyHeaderAuth(agentOpenAPITimestampSecurityName, "X-Agent-Timestamp", "调用方生成的请求发起时间，支持 Unix 秒、Unix 毫秒或 RFC3339 时间，必须与签名原文 timestamp 行一致。")
+	g.addAPIKeyHeaderAuth(agentOpenAPINonceSecurityName, "X-Agent-Nonce", "调用方每次请求自行生成的随机串，不需要平台提前分配；同一账号在 5 分钟内不可重复。")
+	g.addAPIKeyHeaderAuth(agentOpenAPISignSecurityName, "X-Agent-Sign", "调用方按签名规则实时计算的 HMAC-SHA256 小写十六进制签名，不是固定值。")
 }

 // addAPIKeyHeaderAuth 添加一个 Header 类型的 API Key 认证定义
--- a/tests/agent_open_api/README.md
+++ b/tests/agent_open_api/README.md
@@ -0,0 +1,61 @@
+# 代理开放接口第三方对接示例
+
+本目录是按 Apifox 文档实现的第三方调用示例，不依赖当前项目内部包。
+
+## 默认配置
+
+- 服务地址：`https://cmp-api.boss160.cn`
+- 账号：`15571055000`
+- 密码：`Admin@123456`
+
+也可以通过环境变量覆盖：
+
+```bash
+AGENT_OPEN_API_BASE_URL=https://cmp-api.boss160.cn \
+AGENT_OPEN_API_ACCOUNT=15571055000 \
+AGENT_OPEN_API_PASSWORD='Admin@123456' \
+go run ./tests/agent_open_api -action wallet-balance
+```
+
+## 支持的 action
+
+```bash
+# 查询预充值钱包余额
+go run ./tests/agent_open_api -action wallet-balance
+
+# 查询套餐列表
+go run ./tests/agent_open_api -action packages -page 1 -page-size 20
+
+# 查询单卡实名状态
+go run ./tests/agent_open_api -action realname-status -card-no <ICCID或虚拟号或MSISDN>
+
+# 查询单卡状态
+go run ./tests/agent_open_api -action card-status -card-no <ICCID或虚拟号或MSISDN>
+
+# 查询单卡流量
+go run ./tests/agent_open_api -action card-traffic -card-no <ICCID或虚拟号或MSISDN>
+
+# 查询预充值钱包流水
+go run ./tests/agent_open_api -action wallet-transactions -page 1 -page-size 20
+
+# 钱包套餐购买，会真实创建订单，必须显式传入该 action
+go run ./tests/agent_open_api -action package-order -card-nos <卡1,卡2> -package-code <套餐编码>
+```
+
+## 签名规则
+
+每个请求携带 `X-Agent-Account`、`X-Agent-Password`、`X-Agent-Timestamp`、`X-Agent-Nonce`、`X-Agent-Sign`。
+
+签名原文按以下 7 行拼接，最后一行后不追加换行：
+
+```text
+METHOD
+PATH
+canonical_query
+body_sha256
+timestamp
+nonce
+account
+```
+
+`canonical_query` 会排除 `sign` 参数，参数名升序，同名多值按值升序，并使用 URL QueryEscape 编码。`body_sha256` 使用最终发送请求体字节计算，GET 和空 body 使用空字符串的 SHA256。
--- a/tests/agent_open_api/main.go
+++ b/tests/agent_open_api/main.go
@@ -0,0 +1,401 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"crypto/hmac"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"flag"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+)
+
+const (
+	defaultBaseURL  = "https://cmp-api.boss160.cn"
+	defaultAccount  = "15571055000"
+	defaultPassword = "Admin@123456"
+)
+
+// apiResponse 是文档定义的统一响应外壳，data 保持原始 JSON 便于兼容列表或分页结构。
+type apiResponse struct {
+	Code      int             `json:"code"`
+	Data      json.RawMessage `json:"data"`
+	Msg       string          `json:"msg"`
+	Timestamp string          `json:"timestamp"`
+}
+
+// walletPackageOrderRequest 是“钱包套餐购买”的请求体。
+type walletPackageOrderRequest struct {
+	CardNos     []string `json:"card_nos"`
+	PackageCode string   `json:"package_code"`
+}
+
+// client 是第三方调用方视角的独立客户端，不依赖当前项目内部代码。
+type client struct {
+	baseURL    string
+	account    string
+	password   string
+	httpClient *http.Client
+}
+
+func main() {
+	baseURL := flag.String("base-url", envOrDefault("AGENT_OPEN_API_BASE_URL", defaultBaseURL), "接口服务地址")
+	account := flag.String("account", envOrDefault("AGENT_OPEN_API_ACCOUNT", defaultAccount), "代理账号用户名或手机号")
+	password := flag.String("password", envOrDefault("AGENT_OPEN_API_PASSWORD", defaultPassword), "代理账号登录密码")
+	action := flag.String("action", "wallet-balance", "调用动作：realname-status、card-status、card-traffic、packages、wallet-balance、package-order、wallet-transactions")
+	cardNo := flag.String("card-no", "", "卡标识，支持 ICCID、虚拟号、MSISDN")
+	cardNos := flag.String("card-nos", "", "卡标识列表，多个值用英文逗号分隔")
+	packageCode := flag.String("package-code", "", "套餐编码")
+	page := flag.Int("page", 0, "页码，不传或 0 表示省略")
+	pageSize := flag.Int("page-size", 0, "每页数量，不传或 0 表示省略")
+	packageType := flag.String("package-type", "", "套餐类型：formal 或 addon")
+	seriesID := flag.Int("series-id", -1, "套餐系列 ID，不传或 -1 表示省略")
+	packageName := flag.String("package-name", "", "套餐名称，模糊搜索")
+	transactionType := flag.String("transaction-type", "", "交易类型：recharge、deduct、refund")
+	startDate := flag.String("start-date", "", "开始日期，格式 YYYY-MM-DD")
+	endDate := flag.String("end-date", "", "结束日期，格式 YYYY-MM-DD")
+	timeout := flag.Duration("timeout", 15*time.Second, "请求超时时间")
+	flag.Parse()
+
+	c := &client{
+		baseURL:  strings.TrimRight(*baseURL, "/"),
+		account:  *account,
+		password: *password,
+		httpClient: &http.Client{
+			Timeout: *timeout,
+		},
+	}
+
+	ctx := context.Background()
+	statusCode, responseBody, err := dispatch(ctx, c, runOptions{
+		action:          *action,
+		cardNo:          *cardNo,
+		cardNos:         *cardNos,
+		packageCode:     *packageCode,
+		page:            *page,
+		pageSize:        *pageSize,
+		packageType:     *packageType,
+		seriesID:        *seriesID,
+		packageName:     *packageName,
+		transactionType: *transactionType,
+		startDate:       *startDate,
+		endDate:         *endDate,
+	})
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "调用失败：%v\n", err)
+		os.Exit(1)
+	}
+
+	fmt.Printf("HTTP %d\n", statusCode)
+	printJSON(responseBody)
+	if statusCode < http.StatusOK || statusCode >= http.StatusMultipleChoices {
+		os.Exit(1)
+	}
+}
+
+// runOptions 保存命令行参数，避免把主流程写成过长函数。
+type runOptions struct {
+	action          string
+	cardNo          string
+	cardNos         string
+	packageCode     string
+	page            int
+	pageSize        int
+	packageType     string
+	seriesID        int
+	packageName     string
+	transactionType string
+	startDate       string
+	endDate         string
+}
+
+func dispatch(ctx context.Context, c *client, opts runOptions) (int, []byte, error) {
+	switch opts.action {
+	case "realname-status":
+		if opts.cardNo == "" {
+			return 0, nil, errors.New("realname-status 需要传入 -card-no")
+		}
+		return c.queryRealnameStatus(ctx, opts.cardNo)
+	case "card-status":
+		if opts.cardNo == "" {
+			return 0, nil, errors.New("card-status 需要传入 -card-no")
+		}
+		return c.queryCardStatus(ctx, opts.cardNo)
+	case "card-traffic":
+		if opts.cardNo == "" {
+			return 0, nil, errors.New("card-traffic 需要传入 -card-no")
+		}
+		return c.queryCardTraffic(ctx, opts.cardNo)
+	case "packages":
+		return c.queryPackages(ctx, packageQuery(opts))
+	case "wallet-balance":
+		return c.queryWalletBalance(ctx)
+	case "package-order":
+		requestBody, err := buildPackageOrderRequest(opts.cardNos, opts.packageCode)
+		if err != nil {
+			return 0, nil, err
+		}
+		return c.createWalletPackageOrder(ctx, requestBody)
+	case "wallet-transactions":
+		if err := validateDateRange(opts.startDate, opts.endDate); err != nil {
+			return 0, nil, err
+		}
+		return c.queryWalletTransactions(ctx, walletTransactionQuery(opts))
+	default:
+		return 0, nil, fmt.Errorf("未知 action：%s", opts.action)
+	}
+}
+
+func (c *client) queryRealnameStatus(ctx context.Context, cardNo string) (int, []byte, error) {
+	query := url.Values{}
+	query.Add("card_no", cardNo)
+	return c.get(ctx, "/api/open/v1/cards/realname-status", query)
+}
+
+func (c *client) queryCardStatus(ctx context.Context, cardNo string) (int, []byte, error) {
+	query := url.Values{}
+	query.Add("card_no", cardNo)
+	return c.get(ctx, "/api/open/v1/cards/status", query)
+}
+
+func (c *client) queryCardTraffic(ctx context.Context, cardNo string) (int, []byte, error) {
+	query := url.Values{}
+	query.Add("card_no", cardNo)
+	return c.get(ctx, "/api/open/v1/cards/traffic", query)
+}
+
+func (c *client) queryPackages(ctx context.Context, query url.Values) (int, []byte, error) {
+	return c.get(ctx, "/api/open/v1/packages", query)
+}
+
+func (c *client) queryWalletBalance(ctx context.Context) (int, []byte, error) {
+	return c.get(ctx, "/api/open/v1/wallet/balance", nil)
+}
+
+func (c *client) createWalletPackageOrder(ctx context.Context, body walletPackageOrderRequest) (int, []byte, error) {
+	return c.postJSON(ctx, "/api/open/v1/wallet/package-orders", body)
+}
+
+func (c *client) queryWalletTransactions(ctx context.Context, query url.Values) (int, []byte, error) {
+	return c.get(ctx, "/api/open/v1/wallet/transactions", query)
+}
+
+func (c *client) get(ctx context.Context, path string, query url.Values) (int, []byte, error) {
+	return c.do(ctx, http.MethodGet, path, query, nil)
+}
+
+func (c *client) postJSON(ctx context.Context, path string, body any) (int, []byte, error) {
+	bodyBytes, err := json.Marshal(body)
+	if err != nil {
+		return 0, nil, fmt.Errorf("序列化请求体失败：%w", err)
+	}
+	return c.do(ctx, http.MethodPost, path, nil, bodyBytes)
+}
+
+func (c *client) do(ctx context.Context, method string, path string, query url.Values, body []byte) (int, []byte, error) {
+	endpoint, err := url.Parse(c.baseURL)
+	if err != nil {
+		return 0, nil, fmt.Errorf("解析 base-url 失败：%w", err)
+	}
+	endpoint.Path = strings.TrimRight(endpoint.Path, "/") + path
+	endpoint.RawQuery = canonicalQuery(query)
+
+	timestamp := strconv.FormatInt(time.Now().Unix(), 10)
+	nonce, err := newNonce()
+	if err != nil {
+		return 0, nil, err
+	}
+	sign := buildAgentSign(method, path, query, body, timestamp, nonce, c.account, c.password)
+
+	var requestBody io.Reader
+	if len(body) > 0 {
+		requestBody = bytes.NewReader(body)
+	}
+	request, err := http.NewRequestWithContext(ctx, method, endpoint.String(), requestBody)
+	if err != nil {
+		return 0, nil, fmt.Errorf("创建 HTTP 请求失败：%w", err)
+	}
+
+	request.Header.Set("Accept", "application/json")
+	request.Header.Set("X-Agent-Account", c.account)
+	request.Header.Set("X-Agent-Password", c.password)
+	request.Header.Set("X-Agent-Timestamp", timestamp)
+	request.Header.Set("X-Agent-Nonce", nonce)
+	request.Header.Set("X-Agent-Sign", sign)
+	if len(body) > 0 {
+		request.Header.Set("Content-Type", "application/json")
+	}
+
+	response, err := c.httpClient.Do(request)
+	if err != nil {
+		return 0, nil, fmt.Errorf("发送 HTTP 请求失败：%w", err)
+	}
+	defer response.Body.Close()
+
+	responseBody, err := io.ReadAll(response.Body)
+	if err != nil {
+		return response.StatusCode, nil, fmt.Errorf("读取响应失败：%w", err)
+	}
+	return response.StatusCode, responseBody, nil
+}
+
+func buildAgentSign(method string, path string, query url.Values, body []byte, timestamp string, nonce string, account string, password string) string {
+	bodyHash := sha256.Sum256(body)
+	signPayload := strings.Join([]string{
+		strings.ToUpper(method),
+		path,
+		canonicalQuery(query),
+		hex.EncodeToString(bodyHash[:]),
+		timestamp,
+		nonce,
+		account,
+	}, "\n")
+
+	mac := hmac.New(sha256.New, []byte(password))
+	mac.Write([]byte(signPayload))
+	return hex.EncodeToString(mac.Sum(nil))
+}
+
+func canonicalQuery(query url.Values) string {
+	if len(query) == 0 {
+		return ""
+	}
+
+	keys := make([]string, 0, len(query))
+	for key := range query {
+		if strings.EqualFold(key, "sign") {
+			continue
+		}
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+
+	parts := make([]string, 0)
+	for _, key := range keys {
+		values := append([]string(nil), query[key]...)
+		sort.Strings(values)
+		for _, value := range values {
+			parts = append(parts, url.QueryEscape(key)+"="+url.QueryEscape(value))
+		}
+	}
+	return strings.Join(parts, "&")
+}
+
+func newNonce() (string, error) {
+	bytes := make([]byte, 16)
+	if _, err := rand.Read(bytes); err != nil {
+		return "", fmt.Errorf("生成 nonce 失败：%w", err)
+	}
+	return strconv.FormatInt(time.Now().UnixNano(), 10) + "-" + hex.EncodeToString(bytes), nil
+}
+
+func packageQuery(opts runOptions) url.Values {
+	query := url.Values{}
+	addPositiveInt(query, "page", opts.page)
+	addPositiveInt(query, "page_size", opts.pageSize)
+	addString(query, "package_type", opts.packageType)
+	if opts.seriesID >= 0 {
+		query.Add("series_id", strconv.Itoa(opts.seriesID))
+	}
+	addString(query, "package_name", opts.packageName)
+	return query
+}
+
+func walletTransactionQuery(opts runOptions) url.Values {
+	query := url.Values{}
+	addPositiveInt(query, "page", opts.page)
+	addPositiveInt(query, "page_size", opts.pageSize)
+	addString(query, "transaction_type", opts.transactionType)
+	addString(query, "start_date", opts.startDate)
+	addString(query, "end_date", opts.endDate)
+	return query
+}
+
+func addPositiveInt(query url.Values, key string, value int) {
+	if value > 0 {
+		query.Add(key, strconv.Itoa(value))
+	}
+}
+
+func addString(query url.Values, key string, value string) {
+	if value != "" {
+		query.Add(key, value)
+	}
+}
+
+func buildPackageOrderRequest(cardNos string, packageCode string) (walletPackageOrderRequest, error) {
+	if strings.TrimSpace(cardNos) == "" {
+		return walletPackageOrderRequest{}, errors.New("package-order 需要传入 -card-nos")
+	}
+	if strings.TrimSpace(packageCode) == "" {
+		return walletPackageOrderRequest{}, errors.New("package-order 需要传入 -package-code")
+	}
+
+	items := strings.Split(cardNos, ",")
+	cards := make([]string, 0, len(items))
+	for _, item := range items {
+		cardNo := strings.TrimSpace(item)
+		if cardNo != "" {
+			cards = append(cards, cardNo)
+		}
+	}
+	if len(cards) == 0 {
+		return walletPackageOrderRequest{}, errors.New("package-order 的 -card-nos 不能为空")
+	}
+	if len(cards) > 100 {
+		return walletPackageOrderRequest{}, errors.New("package-order 的 -card-nos 最多支持 100 张卡")
+	}
+
+	return walletPackageOrderRequest{
+		CardNos:     cards,
+		PackageCode: strings.TrimSpace(packageCode),
+	}, nil
+}
+
+func validateDateRange(startDate string, endDate string) error {
+	if startDate != "" {
+		if _, err := time.Parse(time.DateOnly, startDate); err != nil {
+			return fmt.Errorf("start-date 格式必须为 YYYY-MM-DD：%w", err)
+		}
+	}
+	if endDate != "" {
+		if _, err := time.Parse(time.DateOnly, endDate); err != nil {
+			return fmt.Errorf("end-date 格式必须为 YYYY-MM-DD：%w", err)
+		}
+	}
+	return nil
+}
+
+func envOrDefault(key string, fallback string) string {
+	value := strings.TrimSpace(os.Getenv(key))
+	if value == "" {
+		return fallback
+	}
+	return value
+}
+
+func printJSON(body []byte) {
+	var raw json.RawMessage
+	if err := json.Unmarshal(body, &raw); err != nil {
+		fmt.Println(string(body))
+		return
+	}
+
+	var pretty bytes.Buffer
+	if err := json.Indent(&pretty, raw, "", "  "); err != nil {
+		fmt.Println(string(body))
+		return
+	}
+	fmt.Println(pretty.String())
+}