# 资源上传文档

## 概述

本系统提供了完整的文件上传和管理功能，支持本地存储（未来可扩展至云存储）。主要用于上传券商Logo、用户头像等资源文件。

## 目录结构

```
storage/
├── dto/
│   └── upload-file.dto.ts          # 上传文件DTO
├── interfaces/
│   └── storage-provider.interface.ts  # 存储提供者接口
├── providers/
│   └── local-storage.provider.ts    # 本地存储实现
├── storage.controller.ts            # 存储控制器
├── storage.module.ts                # 存储模块
└── storage.service.ts               # 存储服务
```

## 环境配置

### 必需的环境变量

在 `.env` 文件中配置以下环境变量：

```env
# 存储类型：local（本地存储），未来可扩展为 qiniu、oss 等
STORAGE_TYPE=local

# 文件存储路径（相对于项目根目录）
STORAGE_PATH=./uploads

# 文件访问基础URL（用于生成文件访问链接）
STORAGE_BASE_URL=http://localhost:3200/uploads
```

### 配置说明

| 变量名             | 说明            | 默认值                          | 示例                              |
| ------------------ | --------------- | ------------------------------- | --------------------------------- |
| `STORAGE_TYPE`     | 存储类型        | `local`                         | `local`、`qiniu`（未来支持）      |
| `STORAGE_PATH`     | 文件存储路径    | `./uploads`                     | `./uploads`、`/var/www/uploads`   |
| `STORAGE_BASE_URL` | 文件访问基础URL | `http://localhost:3200/uploads` | `https://api.example.com/uploads` |

### 生产环境配置建议

```env
# 生产环境配置示例
STORAGE_TYPE=local
STORAGE_PATH=/var/www/invest-mind/uploads
STORAGE_BASE_URL=https://api.example.com/uploads
```

## 静态文件服务配置

系统在 `main.ts` 中自动配置了静态文件服务，无需额外配置：

```typescript
// 配置静态文件服务
const storagePath = configService.get<string>('STORAGE_PATH') || './uploads';
app.useStaticAssets(join(process.cwd(), storagePath), {
    prefix: '/uploads/',
});
```

这意味着所有存储在 `STORAGE_PATH` 目录下的文件都可以通过 `/uploads/` 前缀访问。

## API 接口

### 1. 管理员上传文件

**接口地址：** `POST /api/storage/upload`

**权限要求：** 需要管理员权限（`admin` 或 `super_admin`）

**请求格式：** `multipart/form-data`

**请求参数：**

| 参数名     | 类型   | 必填 | 说明         | 可选值                   |
| ---------- | ------ | ---- | ------------ | ------------------------ |
| `file`     | File   | 是   | 要上传的文件 | -                        |
| `folder`   | string | 否   | 存储文件夹   | `broker`、`user`、`temp` |
| `filename` | string | 否   | 自定义文件名 | -                        |

**文件限制：**

- 最大文件大小：5MB
- 允许的文件类型：`image/jpeg`、`image/jpg`、`image/png`、`image/gif`、`image/webp`

**请求示例：**

```bash
curl -X POST http://localhost:3200/api/storage/upload \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "file=@/path/to/image.jpg" \
  -F "folder=broker" \
  -F "filename=custom-name.jpg"
```

**响应示例：**

```json
{
    "path": "broker/1234567890-abcdef-broker-logo.jpg",
    "url": "http://localhost:3200/uploads/broker/1234567890-abcdef-broker-logo.jpg",
    "filename": "1234567890-abcdef-broker-logo.jpg",
    "size": 102400,
    "mimetype": "image/jpeg"
}
```

### 2. 用户上传头像

**接口地址：** `POST /api/storage/upload/avatar`

**权限要求：** 无需鉴权（公开接口）

**请求格式：** `multipart/form-data`

**请求参数：**

| 参数名 | 类型 | 必填 | 说明             |
| ------ | ---- | ---- | ---------------- |
| `file` | File | 是   | 要上传的头像文件 |

**文件限制：**

