# 排行榜自定义排序功能说明

## 功能概述

实现了在后台管理系统中对排行榜书籍进行自定义排序的功能，支持：
1. **按排行榜类型管理**：畅销榜、热门榜、口碑榜、好评榜等
2. **按分类管理**：支持按分类筛选和管理排行榜（如：文艺类畅销榜、历史类畅销榜）
3. **拖拽排序**：在前端页面通过拖拽调整书籍顺序
4. **添加/移除书籍**：可以添加书籍到排行榜或从排行榜移除
5. **批量保存排序**：一次性保存所有排序更改

## 数据库设计

### 1. 扩展ranking_items表

在 `ranking_items` 表中添加 `category_id` 字段，支持按分类管理：

```sql
ALTER TABLE `ranking_items` 
ADD COLUMN `category_id` INT DEFAULT NULL COMMENT '分类ID，NULL表示不按分类' AFTER `group_id`,
ADD INDEX `idx_category_id` (`category_id`);
```

### 2. 创建默认排行榜组

执行 `ranking_custom_sort_schema.sql` 脚本会自动创建默认排行榜组：
- 畅销榜 (bestseller)
- 热门榜 (popular)
- 口碑榜 (reputation)
- 好评榜 (good_reviews)
- 新书榜 (new_books)

## 后端实现

### 1. 实体类更新

**文件**：`book/src/main/java/com/yu/book/admin/entity/RankingItem.java`

添加 `categoryId` 字段：
```java
private Integer categoryId; // 分类ID，NULL表示不按分类
```

### 2. Mapper扩展

**文件**：`book/src/main/java/com/yu/book/admin/mapper/RankingMapper.java`

新增方法：
- `selectItemsByCategory()` - 按分类查询排行榜项
- `batchUpdateSort()` - 批量更新排序
- `selectItemByGroupAndBook()` - 根据组和书籍查询

### 3. Service扩展

**文件**：`book/src/main/java/com/yu/book/admin/service/AdminRankingService.java`

新增方法：
- `listItemsWithBooks()` - 查询排行榜项（包含书籍信息）
- `batchUpdateSort()` - 批量更新排序
- `addBookToRanking()` - 添加书籍到排行榜
- `removeBookFromRanking()` - 从排行榜移除书籍

### 4. Controller扩展

**文件**：`book/src/main/java/com/yu/book/admin/controller/AdminRankingController.java`

新增接口：
- `GET /api/admin/ranking/items/with-books` - 查询排行榜项（包含书籍信息）
- `POST /api/admin/ranking/sort` - 批量更新排序
- `POST /api/admin/ranking/items/add` - 添加书籍到排行榜
- `DELETE /api/admin/ranking/items/{id}/remove` - 从排行榜移除书籍

### 5. DTO和VO

**文件**：
- `RankingSortDTO.java` - 排序DTO，用于批量更新排序
- `RankingItemVO.java` - 排行榜项VO，包含书籍详细信息

## 前端实现

### 1. API工具类

**文件**：`book/book-admin/src/main/resources/static/utils/api.js`

新增API方法：
- `getRankingGroups()` - 获取所有排行榜组
- `getRankingItemsWithBooks()` - 获取排行榜项（包含书籍信息）
- `batchUpdateRankingSort()` - 批量更新排序
- `addBookToRanking()` - 添加书籍到排行榜
- `removeBookFromRanking()` - 从排行榜移除书籍

### 2. 管理页面

**文件**：`book/book-admin/src/main/resources/static/pages/rankings.html`

功能特性：
- 选择排行榜类型（下拉选择）
- 选择分类筛选（可选）
- 显示书籍列表（包含封面、标题、作者、分类）
- 拖拽排序（HTML5 Drag and Drop API）
- 添加书籍（搜索并添加）
- 移除书籍（从排行榜移除）
- 保存排序（批量保存）

## 使用步骤

### 1. 数据库初始化

```bash
# 执行数据库脚本
mysql -u root -p books_db < book/src/main/resources/db/ranking_custom_sort_schema.sql
```

### 2. 启动后端服务

确保后端服务已启动（端口8081或8001）

### 3. 打开管理页面

使用浏览器打开 `http://localhost:8081/pages/rankings.html` 或 `http://localhost:8001/pages/rankings.html`

### 4. 登录

使用管理员账号登录（如果未登录）

### 5. 管理排行榜

1. **选择排行榜类型**：从下拉列表选择（如：畅销榜）
2. **选择分类**（可选）：选择特定分类，或选择"全部分类"
3. **查看书籍列表**：显示当前排行榜中的书籍
4. **拖拽排序**：拖动书籍项调整顺序
5. **添加书籍**：点击"添加书籍"按钮，搜索并添加
6. **移除书籍**：点击书籍项的"移除"按钮
7. **保存排序**：点击"保存排序"按钮保存更改

## API接口说明

### 1. 查询排行榜项（包含书籍信息）

**GET** `/api/admin/ranking/items/with-books`

请求参数：
- `groupId` - 排行榜组ID（必填）
- `categoryId` - 分类ID（可选，NULL表示全部分类）
- `status` - 状态（可选，1-启用，0-禁用）

响应：
```json
{
  "code": 200,
  "data": [
    {
      "id": 1,
      "groupId": 1,
      "groupName": "畅销榜",
      "categoryId": 6,
      "categoryName": "文艺",
      "bookId": 10,
      "bookTitle": "思维的艺术",
      "bookAuthor": "延斯·森特根",
      "bookCover": "https://...",
      "sort": 1,
      "status": 1
    }
  ]
}
```

### 2. 批量更新排序

**POST** `/api/admin/ranking/sort`

请求体：
```json
{
  "groupId": 1,
  "categoryId": 6,
  "items": [
    { "id": 1, "bookId": 10, "sort": 1 },
    { "id": 2, "bookId": 11, "sort": 2 },
    { "id": 3, "bookId": 12, "sort": 3 }
  ]
}
```

### 3. 添加书籍到排行榜

**POST** `/api/admin/ranking/items/add`

请求参数：
- `groupId` - 排行榜组ID（必填）
- `bookId` - 书籍ID（必填）
- `categoryId` - 分类ID（可选）

### 4. 从排行榜移除书籍

**DELETE** `/api/admin/ranking/items/{id}/remove`

## 前端排行榜页面集成

更新前端排行榜页面（`books/pages/ranking/ranking.vue`），使用自定义排序数据：

1. 如果存在自定义排序数据，使用自定义排序
2. 如果不存在，使用默认的自动排序（按阅读量、点赞量等）

## 注意事项

1. **排序值**：数字越小越靠前（1表示第一位）
2. **分类筛选**：`categoryId` 为 NULL 表示不按分类，显示全部分类的书籍
3. **批量更新**：使用 CASE WHEN 语句实现高效的批量更新
4. **拖拽排序**：使用 HTML5 Drag and Drop API，兼容现代浏览器
5. **数据验证**：添加书籍时会检查是否已存在，避免重复

## 技术要点

1. **批量更新SQL**：使用 CASE WHEN 语句实现高效的批量更新
2. **拖拽排序**：使用 HTML5 Drag and Drop API
3. **前后端交互**：使用 Fetch API 和 Promise
4. **数据同步**：排序后需要保存才能生效

---

**创建时间：** 2024年  
**最后更新：** 2024年