# 排行榜前后端对接完成说明

## ✅ 实现完成

已成功实现前端小程序排行榜页面与数据库的完整对接，支持通过后台管理系统自定义排序。

## 📋 实现内容

### 1. 后端接口扩展

#### RankingController（前端接口）
- ✅ `GET /api/ranking/groups` - 获取所有启用的排行榜类型
- ✅ `GET /api/ranking/list?code={code}&categoryId={categoryId}` - 根据排行榜类型和分类获取书籍列表

#### RankingQueryService（服务层）
- ✅ `getAllActiveRankingGroups()` - 获取所有启用的排行榜类型
- ✅ `getRankingBooksByCode(code, categoryId)` - 根据排行榜类型code和分类ID获取书籍（支持分类筛选）

#### RankingGroupVO（新增）
- ✅ 排行榜组VO类，用于返回排行榜类型信息

### 2. 前端小程序更新

#### API工具类（books/utils/api.js）
- ✅ `getAllRankingGroups()` - 获取所有排行榜类型
- ✅ `getRankingByCode(code, categoryId)` - 获取排行榜书籍（支持分类参数）

#### 排行榜页面（books/pages/ranking/ranking.vue）
- ✅ 从数据库动态加载排行榜类型（顶部标签栏）
- ✅ 从数据库动态加载分类列表（左侧边栏）
- ✅ 根据选中的排行榜类型和分类从数据库获取书籍列表
- ✅ 支持切换排行榜类型和分类
- ✅ 显示加载状态和空状态

### 3. 数据流程

```
前端小程序 ranking.vue
    ↓
1. 页面加载时调用 initData()
    ↓
2. 并行加载：
   - getAllRankingGroups() → 获取排行榜类型
   - getAllCategories() → 获取分类列表
    ↓
3. 加载完成后调用 loadBookList()
    ↓
4. 根据 activeTab 和 activeCategory 调用：
   - getRankingByCode(groupCode, categoryId)
    ↓
5. 后端查询数据库：
   - ranking_groups 表 → 获取排行榜类型
   - categories 表 → 获取分类列表
   - ranking_items 表 → 获取排行榜书籍（按sort排序）
   - books 表 → 获取书籍详细信息
    ↓
6. 返回数据并渲染到页面
```

## 🔄 数据对应关系

### 排行榜类型（顶部标签栏）
- **数据来源**：`ranking_groups` 表
- **筛选条件**：`status = 1`（只显示启用的）
- **排序**：按 `sort` 字段升序
- **显示字段**：`name`（排行榜名称）

### 分类列表（左侧边栏）
- **数据来源**：`categories` 表
- **筛选条件**：`status = 1`（只显示启用的）
- **排序**：按 `sort_order` 字段升序
- **显示字段**：`name`（分类名称）
- **特殊项**：自动添加"全部分类"选项（索引0）

### 书籍列表（右侧内容区）
- **数据来源**：`ranking_items` 表 + `books` 表
- **筛选条件**：
  - `group_id` = 当前排行榜类型ID
  - `category_id` = 当前分类ID（如果选择了分类）
  - `status = 1`（只显示启用的）
- **排序**：按 `sort` 字段升序（自定义排序）
- **显示字段**：书籍标题、作者、封面等

## 🎯 功能特性

### 1. 动态数据加载
- ✅ 排行榜类型从数据库动态获取
- ✅ 分类列表从数据库动态获取
- ✅ 书籍列表从数据库动态获取

### 2. 分类筛选
- ✅ 支持"全部分类"（显示所有书籍）
- ✅ 支持按分类筛选（只显示该分类的书籍）
- ✅ 切换分类时自动刷新书籍列表

### 3. 自定义排序
- ✅ 书籍顺序按 `sort` 字段排序（数字越小越靠前）
- ✅ 可通过后台管理系统调整排序
- ✅ 排序保存后，前端立即生效

### 4. 后台管理集成
- ✅ 在后台管理系统添加书籍到排行榜
- ✅ 在后台管理系统调整书籍排序
- ✅ 支持按分类管理排行榜

## 📝 使用步骤

### 1. 数据库初始化

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

### 2. 启动后端服务

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

### 3. 在后台管理系统添加书籍

1. 打开排行榜管理页面：`http://localhost:8081/pages/rankings.html`
2. 选择排行榜类型（如：畅销榜）
3. 选择分类（如：文艺，或全部分类）
4. 点击"添加书籍"按钮
5. 搜索并添加书籍
6. 拖拽调整排序
7. 点击"保存排序"

### 4. 前端小程序查看

1. 打开小程序排行榜页面
2. 选择排行榜类型（如：畅销榜）
3. 选择分类（如：文艺）
4. 查看书籍列表（按后台设置的顺序显示）

## 🔍 API接口说明

### 1. 获取排行榜类型

**GET** `/api/ranking/groups`

响应：
```json
{
  "code": 200,
  "data": [
    {
      "id": 1,
      "name": "畅销榜",
      "code": "bestseller",
      "description": "按销量和阅读量排序的畅销书籍",
      "sort": 1
    },
    {
      "id": 2,
      "name": "热门榜",
      "code": "popular",
      "description": "按浏览量和热度排序的热门书籍",
      "sort": 2
    }
  ]
}
```

### 2. 获取排行榜书籍

**GET** `/api/ranking/list?code=bestseller&categoryId=6`

参数：
- `code` - 排行榜类型code（必填，如：bestseller、popular）
- `categoryId` - 分类ID（可选，不传表示全部分类）

响应：
```json
{
  "code": 200,
  "data": [
    {
      "id": 10,
      "title": "思维的艺术",
      "author": "延斯·森特根",
      "cover": "https://...",
      "image": "https://...",
      ...
    }
  ]
}
```

## ⚠️ 注意事项

1. **排序逻辑**：
   - 如果存在自定义排序（`sort`字段有值），按`sort ASC`排序
   - 如果`sort`相同，按`weight DESC`排序
   - 如果都没有，按`id DESC`排序

2. **分类筛选**：
   - `categoryId`为`null`时，查询所有记录（不按分类筛选）
   - `categoryId`不为`null`时，只查询该分类的记录

3. **数据一致性**：
   - 确保`ranking_items`表中的`book_id`对应的书籍存在
   - 确保`ranking_items`表中的`category_id`对应的分类存在（如果category_id不为null）

4. **默认数据**：
   - 如果数据库中没有排行榜类型数据，前端会使用默认值
   - 如果数据库中没有分类数据，前端会使用默认值

## 🎉 完成状态

- ✅ 后端接口已实现
- ✅ 前端小程序已对接
- ✅ 后台管理系统已集成
- ✅ 前后端交互已实现
- ✅ 自定义排序功能已实现

现在可以通过后台管理系统添加书籍并自定义排序，前端小程序会实时显示排序结果！

---

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