java/API.md

# 网盘系统 API 接口文档

## 网关入口

**统一访问地址：** `http://localhost:8888`

所有请求通过网关路由到对应微服务，前端无需关心后端服务拆分。

---

## 1. 用户认证服务 (wangpan-user-service:8081)

### 1.1 用户登录
- **接口：** `POST /api/login`
- **请求体：**
```json
{
  "username": "用户名",
  "password": "密码"
}
```
- **响应：**
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "success": true,
    "token": "访问令牌",
    "user": { "id": 1, "username": "xxx", ... }
  }
}
```

### 1.2 用户注册
- **接口：** `POST /api/register`
- **请求体：**
```json
{
  "username": "用户名",
  "password": "密码"
}
```
- **响应：** 登录成功相同格式

### 1.3 令牌验证
- **接口：** `GET /api/token/validate`
- **请求头：** `Authorization: Bearer <token>`
- **响应：** 令牌是否有效

### 1.4 登录日志查询
- **接口：** `GET /api/login-logs`
- **参数：**
  - `username` (可选) - 按用户名筛选
  - `result` (可选) - 按登录结果筛选 (success/fail)
  - `pageNo` (默认 1) - 页码
  - `pageSize` (默认 20) - 每页条数
- **请求头：** `Authorization: Bearer <token>`

---

## 2. 网盘管理服务 (wangpan-drive-service:8082)

### 2.1 创建网盘
- **接口：** `POST /api/drive`
- **请求体：**
```json
{
  "name": "网盘名称"
}
```
- **请求头：** `Authorization: Bearer <token>`

### 2.2 查询网盘列表
- **接口：** `GET /api/drive`
- **参数：**
  - `pageNo` (默认 1)
  - `pageSize` (默认 20)
- **请求头：** `Authorization: Bearer <token>`

### 2.3 查询网盘详情
- **接口：** `GET /api/drive/{id}`
- **请求头：** `Authorization: Bearer <token>`

### 2.4 更新网盘
- **接口：** `PUT /api/drive/{id}`
- **请求体：**
```json
{
  "name": "新网盘名称"
}
```
- **请求头：** `Authorization: Bearer <token>`

### 2.5 删除网盘
- **接口：** `DELETE /api/drive/{id}`
- **请求头：** `Authorization: Bearer <token>`

### 2.6 创建文件夹
- **接口：** `POST /api/drive/{driveId}/folders`
- **请求体：**
```json
{
  "name": "文件夹名称",
  "parentId": 0
}
```
- **请求头：** `Authorization: Bearer <token>`

### 2.7 查询文件夹列表
- **接口：** `GET /api/drive/{driveId}/folders`
- **参数：**
  - `parentId` (默认 0) - 父文件夹 ID
- **请求头：** `Authorization: Bearer <token>`

### 2.8 查询文件夹详情
- **接口：** `GET /api/drive/{driveId}/folders/{folderId}`
- **请求头：** `Authorization: Bearer <token>`

### 2.9 更新文件夹
- **接口：** `PUT /api/drive/{driveId}/folders/{folderId}`
- **请求体：**
```json
{
  "name": "新文件夹名称"
}
```
- **请求头：** `Authorization: Bearer <token>`

### 2.10 删除文件夹
- **接口：** `DELETE /api/drive/{driveId}/folders/{folderId}`
- **请求头：** `Authorization: Bearer <token>`

### 2.11 创建电影文件
- **接口：** `POST /api/drive/{driveId}/movies`
- **请求体：**
```json
{
  "title": "电影名称",
  "folderId": 0,
  "posterUrl": "海报URL",
  "overview": "简介",
  "releaseDate": "2024-01-01",
  "voteAverage": 8.5,
  "tmdbId": 12345,
  "category": "动作",
  "scrapeType": "auto"
}
```
- **请求头：** `Authorization: Bearer <token>`

### 2.12 查询电影文件列表
- **接口：** `GET /api/drive/{driveId}/movies`
- **参数：**
  - `folderId` (默认 0) - 文件夹 ID
- **请求头：** `Authorization: Bearer <token>`

### 2.13 查询电影文件详情
- **接口：** `GET /api/drive/{driveId}/movies/{movieId}`
- **请求头：** `Authorization: Bearer <token>`

### 2.14 更新电影文件
- **接口：** `PUT /api/drive/{driveId}/movies/{movieId}`
- **请求体：** 同创建
- **请求头：** `Authorization: Bearer <token>`

### 2.15 删除电影文件
- **接口：** `DELETE /api/drive/{driveId}/movies/{movieId}`
- **请求头：** `Authorization: Bearer <token>`

---

## 3. TMDB 刮削服务 (wangpan-tmdb-service:8083)

### 3.1 电影列表查询
- **接口：** `GET /api/movies`
- **参数：**
  - `keyword` (可选) - 搜索关键词
  - `status` (可选) - 状态 (pending/scraped/failed)
  - `category` (可选) - 分类
  - `scrapeType` (可选) - 刮削类型
  - `pageNo` (默认 1)
  - `pageSize` (默认 20)
- **请求头：** `Authorization: Bearer <token>`

### 3.2 电影详情查询
- **接口：** `GET /api/movies/{id}`
- **请求头：** `Authorization: Bearer <token>`

### 3.3 创建电影
- **接口：** `POST /api/movies`
- **请求体：**
```json
{
  "title": "电影名称"
}
```
- **请求头：** `Authorization: Bearer <token>`

### 3.4 更新电影
- **接口：** `PUT /api/movies/{id}`
- **请求体：** 电影更新字段
- **请求头：** `Authorization: Bearer <token>`

### 3.5 删除电影
- **接口：** `DELETE /api/movies/{id}`
- **请求头：** `Authorization: Bearer <token>`

### 3.6 批量删除电影
- **接口：** `POST /api/movies/batch-delete`
- **请求体：**
```json
{
  "ids": [1, 2, 3]
}
```
- **请求头：** `Authorization: Bearer <token>`

### 3.7 电影统计
- **接口：** `GET /api/movies/stats`
- **请求头：** `Authorization: Bearer <token>`

### 3.8 TMDB API Key 获取
- **接口：** `GET /api/tmdb/key`
- **请求头：** `Authorization: Bearer <token>`

### 3.9 TMDB API Key 设置
- **接口：** `POST /api/tmdb/key`
- **请求体：**
```json
{
  "tmdbApiKey": "你的API Key"
}
```
- **请求头：** `Authorization: Bearer <token>`

### 3.10 单部电影刮削
- **接口：** `POST /api/tmdb-scraper/scrape`
- **请求体：**
```json
{
  "movieId": 1
}
```
- **请求头：** `Authorization: Bearer <token>`

### 3.11 批量刮削
- **接口：** `POST /api/tmdb-scraper/batch-scrape`
- **请求体：**
```json
{
  "movieIds": [1, 2, 3]
}
```
- **请求头：** `Authorization: Bearer <token>`

### 3.12 查询缓存列表
- **接口：** `GET /api/tmdb-scraper/caches`
- **参数：**
  - `pageNo` (默认 1)
  - `pageSize` (默认 20)
- **请求头：** `Authorization: Bearer <token>`

### 3.13 刮削统计
- **接口：** `GET /api/tmdb-scraper/stats`
- **请求头：** `Authorization: Bearer <token>`

### 3.14 手动触发定时任务
- **接口：** `POST /api/tmdb-scraper/trigger`
- **请求头：** `Authorization: Bearer <token>`

### 3.15 查询刮削日志
- **接口：** `GET /api/tmdb-scraper/scraper-logs`
- **参数：**
  - `pageNo` (默认 1)
  - `pageSize` (默认 20)
- **请求头：** `Authorization: Bearer <token>`

### 3.16 删除缓存
- **接口：** `DELETE /api/tmdb-scraper/cache/{movieId}`
- **请求头：** `Authorization: Bearer <token>`

---

## 通用响应格式

```json
{
  "code": 200,
  "message": "操作结果描述",
  "data": { ... }
}
```

### 状态码说明
| 状态码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权/令牌无效 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

---

## 服务架构说明

```
前端 → Gateway(8888) → 路由转发 → 微服务
                              ├── user-service(8081)
                              ├── drive-service(8082)
                              └── tmdb-service(8083)
```

所有服务通过网关统一路由转发，各服务独立运行。