docs(api): 补全 OpenAPI 注释与生成文档

为接口、模型与脚本补齐 Swagger/OpenAPI 注释，生成最新文档，并增加一键生成与查看入口。

apps/api/internal/httpapi/billing_admin_handlers.go

@@ -12,13 +12,29 @@ import (
 )
 
 type walletBalanceRequest struct {
-	Currency       string         `json:"currency"`
-	Balance        float64        `json:"balance"`
-	Reason         string         `json:"reason"`
-	IdempotencyKey string         `json:"idempotencyKey"`
+	Currency       string         `json:"currency" example:"USD"`
+	Balance        float64        `json:"balance" example:"100"`
+	Reason         string         `json:"reason" example:"manual recharge"`
+	IdempotencyKey string         `json:"idempotencyKey" example:"wallet-set-20260514-001"`
 	Metadata       map[string]any `json:"metadata"`
 }
 
+// setUserWalletBalance godoc
+// @Summary 设置用户钱包余额
+// @Description 管理端把指定用户钱包余额调整到目标值，并记录审计日志；balance 不允许为负数。
+// @Tags billing
+// @Accept json
+// @Produce json
+// @Security BearerAuth
+// @Param userID path string true "用户 ID"
+// @Param input body walletBalanceRequest true "钱包余额设置请求"
+// @Success 200 {object} WalletAdjustmentResponse
+// @Failure 400 {object} ErrorEnvelope
+// @Failure 401 {object} ErrorEnvelope
+// @Failure 403 {object} ErrorEnvelope
+// @Failure 404 {object} ErrorEnvelope
+// @Failure 500 {object} ErrorEnvelope
+// @Router /api/admin/users/{userID}/wallet [patch]
 func (s *Server) setUserWalletBalance(w http.ResponseWriter, r *http.Request) {
 	actor, _ := auth.UserFromContext(r.Context())
 	var input walletBalanceRequest
@@ -79,6 +95,23 @@ func (s *Server) setUserWalletBalance(w http.ResponseWriter, r *http.Request) {
 	})
 }
 
+// listAuditLogs godoc
+// @Summary 列出审计日志
+// @Description 管理端按分类、动作、目标类型和目标 ID 查询审计日志。
+// @Tags billing
+// @Produce json
+// @Security BearerAuth
+// @Param category query string false "审计分类"
+// @Param action query string false "审计动作"
+// @Param targetType query string false "目标类型"
+// @Param targetId query string false "目标 ID"
+// @Param limit query int false "返回数量" default(100)
+// @Success 200 {object} AuditLogListResponse
+// @Failure 400 {object} ErrorEnvelope
+// @Failure 401 {object} ErrorEnvelope
+// @Failure 403 {object} ErrorEnvelope
+// @Failure 500 {object} ErrorEnvelope
+// @Router /api/admin/audit-logs [get]
 func (s *Server) listAuditLogs(w http.ResponseWriter, r *http.Request) {
 	query := r.URL.Query()
 	limit, err := positiveQueryInt(query.Get("limit"), 100)