扩展认证逻辑支持 API Token 和动态权限解析，更新配置结构及 Swagger 文档

internal/api/public/config.go

@@ -16,11 +16,23 @@ func NewConfigHandler() *ConfigHandler {
 
 // PublicConfig 公开配置结构
 type PublicConfig struct {
-	Site     config.SiteConfig   `json:"site"`
-	Upload   config.UploadConfig `json:"upload"`
-	APIToken struct {
-		Enabled bool `json:"enabled"`
-	} `json:"api_token"`
+	Site     config.SiteConfig    `json:"site"`
+	Security PublicSecurityConfig `json:"security"`
+	Upload   config.UploadConfig  `json:"upload"`
+	APIToken PublicAPITokenConfig `json:"api_token"`
+	Storage  PublicStorageConfig  `json:"storage"`
+}
+
+type PublicSecurityConfig struct {
+	PickupCodeLength int `json:"pickup_code_length"`
+}
+
+type PublicAPITokenConfig struct {
+	Enabled bool `json:"enabled"`
+}
+
+type PublicStorageConfig struct {
+	Type string `json:"type"`
 }
 
 // GetPublicConfig 获取非敏感配置
@@ -32,10 +44,18 @@ type PublicConfig struct {
 // @Router /api/config [get]
 func (h *ConfigHandler) GetPublicConfig(c *gin.Context) {
 	pub := PublicConfig{
-		Site:   config.GlobalConfig.Site,
+		Site: config.GlobalConfig.Site,
+		Security: PublicSecurityConfig{
+			PickupCodeLength: config.GlobalConfig.Security.PickupCodeLength,
+		},
 		Upload: config.GlobalConfig.Upload,
+		APIToken: PublicAPITokenConfig{
+			Enabled: config.GlobalConfig.APIToken.Enabled,
+		},
+		Storage: PublicStorageConfig{
+			Type: config.GlobalConfig.Storage.Type,
+		},
 	}
-	pub.APIToken.Enabled = config.GlobalConfig.APIToken.Enabled
 
 	c.JSON(http.StatusOK, model.SuccessResponse(pub))
 }

internal/api/public/pickup.go

@@ -29,8 +29,9 @@ type PickupResponse struct {
 
 // DownloadBatch 批量下载文件 (ZIP)
 // @Summary      批量下载文件
-// @Description  根据取件码将批次内的所有文件打包为 ZIP 格式一次性下载
+// @Description  根据取件码将批次内的所有文件打包为 ZIP 格式一次性下载。可选提供带 pickup scope 的 API Token。
 // @Tags         Public
+// @Security     APITokenAuth
 // @Param        pickup_code  path  string  true  "取件码"
 // @Produce      application/zip
 // @Success      200  {file}    file
@@ -82,8 +83,9 @@ func NewPickupHandler() *PickupHandler {
 
 // Pickup 获取批次信息
 // @Summary      获取批次信息
-// @Description  根据取件码获取文件批次详详情和文件列表
+// @Description  根据取件码获取文件批次详细信息和文件列表。可选提供带 pickup scope 的 API Token。
 // @Tags         Public
+// @Security     APITokenAuth
 // @Produce      json
 // @Param        pickup_code  path  string  true  "取件码"
 // @Success      200  {object}  model.Response{data=PickupResponse}
@@ -122,8 +124,9 @@ func (h *PickupHandler) Pickup(c *gin.Context) {
 
 // DownloadFile 下载单个文件
 // @Summary      下载单个文件
-// @Description  根据文件 ID 下载单个文件
+// @Description  根据文件 ID 下载单个文件。可选提供带 pickup scope 的 API Token。
 // @Tags         Public
+// @Security     APITokenAuth
 // @Param        file_id  path  string  true  "文件 ID (UUID)"
 // @Produce      application/octet-stream
 // @Success      200  {file}    file

internal/api/public/upload.go

@@ -29,10 +29,11 @@ type UploadResponse struct {
 
 // Upload 上传文件并生成取件码
 // @Summary      上传文件
-// @Description  上传一个或多个文件并创建一个提取批次
+// @Description  上传一个或多个文件并创建一个提取批次。如果配置了 require_token，则必须提供带 upload scope 的 API Token。
 // @Tags         Public
 // @Accept       multipart/form-data
 // @Produce      json
+// @Security     APITokenAuth
 // @Param        files       formData  file    true   "文件列表"
 // @Param        remark      formData  string  false  "备注"
 // @Param        expire_type formData  string  false  "过期类型 (time/download/permanent)"
@@ -105,10 +106,11 @@ type UploadTextRequest struct {
 
 // UploadText 发送长文本并生成取件码
 // @Summary      发送长文本
-// @Description  中转一段长文本内容并创建一个提取批次
+// @Description  中转一段长文本内容并创建一个提取批次。如果配置了 require_token，则必须提供带 upload scope 的 API Token。
 // @Tags         Public
 // @Accept       json
 // @Produce      json
+// @Security     APITokenAuth
 // @Param        request body UploadTextRequest true "文本内容及配置"
 // @Success      200  {object}  model.Response{data=UploadResponse}
 // @Failure      400  {object}  model.Response