# 版块页面与排行榜页面 Spec

## Why
当前 Xiuno BBS 缺少一个全局版块总览页面（展示所有版块及子版块的树形结构）和排行榜页面（热门帖子、活跃用户、积分榜），这两个页面是论坛系统的核心导航和互动入口，对用户发现内容和活跃社区至关重要。

## What Changes
- 新增版块总览页面（`/forum` 路由），以卡片式布局展示所有版块的树形结构
- 新增排行榜页面（`/leaderboard` 路由），支持热门帖子/活跃用户/积分榜三个标签页
- 新增两个 RESTful API 端点：`GET /api/v1/forum/tree` 和 `GET /api/v1/leaderboard/*`
- 前端使用 Alpine.js 管理交互状态，fetch 调用 API，Mock 数据先行

## Impact
- Affected code:
  - `route/index.php` — 新增 `/forum` 路由分发
  - `route/leaderboard.php` — 新增排行榜路由
  - `api/v1/forum.php` — 新增 `tree` 端点
  - `api/v1/leaderboard.php` — 新增排行榜 API
  - `view/htm/forum_index.htm` — 新增版块总览模板
  - `view/htm/leaderboard.htm` — 新增排行榜模板
  - `view/htm/sidebar_left.inc.htm` — 左侧导航新增"版块"和"排行榜"入口
  - `service/ForumService.php` — 新增 `getForumTree()` 方法
  - `service/LeaderboardService.php` — 新增排行榜服务类

## ADDED Requirements

### Requirement: 版块总览页面
系统 SHALL 提供版块总览页面，路径为 `/forum`，以卡片式布局展示所有顶级版块及其子版块。

#### Scenario: 展示版块树形结构
- **WHEN** 用户访问 `/forum`
- **THEN** 页面以卡片形式展示所有顶级版块，每个卡片包含版块图标、名称、描述、今日发帖数、主题总数、最后发表信息
- **AND** 若版块有子版块，卡片内以标签形式展示子版块（可点击跳转）
- **AND** 含子版块的版块支持 Alpine.js 管理的"展开/收起"折叠交互
- **AND** 若版块有版主，卡片底部显示"版主：用户名"

#### Scenario: 侧边栏统计信息
- **WHEN** 版块总览页面加载
- **THEN** 右侧边栏显示"统计信息"（总帖数、会员数、在线人数）和"活跃版块"列表
- **AND** 移动端（<768px）侧边栏移至主内容下方

#### Scenario: 移动端适配
- **WHEN** 在移动端（<768px）访问版块页面
- **THEN** 卡片占满宽度，侧边栏移至底部，布局保持可读性

### Requirement: 排行榜页面
系统 SHALL 提供排行榜页面，路径为 `/leaderboard`，支持热门帖子、活跃用户、积分榜三个标签页。

#### Scenario: 默认展示热门帖子
- **WHEN** 用户访问 `/leaderboard`
- **THEN** 默认展示"热门帖子"标签页，显示本周热门帖子列表
- **AND** 每项显示序号、标题（带链接）、作者、回复数、浏览数、最后回复时间

#### Scenario: 切换标签页
- **WHEN** 用户点击"活跃用户"或"积分榜"标签
- **THEN** 通过 fetch 请求对应 API 并重新渲染列表内容
- **AND** 当前标签页高亮显示

#### Scenario: 时间范围筛选
- **WHEN** 用户选择"本周"/"本月"/"全部"时间范围
- **THEN** 重新请求当前榜单数据并刷新列表

#### Scenario: 分页加载
- **WHEN** 用户点击"加载更多"按钮
- **THEN** 请求下一页数据并追加到当前列表

#### Scenario: 加载状态与空数据
- **WHEN** 数据正在加载
- **THEN** 显示加载动画（旋转图标）
- **WHEN** 数据为空
- **THEN** 显示空数据占位提示

#### Scenario: 移动端适配
- **WHEN** 在移动端访问排行榜页面
- **THEN** 表格布局调整为卡片列表，每项显示关键信息

### Requirement: 版块树形 API
系统 SHALL 提供 `GET /api/v1/forum/tree` 端点，返回版块树形结构数据。

#### Scenario: 获取版块树
- **WHEN** 客户端请求 `GET /api/v1/forum/tree`
- **THEN** 返回顶级版块列表，每个版块包含 `fid`、`name`、`description`、`icon`、`today_posts`、`threads`、`last_post`（含 title、username、time）、`moderators`、`children`（子版块数组）
- **AND** 响应格式遵循 `{ code: 0, msg: "ok", data: [...] }`

### Requirement: 排行榜 API
系统 SHALL 提供三个排行榜 API 端点。

#### Scenario: 热门帖子 API
- **WHEN** 客户端请求 `GET /api/v1/leaderboard/threads?period=week&page=1&page_size=20`
- **THEN** 返回热门帖子列表，每项含 `tid`、`title`、`author`、`replies`、`views`、`last_reply_time`
- **AND** 支持 `period`（week/month/all）、`page`、`page_size` 参数

#### Scenario: 活跃用户 API
- **WHEN** 客户端请求 `GET /api/v1/leaderboard/users?period=week&page=1&page_size=20`
- **THEN** 返回活跃用户列表，每项含 `uid`、`username`、`avatar`、`posts`、`reputation`、`registered_at`

#### Scenario: 积分榜 API
- **WHEN** 客户端请求 `GET /api/v1/leaderboard/credits?period=all&page=1&page_size=20`
- **THEN** 返回积分排行列表，每项含 `uid`、`username`、`credits`、`level`（等级名称）

### Requirement: 导航入口
系统 SHALL 在左侧导航栏新增"版块"和"排行榜"入口链接。

#### Scenario: 导航链接
- **WHEN** 用户查看左侧导航栏
- **THEN** 可见"版块"（ti-layout-grid）和"排行榜"（ti-trophy）两个导航项
- **AND** 点击后分别跳转至 `/forum` 和 `/leaderboard`