# 数字图书馆（门户）API 文档（高质量版）

更新时间：2025-11-07

## 概览
- 业务说明：面向登录用户的图书浏览、下载、收藏与“我的上传”管理；支持一次性创建图书+资产。非上架记录仅作者本人可见。
- 角色权限：登录（`isAuthenticated()`）。编辑/删除/资产变更仅限上传者本人；下载仅对上架记录开放。
- 依赖表：`tb_library_book`（图书）、`tb_library_book_asset`（资产）、`tb_library_book_favorite`（收藏）
- 环境：
  - baseURL：`http://localhost:8080`
  - 认证：`Authorization: Bearer <token>`

## 数据模型与规则
- Library（主体字段）
  - `id` bigint；`isbn13`（必填，系统校验并规范化为 13 位）
  - `title` 标题（必填 ≤128）；`author`；`publisher`；`publishYear`；`language`；`keywords`；`summary`；`coverUrl`
  - `status` 0待审 1已通过 2驳回 3已下架；审核：`auditBy/auditTime/auditReason`；发布：`publishTime`
  - 统计：`downloadCount/lastDownloadTime`；作者：`uploaderId/uploaderName`；审计：`create_by/.../del_flag`
- LibraryAsset（资产字段）
  - `id`、`bookId`；`assetType` '0'文件/'1'外链；`format` pdf/epub/mobi/zip
  - 文件类：`fileUrl/fileSize/fileHash/ossObjectKey`；外链：`linkUrl`；`sort`
- 状态流转
  - 新增 → 待审(0)；审核通过 → 上架(1)；审核驳回 → 驳回(2)；下架 → 下架(3)
  - 编辑/增删资产：仅作者且“非上架(≠1)”允许；编辑后置为“待审(0)”
- 下载优先顺序：未指定 `assetId` 时按 pdf→epub→mobi→zip 选择

## 分页/过滤/排序
- 分页：`pageNum/pageSize`（默认 1/10）
- 过滤：
  - `keyword` 匹配 title/author/isbn13/keywords
  - `format` 筛选存在指定格式的“文件型资产”
  - `uploaderId` 指定上传者（当等于当前用户时，返回全状态，可叠加 `status` 过滤）
  - `status` 仅在“我的上传”场景生效；通用列表恒定返回 `status=1`
- 排序：`orderByColumn` + `isAsc`；默认 `publish_time desc, id desc`

## 路由清单与参数

### 列表
- 方法：GET
- 路径：`/portal/library/list`
- 权限：登录
- 请求参数（query，可选）：
  - `keyword`(string) 关键字
  - `format`(string) `pdf|epub|mobi|zip`
  - `uploaderId`(long) 设置为当前登录用户ID可启用“我的上传”
  - `status`(int) 0/1/2/3（仅在“我的上传”时有效）
  - `pageNum`(int)/`pageSize`(int)
- 返回示例：
```json
{ "code":200, "rows":[ { "id":1, "title":"CSAPP", "status":1 } ], "total":1 }
```

### 详情
- 方法：GET
- 路径：`/portal/library/{id}`
- 权限：登录
- 返回：`{ library, book(兼容), assets[], favorite }`
- 示例：
```json
{
  "code":200,
  "data":{
    "library": { "id": 1, "title": "CSAPP", "status": 1 },
    "book":    { "id": 1, "title": "CSAPP", "status": 1 },
    "assets":  [ { "id": 11, "assetType": "0", "format": "pdf", "fileUrl": "https://..." } ],
    "favorite": true
  }
}
```

### 下载（302）
- 方法：GET
- 路径：`/portal/library/{id}/download`
- 权限：登录
- 参数（query，可选）：`assetId`(long)
- 行为：302 到资产的 `fileUrl` 或 `linkUrl`；未上架或不存在返回 HTTP 404

### 新增（图书）
- 方法：POST
- 路径：`/portal/library`
- 权限：登录
- 请求体（json）：
```json
{ "isbn13":"9787111544937", "title":"CSAPP", "author":"Randal E. Bryant", "summary":"深入理解计算机系统" }
```
- 返回：`{ "code":200, "data": { "id": 1001 } }`
- 说明：服务端将校验 ISBN-13 并去重；初始状态为 `0(待审)`。

### 一次性新增（图书+资产）
- 方法：POST
- 路径：`/portal/library/full`
- 权限：登录
- 请求体（json）：
```json
{
  "isbn13": "9787111544937",
  "title": "CSAPP",
  "author": "Randal E. Bryant",
  "assets": [
    { "assetType":"0", "format":"pdf", "fileUrl":"https://oss/.../csapp.pdf", "fileSize": 1234567 }
  ]
}
```
- 返回：`{ "code":200, "data": { "id": 1001 } }`

### 编辑/删除（仅作者，非上架）
- 编辑：PUT  `/portal/library`（Body 含 `id` 与变更字段，编辑后置 `status=0`）
- 删除：DELETE `/portal/library/{ids}`（逗号分隔）

### 资产增删（仅作者，非上架）
- 新增资产：POST   `/portal/library/{id}/asset`（Body：单个资产对象）
- 删除资产：DELETE `/portal/library/{id}/asset/{assetId}`

### 收藏
- 设置：POST `/portal/library/{id}/favorite`（Body：`{ "favorite": true|false }`）
- 列表：GET  `/portal/library/favorite`（分页返回收藏列表）

### 榜单
- GET `/portal/library/top?limit=10`（下载量 TopN）
- GET `/portal/library/top/users?limit=10`（贡献者 TopN：`TopUserVO={userId,username,nickname,passedCount}`）

## 上传与校验（OSS）
- 上传网关：`POST /portal/upload/oss`
  - 场景：`library.pdf`（仅 pdf，≤100MB）、`library.extra`（epub/mobi/zip，≤100MB）
  - 表单：`file`（binary），可选 `dir`/`publicUrl`
  - 成功：返回 `data.url`，用于 `fileUrl`

## 错误码与语义
- 401 未授权：未携带/过期 token
- 403 越权：非作者修改/增删资产/删除
- 404 不存在或未上架：非作者访问未上架详情/下载
- 409 状态冲突：上架状态不允许编辑或增删资产
- 500 业务错误：参数校验/唯一约束（如 ISBN 冲突）

## Apifox 导入建议
- 分组：数字图书馆-门户；环境 `local` baseURL=`http://localhost:8080`；全局变量 `Authorization`。
- 建议用例：
  1) 登录获取 token → 设置变量
  2) 创建图书(full) → 校验返回 id → 列表（我的上传）应可见且 `status=0`
  3) 添加资产 → 详情应含新资产
  4) 收藏开关 → 收藏列表应出现/移除
  5) 下载（上架前应返回 404；上架后 302）