# 数字图书馆 API 文档（MVP，已拆分）

> 重要说明：本文为早期总览版，现已拆分为两份更清晰的文档，请优先参考：
> - 门户端：docs/api/数字图书馆-门户.md
> - 管理端：docs/api/数字图书馆-管理.md


更新时间：2025-11-03

## 概览
- 业务：电子图书上传（走审核）、发布/下架、下载访问、收藏、排行榜（下载榜与用户贡献榜）。
- RuoYi 对齐：权限标识一致；分页参数 `pageNum/pageSize`；列表返回 `rows/total`；统一响应 `AjaxResult`。
- ISBN：仅接受 ISBN-13（数字字符串），可输入含连字符，入库前规范化+校验位校验。

依赖表：`tb_library_book`、`tb_library_book_asset`、`tb_library_book_favorite`、`tb_library_book_download_log`、`tb_library_book_log`、`tb_library_librarian`。

权限矩阵（按钮级）：
- 图书：`manage:library:list` `manage:library:get` `manage:library:approve` `manage:library:reject` `manage:library:offline` `manage:library:online` `manage:library:remove` `manage:library:hardRemove`
- 图书管理员：`manage:libraryLibrarian:list` `manage:libraryLibrarian:add` `manage:libraryLibrarian:remove`
- 上传：`manage:upload:oss`（通用 OSS 上传）

## 路由清单
- 门户（需登录）
  - GET `/portal/library/list`（分页列表，已通过）
  - GET `/portal/library/{id}`（详情，含全部资产用于多格式下载）
  - GET `/portal/library/{id}/download`（计数并 302 跳转，支持 `assetId`）
  - POST `/portal/library/{id}/favorite`（收藏/取消收藏）
  - POST `/portal/library`（用户上传，进入待审）
  - PUT `/portal/library`（用户编辑，回到待审）
  - DELETE `/portal/library/{ids}`（删除本人待审/驳回/下架）
  - POST `/portal/library/{id}/asset`（追加资产）
  - DELETE `/portal/library/{id}/asset/{assetId}`（删除资产）
  - GET `/portal/library/top`（图书下载总榜）
  - GET `/portal/library/top/users`（用户贡献榜）
- 后台管理
  - GET `/manage/library/list` 权限：`manage:library:list`
  - GET `/manage/library/{id}` 权限：`manage:library:get`
  - PUT `/manage/library/{id}/approve` 权限：`manage:library:approve`
  - PUT `/manage/library/{id}/reject` 权限：`manage:library:reject`
  - PUT `/manage/library/{id}/offline` 权限：`manage:library:offline`
  - PUT `/manage/library/{id}/online` 权限：`manage:library:online`
  - DELETE `/manage/library/{ids}` 权限：`manage:library:remove`
  - DELETE `/manage/library/{ids}/hard` 权限：`manage:library:hardRemove`
  - GET `/manage/library/librarian/list` 权限：`manage:libraryLibrarian:list`
  - POST `/manage/library/librarian` 权限：`manage:libraryLibrarian:add`
  - DELETE `/manage/library/librarian/{userIds}` 权限：`manage:libraryLibrarian:remove`

## 公共数据结构
- LibraryVO（列表项）
  - `id, isbn13, title, author, publisher, publishYear, language, coverUrl, status, downloadCount, publishTime, lastDownloadTime`
- AssetVO（资产）
  - `id, assetType(0|1), format(pdf|epub|mobi|zip), fileUrl, fileSize, linkUrl, sort`
- LibraryDetailVO（详情）
  - `library: LibraryVO`
  - `assets: AssetVO[]`（用于渲染多格式下载按钮）
  - `favorite: boolean`（当前用户是否已收藏）
- TopUserVO（贡献榜项）
  - `userId, username, nickname, passedCount`

