{
  "swagger": "2.0",
  "info": {
    "title": "文件服务",
    "version": "1.0.0"
  },
  "basePath": "/",
  "paths": {
    "/admin/file/list": {
      "get": {
        "tags": [
          "文件管理"
        ],
        "summary": "文件列表（分页）",
        "description": "支持按文件类型、分组、上传者等条件筛选，按上传时间倒序分页返回\n\n**关联字典**：\n- file_type：文件类型（列表筛选+显示）\n- file_status：文件状态（显示）",
        "operationId": "listFilesUsingGET",
        "produces": [
          "*/*"
        ],
        "parameters": [
          {
            "name": "endDate",
            "in": "query",
            "description": "结束日期",
            "required": false,
            "type": "string",
            "x-example": "2026-12-31"
          },
          {
            "name": "fileType",
            "in": "query",
            "description": "文件类型",
            "required": false,
            "type": "string",
            "x-example": "image"
          },
          {
            "name": "groupKey",
            "in": "query",
            "description": "业务分组",
            "required": false,
            "type": "string",
            "x-example": "scenic"
          },
          {
            "name": "keyword",
            "in": "query",
            "description": "搜索关键词",
            "required": false,
            "type": "string",
            "x-example": "风景"
          },
          {
            "name": "page",
            "in": "query",
            "description": "页码",
            "required": false,
            "type": "integer",
            "format": "int32",
            "x-example": 1
          },
          {
            "name": "pageSize",
            "in": "query",
            "description": "每页条数",
            "required": false,
            "type": "integer",
            "format": "int32",
            "x-example": 20
          },
          {
            "name": "startDate",
            "in": "query",
            "description": "开始日期",
            "required": false,
            "type": "string",
            "x-example": "2026-01-01"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/统一响应结果«IPage«文件信息»»",
              "originalRef": "统一响应结果«IPage«文件信息»»"
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        },
        "responsesObject": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/统一响应结果«IPage«文件信息»»",
              "originalRef": "统一响应结果«IPage«文件信息»»"
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        },
        "deprecated": false,
        "x-order": "2147483647"
      }
    },
    "/admin/file/stats": {
      "get": {
        "tags": [
          "文件管理"
        ],
        "summary": "存储统计",
        "description": "返回文件总数、总存储空间、各类型文件占比等统计信息",
        "operationId": "getStatsUsingGET",
        "produces": [
          "*/*"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/统一响应结果«文件统计信息»",
              "originalRef": "统一响应结果«文件统计信息»"
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        },
        "responsesObject": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/统一响应结果«文件统计信息»",
              "originalRef": "统一响应结果«文件统计信息»"
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        },
        "deprecated": false,
        "x-order": "2147483647"
      }
    },
    "/admin/file/upload/confirm": {
      "post": {
        "tags": [
          "文件管理"
        ],
        "summary": "确认上传完成",
        "description": "上传流程第二步：前端直传OSS完成后调用此接口，系统验证文件存在性并创建文件记录。支持MD5去重，相同文件不会重复存储",
        "operationId": "confirmUploadUsingPOST",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "*/*"
        ],
        "parameters": [
          {
            "in": "body",
            "name": "request",
            "description": "确认上传请求",
            "required": false,
            "schema": {
              "$ref": "#/definitions/上传确认请求",
              "originalRef": "上传确认请求"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/统一响应结果«文件信息»",
              "originalRef": "统一响应结果«文件信息»"
            }
          },
          "201": {
            "description": "Created"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        },
        "responsesObject": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/统一响应结果«文件信息»",
              "originalRef": "统一响应结果«文件信息»"
            }
          },
          "201": {
            "description": "Created"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        },
        "deprecated": false,
        "x-order": "2147483647"
      }
    },
    "/admin/file/upload/token": {
      "post": {
        "tags": [
          "文件管理"
        ],
        "summary": "请求上传凭证",
        "description": "上传流程第一步：前端请求上传凭证 → 获取OSS预签名URL和临时凭证 → 前端直传OSS → 调用确认上传接口。凭证有效期有限，过期需重新请求",
        "operationId": "requestUploadTokenUsingPOST",
        "consumes": [
          "application/json"
        ],
        "produces": [
          "*/*"
        ],
        "parameters": [
          {
            "in": "body",
            "name": "request",
            "description": "上传凭证请求",
            "required": false,
            "schema": {
              "$ref": "#/definitions/上传令牌请求",
              "originalRef": "上传令牌请求"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/统一响应结果«上传令牌信息»",
              "originalRef": "统一响应结果«上传令牌信息»"
            }
          },
          "201": {
            "description": "Created"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        },
        "responsesObject": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/统一响应结果«上传令牌信息»",
              "originalRef": "统一响应结果«上传令牌信息»"
            }
          },
          "201": {
            "description": "Created"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        },
        "deprecated": false,
        "x-order": "2147483647"
      }
    },
    "/admin/file/{fileId}": {
      "get": {
        "tags": [
          "文件管理"
        ],
        "summary": "文件详情",
        "description": "**关联字典**：\n- file_type：文件类型（显示）\n- file_status：文件状态（显示）",
        "operationId": "getFileDetailUsingGET",
        "produces": [
          "*/*"
        ],
        "parameters": [
          {
            "name": "fileId",
            "in": "path",
            "description": "文件ID",
            "required": false,
            "type": "integer",
            "format": "int64"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/统一响应结果«文件信息»",
              "originalRef": "统一响应结果«文件信息»"
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        },
        "responsesObject": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/统一响应结果«文件信息»",
              "originalRef": "统一响应结果«文件信息»"
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        },
        "deprecated": false,
        "x-order": "2147483647"
      },
      "delete": {
        "tags": [
          "文件管理"
        ],
        "summary": "删除文件",
        "description": "软删除文件记录，如果文件存在引用关系则不允许删除。OSS上的物理文件由定时任务清理",
        "operationId": "deleteFileUsingDELETE",
        "produces": [
          "*/*"
        ],
        "parameters": [
          {
            "name": "fileId",
            "in": "path",
            "description": "文件ID",
            "required": false,
            "type": "integer",
            "format": "int64"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/统一响应结果«Void»",
              "originalRef": "统一响应结果«Void»"
            }
          },
          "204": {
            "description": "No Content"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          }
        },
        "responsesObject": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/统一响应结果«Void»",
              "originalRef": "统一响应结果«Void»"
            }
          },
          "204": {
            "description": "No Content"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          }
        },
        "deprecated": false,
        "x-order": "2147483647"
      }
    },
    "/admin/file/{fileId}/preview": {
      "get": {
        "tags": [
          "文件管理"
        ],
        "summary": "文件内容流式预览",
        "description": "流式输出文件内容，设置正确的Content-Type头，支持浏览器直接预览图片和PDF等文件",
        "operationId": "previewContentUsingGET",
        "produces": [
          "*/*"
        ],
        "parameters": [
          {
            "name": "fileId",
            "in": "path",
            "description": "文件ID",
            "required": false,
            "type": "integer",
            "format": "int64"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        },
        "responsesObject": {
          "200": {
            "description": "OK"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        },
        "deprecated": false,
        "x-order": "2147483647"
      }
    },
    "/admin/file/{fileId}/refs": {
      "get": {
        "tags": [
          "文件管理"
        ],
        "summary": "文件引用列表",
        "description": "查看文件被哪些业务实体引用（如景区封面、酒店图片等），用于判断文件是否可安全删除",
        "operationId": "getFileRefsUsingGET",
        "produces": [
          "*/*"
        ],
        "parameters": [
          {
            "name": "fileId",
            "in": "path",
            "description": "文件ID",
            "required": false,
            "type": "integer",
            "format": "int64"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/统一响应结果«List«文件引用信息»»",
              "originalRef": "统一响应结果«List«文件引用信息»»"
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        },
        "responsesObject": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/统一响应结果«List«文件引用信息»»",
              "originalRef": "统一响应结果«List«文件引用信息»»"
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        },
        "deprecated": false,
        "x-order": "2147483647"
      }
    },
    "/mp/file/preview-by-url": {
      "get": {
        "tags": [
          "C端文件上传"
        ],
        "summary": "文件在线预览",
        "description": "返回HTML预览页面，小程序通过web-view打开。支持PDF、图片、Office文档",
        "operationId": "previewByUrlUsingGET",
        "produces": [
          "*/*"
        ],
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "description": "文件完整URL",
            "required": false,
            "type": "string",
            "allowEmptyValue": false
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        },
        "responsesObject": {
          "200": {
            "description": "OK"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        },
        "deprecated": false,
        "x-order": "2147483647"
      }
    },
    "/mp/file/upload": {
      "post": {
        "tags": [
          "C端文件上传"
        ],
        "summary": "上传文件（C端用户）",
        "description": "小程序端直接上传文件，支持头像、评价图片等场景。groupKey决定存储路径和文件策略，默认为avatar",
        "operationId": "uploadUsingPOST",
        "consumes": [
          "multipart/form-data"
        ],
        "produces": [
          "*/*"
        ],
        "parameters": [
          {
            "name": "file",
            "in": "formData",
            "description": "上传文件",
            "required": false,
            "type": "file"
          },
          {
            "name": "groupKey",
            "in": "query",
            "description": "文件分组标识",
            "required": false,
            "type": "string",
            "default": "avatar",
            "allowEmptyValue": false
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/统一响应结果«文件信息»",
              "originalRef": "统一响应结果«文件信息»"
            }
          },
          "201": {
            "description": "Created"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        },
        "responsesObject": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/统一响应结果«文件信息»",
              "originalRef": "统一响应结果«文件信息»"
            }
          },
          "201": {
            "description": "Created"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        },
        "deprecated": false,
        "x-order": "2147483647"
      }
    },
    "/mp/file/{fileId}/preview": {
      "get": {
        "tags": [
          "C端文件上传"
        ],
        "summary": "文件内容流式预览",
        "description": "流式输出文件内容，设置正确的Content-Type头。用于小程序端通过web-view直接预览图片和PDF等文件。",
        "operationId": "previewContentUsingGET_1",
        "produces": [
          "*/*"
        ],
        "parameters": [
          {
            "name": "fileId",
            "in": "path",
            "description": "文件ID",
            "required": false,
            "type": "integer",
            "format": "int64"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        },
        "responsesObject": {
          "200": {
            "description": "OK"
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found"
          }
        },
        "deprecated": false,
        "x-order": "2147483647"
      }
    }
  },
  "definitions": {
    "IPage«文件信息»": {
      "type": "object",
      "properties": {
        "current": {
          "type": "integer",
          "format": "int64"
        },
        "pages": {
          "type": "integer",
          "format": "int64"
        },
        "records": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/文件信息",
            "originalRef": "文件信息"
          }
        },
        "size": {
          "type": "integer",
          "format": "int64"
        },
        "total": {
          "type": "integer",
          "format": "int64"
        }
      },
      "title": "IPage«文件信息»"
    },
    "STS临时凭证信息": {
      "type": "object",
      "properties": {
        "accessKeyId": {
          "type": "string",
          "description": "AccessKey ID"
        },
        "accessKeySecret": {
          "type": "string",
          "description": "AccessKey Secret"
        },
        "expiration": {
          "type": "string",
          "description": "过期时间"
        },
        "securityToken": {
          "type": "string",
          "description": "安全令牌"
        }
      },
      "title": "STS临时凭证信息"
    },
    "上传令牌信息": {
      "type": "object",
      "properties": {
        "bucket": {
          "type": "string",
          "description": "OSS Bucket名称"
        },
        "contentType": {
          "type": "string",
          "description": "上传时必须使用的Content-Type（与预签名URL签名一致）"
        },
        "expireAt": {
          "type": "string",
          "format": "date-time",
          "description": "过期时间"
        },
        "file": {
          "description": "秒传文件信息",
          "$ref": "#/definitions/文件信息",
          "originalRef": "文件信息"
        },
        "fileId": {
          "type": "string",
          "description": "文件ID"
        },
        "ossKey": {
          "type": "string",
          "description": "OSS对象Key"
        },
        "presignedUrl": {
          "type": "string",
          "description": "预签名上传URL"
        },
        "region": {
          "type": "string",
          "description": "OSS Region"
        },
        "stsToken": {
          "description": "STS临时凭证",
          "$ref": "#/definitions/STS临时凭证信息",
          "originalRef": "STS临时凭证信息"
        },
        "uploadMode": {
          "type": "string",
          "description": "上传模式: PRESIGNED_URL/STS_MULTIPART/INSTANT"
        }
      },
      "title": "上传令牌信息"
    },
    "上传令牌请求": {
      "type": "object",
      "required": [
        "fileHash",
        "fileName",
        "fileSize"
      ],
      "properties": {
        "fileHash": {
          "type": "string",
          "example": "d41d8cd98f00b204e9800998ecf8427e",
          "description": "文件MD5哈希"
        },
        "fileName": {
          "type": "string",
          "example": "photo.jpg",
          "description": "文件名"
        },
        "fileSize": {
          "type": "integer",
          "format": "int64",
          "example": 1048576,
          "description": "文件大小(字节)"
        },
        "forcePresigned": {
          "type": "boolean",
          "example": false,
          "description": "强制使用预签名URL（跳过STS分片模式）"
        },
        "groupKey": {
          "type": "string",
          "example": "scenic",
          "description": "业务分组"
        }
      },
      "title": "上传令牌请求"
    },
    "上传确认请求": {
      "type": "object",
      "required": [
        "fileId"
      ],
      "properties": {
        "fileId": {
          "type": "string",
          "example": 1234567890,
          "description": "文件ID"
        }
      },
      "title": "上传确认请求"
    },
    "文件信息": {
      "type": "object",
      "properties": {
        "createdAt": {
          "type": "string",
          "format": "date-time",
          "description": "创建时间"
        },
        "fileHash": {
          "type": "string",
          "description": "文件MD5哈希"
        },
        "fileId": {
          "type": "string",
          "description": "文件ID"
        },
        "fileName": {
          "type": "string",
          "description": "文件名"
        },
        "fileSize": {
          "type": "integer",
          "format": "int64",
          "description": "文件大小(字节)"
        },
        "fileType": {
          "type": "string",
          "description": "文件类型"
        },
        "groupKey": {
          "type": "string",
          "description": "业务分组"
        },
        "mimeType": {
          "type": "string",
          "description": "MIME类型"
        },
        "ossUrl": {
          "type": "string",
          "description": "OSS地址"
        },
        "previewUrl": {
          "type": "string",
          "description": "预览地址"
        },
        "refCount": {
          "type": "integer",
          "format": "int32",
          "description": "引用次数"
        },
        "status": {
          "type": "string",
          "description": "文件状态"
        },
        "thumbnailUrl": {
          "type": "string",
          "description": "缩略图地址"
        }
      },
      "title": "文件信息"
    },
    "文件引用信息": {
      "type": "object",
      "properties": {
        "bizId": {
          "type": "string",
          "description": "业务ID"
        },
        "bizType": {
          "type": "string",
          "description": "业务类型"
        },
        "createdAt": {
          "type": "string",
          "format": "date-time",
          "description": "创建时间"
        },
        "fileId": {
          "type": "string",
          "description": "文件ID"
        },
        "refId": {
          "type": "string",
          "description": "引用ID"
        }
      },
      "title": "文件引用信息"
    },
    "文件统计信息": {
      "type": "object",
      "properties": {
        "countByGroup": {
          "type": "object",
          "description": "按分组统计文件数量",
          "additionalProperties": {
            "type": "integer",
            "format": "int64"
          }
        },
        "countByType": {
          "type": "object",
          "description": "按类型统计文件数量",
          "additionalProperties": {
            "type": "integer",
            "format": "int64"
          }
        },
        "sizeByType": {
          "type": "object",
          "description": "按类型统计文件大小",
          "additionalProperties": {
            "type": "integer",
            "format": "int64"
          }
        },
        "totalCount": {
          "type": "integer",
          "format": "int64",
          "description": "文件总数"
        },
        "totalSize": {
          "type": "integer",
          "format": "int64",
          "description": "文件总大小(字节)"
        }
      },
      "title": "文件统计信息"
    },
    "统一响应结果«IPage«文件信息»»": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32",
          "example": 200,
          "description": "状态码"
        },
        "data": {
          "description": "响应数据",
          "$ref": "#/definitions/IPage«文件信息»",
          "originalRef": "IPage«文件信息»"
        },
        "message": {
          "type": "string",
          "example": "成功",
          "description": "响应消息"
        }
      },
      "title": "统一响应结果«IPage«文件信息»»"
    },
    "统一响应结果«List«文件引用信息»»": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32",
          "example": 200,
          "description": "状态码"
        },
        "data": {
          "type": "array",
          "description": "响应数据",
          "items": {
            "$ref": "#/definitions/文件引用信息",
            "originalRef": "文件引用信息"
          }
        },
        "message": {
          "type": "string",
          "example": "成功",
          "description": "响应消息"
        }
      },
      "title": "统一响应结果«List«文件引用信息»»"
    },
    "统一响应结果«Void»": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32",
          "example": 200,
          "description": "状态码"
        },
        "message": {
          "type": "string",
          "example": "成功",
          "description": "响应消息"
        }
      },
      "title": "统一响应结果«Void»"
    },
    "统一响应结果«上传令牌信息»": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32",
          "example": 200,
          "description": "状态码"
        },
        "data": {
          "description": "响应数据",
          "$ref": "#/definitions/上传令牌信息",
          "originalRef": "上传令牌信息"
        },
        "message": {
          "type": "string",
          "example": "成功",
          "description": "响应消息"
        }
      },
      "title": "统一响应结果«上传令牌信息»"
    },
    "统一响应结果«文件信息»": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32",
          "example": 200,
          "description": "状态码"
        },
        "data": {
          "description": "响应数据",
          "$ref": "#/definitions/文件信息",
          "originalRef": "文件信息"
        },
        "message": {
          "type": "string",
          "example": "成功",
          "description": "响应消息"
        }
      },
      "title": "统一响应结果«文件信息»"
    },
    "统一响应结果«文件统计信息»": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32",
          "example": 200,
          "description": "状态码"
        },
        "data": {
          "description": "响应数据",
          "$ref": "#/definitions/文件统计信息",
          "originalRef": "文件统计信息"
        },
        "message": {
          "type": "string",
          "example": "成功",
          "description": "响应消息"
        }
      },
      "title": "统一响应结果«文件统计信息»"
    }
  }
}