- 最大文件大小：2MB
- 允许的文件类型：`image/jpeg`、`image/jpg`、`image/png`、`image/gif`、`image/webp`
- 文件固定存储在 `user` 文件夹

**请求示例：**

```bash
curl -X POST http://localhost:3200/api/storage/upload/avatar \
  -F "file=@/path/to/avatar.jpg"
```

**响应示例：**

```json
{
    "path": "user/1234567890-abcdef-avatar.jpg",
    "url": "http://localhost:3200/uploads/user/1234567890-abcdef-avatar.jpg",
    "filename": "1234567890-abcdef-avatar.jpg",
    "size": 51200,
    "mimetype": "image/jpeg"
}
```

### 3. 删除文件

**接口地址：** `DELETE /api/storage/{path}`

**权限要求：** 需要管理员权限（`admin` 或 `super_admin`）

**路径参数：**

| 参数名 | 类型   | 说明         | 示例                                       |
| ------ | ------ | ------------ | ------------------------------------------ |
| `path` | string | 文件相对路径 | `broker/1234567890-abcdef-broker-logo.jpg` |

**请求示例：**

```bash
curl -X DELETE http://localhost:3200/api/storage/broker/1234567890-abcdef-broker-logo.jpg \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**响应：**

- 成功：`204 No Content`
- 文件不存在：`404 Not Found`
- 权限不足：`403 Forbidden`

## 文件夹类型说明

系统支持三种文件夹类型，用于分类存储不同类型的文件：

| 文件夹   | 用途         | 说明                           |
| -------- | ------------ | ------------------------------ |
| `broker` | 券商相关文件 | 用于存储券商Logo等基础数据文件 |
| `user`   | 用户相关文件 | 用于存储用户头像等个人文件     |
| `temp`   | 临时文件     | 用于存储临时文件，可定期清理   |

## 文件访问

### 访问方式

上传成功后，系统会返回文件的访问URL，可以通过以下方式访问：

1. **直接访问URL**：使用返回的 `url` 字段直接访问

    ```
    http://localhost:3200/uploads/broker/1234567890-abcdef-broker-logo.jpg
    ```

2. **通过静态文件服务**：所有文件都通过 `/uploads/` 前缀提供静态文件服务
    ```
    http://localhost:3200/uploads/{folder}/{filename}
    ```

### 文件命名规则

如果不指定自定义文件名，系统会自动生成文件名，格式为：

```
{timestamp}-{random}-{originalname}
```

例如：

- 原始文件名：`logo.jpg`
- 生成文件名：`1234567890-abcdef-logo.jpg`

其中：

- `timestamp`：时间戳（毫秒）
- `random`：8字节随机十六进制字符串
- `originalname`：原始文件名（去除特殊字符）

### 文件名清理规则

系统会自动清理文件名中的特殊字符：

- 保留：字母、数字、下划线 `_`、连字符 `-`
- 替换：其他特殊字符会被替换为下划线 `_`

## 文件存储结构

本地存储的文件结构如下：

```
uploads/
├── broker/          # 券商相关文件
│   └── 1234567890-abcdef-broker-logo.jpg
├── user/            # 用户相关文件
│   └── 1234567890-abcdef-avatar.jpg
└── temp/            # 临时文件
    └── 1234567890-abcdef-temp-file.jpg
```

## 安全特性

### 1. 路径遍历防护

删除文件时会进行安全检查，防止路径遍历攻击：

```typescript
// 安全检查：确保文件路径在 basePath 内
const resolvedPath = path.resolve(fullPath);
const resolvedBasePath = path.resolve(this.basePath);
if (!resolvedPath.startsWith(resolvedBasePath)) {
    throw new Error('非法文件路径');
}
```

### 2. 文件类型验证

- 仅允许上传图片文件（jpeg、jpg、png、gif、webp）
- 通过 MIME 类型和文件扩展名双重验证

### 3. 文件大小限制

- 管理员上传：最大 5MB
- 用户头像：最大 2MB

### 4. 权限控制

- 管理员上传和删除操作需要管理员权限
- 用户头像上传无需鉴权（用于注册场景）

## 使用示例

### JavaScript/TypeScript 示例

```typescript
// 上传文件
const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('folder', 'broker');
formData.append('filename', 'custom-name.jpg');