## 接口：门户-列表
- 方法：GET
- 路径：/portal/library/list
- 权限：登录
- 请求参数（query）：
  - `pageNum` int 必需；`pageSize` int 必需（≤50）
  - `keyword` string 可选（标题/作者/ISBN/关键字）
  - `format` string 可选（pdf|epub|mobi|zip）
  - `publisher` string 可选；`yearStart` int 可选；`yearEnd` int 可选
  - 排序：`orderByColumn` 可选（publishTime|downloadCount|updateTime）；`isAsc` 可选（asc|desc，默认 desc）
- 返回示例：
```json
{ "code":200, "msg":"成功", "rows":[ { "id":101, "isbn13":"9787110000028", "title":"Java 核心技术 卷I", "author":"Cay S. Horstmann", "publisher":"机械工业出版社", "publishYear":2022, "coverUrl":null, "downloadCount":12 } ], "total":123 }
```

## 接口：门户-详情
- 方法：GET
- 路径：/portal/library/{id}
- 权限：登录
- 行为：返回图书与全部资产；前端据此展示多格式下载按钮（存在的格式才显示）。
- 返回示例：
```json
{ "code":200, "msg":"成功", "data": { "library": { "id":101, "isbn13":"9787110000028", "title":"Java 核心技术 卷I", "author":"Cay S. Horstmann", "status":1, "downloadCount":12 }, "assets":[ { "id":1, "assetType":"0", "format":"pdf", "fileUrl":"https://oss/...pdf", "fileSize":10485760, "sort":1 } ], "favorite": false } }
```

## 接口：门户-下载
- 方法：GET
- 路径：/portal/library/{id}/download
- 权限：登录
- 请求参数（query）：`assetId` 可选（指定资产）
- 行为：计数并 302 跳转到文件/外链；失败返回错误码
- 返回：302 或 `{ code!=200, msg }`

## 接口：门户-收藏/取消收藏
- 方法：POST
- 路径：/portal/library/{id}/favorite
- 权限：登录
- 请求体：`{ "favorite": true|false }`
- 行为：幂等；重复收藏/取消收藏均成功
- 返回示例：`{ "code":200, "msg":"操作成功" }`

## 接口：门户-新增图书
- 方法：POST
- 路径：/portal/library
- 权限：登录
- 请求体（application/json）：
```json
{ "isbn13":"9787110000028", "title":"Java 核心技术 卷I", "author":"Cay S. Horstmann", "publisher":"机械工业出版社", "publish_year":2022, "language":"zh", "keywords":"Java,基础", "summary":"...", "cover_url": null }
```
- 行为：进入待审（status=0），编辑会回到待审
- 返回示例：`{ "code":200, "msg":"操作成功", "data": { "id": 101 } }`

## 接口：门户-编辑图书
- 方法：PUT
- 路径：/portal/library
- 权限：登录
- 请求体：同新增，需包含 `id`
- 行为：仅允许编辑本人图书；状态回到待审
- 返回示例：`{ "code":200, "msg":"操作成功" }`

## 接口：门户-删除图书
- 方法：DELETE
- 路径：/portal/library/{ids}
- 权限：登录
- 行为：删除本人“待审/驳回/下架”的记录；已通过不可直接删除
- 返回示例：`{ "code":200, "msg":"操作成功" }`

## 接口：门户-追加资产
- 方法：POST
- 路径：/portal/library/{id}/asset
- 权限：登录
- 请求体：
```json
{ "asset_type": 0, "format": "pdf", "file_url": "https://oss/...pdf", "file_size": 10485760, "file_hash": "sha256:..." }
```
- 行为：追加多格式资产；文件型白名单与大小校验
- 返回示例：`{ "code":200, "msg":"操作成功", "data": { "assetId": 1 } }`

## 接口：门户-删除资产
- 方法：DELETE
- 路径：/portal/library/{id}/asset/{assetId}
- 权限：登录
- 行为：仅在“待审/驳回/下架”状态允许；删除文件型资产仅删库，不删 OSS（由硬删除处理）
- 返回示例：`{ "code":200, "msg":"操作成功" }`

