yg-yygl 0.0.1

package/src/views/file//346/226/207/344/273/266/347/256/241/347/220/206/345/211/215/347/253/257/345/274/200/345/217/221/346/226/207/346/241/243.md

@@ -0,0 +1,1166 @@
+# 文件管理模块 - 前端开发文档
+
+## 一、模块概述
+
+本模块包含两个主要功能：
+
+- **文件配置**：管理多种文件存储器的配置（本地磁盘、SFTP、MinIO对象存储）
+- **文件列表**：管理已上传的文件，支持上传、查询、预览、下载、删除
+
+---
+
+## 二、文件配置模块
+
+### 2.1 列表页面 (`file-config/index.vue`)
+
+#### 页面结构
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  文件配置                                                    │
+├─────────────────────────────────────────────────────────────┤
+│  筛选区域：                                                  │
+│  ┌─────────┐ ┌─────────┐ ┌───────────┐ ┌─────────┐          │
+│  │配置名   │ │存储器   │ │创建时间   │ │[查询]   │          │
+│  └─────────┘ └─────────┘ └───────────┘ │[重置]   │          │
+│                                          └─────────┘          │
+├─────────────────────────────────────────────────────────────┤
+│  [+ 新增]                                                   │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │表格列：编号|配置名|存储器|备注|主配置|激活状态|...│   │
+│  ├─────────────────────────────────────────────────────┤   │
+│  │数据行...                                            │   │
+│  └─────────────────────────────────────────────────────┘   │
+│  分页器                                                    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+#### 筛选条件
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| 配置名 | String | 模糊匹配 |
+| 存储器 | Select | 下拉选择存储器类型 |
+| 创建时间 | DateRange | 日期区间筛选 |
+
+#### 表格列定义
+
+| 列名 | 字段 | 类型 | 说明 |
+|------|------|------|------|
+| 编号 | id | Number | 系统生成唯一标识 |
+| 配置名 | configName | String | 用户自定义配置名称 |
+| 存储器 | storageType | String | 存储类型（local-本地磁盘，sftp-SFTP服务器，minio-MinIO对象存储）|
+| 备注 | configRemark | String | 备注信息 |
+| 主配置 | isPrimary | Number | 0-否，1-是 |
+| 激活状态 | isActive | Number | 0-未激活，1-已激活（开关按钮）|
+| 创建人 | createUser | Number | 创建人ID |
+| 创建时间 | createTime | String | YYYY-MM-DD HH:MM:SS |
+| 最后更新时间 | updateTime | String | YYYY-MM-DD HH:MM:SS |
+| 操作 | - | - | 编辑/主配置/删除 |
+
+#### 排序与分页
+
+- **排序**：按照编号由大到小排序
+- **分页**：支持分页展示
+
+#### 列表操作
+
+| 操作 | 说明 | 确认提示 |
+|------|------|----------|
+| 编辑 | 修改配置信息 | - |
+| 主配置 | 设置该配置为默认主配置，仅允许一个主配置存在 | "确认将该配置设为主配置？" |
+| 删除 | 删除当前配置 | "是否删除所选中数据？" |
+
+> **注意**：仅激活状态的主配置可用
+
+#### API 接口
+
+> **重要说明**：所有接口均为 POST 请求，参数放在 Request Body 中
+
+```typescript
+// 列表查询
+POST /api/fileConfig/page
+body: {
+  current: number            // 当前页码，默认第1页
+  size: number               // 每页大小，默认10条
+  model: {
+    configName?: string      // 配置名（模糊匹配）
+    storageType?: string     // 存储器类型（local/sftp/minio）
+    isPrimary?: number       // 是否主配置（0-否，1-是）
+  }
+}
+// 响应: Result<PageResult<FileConfigResponse>>
+// PageResult 包含: records (列表数据), total (总数), current (当前页), size (每页大小)
+
+// 根据ID查询配置详情
+POST /api/fileConfig/get
+body: {
+  id: number                 // 配置ID
+}
+// 响应: Result<FileConfigResponse>
+
+// 创建配置
+POST /api/fileConfig/create
+body: {
+  configName: string         // 配置名称
+  configRemark?: string      // 配置备注
+  storageType: string        // 存储器类型（local/sftp/minio）
+  customDomain?: string      // 自定义域名
+  isPrimary?: number         // 是否主配置（0-否，1-是）
+  // 动态字段根据 storageType 变化
+  basePath?: string          // 基础路径（local/sftp）
+  host?: string              // 主机地址（sftp）
+  port?: number              // 主机端口（sftp）
+  username?: string          // 用户名（sftp）
+  password?: string          // 密码（sftp）
+  endpoint?: string          // 节点地址（minio）
+  bucketName?: string        // 存储桶名称（minio）
+  accessKey?: string         // 访问密钥（minio）
+  accessSecret?: string      // 访问密钥秘钥（minio）
+  pathStyle?: number         // 是否使用Path Style（minio，0-否，1-是）
+  publicAccess?: number      // 公开访问（minio，0-私有，1-公开）
+  region?: string            // 区域（minio）
+}
+// 响应: Result<FileConfigResponse>
+
+// 更新配置
+POST /api/fileConfig/update
+body: {
+  id: number                 // 配置ID（必填）
+  configName: string         // 配置名称
+  configRemark?: string      // 配置备注
+  storageType: string        // 存储器类型（local/sftp/minio）
+  customDomain?: string      // 自定义域名
+  isPrimary?: number         // 是否主配置（0-否，1-是）
+  // 动态字段根据 storageType 变化（storageType 不可修改）
+  basePath?: string          // 基础路径（local/sftp）
+  host?: string              // 主机地址（sftp）
+  port?: number              // 主机端口（sftp）
+  username?: string          // 用户名（sftp）
+  password?: string          // 密码（sftp）
+  endpoint?: string          // 节点地址（minio）
+  bucketName?: string        // 存储桶名称（minio）
+  accessKey?: string         // 访问密钥（minio）
+  accessSecret?: string      // 访问密钥秘钥（minio）
+  pathStyle?: number         // 是否使用Path Style（minio，0-否，1-是）
+  publicAccess?: number      // 公开访问（minio，0-私有，1-公开）
+  region?: string            // 区域（minio）
+}
+// 响应: Result<FileConfigResponse>
+
+// 删除配置
+POST /api/fileConfig/delete
+body: {
+  id: number                 // 配置ID
+}
+// 响应: Result<Void>
+```
+
+---
+
+### 2.2 新增/编辑页面 (`file-config/form.vue`)
+
+#### 展示方式
+
+- **右侧抽屉**展示表单
+
+#### 通用字段
+
+| 字段 | 类型 | 必填 | 长度限制 | 格式要求 | 占位提示 | 说明 |
+|------|------|------|----------|----------|----------|------|
+| 配置名 | String | 是 | 1-50 | 中文/英文/数字/下划线/中划线 | 请输入配置名 | 唯一标识，不可重复 |
+| 备注 | String | 否 | 0-200 | 无限制 | 请输入备注信息 | 说明性文字 |
+| 存储器 | Select | 是 | - | 枚举 | 请选择存储器类型 | - |
+| 自定义域名 | URL | 否 | 0-255 | http:// 或 https:// 开头 | 请输入自定义域名 | 为空时使用默认域名 |
+
+#### 存储器枚举值
+
+```typescript
+enum StorageType {
+  LOCAL = 'local',   // 本地磁盘
+  SFTP = 'sftp',     // SFTP 服务器
+  MINIO = 'minio'    // MinIO 对象存储
+}
+```
+
+#### 动态字段配置
+
+##### 本地磁盘（local）
+
+| 字段 | 类型 | 必填 | 长度限制 | 占位提示 | 说明 |
+|------|------|------|----------|----------|------|
+| 基础路径 | String | 是 | 1-255 | 请输入基础路径 | mac/linux 使用 /，windows 使用 \\，需确保目录存在且有读写权限 |
+
+##### SFTP 服务器（sftp）
+
+| 字段 | 类型 | 必填 | 长度限制 | 格式要求 | 占位提示 | 说明 |
+|------|------|------|----------|----------|----------|------|
+| 基础路径 | String | 是 | 1-255 | - | 请输入基础路径 | SFTP 服务器上的工作目录 |
+| 主机地址 | String | 是 | 1-255 | IP 或域名格式 | 请输入主机地址 | 服务器地址 |
+| 主机端口 | Number | 是 | 1-65535 | 整数 | 请输入主机端口 | SFTP 默认端口 22 |
+| 用户名 | String | 是 | 1-100 | 无限制 | 请输入用户名 | 登录账号 |
+| 密码 | String | 是 | 1-100 | 无限制 | 请输入密码 | 登录密码，敏感信息需加密存储 |
+
+##### MinIO 对象存储（minio）
+
+| 字段 | 类型 | 必填 | 长度限制 | 格式要求 | 占位提示 | 说明 |
+|------|------|------|----------|----------|----------|------|
+| 节点地址 | String | 是 | 1-255 | 合法 URL 格式 | 请输入节点地址 | MinIO 服务器地址 |
+| 存储 bucket | String | 是 | 3-63 | 小写字母/数字/中划线，不能以中划线开头结尾 | 请输入存储桶名称 | 存储桶名称 |
+| accessKey | String | 是 | 1-100 | 无限制 | 请输入访问密钥 | 访问密钥 ID |
+| accessSecret | String | 是 | 1-100 | 无限制 | 请输入访问密钥秘钥 | 访问密钥 Secret（敏感信息需加密存储）|
+| Path Style | Radio | 是 | - | - | - | 是否使用Path Style（0-否，1-是）|
+| 公开访问 | Radio | 是 | - | - | - | 公开访问（0-私有，1-公开）|
+| 区域 | String | 否 | 0-50 | 字母/数字/中划线 | 请填写区域 | 区域（一般仅 AWS 需要填写）|
+
+#### 校验规则汇总
+
+##### 通用校验
+
+| 字段 | 校验规则 | 错误提示 |
+|------|----------|----------|
+| 配置名 | • 必填<br>• 长度 1-50<br>• 仅支持中文、英文、数字、下划线、中划线<br>• 新增时不可与已有配置名重复<br>• 编辑时修改配置名不可与已有配置名重复 | • 请填写配置名<br>• 配置名长度不能超过 50 个字符<br>• 配置名只能包含中文、英文、数字、下划线和中划线<br>• 配置名已存在 |
+| 备注 | • 长度 0-200 | • 备注长度不能超过 200 个字符 |
+| 存储器 | • 必选 | • 请选择存储器 |
+| 自定义域名 | • 如果填写，必须是合法 URL 格式，以 http:// 或 https:// 开头 | • 自定义域名格式不正确，请以 http:// 或 https:// 开头 |
+
+##### 本地磁盘校验
+
+| 字段 | 校验规则 | 错误提示 |
+|------|----------|----------|
+| 基础路径 | • 必填<br>• 长度 1-255 | • 请填写基础路径<br>• 基础路径长度不能超过 255 个字符 |
+
+##### SFTP 校验
+
+| 字段 | 校验规则 | 错误提示 |
+|------|----------|----------|
+| 基础路径 | • 必填<br>• 长度 1-255 | • 请填写基础路径<br>• 基础路径长度不能超过 255 个字符 |
+| 主机地址 | • 必填<br>• 长度 1-255<br>• IP 或域名格式 | • 请填写主机地址<br>• 主机地址长度不能超过 255 个字符<br>• 请输入有效的 IP 地址或域名 |
+| 主机端口 | • 必填<br>• 整数<br>• 范围 1-65535 | • 请填写主机端口<br>• 主机端口必须为整数<br>• 主机端口范围应为 1-65535 |
+| 用户名 | • 必填<br>• 长度 1-100 | • 请填写用户名<br>• 用户名长度不能超过 100 个字符 |
+| 密码 | • 必填<br>• 长度 1-100 | • 请填写密码<br>• 密码长度不能超过 100 个字符 |
+
+##### MinIO 对象存储校验
+
+| 字段 | 校验规则 | 错误提示 |
+|------|----------|----------|
+| 节点地址 | • 必填<br>• 长度 1-255<br>• 合法 URL 格式 | • 请填写节点地址<br>• 节点地址长度不能超过 255 个字符<br>• 请输入有效的 URL 地址 |
+| 存储 bucket | • 必填<br>• 长度 3-63<br>• 小写字母、数字、中划线<br>• 不能以中划线开头或结尾 | • 请填写存储 bucket<br>• 存储 bucket 长度应为 3-63 个字符<br>• 存储 bucket 只能包含小写字母、数字和中划线<br>• 存储 bucket 不能以中划线开头或结尾 |
+| accessKey | • 必填<br>• 长度 1-100 | • 请填写 accessKey<br>• accessKey 长度不能超过 100 个字符 |
+| accessSecret | • 必填<br>• 长度 1-100 | • 请填写 accessSecret<br>• accessSecret 长度不能超过 100 个字符 |
+| 区域 | • 如果填写，长度 0-50<br>• 字母、数字、中划线 | • 区域长度不能超过 50 个字符<br>• 区域只能包含字母、数字和中划线 |
+
+#### 测试连接功能
+
+**触发方式**：点击表单底部"测试"按钮
+
+**逻辑**：使用当前表单中填写的所有配置参数（包括通用字段和存储器相关动态字段）向目标存储服务发起连接测试，验证配置的有效性。
+
+**测试结果展示**：
+
+| 结果 | 提示方式 | 文案示例 | 样式 |
+|------|----------|----------|------|
+| 测试成功 | 顶部成功提示条或弹窗 | 测试成功！配置可用。 | 绿色成功提示 |
+| 测试失败 | 顶部失败提示条或弹窗 | 测试失败：[具体错误原因] | 红色错误提示 |
+
+#### API 接口
+
+```typescript
+// 新增配置
+POST /api/file/config
+body: {
+  configName: string         // 配置名称
+  configRemark?: string      // 配置备注
+  storageType: StorageType   // 存储器类型（local/sftp/minio）
+  customDomain?: string      // 自定义域名
+  // 动态字段根据 storageType 变化
+  basePath?: string          // 基础路径（local/sftp）
+  host?: string              // 主机地址（sftp）
+  port?: number              // 主机端口（sftp）
+  username?: string          // 用户名（sftp）
+  password?: string          // 密码（sftp）
+  endpoint?: string          // 节点地址（minio）
+  bucketName?: string        // 存储桶名称（minio）
+  accessKey?: string         // 访问密钥（minio）
+  accessSecret?: string      // 访问密钥秘钥（minio）
+  pathStyle?: number         // 是否使用Path Style（minio，0-否，1-是）
+  publicAccess?: number      // 公开访问（minio，0-私有，1-公开）
+  region?: string            // 区域（minio）
+}
+
+// 编辑配置
+PUT /api/file/config/{id}
+body: {
+  configName: string
+  configRemark?: string
+  customDomain?: string
+  // 动态字段根据 storageType 变化（storageType 不可修改）
+}
+
+// 获取配置详情
+GET /api/file/config/{id}
+
+// 测试连接
+POST /api/file/config/test
+body: {
+  storageType: string
+  config: Record<string, any>
+}
+// 成功响应: { success: true, message: '测试成功！配置可用。' }
+// 失败响应: { success: false, message: '测试失败：具体错误原因' }
+
+// 检查配置名是否存在
+GET /api/file/config/check-name
+params: {
+  configName: string
+  excludeId?: number  // 编辑时排除当前配置
+}
+```
+
+#### 交互规则
+
+1. **实时校验**
+   - 用户输入时实时进行格式校验，错误时在字段下方显示红色提示文字
+   - 表单提交时进行完整校验，所有校验通过后方可提交
+
+2. **存储器切换**
+   - 切换存储器时，动态字段区域清空并重新渲染
+   - 通用字段（配置名、备注、自定义域名）保留用户已输入的内容
+
+3. **提交成功与失败**
+   - 提交成功：显示成功提示，返回列表页
+   - 提交失败：显示错误提示，保留用户输入内容
+
+---
+
+## 三、文件列表模块
+
+文件列表模块用于展示和管理已上传的文件，支持文件的上传、查询、预览、下载（复制链接）和删除等操作。用户可以通过筛选条件快速定位目标文件，并对文件进行批量管理。
+
+---
+
+### 3.1 列表页面 (`file-list/index.vue`)
+
+#### 功能界面
+
+#### 查询与筛选
+
+| 字段 | 说明 |
+|------|------|
+| 文件路径 | 支持模糊匹配，按文件存储路径筛选 |
+| 文件类型 | 支持模糊匹配（如 image/jpeg）|
+| 创建时间 | 支持按日期区间筛选 |
+
+提供【查询】按钮，点击后根据筛选条件刷新列表
+
+提供【重置】按钮，清空所有筛选条件
+
+#### 列表展示
+
+| 列名 | 说明 |
+|------|------|
+| 多选框 | 用于批量操作，支持全选/反选 |
+| 文件名 | 文件原始名称 |
+| 文件路径 | 文件在存储中的相对路径，如 20260323/飞机.jpg |
+| URL | 文件访问地址，显示截断地址，鼠标悬浮显示完整地址 |
+| 文件大小 | 文件大小，自动格式化为 KB、MB、GB，保留两位小数 |
+| 文件类型 | MIME 类型，如 image/jpeg |
+| 文件内容 | 文件预览，图片显示缩略图，支持点击预览 |
+| 上传时间 | 文件上传时间，格式为 YYYY-MM-DD HH:MM:SS |
+| 操作 | 包含"复制链接"、"删除"按钮 |
+
+#### 排序与分页
+
+- **排序**：按照上传时间由近及远排序
+- **分页**：支持分页展示
+
+#### 列表行操作功能
+
+| 操作 | 说明 |
+|------|------|
+| 复制链接 | 复制文件访问 URL 到剪贴板，提示"复制成功" |
+| 删除 | 删除单个文件，需二次确认：是否删除所选中数据？（取消、确定）|
+
+#### 列表头操作功能
+
+| 操作 | 说明 |
+|------|------|
+| 上传文件 | 点击后弹出文件选择对话框 |
+| 批量删除 | 支持多选，提供【批量删除】按钮，删除选中配置，需二次确认：是否删除所选中数据？（取消、确定）<br>至少选中一个文件时按钮才可点击，否则提示：至少选中一个文件 |
+
+#### API 接口
+
+> **重要说明**：所有接口均为 POST 请求，参数放在 Request Body 中
+
+```typescript
+// 列表查询
+POST /api/fileInfo/page
+body: {
+  current: number            // 当前页码，默认第1页
+  size: number               // 每页大小，默认10条
+  model: {
+    fileName?: string        // 文件名（模糊匹配）
+    filePath?: string        // 文件路径（模糊匹配）
+    fileType?: string        // 文件类型（模糊匹配，如 image/jpeg）
+  }
+}
+// 响应: Result<PageResult<FileInfoResponse>>
+// PageResult 包含: records (列表数据), total (总数), current (当前页), size (每页大小)
+
+// 根据ID查询文件详情
+POST /api/fileInfo/get
+body: {
+  id: number                 // 文件ID
+}
+// 响应: Result<FileInfoResponse>
+
+// 删除单个文件
+POST /api/fileInfo/delete
+body: {
+  id: number                 // 文件ID
+}
+// 响应: Result<Void>
+
+// 批量删除文件（调用多次删除接口或后端支持批量删除）
+POST /api/fileInfo/delete
+body: {
+  id: number                 // 文件ID（循环调用或使用批量接口）
+}
+// 响应: Result<Void>
+
+// 复制链接（前端实现）
+// 使用 navigator.clipboard.writeText(url)
+```
+
+---
+
+### 3.2 上传文件弹窗 (`file-list/upload.vue`)
+
+#### 功能界面
+
+#### 功能说明
+
+| 项目 | 说明 |
+|------|------|
+| 触发方式 | 提供拖拽上传、点击上传 |
+| 文件格式限制 | jpg、png、gif |
+| 文件数量限制 | 1 个，当已选择 1 个文件后，再次选择文件时提示：最多只能上传一个文件！ |
+| 文件大小限制 | 单个文件不超过 100MB |
+| 待上传列表 | 显示已选中的待上传文件列表：文件名.后缀；支持删除待上传文件 |
+
+#### 交互规则
+
+| 操作 | 结果 |
+|------|------|
+| 点击确定 | 开始上传待上传列表中的文件 |
+| 点击取消 | 关闭弹窗，清空已选文件列表 |
+| 上传成功 | toast 提示：文件上传成功，返回列表 |
+| 上传失败 | toast 提示相应的报错信息 |
+
+#### API 接口
+
+```typescript
+// 上传文件
+POST /api/common/upload/file
+Content-Type: multipart/form-data
+body: {
+  file: CommonsMultipartFile  // 文件对象（使用 CommonsMultipartFile）
+  source?: string             // 存储源，默认为 "local"，支持 "minio"
+}
+// 响应: Result<FileResponse>
+// FileResponse 包含:
+//   id: string                // 文件ID（数据库自增ID的字符串形式）
+//   fileUrl: string           // 文件访问地址
+//   fileName: string          // 文件名（经过XSS过滤）
+//   fileType: string          // 文件类型（扩展名，如 "jpg"、"png"）
+//   fileSize: string          // 文件大小（格式化后，如 "1.23 MB"）
+//
+// 错误响应示例:
+//   Result.error(-1, "上传文件不能为空")
+//   Result.error(-1, "不支持的上传目标")
+//   Result.error(-1, "不支持的文件类型: xxx, 支持的类型: [...]")
+//   Result.error(-1, "文件上传安全检查失败: ...")
+//   Result.error(-1, "文件上传参数错误: ...")
+//   Result.error(-1, "文件上传失败: ...")
+
+// 文件下载（如需实现下载功能）
+POST /api/common/download/file
+body: {
+  fileName: string            // 文件名（URL编码）
+  source?: string             // 存储源，默认为 "local"
+}
+// 响应: 直接写入 HttpServletResponse（文件流）
+// 注意：此接口由于直接写入HttpServletResponse，无法完全遵循Feign规范
+
+// 保存附件信息（通用接口，用于关联业务ID）
+POST /api/common/attachment/save
+params: {
+  businessId: string          // 业务ID
+}
+body: List<Attachment>        // 附件列表
+// 响应: Result<Void>
+
+// 根据业务ID查询关联附件
+POST /api/common/attachment/query
+params: {
+  businessId: string          // 业务ID
+}
+// 响应: Result<List<Attachment>>
+
+// 获取图片（通过ID或业务ID）
+GET /api/common/image/queryById
+params: {
+  id?: string                 // 文件ID（可选）
+  businessId?: string         // 业务ID（可选）
+  tenantId?: string           // 租户ID（可选）
+}
+// 响应: ResponseEntity<ByteArrayResource>
+// 注意：id 和 businessId 至少需要提供一个
+```
+
+---
+
+## 四、文件结构
+
+```
+apps/admin/src/views/file/
+├── 文件管理前端开发文档.md       # 本文档
+├── file-config/
+│   ├── index.vue                  # 列表页
+│   ├── form.vue                   # 新增/编辑抽屉
+│   └── components/
+│       ├── LocalDiskForm.vue      # 本地磁盘表单
+│       ├── SftpForm.vue           # SFTP表单
+│       └── MinioForm.vue          # MinIO表单
+└── file-list/
+    ├── index.vue                  # 列表页
+    ├── upload.vue                 # 上传弹窗
+    └── components/
+        └── ImagePreview.vue       # 图片预览
+```
+
+---
+
+## 五、类型定义
+
+```typescript
+// types/file.d.ts
+
+/** 存储器类型枚举 */
+enum StorageType {
+  LOCAL = 'local',     // 本地磁盘
+  SFTP = 'sftp',       // SFTP 服务器
+  MINIO = 'minio'      // MinIO 对象存储
+}
+
+/** 文件配置 */
+interface FileConfig {
+  id: number
+  configName: string           // 配置名称
+  configRemark?: string        // 配置备注
+  storageType: StorageType     // 存储器类型（local/sftp/minio）
+  customDomain?: string        // 自定义域名
+  isPrimary: number            // 是否主配置（0-否，1-是）
+  createTime: string           // 创建时间
+  updateTime?: string          // 更新时间
+
+  // 本地磁盘和SFTP字段
+  basePath?: string            // 基础路径
+
+  // SFTP 字段
+  host?: string                // 主机地址
+  port?: number                // 主机端口
+  username?: string            // 用户名
+  password?: string            // 密码（脱敏显示）
+
+  // MinIO 字段
+  endpoint?: string            // 节点地址
+  bucketName?: string          // 存储桶名称
+  accessKey?: string           // 访问密钥
+  accessSecret?: string        // 访问密钥秘钥（脱敏显示）
+  pathStyle?: number           // 是否使用Path Style（0-否，1-是）
+  publicAccess?: number        // 公开访问（0-私有，1-公开）
+  region?: string              // 区域
+}
+
+/** 本地磁盘配置 */
+interface LocalDiskConfig {
+  basePath: string              // 基础路径
+}
+
+/** SFTP 配置 */
+interface SftpConfig {
+  basePath: string              // 基础路径
+  host: string                  // 主机地址
+  port: number                  // 主机端口
+  username: string              // 用户名
+  password: string              // 密码
+}
+
+/** MinIO 配置 */
+interface MinioConfig {
+  endpoint: string              // 节点地址
+  bucketName: string            // 存储桶名称
+  accessKey: string             // 访问密钥
+  accessSecret: string          // 访问密钥秘钥
+  pathStyle: number             // 是否使用Path Style（0-否，1-是）
+  publicAccess: number          // 公开访问（0-私有，1-公开）
+  region?: string               // 区域
+}
+
+/** 文件信息 */
+interface FileInfo {
+  id: number                   // 文件ID
+  url: string                  // 文件访问地址
+  fileName: string             // 文件名
+  fileType: string             // 文件类型（扩展名）
+  fileSize: string             // 文件大小（格式化后，如 "1.23 MB"）
+  businessId?: string          // 业务ID
+  createUser?: number          // 创建人ID
+  createTime: string           // 创建时间
+  updateUser?: number          // 更新人ID
+  updateTime?: string          // 更新时间
+  tenantId?: number            // 租户ID
+}
+
+/** 文件上传响应 */
+interface FileResponse {
+  id: string                   // 文件ID
+  fileUrl: string              // 文件访问地址
+  fileName: string             // 文件名
+  fileType: string             // 文件类型（扩展名）
+  fileSize: string             // 文件大小（格式化后）
+}
+
+/** 文件上传请求 */
+interface FileUploadRequest {
+  file: File                   // 文件对象
+  source?: string              // 存储源，默认 "local"
+}
+
+/** 分页请求 */
+interface PageRequest<T = any> {
+  current: number              // 当前页码，默认第1页
+  size: number                 // 每页大小，默认10条
+  model?: T                    // 查询条件
+}
+
+/** 分页响应 */
+interface PageResponse<T> {
+  records: T[]                 // 列表数据
+  total: number                // 总数
+  current: number              // 当前页
+  size: number                 // 每页大小
+}
+
+/** API 响应 */
+interface ApiResponse<T = any> {
+  code: number                 // 状态码（0表示成功）
+  message: string              // 消息
+  data: T                      // 数据
+}
+```
+
+---
+
+## 六、状态管理
+
+```typescript
+// stores/file.ts
+import { defineStore } from 'pinia'
+
+export const useFileStore = defineStore('file', {
+  state: () => ({
+    currentStorageType: null as StorageType | null,
+    configList: [] as FileConfig[],
+    fileList: [] as FileInfo[],
+    configTotal: 0,
+    fileTotal: 0
+  }),
+
+  getters: {
+    // 存储器类型选项
+    storageTypeOptions: () => [
+      { label: '本地磁盘', value: 'local' },
+      { label: 'SFTP 服务器', value: 'sftp' },
+      { label: 'MinIO 对象存储', value: 'minio' }
+    ],
+
+    // 是否为主配置
+    isPrimary: (state) => (configId: number) => {
+      const config = state.configList.find(c => c.id === configId)
+      return config?.isPrimary === 1
+    }
+  },
+
+  actions: {
+    setStorageType(type: StorageType) {
+      this.currentStorageType = type
+    },
+
+    setConfigList(list: FileConfig[], total: number) {
+      this.configList = list
+      this.configTotal = total
+    },
+
+    setFileList(list: FileInfo[], total: number) {
+      this.fileList = list
+      this.fileTotal = total
+    }
+  }
+})
+```
+
+---
+
+## 七、工具函数
+
+```typescript
+// utils/file.ts
+
+/**
+ * 文件大小格式化
+ * @param bytes 字节数
+ * @returns 格式化后的文件大小
+ */
+export function formatFileSize(bytes: number): string {
+  if (bytes === 0) return '0 B'
+  const k = 1024
+  const sizes = ['B', 'KB', 'MB', 'GB', 'TB']
+  const i = Math.floor(Math.log(bytes) / Math.log(k))
+  return (bytes / Math.pow(k, i)).toFixed(2) + ' ' + sizes[i]
+}
+
+/**
+ * URL 复制到剪贴板
+ * @param text 要复制的文本
+ * @returns 是否成功
+ */
+export async function copyToClipboard(text: string): Promise<boolean> {
+  try {
+    await navigator.clipboard.writeText(text)
+    return true
+  } catch {
+    // 降级方案
+    const textarea = document.createElement('textarea')
+    textarea.value = text
+    textarea.style.position = 'fixed'
+    textarea.style.opacity = '0'
+    document.body.appendChild(textarea)
+    textarea.select()
+    try {
+      document.execCommand('copy')
+      return true
+    } catch {
+      return false
+    } finally {
+      document.body.removeChild(textarea)
+    }
+  }
+}
+
+/**
+ * 验证 IP 地址格式
+ * @param ip IP 地址
+ */
+export function isValidIP(ip: string): boolean {
+  const reg = /^((25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(25[0-5]|2[0-4]\d|[01]?\d\d?)$/
+  return reg.test(ip)
+}
+
+/**
+ * 验证域名格式
+ * @param domain 域名
+ */
+export function isValidDomain(domain: string): boolean {
+  const reg = /^([a-zA-Z0-9]([a-zA-Z0-9\-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]{2,}$/
+  return reg.test(domain)
+}
+
+/**
+ * 验证 URL 格式
+ * @param url URL 地址
+ */
+export function isValidURL(url: string): boolean {
+  try {
+    new URL(url)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * S3 bucket 名称验证
+ * @param bucket bucket 名称
+ */
+export function isValidS3Bucket(bucket: string): boolean {
+  // 长度 3-63
+  if (bucket.length < 3 || bucket.length > 63) return false
+  // 小写字母、数字、中划线，不能以中划线开头或结尾
+  const reg = /^[a-z0-9][a-z0-9-]*[a-z0-9]$/
+  return reg.test(bucket)
+}
+
+/**
+ * 文件类型验证
+ * @param file 文件对象
+ * @param allowedTypes 允许的文件类型
+ */
+export function isValidFileType(file: File, allowedTypes: string[]): boolean {
+  const fileType = file.type
+  const fileName = file.name
+  const extension = fileName.substring(fileName.lastIndexOf('.')).toLowerCase()
+
+  return allowedTypes.some(type => {
+    if (type.startsWith('.')) {
+      return extension === type
+    }
+    return fileType === type || fileType.startsWith(type + '/')
+  })
+}
+
+/**
+ * 文件大小验证
+ * @param file 文件对象
+ * @param maxSizeInMB 最大大小（MB）
+ */
+export function isValidFileSize(file: File, maxSizeInMB: number): boolean {
+  const maxSizeInBytes = maxSizeInMB * 1024 * 1024
+  return file.size <= maxSizeInBytes
+}
+```
+
+---
+
+## 八、表单校验规则
+
+```typescript
+// utils/validation.ts
+
+import { isValidIP, isValidDomain, isValidURL, isValidS3Bucket } from './file'
+
+/** 通用字段校验规则 */
+export const commonRules = {
+  configName: [
+    { required: true, message: '请填写配置名' },
+    { max: 50, message: '配置名长度不能超过 50 个字符' },
+    {
+      pattern: /^[\u4e00-\u9fa5a-zA-Z0-9_-]+$/,
+      message: '配置名只能包含中文、英文、数字、下划线和中划线'
+    }
+  ],
+  remark: [
+    { max: 200, message: '备注长度不能超过 200 个字符' }
+  ],
+  storageType: [
+    { required: true, message: '请选择存储器' }
+  ],
+  customDomain: [
+    {
+      validator: (_rule: any, value: string) => {
+        if (!value) return Promise.resolve()
+        if (!value.startsWith('http://') && !value.startsWith('https://')) {
+          return Promise.reject('自定义域名格式不正确，请以 http:// 或 https:// 开头')
+        }
+        if (!isValidURL(value)) {
+          return Promise.reject('请输入有效的 URL 地址')
+        }
+        return Promise.resolve()
+      }
+    }
+  ]
+}
+
+/** 本地磁盘校验规则 */
+export const localDiskRules = {
+  basePath: [
+    { required: true, message: '请填写基础路径' },
+    { max: 255, message: '基础路径长度不能超过 255 个字符' }
+  ]
+}
+
+/** SFTP 校验规则 */
+export const sftpRules = {
+  basePath: [
+    { required: true, message: '请填写基础路径' },
+    { max: 255, message: '基础路径长度不能超过 255 个字符' }
+  ],
+  host: [
+    { required: true, message: '请填写主机地址' },
+    { max: 255, message: '主机地址长度不能超过 255 个字符' },
+    {
+      validator: (_rule: any, value: string) => {
+        if (!isValidIP(value) && !isValidDomain(value)) {
+          return Promise.reject('请输入有效的 IP 地址或域名')
+        }
+        return Promise.resolve()
+      }
+    }
+  ],
+  port: [
+    { required: true, message: '请填写主机端口' },
+    {
+      validator: (_rule: any, value: number) => {
+        if (!Number.isInteger(value)) {
+          return Promise.reject('主机端口必须为整数')
+        }
+        if (value < 1 || value > 65535) {
+          return Promise.reject('主机端口范围应为 1-65535')
+        }
+        return Promise.resolve()
+      }
+    }
+  ],
+  username: [
+    { required: true, message: '请填写用户名' },
+    { max: 100, message: '用户名长度不能超过 100 个字符' }
+  ],
+  password: [
+    { required: true, message: '请填写密码' },
+    { max: 100, message: '密码长度不能超过 100 个字符' }
+  ]
+}
+
+/** MinIO 校验规则 */
+export const minioRules = {
+  endpoint: [
+    { required: true, message: '请填写节点地址' },
+    { max: 255, message: '节点地址长度不能超过 255 个字符' },
+    {
+      validator: (_rule: any, value: string) => {
+        if (!isValidURL(value)) {
+          return Promise.reject('请输入有效的 URL 地址')
+        }
+        return Promise.resolve()
+      }
+    }
+  ],
+  bucketName: [
+    { required: true, message: '请填写存储桶名称' },
+    {
+      validator: (_rule: any, value: string) => {
+        if (value.length < 3 || value.length > 63) {
+          return Promise.reject('存储桶长度应为 3-63 个字符')
+        }
+        if (!isValidS3Bucket(value)) {
+          return Promise.reject('存储桶只能包含小写字母、数字和中划线，且不能以中划线开头或结尾')
+        }
+        return Promise.resolve()
+      }
+    }
+  ],
+  accessKey: [
+    { required: true, message: '请填写访问密钥' },
+    { max: 100, message: '访问密钥长度不能超过 100 个字符' }
+  ],
+  accessSecret: [
+    { required: true, message: '请填写访问密钥秘钥' },
+    { max: 100, message: '访问密钥秘钥长度不能超过 100 个字符' }
+  ],
+  region: [
+    {
+      validator: (_rule: any, value: string) => {
+        if (!value) return Promise.resolve()
+        if (value.length > 50) {
+          return Promise.reject('区域长度不能超过 50 个字符')
+        }
+        if (!/^[a-zA-Z0-9-]+$/.test(value)) {
+          return Promise.reject('区域只能包含字母、数字和中划线')
+        }
+        return Promise.resolve()
+      }
+    }
+  ]
+}
+```
+
+---
+
+## 九、组件示例
+
+### 9.1 配置名校验组件（异步校验）
+
+```vue
+<!-- file-config/components/ConfigNameInput.vue -->
+<template>
+  <el-form-item label="配置名" prop="configName">
+    <el-input
+      v-model="modelValue"
+      placeholder="请输入配置名"
+      @blur="checkNameExists"
+    />
+  </el-form-item>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const props = defineProps<{
+  modelValue: string
+  excludeId?: number
+}>()
+
+const emit = defineEmits<{
+  (e: 'update:modelValue', value: string): void
+  (e: 'nameExists', exists: boolean): void
+}>()
+
+const checkNameExists = async () => {
+  if (!props.modelValue) return
+  // 调用 API 检查配置名是否存在
+  // const exists = await api.checkConfigName(props.modelValue, props.excludeId)
+  // emit('nameExists', exists)
+}
+</script>
+```
+
+### 9.2 图片预览组件
+
+```vue
+<!-- file-list/components/ImagePreview.vue -->
+<template>
+  <el-image
+    :src="src"
+    :preview-src-list="previewList"
+    fit="cover"
+    class="preview-image"
+  >
+    <template #error>
+      <div class="image-slot">
+        <el-icon><Picture /></el-icon>
+      </div>
+    </template>
+  </el-image>
+</template>
+
+<script setup lang="ts">
+import { Picture } from '@element-plus/icons-vue'
+
+defineProps<{
+  src: string
+  previewList?: string[]
+}>()
+</script>
+
+<style scoped>
+.preview-image {
+  width: 60px;
+  height: 60px;
+  border-radius: 4px;
+}
+.image-slot {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  height: 100%;
+  background: #f5f7fa;
+  color: #909399;
+}
+</style>
+```
+
+---
+
+## 十、安全需求
+
+由于 MinIO 默认支持匿名访问（需配置策略），为保障安全，必须在**预览层或网关层加入认证机制**。
+
+### 安全建议
+
+1. **敏感数据加密存储**：密码、accessSecret 等敏感信息需加密存储
+2. **URL 访问控制**：私有文件需签名 URL 或通过后端代理访问
+3. **文件上传校验**：严格校验文件类型和大小
+4. **权限控制**：确保用户只能操作自己有权限的配置和文件
+
+---
+
+## 十一、后端接口对照
+
+### 11.1 接口规范说明
+
+| 项目 | 说明 |
+|------|------|
+| 请求方式 | 所有接口均为 **POST** 请求 |
+| 参数传递 | 参数放在 **Request Body** 中 |
+| 响应格式 | 统一使用 `Result<T>` 包装 |
+| 分页参数 | 使用 `current`（当前页）和 `size`（每页大小）|
+| 分页响应 | 返回 `PageResult<T>`，包含 `records`（列表数据）、`total`（总数）|
+
+### 11.2 文件配置接口
+
+| 功能 | 接口路径 | 请求参数 | 响应类型 |
+|------|----------|----------|----------|
+| 分页查询 | POST /api/fileConfig/page | PageParam\<FileConfigQueryRequest\> | Result\<PageResult\<FileConfigResponse\>\> |
+| 根据ID查询 | POST /api/fileConfig/get | FileConfigIdRequest | Result\<FileConfigResponse\> |
+| 创建配置 | POST /api/fileConfig/create | FileConfigCreateRequest | Result\<FileConfigResponse\> |
+| 更新配置 | POST /api/fileConfig/update | FileConfigUpdateRequest | Result\<FileConfigResponse\> |
+| 删除配置 | POST /api/fileConfig/delete | FileConfigIdRequest | Result\<Void\> |
+
+### 11.3 文件信息接口
+
+| 功能 | 接口路径 | 请求参数 | 响应类型 |
+|------|----------|----------|----------|
+| 分页查询 | POST /api/fileInfo/page | PageParam\<FileInfoQueryRequest\> | Result\<PageResult\<FileInfoResponse\>\> |
+| 根据ID查询 | POST /api/fileInfo/get | FileInfoIdRequest | Result\<FileInfoResponse\> |
+| 创建文件 | POST /api/fileInfo/create | FileInfoCreateRequest | Result\<FileInfoResponse\> |
+| 更新文件 | POST /api/fileInfo/update | FileInfoUpdateRequest | Result\<FileInfoResponse\> |
+| 删除文件 | POST /api/fileInfo/delete | FileInfoIdRequest | Result\<Void\> |
+
+### 11.4 文件上传/下载接口
+
+| 功能 | 接口路径 | 请求参数 | 响应类型 |
+|------|----------|----------|----------|
+| 文件上传 | POST /api/common/upload/file | FileUploadRequest（包含 File 对象）| Result\<FileResponse\> |
+| 文件下载 | POST /api/common/download/file | FileDownloadRequest | void（直接写入响应流）|
+| 保存附件 | POST /api/common/attachment/save | businessId + List\<Attachment\> | Result\<Void\> |
+| 查询附件 | POST /api/common/attachment/query | businessId | Result\<List\<Attachment\>\> |
+| 获取图片 | GET /api/common/image/queryById | id / businessId / tenantId | ResponseEntity\<ByteArrayResource\> |
+
+---
+
+## 十二、开发注意事项
+
+1. **接口调用规范**
+   - 所有接口均为 POST 请求，使用 axios.post() 调用
+   - 参数放在请求体中，不是 URL 参数
+   - 分页参数使用 `current` 和 `size`，不是 `page` 和 `pageSize`
+
+2. **表单状态管理**
+   - 新增时表单为空或默认值
+   - 编辑时回显已有数据，"存储器"不支持修改
+   - 切换存储器时动态字段清空重渲染，通用字段保留
+
+3. **后端字段映射**
+   - 前端使用驼峰命名（configName、configRemark）
+   - 后端使用下划线命名（config_name、config_remark）
+   - 布尔值使用 Integer：0-否，1-是
+   - 敏感字段（密码、accessSecret）响应时为脱敏显示
+
+4. **实时校验**
+   - 输入时实时校验，错误显示红色提示
+   - 提交时完整校验，所有校验通过方可提交
+
+5. **文件上传**
+   - 使用 CommonsMultipartFile 格式
+   - 支持多种存储源（local、minio）
+   - 严格校验文件类型（白名单机制）
+   - 显示上传进度和结果
+
+6. **用户体验**
+   - 删除等危险操作需二次确认
+   - 操作成功/失败给出明确提示
+   - 加载状态使用 Loading 遮罩
+
+---
+
+**文档版本**：v1.2
+**更新日期**：2026-04-07
+**更新内容**：
+- 根据后端 FileConfigController 和 FileInfoController 更新接口定义
+- 所有接口改为 POST 请求，参数放在 Request Body 中
+- 更新分页参数为 current/size
+- 更新响应结构为 Result\<PageResult\<T\>\>
+- 新增 FileResponse 类型定义
+- 添加后端接口对照章节