const response = await fetch('http://localhost:3200/api/storage/upload', {
    method: 'POST',
    headers: {
        Authorization: `Bearer ${token}`,
    },
    body: formData,
});

const result = await response.json();
console.log('文件URL:', result.url);
```

### React 示例

```tsx
import { useState } from 'react';

function FileUpload() {
    const [file, setFile] = useState<File | null>(null);
    const [uploading, setUploading] = useState(false);
    const [result, setResult] = useState<any>(null);

    const handleUpload = async () => {
        if (!file) return;

        setUploading(true);
        const formData = new FormData();
        formData.append('file', file);
        formData.append('folder', 'broker');

        try {
            const response = await fetch(
                'http://localhost:3200/api/storage/upload',
                {
                    method: 'POST',
                    headers: {
                        Authorization: `Bearer ${localStorage.getItem('token')}`,
                    },
                    body: formData,
                },
            );

            const data = await response.json();
            setResult(data);
        } catch (error) {
            console.error('上传失败:', error);
        } finally {
            setUploading(false);
        }
    };

    return (
        <div>
            <input
                type="file"
                accept="image/*"
                onChange={(e) => setFile(e.target.files?.[0] || null)}
            />
            <button onClick={handleUpload} disabled={uploading}>
                {uploading ? '上传中...' : '上传'}
            </button>
            {result && (
                <div>
                    <p>上传成功！</p>
                    <img src={result.url} alt="上传的文件" />
                </div>
            )}
        </div>
    );
}
```

## 扩展性

### 添加新的存储提供者

系统采用策略模式，可以轻松添加新的存储提供者（如七牛云、阿里云OSS等）：

1. 实现 `IStorageProvider` 接口
2. 在 `StorageService` 中添加新的存储类型判断
3. 配置相应的环境变量

示例：

```typescript
// providers/qiniu-storage.provider.ts
export class QiniuStorageProvider implements IStorageProvider {
    // 实现接口方法
}

// storage.service.ts
switch (storageType) {
    case 'qiniu':
        this.provider = new QiniuStorageProvider(configService);
        break;
}
```

## 常见问题

### 1. 文件上传失败

**问题：** 上传文件时返回 400 错误

**解决方案：**

- 检查文件大小是否超过限制（管理员5MB，头像2MB）
- 检查文件类型是否为支持的图片格式
- 检查文件是否损坏

### 2. 文件无法访问

**问题：** 上传成功但无法通过URL访问文件

**解决方案：**

- 检查 `STORAGE_BASE_URL` 配置是否正确
- 检查静态文件服务是否正常启动
- 检查文件是否实际存在于 `STORAGE_PATH` 目录
- 检查文件权限是否正确

### 3. 删除文件失败

**问题：** 删除文件时返回 404 或 403 错误

**解决方案：**

- 404：检查文件路径是否正确，文件是否存在
- 403：检查是否有管理员权限
- 检查文件路径是否包含非法字符

### 4. 生产环境配置

**问题：** 如何在生产环境配置文件存储

**解决方案：**

1. 设置 `STORAGE_PATH` 为绝对路径（如 `/var/www/uploads`）
2. 设置 `STORAGE_BASE_URL` 为生产域名（如 `https://api.example.com/uploads`）
3. 确保目录有写入权限：`chmod -R 755 /var/www/uploads`
4. 考虑使用云存储服务（未来支持）

## 相关文件

- `storage.controller.ts` - API 控制器
- `storage.service.ts` - 存储服务
- `local-storage.provider.ts` - 本地存储实现
- `storage-provider.interface.ts` - 存储提供者接口
- `main.ts` - 静态文件服务配置

## 更新日志

- 初始版本：支持本地存储、文件上传、文件删除功能