# 数字图书馆（管理）API 文档（高质量版）

更新时间：2025-11-07

## 概览
- 能力：全量检索、审批（通过/驳回）、上下架、资产查看与下载、图书的增删改、图书管理员任免、收藏与下载榜单。
- 权限：`manage:library:*` 与 `manage:libraryLibrarian:*`
- 依赖表：`tb_library_book`、`tb_library_book_asset`、`tb_library_book_favorite`
- 环境：baseURL `http://localhost:8080`；认证头 `Authorization: Bearer <token>`

## 字段与状态
- 字段：同门户文档“数据模型与规则”。
- 状态流转（与 SQL 条件一致）：
  - 通过：仅 `status in (0,3)` → 1
  - 驳回：允许 `status in (0,1,3)` → 2
  - 下架：仅 `status = 1` → 3
  - 上线（转待审）：仅 `status in (2,3)` → 0

## 权限矩阵
- 列表：`manage:library:list`；详情：`manage:library:get`
- 新增：`manage:library:add`；编辑：`manage:library:edit`；删除：`manage:library:remove`
- 审批：`manage:library:approve|reject`
- 上下架：`manage:library:online|offline`
- 下载：`manage:library:download`
- 图书管理员：`manage:libraryLibrarian:list|add|remove`

## 查询/分页/过滤
- 列表：GET `/manage/library/list`
- 参数（query，可选）：
  - `status`(int) 0/1/2/3
  - `keyword`(string) 匹配 title/author/isbn13/keywords
  - `format`(string) `pdf|epub|mobi|zip`
  - `uploaderId`(long) 或 `uploaderName`(string)
  - `pageNum`(int)/`pageSize`(int)
- 排序：`orderByColumn` + `isAsc`（默认 `publish_time desc, id desc`）
- 返回示例：
```json
{ "code":200, "rows":[ { "id":1, "title":"CSAPP", "status":0, "uploaderName":"student" } ], "total":1 }
```

## 详情
- GET `/manage/library/{id}` | 权限：`manage:library:get`
- GET `/manage/library/{id}/assets` | 权限：`manage:library:get`

## 下载（302 审核用途）
- GET `/manage/library/{id}/download[?assetId=]` | 权限：`manage:library:download`
- 行为：任意状态均可，302 到资产 `fileUrl`/`linkUrl`；若未指定 `assetId` 按 pdf→epub→mobi→zip 选择。

## 新增/编辑/删除
- 新增：POST `/manage/library` | 权限：`manage:library:add`
- 编辑：PUT  `/manage/library` | 权限：`manage:library:edit`
- 删除：DELETE `/manage/library/{ids}` | 权限：`manage:library:remove`
- 硬删除（占位）：DELETE `/manage/library/{ids}/hard` | 权限：`manage:library:remove`（当前返回 601 警告）
- 请求示例（新增）：
```json
{ "isbn13":"9787111544937", "title":"CSAPP", "author":"Randal E. Bryant" }
```

## 审批与上下架
- 通过：PUT `/manage/library/{id}/approve` | 权限：`manage:library:approve`
- 驳回：PUT `/manage/library/{id}/reject` | 权限：`manage:library:reject` | Body：`{ "reason":"与主题不符" }`
- 下架：PUT `/manage/library/{id}/offline` | 权限：`manage:library:offline` | Body：`{ "reason":"侵权或敏感" }`
- 上线：PUT `/manage/library/{id}/online` | 权限：`manage:library:online`

## 图书管理员（任免）
- 列表：GET `/manage/library/librarian/list` | 权限：`manage:libraryLibrarian:list`
- 任命：POST `/manage/library/librarian` | 权限：`manage:libraryLibrarian:add` | Body：`{ "userId": 1001 }`
- 解除：DELETE `/manage/library/librarian/{userIds}` | 权限：`manage:libraryLibrarian:remove`

## 榜单
- 管理端不提供独立“榜单”接口；请使用门户端接口：
  - GET `/portal/library/top?limit=10`
  - GET `/portal/library/top/users?limit=10`

## 统计趋势（折线图）

### 上传趋势
- 方法：GET
- 路径：`/manage/library/stats/uploadTrend`
- 权限：登录（isAuthenticated）
- 参数（query）：`days`(int) 可选，默认 30，范围 1~365（含今天）
- 返回示例：
```json
{ "code":200, "data":[ {"day":"2025-11-01","count":3}, {"day":"2025-11-02","count":5} ] }
```
- 说明：按 `tb_library_book.create_time` 聚合；无数据日期补零。

### 下载趋势
- 方法：GET
- 路径：`/manage/library/stats/downloadTrend`
- 权限：登录（isAuthenticated）
- 参数（query）：`days`(int) 可选，默认 30，范围 1~365（含今天）
- 返回示例：
```json
{ "code":200, "data":[ {"day":"2025-11-01","count":12}, {"day":"2025-11-02","count":8} ] }
```
- 说明：按 `tb_library_book_download_log.create_time` 聚合，仅统计 `result='0'` 成功记录；无数据日期补零。

## 统计排行（柱状图）

### 图书下载榜（TopN）
- 方法：GET
- 路径：`/manage/library/stats/topBooks`
- 权限：登录（isAuthenticated）
- 参数（query）：`limit`(int) 可选，默认 5
- 返回示例：
```json
{ "code":200, "data":[ {"id":1, "title":"CSAPP", "downloadCount":123} ] }
```

### 用户下载榜（TopN）
- 方法：GET
- 路径：`/manage/library/stats/topDownloadUsers`
- 权限：登录（isAuthenticated）
- 参数（query）：`limit`(int) 可选，默认 5
- 返回示例：
```json
{ "code":200, "data":[ {"userId":1001, "nickname":"student", "passedCount":56} ] }
```
- 说明：此处 `passedCount` 字段代表“下载次数”（历史字段名复用）。

### 用户上传榜（TopN）
- 方法：GET
- 路径：`/manage/library/stats/topUploadUsers`
- 权限：登录（isAuthenticated）
- 参数（query）：`limit`(int) 默认 5
- 返回示例：
```json
{ "code":200, "data":[ {"userId":1002, "nickname":"alice", "passedCount":12} ] }
```
- 说明：`passedCount` 表示该用户通过审核并上架的图书数量。

## 业务与错误码
- 下载：增加 `downloadCount` 并记录 `LibraryDownloadLog`；资产列表用于管理端选择。
- 常见错误码：
  - 401 未授权；403 权限不足；404 记录或资产不存在；409 流转冲突；500 业务失败

## 上传与资产
- 管理端可复用统一上传接口：`POST /manage/upload/oss`（权限：`manage:upload:oss`）
  - 参数：`dir`（可选）、`publicUrl`（可选）
  - 返回：`data.url` 可直接用于 LibraryAsset.fileUrl

## Apifox 导入建议
- 分组：数字图书馆-管理；环境 `local`；变量 `Authorization`。
- 建议用例：
  1) 新增图书 → 审批通过 → 下载应 302
  2) 驳回/下架/上线 → 验证状态机约束
  3) 管理员任免 → 列表可见变更