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

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

apps/api/internal/httpapi/wallet_handlers.go

@@ -7,6 +7,17 @@ import (
 	"github.com/easyai/easyai-ai-gateway/apps/api/internal/store"
 )
 
+// getWallet godoc
+// @Summary 获取钱包摘要
+// @Description 返回当前用户的钱包账户、余额和最近消费摘要，可按 currency 过滤。
+// @Tags wallet
+// @Produce json
+// @Security BearerAuth
+// @Param currency query string false "币种" default(USD)
+// @Success 200 {object} store.WalletSummary
+// @Failure 401 {object} ErrorEnvelope
+// @Failure 500 {object} ErrorEnvelope
+// @Router /api/workspace/wallet [get]
 func (s *Server) getWallet(w http.ResponseWriter, r *http.Request) {
 	user, ok := auth.UserFromContext(r.Context())
 	if !ok {
@@ -22,6 +33,24 @@ func (s *Server) getWallet(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, http.StatusOK, summary)
 }
 
+// listWalletTransactions godoc
+// @Summary 列出钱包交易
+// @Description 返回当前用户的钱包交易流水，支持关键字、方向、交易类型、时间范围和分页过滤。
+// @Tags wallet
+// @Produce json
+// @Security BearerAuth
+// @Param q query string false "搜索关键字，别名 query"
+// @Param direction query string false "交易方向"
+// @Param transactionType query string false "交易类型"
+// @Param createdFrom query string false "创建时间起点，别名 from"
+// @Param createdTo query string false "创建时间终点，别名 to"
+// @Param page query int false "页码" default(1)
+// @Param pageSize query int false "每页数量，别名 limit" default(50)
+// @Success 200 {object} WalletTransactionListResponse
+// @Failure 400 {object} ErrorEnvelope
+// @Failure 401 {object} ErrorEnvelope
+// @Failure 500 {object} ErrorEnvelope
+// @Router /api/workspace/wallet/transactions [get]
 func (s *Server) listWalletTransactions(w http.ResponseWriter, r *http.Request) {
 	user, ok := auth.UserFromContext(r.Context())
 	if !ok {