# 系统服务后端API文档 V0.1

## 基础信息

- **Base URL**: `http://localhost:8000`
- **API前缀**: `/api/oss`
- **认证方式**: Bearer Token（所有接口均需要用户登录）

## 统一响应格式

```json
{
  "code": 200,
  "message": "success",
  "data": {}
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| code | int | 状态码：200成功，400参数错误，401未认证，404资源不存在，500服务器错误 |
| message | string | 响应消息 |
| data | object | 响应数据 |

---

## 接口列表

### 1. 文件上传接口

**POST** `/api/oss/upload`

上传文件到阿里云OSS，返回公开访问URL。

#### 请求头

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| Content-Type | string | 是 | multipart/form-data |
| Authorization | string | 是 | Bearer {token} |

#### 请求参数（Form Data）

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| file | file | 是 | - | 要上传的文件，最大20MB |
| prefix | string | 否 | uploads | 存储路径前缀 |

#### 响应示例

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "url": "https://your-bucket.oss-cn-beijing.aliyuncs.com/uploads/20251229/abc123def456.png",
    "filename": "example.png",
    "size": 102400
  }
}
```

#### 错误响应示例

```json
{
  "code": 400,
  "message": "文件大小超过20MB限制",
  "data": null
}
```

---

### 2. 文件下载接口

**GET** `/api/oss/download`

从OSS下载文件，返回文件流。

#### 请求头

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| Authorization | string | 是 | Bearer {token} |

#### 请求参数（Query）

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file_path | string | 是 | OSS文件路径（不含域名），如：uploads/20251229/abc123.png |

#### 响应

成功时返回文件流，响应头包含：
- `Content-Type`: 文件MIME类型
- `Content-Disposition`: attachment; filename=文件名

#### 错误响应示例

```json
{
  "code": 404,
  "message": "文件不存在",
  "data": null
}
```

---

### 3. 获取签名URL接口

**GET** `/api/oss/signed-url`

获取文件的临时签名访问URL，适用于私有文件访问。

#### 请求头

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| Authorization | string | 是 | Bearer {token} |

#### 请求参数（Query）

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| file_path | string | 是 | - | OSS文件路径（不含域名） |
| expires | int | 否 | 3600 | 签名URL有效期（秒） |

#### 响应示例

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "url": "https://your-bucket.oss-cn-beijing.aliyuncs.com/uploads/20251229/abc123.png?OSSAccessKeyId=xxx&Expires=xxx&Signature=xxx",
    "expires_in": 3600
  }
}
```

---

## 错误码说明

| 错误码 | HTTP状态码 | 说明 |
|--------|-----------|------|
| 400 | 400 | 文件大小超过限制 |
| 401 | 401 | 未认证或Token无效 |
| 404 | 404 | 文件不存在 |
| 500 | 500 | OSS服务未配置或服务器错误 |

---

## 前端对接示例

### 文件上传

```javascript
const formData = new FormData();
formData.append('file', fileObject);
formData.append('prefix', 'images');

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

const data = await response.json();
if (data.code === 200) {
  console.log('文件URL:', data.data.url);
}
```

### 文件下载

```javascript
const response = await fetch(
  `http://localhost:8000/api/oss/download?file_path=${encodeURIComponent('uploads/20251229/abc123.png')}`,
  {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${token}`
    }
  }
);

if (response.ok) {
  const blob = await response.blob();
  const url = window.URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = 'filename.png';
  a.click();
}
```

### 获取签名URL

```javascript
const response = await fetch(
  `http://localhost:8000/api/oss/signed-url?file_path=${encodeURIComponent('uploads/20251229/abc123.png')}&expires=7200`,
  {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${token}`
    }
  }
);

const data = await response.json();
if (data.code === 200) {
  console.log('签名URL:', data.data.url);
  // 可直接用于img标签或下载
}
```

---

## 在线文档

启动服务后访问：
- Swagger UI: `http://localhost:8000/docs`
- ReDoc: `http://localhost:8000/redoc`