## 接口：门户-下载总榜
- 方法：GET
- 路径：/portal/library/top
- 权限：登录
- 请求参数：`limit` 可选（默认10，最大100）
- 返回示例：
```json
{ "code":200, "msg":"成功", "data": [ { "id":101, "title":"Java 核心技术 卷I", "author":"Cay S. Horstmann", "cover_url": null, "download_count": 12 } ] }
```

## 接口：门户-用户贡献榜
- 方法：GET
- 路径：/portal/library/top/users
- 权限：登录
- 请求参数：`limit` 可选（默认10，最大100）
- 口径：仅统计 `tb_book.status=1`
- 返回示例：
```json
{ "code":200, "msg":"成功", "data": [ { "userId": 2001, "username":"librarian01", "nickname":"图书管理员01", "passedCount": 8 } ] }
```

## 接口：后台-列表
- 方法：GET
- 路径：/manage/library/list
- 权限：manage:library:list
- 请求参数（query）：`pageNum` `pageSize` `status?` `keyword?` `uploaderId?` `publisher?` `yearStart?` `yearEnd?`
- 返回：同门户列表但含状态视角

## 接口：后台-详情
- 方法：GET
- 路径：/manage/library/{id}
- 权限：manage:library:get
- 返回：`{ code, msg, data: { book, assets } }`

## 接口：后台-审核通过
- 方法：PUT
- 路径：/manage/library/{id}/approve
- 权限：manage:library:approve
- 行为：设置 `status=1, publish_time=now()`；若 ISBN 重复可拒绝（409）
- 返回示例：`{ "code":200, "msg":"操作成功" }`

## 接口：后台-审核驳回
- 方法：PUT
- 路径：/manage/library/{id}/reject
- 权限：manage:library:reject
- 请求体：`{ "reason": "重复 ISBN" }`（必填）
- 行为：设置 `status=2, audit_reason=reason`
- 返回示例：`{ "code":200, "msg":"操作成功" }`

## 接口：后台-下架/上架
- 方法：PUT
- 路径：/manage/library/{id}/offline | /manage/library/{id}/online
- 权限：manage:library:offline | manage:library:online
- 请求体（offline）：`{ "reason": "版权到期" }`（必填）
- 行为：下架→`status=3` 且写入 `audit_reason`；上架→回到待审（0）
- 返回示例：`{ "code":200, "msg":"操作成功" }`

## 接口：后台-删除/硬删除
- 方法：DELETE
- 路径：/manage/library/{ids} | /manage/library/{ids}/hard
- 权限：manage:library:remove | manage:library:hardRemove
- 行为：软删（del_flag=2）；硬删：删除 DB + 删除文件型资产的 OSS 对象（依据 `oss_object_key`）
- 返回示例：`{ "code":200, "msg":"操作成功" }`

## 接口：后台-图书管理员管理
- 方法：GET | POST | DELETE
- 路径：/manage/library/librarian/list | /manage/library/librarian | /manage/library/librarian/{userIds}
- 权限：manage:libraryLibrarian:list | manage:libraryLibrarian:add | manage:libraryLibrarian:remove
- 行为：
  - 任命：写入 `tb_book_librarian` + 绑定系统角色（sys_user_role）
  - 卸任：移除 `tb_book_librarian` + 解绑系统角色（若无其他依赖）
- 返回示例：`{ "code":200, "msg":"操作成功" }`

## 错误码
- 400 参数错误：ISBN-13 无效（长度或校验位）、缺少标题/作者
- 401 未授权：未登录或 Token 失效
- 403 无权限：按钮权限不足或非本人记录
- 404 不存在：记录被删除或不可见
- 500 业务错误：ISBN 已存在或状态不允许操作（RuoYi 默认 ServiceException 返回 500）
- 422 约束：资产文件类型/大小不在白名单

## 备注
- 详情页展示全部已上传格式的下载按钮；默认下载策略（未指定 assetId）优先顺序：pdf > epub > mobi > zip。
- PDF 自动封面：首个 PDF 上传成功后异步抽取首页缩略图，失败不阻塞；可手动覆盖 `coverUrl`。
- 排行榜（MVP）仅提供“总榜”；时间窗留作后续扩展。