# BookmarkController 使用说明

## 概述

`BookmarkController` 是收藏网站的后端API控制器，提供了完整的收藏管理功能，包括CRUD操作、搜索、筛选、统计等。

## API 接口

### 1. 收藏管理

#### 获取收藏列表
```http
GET /api/bookmarks?page=1&limit=12&category_id=1&tag_id=2&search=关键词&orderBy=created_at&orderDirection=desc
```

**查询参数：**
- `page`: 页码（默认1）
- `limit`: 每页数量（默认12）
- `category_id`: 分类ID（可选）
- `tag_id`: 标签ID（可选）
- `search`: 搜索关键词（可选）
- `orderBy`: 排序字段（默认created_at）
- `orderDirection`: 排序方向（默认desc）

**响应示例：**
```json
{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 12,
    "total": 50,
    "totalPages": 5,
    "hasNext": true,
    "hasPrev": false
  },
  "total": 50
}
```

#### 获取单个收藏
```http
GET /api/bookmarks/:id
```

#### 创建收藏
```http
POST /api/bookmarks
Content-Type: application/json

{
  "title": "网站标题",
  "url": "https://example.com",
  "description": "网站描述",
  "category_id": 1,
  "tags": ["JavaScript", "React"],
  "links": [
    {
      "title": "链接标题",
      "url": "https://example.com/link",
      "type": "tutorial"
    }
  ]
}
```

#### 更新收藏
```http
PUT /api/bookmarks/:id
Content-Type: application/json

{
  "title": "更新后的标题",
  "description": "更新后的描述"
}
```

#### 删除收藏
```http
DELETE /api/bookmarks/:id
```

### 2. 搜索和筛选

#### 搜索收藏
```http
GET /api/bookmarks/search?query=关键词&limit=50&includeTags=true
```

#### 按分类获取收藏
```http
GET /api/bookmarks/category/:categoryId?limit=20
```

#### 按标签获取收藏
```http
GET /api/bookmarks/tag/:tagId?limit=20
```

### 3. 统计和快捷访问

#### 获取统计信息
```http
GET /api/bookmarks/stats
```

**响应示例：**
```json
{
  "success": true,
  "data": {
    "total": 50,
    "favorites": 10,
    "totalClicks": 150,
    "categories": [...],
    "popularTags": [...]
  }
}
```

#### 获取快捷访问数据
```http
GET /api/bookmarks/quick-access
```

**响应示例：**
```json
{
  "success": true,
  "data": {
    "favorites": [...],
    "recent": [...],
    "popular": [...]
  }
}
```

### 4. 收藏操作

#### 增加点击次数
```http
POST /api/bookmarks/:id/click
```

#### 切换收藏状态
```http
POST /api/bookmarks/:id/favorite
```

### 5. 批量操作

#### 批量操作
```http
POST /api/bookmarks/batch
Content-Type: application/json

{
  "operation": "delete",
  "bookmarkIds": [1, 2, 3],
  "data": {}
}
```

**支持的操作类型：**
- `delete`: 批量删除
- `move`: 批量移动分类
- `tag`: 批量更新标签

### 6. 分类和标签

#### 获取所有分类
```http
GET /api/categories
```

#### 获取所有标签
```http
GET /api/tags
```

#### 获取热门标签
```http
GET /api/tags/popular?limit=20
```

## 认证要求

所有API接口都需要用户登录认证。系统会自动从session中获取用户ID：

```javascript
const userId = ctx.state.user?.id
if (!userId) {
    throw new CommonError("用户未登录")
}
```

## 错误处理

所有API都使用统一的错误处理格式：

```json
{
  "success": false,
  "message": "错误描述信息"
}
```

**常见HTTP状态码：**
- `200`: 请求成功
- `400`: 请求参数错误或业务逻辑错误
- `401`: 未认证（用户未登录）
- `500`: 服务器内部错误

## 前端集成

前端JavaScript代码已经更新为使用这些API接口。主要变化：

1. **数据加载**: 从模拟数据改为API调用
2. **分页处理**: 使用后端返回的分页信息
3. **错误处理**: 统一的错误处理和用户提示
4. **认证支持**: 自动包含用户认证信息

## 使用示例

### 启动服务器
```bash
npm start
```

### 测试API
```bash
# 获取收藏列表
curl -X GET "http://localhost:3000/api/bookmarks" \
  -H "Cookie: your-session-cookie"

# 创建收藏
curl -X POST "http://localhost:3000/api/bookmarks" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{"title":"测试收藏","url":"https://example.com"}'
```

## 注意事项

1. **用户认证**: 确保用户已登录才能访问API
2. **数据验证**: 所有输入数据都会进行验证
3. **错误处理**: 前端需要处理API调用失败的情况
4. **分页**: 大量数据使用分页加载，避免性能问题
5. **缓存**: 考虑对分类和标签等静态数据进行缓存

## 扩展建议

1. **API版本控制**: 添加版本号支持（如 `/api/v1/bookmarks`）
2. **速率限制**: 添加API调用频率限制
3. **缓存策略**: 实现Redis缓存提升性能
4. **日志记录**: 记录API调用日志用于监控
5. **API文档**: 使用Swagger等工具生成API文档