{
    "swagger": "2.0",
    "info": {
        "description": "自托管的文件暂存柜后端系统 API 文档",
        "title": "文件暂存柜 API",
        "termsOfService": "http://swagger.io/terms/",
        "contact": {
            "name": "API Support",
            "url": "http://www.swagger.io/support",
            "email": "support@swagger.io"
        },
        "license": {
            "name": "Apache 2.0",
            "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
        },
        "version": "1.0"
    },
    "basePath": "/",
    "paths": {
        "/admin/api-tokens": {
            "get": {
                "security": [
                    {
                        "AdminAuth": []
                    }
                ],
                "description": "获取系统中所有 API Token 的详详信息（不包含哈希）",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Admin"
                ],
                "summary": "获取 API Token 列表",
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/model.Response"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/definitions/model.APIToken"
                                            }
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/model.Response"
                        }
                    }
                }
            },
            "post": {
                "security": [
                    {
                        "AdminAuth": []
                    }
                ],
                "description": "创建一个新的 API Token，返回原始 Token（仅显示一次）",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Admin"
                ],
                "summary": "创建 API Token",
                "parameters": [
                    {
                        "description": "Token 信息",
                        "name": "request",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/admin.CreateTokenRequest"
                        }
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Created",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/model.Response"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "$ref": "#/definitions/admin.CreateTokenResponse"
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/model.Response"
                        }
                    }
                }
            }
        },
        "/admin/api-tokens/{id}": {
            "delete": {
                "security": [
                    {
                        "AdminAuth": []
                    }
                ],
                "description": "根据 ID 永久删除 API Token",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Admin"
                ],
                "summary": "删除 API Token",
                "parameters": [
                    {
                        "type": "integer",
                        "description": "Token ID",
                        "name": "id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/model.Response"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/model.Response"
                        }
                    }
                }
            }
        },
        "/admin/batch/{batch_id}": {
            "get": {
                "security": [
                    {
                        "AdminAuth": []
                    }
                ],
                "description": "根据批次 ID 获取批次信息及关联的文件列表",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Admin"
                ],
                "summary": "获取批次详情",
                "parameters": [
                    {
                        "type": "integer",
                        "description": "批次 ID",
                        "name": "batch_id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/model.Response"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "$ref": "#/definitions/model.FileBatch"
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/model.Response"
                        }
                    }
                }
            },
            "put": {
                "security": [
                    {
                        "AdminAuth": []
                    }
                ],
                "description": "允许修改备注、过期策略、最大下载次数、状态等",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Admin"
                ],
                "summary": "修改批次信息",
                "parameters": [
                    {
                        "type": "integer",
                        "description": "批次 ID",
                        "name": "batch_id",
                        "in": "path",
                        "required": true
                    },
                    {
                        "description": "修改内容",
                        "name": "request",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/admin.UpdateBatchRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/model.Response"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "$ref": "#/definitions/model.FileBatch"
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/model.Response"
                        }
                    }
                }
            },
            "delete": {
                "security": [
                    {
                        "AdminAuth": []
                    }
                ],
                "description": "标记批次为已删除，并物理删除关联的存储文件",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Admin"
                ],
                "summary": "删除批次",
                "parameters": [
                    {
                        "type": "integer",
                        "description": "批次 ID",
                        "name": "batch_id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/model.Response"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/model.Response"
                        }
                    }
                }
            }
        },
        "/admin/batches": {
            "get": {
                "security": [
                    {
                        "AdminAuth": []
                    }
                ],
                "description": "分页查询所有文件批次，支持按状态过滤和取件码模糊搜索",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Admin"
                ],
                "summary": "获取批次列表",
                "parameters": [
                    {
                        "type": "integer",
                        "description": "页码 (默认 1)",
                        "name": "page",
                        "in": "query"
                    },
                    {
                        "type": "integer",
                        "description": "每页数量 (默认 20)",
                        "name": "page_size",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "状态 (active/expired/deleted)",
                        "name": "status",
                        "in": "query"
                    },
                    {
                        "type": "string",
                        "description": "取件码 (模糊搜索)",
                        "name": "pickup_code",
                        "in": "query"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/model.Response"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "$ref": "#/definitions/admin.ListBatchesResponse"
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/model.Response"
                        }
                    }
                }
            }
        },
        "/admin/login": {
            "post": {
                "description": "通过密码换取 JWT Token",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Admin"
                ],
                "summary": "管理员登录",
                "parameters": [
                    {
                        "description": "登录请求",
                        "name": "request",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/admin.LoginRequest"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/model.Response"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "$ref": "#/definitions/admin.LoginResponse"
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "schema": {
                            "$ref": "#/definitions/model.Response"
                        }
                    }
                }
            }
        },
        "/api/download/batch/{pickup_code}": {
            "get": {
                "description": "根据取件码将批次内的所有文件打包为 ZIP 格式一次性下载",
                "produces": [
                    "application/zip"
                ],
                "tags": [
                    "Public"
                ],
                "summary": "批量下载文件",
                "parameters": [
                    {
                        "type": "string",
                        "description": "取件码",
                        "name": "pickup_code",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "file"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/model.Response"
                        }
                    }
                }
            }
        },
        "/api/download/file/{file_id}": {
            "get": {
                "description": "根据文件 ID 下载单个文件",
                "produces": [
                    "application/octet-stream"
                ],
                "tags": [
                    "Public"
                ],
                "summary": "下载单个文件",
                "parameters": [
                    {
                        "type": "integer",
                        "description": "文件 ID",
                        "name": "file_id",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "file"
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/model.Response"
                        }
                    },
                    "410": {
                        "description": "Gone",
                        "schema": {
                            "$ref": "#/definitions/model.Response"
                        }
                    }
                }
            }
        },
        "/api/pickup/{pickup_code}": {
            "get": {
                "description": "根据取件码获取文件批次详详情和文件列表",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Public"
                ],
                "summary": "获取批次信息",
                "parameters": [
                    {
                        "type": "string",
                        "description": "取件码",
                        "name": "pickup_code",
                        "in": "path",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/model.Response"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "$ref": "#/definitions/public.PickupResponse"
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "404": {
                        "description": "Not Found",
                        "schema": {
                            "$ref": "#/definitions/model.Response"
                        }
                    }
                }
            }
        },
        "/api/upload": {
            "post": {
                "description": "上传一个或多个文件并创建一个提取批次",
                "consumes": [
                    "multipart/form-data"
                ],
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Public"
                ],
                "summary": "上传文件",
                "parameters": [
                    {
                        "type": "file",
                        "description": "文件列表",
                        "name": "files",
                        "in": "formData",
                        "required": true
                    },
                    {
                        "type": "string",
                        "description": "备注",
                        "name": "remark",
                        "in": "formData"
                    },
                    {
                        "type": "string",
                        "description": "过期类型 (time/download/permanent)",
                        "name": "expire_type",
                        "in": "formData"
                    },
                    {
                        "type": "integer",
                        "description": "过期天数 (针对 time 类型)",
                        "name": "expire_days",
                        "in": "formData"
                    },
                    {
                        "type": "integer",
                        "description": "最大下载次数 (针对 download 类型)",
                        "name": "max_downloads",
                        "in": "formData"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "allOf": [
                                {
                                    "$ref": "#/definitions/model.Response"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "$ref": "#/definitions/public.UploadResponse"
                                        }
                                    }
                                }
                            ]
                        }
                    },
                    "400": {
                        "description": "Bad Request",
                        "schema": {
                            "$ref": "#/definitions/model.Response"
                        }
                    },
                    "500": {
                        "description": "Internal Server Error",
                        "schema": {
                            "$ref": "#/definitions/model.Response"
                        }
                    }
                }
            }
        }
    },
    "definitions": {
        "admin.CreateTokenRequest": {
            "type": "object",
            "required": [
                "name"
            ],
            "properties": {
                "expire_at": {
                    "type": "string"
                },
                "name": {
                    "type": "string",
                    "example": "Test Token"
                },
                "scope": {
                    "type": "string",
                    "example": "upload,pickup"
                }
            }
        },
        "admin.CreateTokenResponse": {
            "type": "object",
            "properties": {
                "data": {
                    "$ref": "#/definitions/model.APIToken"
                },
                "token": {
                    "type": "string"
                }
            }
        },
        "admin.ListBatchesResponse": {
            "type": "object",
            "properties": {
                "data": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/model.FileBatch"
                    }
                },
                "page": {
                    "type": "integer"
                },
                "page_size": {
                    "type": "integer"
                },
                "total": {
                    "type": "integer"
                }
            }
        },
        "admin.LoginRequest": {
            "type": "object",
            "required": [
                "password"
            ],
            "properties": {
                "password": {
                    "type": "string",
                    "example": "admin"
                }
            }
        },
        "admin.LoginResponse": {
            "type": "object",
            "properties": {
                "token": {
                    "type": "string"
                }
            }
        },
        "admin.UpdateBatchRequest": {
            "type": "object",
            "properties": {
                "expire_at": {
                    "type": "string"
                },
                "expire_type": {
                    "type": "string"
                },
                "max_downloads": {
                    "type": "integer"
                },
                "remark": {
                    "type": "string"
                },
                "status": {
                    "type": "string"
                }
            }
        },
        "model.APIToken": {
            "type": "object",
            "properties": {
                "created_at": {
                    "type": "string"
                },
                "expire_at": {
                    "type": "string"
                },
                "id": {
                    "type": "integer"
                },
                "last_used_at": {
                    "type": "string"
                },
                "name": {
                    "type": "string"
                },
                "revoked": {
                    "type": "boolean"
                },
                "scope": {
                    "type": "string"
                }
            }
        },
        "model.FileBatch": {
            "type": "object",
            "properties": {
                "created_at": {
                    "type": "string"
                },
                "download_count": {
                    "type": "integer"
                },
                "expire_at": {
                    "type": "string"
                },
                "expire_type": {
                    "description": "time / download / permanent",
                    "type": "string"
                },
                "file_items": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/model.FileItem"
                    }
                },
                "id": {
                    "type": "integer"
                },
                "max_downloads": {
                    "type": "integer"
                },
                "pickup_code": {
                    "type": "string"
                },
                "remark": {
                    "type": "string"
                },
                "status": {
                    "description": "active / expired / deleted",
                    "type": "string"
                },
                "updated_at": {
                    "type": "string"
                }
            }
        },
        "model.FileItem": {
            "type": "object",
            "properties": {
                "batch_id": {
                    "type": "integer"
                },
                "created_at": {
                    "type": "string"
                },
                "id": {
                    "type": "integer"
                },
                "mime_type": {
                    "type": "string"
                },
                "original_name": {
                    "type": "string"
                },
                "size": {
                    "type": "integer"
                },
                "storage_path": {
                    "type": "string"
                }
            }
        },
        "model.Response": {
            "type": "object",
            "properties": {
                "code": {
                    "type": "integer",
                    "example": 200
                },
                "data": {},
                "msg": {
                    "type": "string",
                    "example": "success"
                }
            }
        },
        "public.PickupResponse": {
            "type": "object",
            "properties": {
                "download_count": {
                    "type": "integer"
                },
                "expire_at": {
                    "type": "string"
                },
                "expire_type": {
                    "type": "string"
                },
                "files": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/model.FileItem"
                    }
                },
                "max_downloads": {
                    "type": "integer"
                },
                "remark": {
                    "type": "string"
                }
            }
        },
        "public.UploadResponse": {
            "type": "object",
            "properties": {
                "batch_id": {
                    "type": "integer"
                },
                "expire_at": {
                    "type": "string"
                },
                "pickup_code": {
                    "type": "string"
                }
            }
        }
    },
    "securityDefinitions": {
        "AdminAuth": {
            "description": "Type \"Bearer \u003cyour-jwt-token\u003e\" to authenticate.",
            "type": "apiKey",
            "name": "Authorization",
            "in": "header"
        }
    }
}