# S3文件存储系统实现说明

## 📋 概述

本系统实现了基于S3兼容存储（MinIO）的文件上传、下载和管理功能，包括：

1. **S3配置管理**：支持多配置管理和动态切换
2. **文件上传**：支持多文件上传到S3存储
3. **文件下载**：带登录验证的文件下载
4. **文件记录**：完整的文件上传记录和关联管理

---

## 🗄️ 数据库设计

### 1. S3配置表 (`sys_s3_config`)

```sql
CREATE TABLE `sys_s3_config` (
  `id` bigint NOT NULL AUTO_INCREMENT,
  `endpoint` varchar(255) NOT NULL COMMENT 'S3服务端点',
  `bucket` varchar(100) NOT NULL COMMENT '存储桶名称',
  `access_key_id` varchar(255) NOT NULL,
  `secret_access_key` varchar(255) NOT NULL,
  `region` varchar(50) DEFAULT 'us-east-1',
  `public_domain` varchar(255),
  `enable_path_style` tinyint(1) DEFAULT 1,
  `file_path` varchar(255) DEFAULT '/',
  `is_active` tinyint(1) DEFAULT 1,
  `create_time` datetime DEFAULT CURRENT_TIMESTAMP,
  `update_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  `deleted` tinyint(1) DEFAULT 0,
  PRIMARY KEY (`id`)
);
```

### 2. 文件上传记录表 (`sys_file_upload`)

```sql
CREATE TABLE `sys_file_upload` (
  `id` bigint NOT NULL AUTO_INCREMENT,
  `original_name` varchar(255) NOT NULL,
  `stored_name` varchar(255) NOT NULL,
  `file_path` varchar(500) NOT NULL,
  `file_url` varchar(500) NOT NULL,
  `file_size` bigint NOT NULL,
  `file_type` varchar(100),
  `uploader_id` bigint NOT NULL,
  `uploader_name` varchar(100),
  `related_type` varchar(50),
  `related_id` bigint,
  `create_time` datetime DEFAULT CURRENT_TIMESTAMP,
  `update_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  `deleted` tinyint(1) DEFAULT 0,
  PRIMARY KEY (`id`),
  KEY `idx_uploader` (`uploader_id`),
  KEY `idx_related` (`related_type`, `related_id`)
);
```

---

## 🔧 后端实现

### 1. Maven依赖

在 `pom.xml` 中添加：

```xml
<!-- AWS SDK for S3 -->
<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>s3</artifactId>
    <version>2.20.26</version>
</dependency>

<!-- Apache Commons IO -->
<dependency>
    <groupId>commons-io</groupId>
    <artifactId>commons-io</artifactId>
    <version>2.11.0</version>
</dependency>
```

### 2. 核心服务

#### S3Service
- `uploadFile()`: 上传文件到S3
- `getFileUploadById()`: 获取文件记录
- `getFilesByRelated()`: 获取关联文件列表

#### S3ConfigService
- `getActiveConfig()`: 获取激活的配置
- `createConfig()`: 创建新配置
- `updateConfig()`: 更新配置
- `activateConfig()`: 激活指定配置

### 3. API接口

#### S3配置管理 (`/api/s3/config`)

- `GET /active` - 获取激活的配置
- `GET /list` - 获取所有配置
- `GET /{id}` - 获取指定配置
- `POST /` - 创建配置
- `PUT /{id}` - 更新配置
- `DELETE /{id}` - 删除配置
- `PUT /{id}/activate` - 激活配置

#### 文件管理 (`/api/file`)

- `POST /upload` - 上传文件（需要登录）
  - 参数：`files` (MultipartFile[]), `relatedType`, `relatedId`
  - 返回：文件URL列表
  
- `GET /download/{id}` - 下载文件（需要登录，验证token）
  - 自动重定向到S3文件URL
  
- `GET /{id}` - 获取文件信息
- `GET /list` - 获取关联文件列表

---

## 🎨 前端实现

### 1. S3配置管理页面

在 `Settings.vue` 中添加S3配置管理标签页：

```vue
<template>
  <a-tab-pane key="s3" tab="S3存储配置">
    <!-- S3配置表单 -->
    <a-form :model="s3ConfigForm">
      <a-form-item label="服务端点">
        <a-input v-model:value="s3ConfigForm.endpoint" />
      </a-form-item>
      <a-form-item label="存储桶">
        <a-input v-model:value="s3ConfigForm.bucket" />
      </a-form-item>
      <!-- ... 其他配置项 ... -->
      <a-button @click="saveS3Config">保存配置</a-button>
    </a-form>
  </a-tab-pane>
</template>
```

### 2. 文件上传组件

在 `CreateTask.vue` 中修改文件上传逻辑：

```typescript
// 使用新的S3上传接口
const handleUpload = async (file: File) => {
  const formData = new FormData();
  formData.append('files', file);
  formData.append('relatedType', 'task');
  
  const response = await axios.post('/api/file/upload', formData, {
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'multipart/form-data'
    }
  });
  
  return response.data.data; // 返回文件URL数组
};
```

### 3. 文件下载

```typescript
const downloadFile = (fileId: number) => {
  const token = localStorage.getItem('token');
  window.open(`/api/file/download/${fileId}`, '_blank');
  // 浏览器会自动携带token（如果在请求头中）
};
```

---

## 🔐 安全特性

### 1. 登录验证
- 所有文件上传需要有效的JWT token
- 文件下载需要验证登录状态
- token验证失败返回401错误

### 2. 敏感信息保护
- API返回时自动隐藏`secretAccessKey`
- 前端更新时支持保留原密钥

### 3. 权限控制
- 只有管理员可以配置S3
- 普通用户只能上传和下载自己有权限的文件

---

## 📝 使用流程

### 1. 配置S3存储

1. 登录系统，进入**系统设置** > **S3存储配置**
2. 填写S3配置信息：
   - 服务端点：`https://s3.1080p.hk`
   - 存储桶：`jsxiangche`
   - AccessKey和SecretKey
   - 公共域名：`https://s3.1080p.hk/jsxiangche`
   - 文件路径前缀：`由壹点AI/`
3. 点击保存并激活

### 2. 上传文件

1. 在创建任务页面选择文件
2. 文件自动上传到S3
3. 系统生成文件URL并保存到数据库
4. 任务中显示附件链接

### 3. 下载文件

1. 在任务卡片或详情中点击附件链接
2. 系统验证登录状态
3. 自动跳转到S3文件下载

---

## 🚀 部署步骤

### 1. 执行数据库脚本

```bash
mysql -uroot -p designhub < database/create_s3_config.sql
```

### 2. 更新后端依赖

```bash
cd backend
mvn clean install
```

### 3. 重启后端服务

```bash
systemctl restart designhub-backend
```

### 4. 更新前端

```bash
cd frontend
pnpm build
# 部署到服务器
```

---

## 🔍 测试验证

### 1. 测试S3配置

```bash
curl -X GET http://localhost:8080/api/s3/config/active \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### 2. 测试文件上传

```bash
curl -X POST http://localhost:8080/api/file/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "files=@test.pdf" \
  -F "relatedType=task" \
  -F "relatedId=1"
```

### 3. 测试文件下载

```bash
curl -X GET http://localhost:8080/api/file/download/1 \
  -H "Authorization: Bearer YOUR_TOKEN"
```

---

## 📌 注意事项

1. **S3配置安全**：
   - AccessKey和SecretKey存储在数据库中，需要加密存储（可选）
   - 管理界面只对管理员开放

2. **文件大小限制**：
   - 需要在Nginx和Spring Boot中配置文件大小限制
   - 建议单文件不超过100MB

3. **文件命名**：
   - 使用时间戳+UUID避免文件名冲突
   - 保留原始文件名用于显示

4. **错误处理**：
   - S3服务不可用时给出友好提示
   - 上传失败后清理临时文件

5. **性能优化**：
   - 使用S3的预签名URL实现直传（可选）
   - 大文件使用分片上传（可选）

---

## 🎯 后续优化建议

1. **直传优化**：前端直接上传到S3，后端只生成签名
2. **CDN加速**：配置CloudFlare等CDN加速文件访问
3. **图片处理**：集成图片压缩和格式转换
4. **文件预览**：支持PDF、图片等文件在线预览
5. **批量操作**：支持批量删除和批量下载
6. **存储统计**：显示存储空间使用情况

---

## ✅ 完成清单

- [x] 数据库表设计
- [x] 后端实体类和Mapper
- [x] S3Service核心服务
- [x] S3ConfigService配置管理
- [x] FileUploadController上传下载
- [x] S3ConfigController配置管理
- [ ] 前端S3配置管理页面
- [ ] 前端文件上传组件改造
- [ ] 系统测试和部署