# Apifox 指南：数字图书馆（已拆分）

> 提示：本指南为合并版，现已拆分为：
> - 门户端：docs/apifox/数字图书馆-门户.md
> - 管理端：docs/apifox/数字图书馆-管理.md

固定信息
- baseURL: `http://localhost:8080`
- 统一请求头(JSON)：
```json
{
  "Authorization": "Bearer {{token}}"
}
```

步骤 0：登录获取 token（两种方式）
- A) 关闭验证码（默认常见：后台配置 sys.account.captchaEnabled=0）
  - 接口：POST /login
  - 请求体(JSON)：
```json
{
  "username": "admin",
  "password": "123456",
  "code": "",
  "uuid": ""
}
```
  - 响应示例(JSON)：
```json
{ "code": 200, "msg": "操作成功", "token": "{{copy_me_and_set_to_env_token}}" }
```

- B) 开启验证码（captchaEnabled=1）
  1) 获取验证码：GET /captchaImage
  - 响应(JSON)：
```json
{ "code": 200, "msg": "操作成功", "img": "data:image/gif;base64,XXX...", "uuid": "a1b2c3-..." }
```
  2) 用图片识别出的 "code" 与上一步的 "uuid" 登录：
```json
{ "username": "admin", "password": "123456", "code": "7+2", "uuid": "a1b2c3-..." }
```
  3) 登录响应同 A)，复制 token 写入环境变量。

步骤 1：新增图书（待审）
- 接口：POST /portal/library
- 请求体(JSON)：
```json
{
  "isbn13": "9787110000120",
  "title": "Java 核心技术 卷I",
  "author": "Cay S. Horstmann",
  "publisher": "机械工业出版社",
  "publishYear": 2022,
  "language": "zh",
  "keywords": "Java,基础",
  "summary": "入门到进阶",
  "coverUrl": null
}
```
- 响应示例(JSON)：
```json
{ "code": 200, "msg": "操作成功", "data": { "id": 1001 } }
```

步骤 2：追加 PDF 资产
- 先上传 OSS 获取 URL（如需）：POST /manage/upload/oss（表单）→ 取 `data.url` 作为 `fileUrl`
- 接口：POST /portal/library/{{libraryId}}/asset
- 请求体(JSON)：
```json
{
  "assetType": "0",
  "format": "pdf",
  "fileUrl": "{{pdfUrl}}",
  "fileSize": 10485760,
  "fileHash": "sha256:DEADBEEF",
  "ossObjectKey": "uploads/2025/11/book-1001.pdf",
  "linkUrl": null,
  "sort": 1
}
```
- 响应示例(JSON)：
```json
{ "code": 200, "msg": "操作成功", "data": { "assetId": 1 } }
```

步骤 3：管理员审核通过
- 接口：PUT /manage/library/{{libraryId}}/approve
- 请求体(JSON)：空
```json
{}
```
- 响应(JSON)：
```json
{ "code": 200, "msg": "操作成功" }
```

步骤 3B：管理员审核驳回（示例）
- 接口：PUT /manage/library/{{libraryId}}/reject
- 请求体(JSON)：
```json
{ "reason": "重复 ISBN / 质量不达标" }
```
- 说明：reason 为必填；接口将写入 audit_reason 并设置状态为驳回（2）。

步骤 4：门户-列表查询
- 接口：GET /portal/library/list
- 查询参数(JSON)：
```json
{ "pageNum": 1, "pageSize": 10, "keyword": "Java" }
```
- 响应(JSON)：
```json
{
  "code": 200,
  "msg": "成功",
  "rows": [
    { "id": 1001, "isbn13": "9787110000028", "title": "Java 核心技术 卷I", "author": "Cay S. Horstmann", "status": 1, "downloadCount": 12 }
  ],
  "total": 1
}
```

步骤 5：门户-详情
- 接口：GET /portal/library/{{libraryId}}
- 响应(JSON)：
```json
{
  "code": 200,
  "msg": "成功",
  "data": {
    "library": { "id": 1001, "isbn13": "9787110000028", "title": "Java 核心技术 卷I", "author": "Cay S. Horstmann", "status": 1, "downloadCount": 12 },
    "assets": [ { "id": 1, "assetType": "0", "format": "pdf", "fileUrl": "{{pdfUrl}}", "fileSize": 10485760, "sort": 1 } ],
    "favorite": false
  }
}
```

步骤 6：门户-下载（302 跳转，需登录）
- 接口：GET /portal/library/{{libraryId}}/download?assetId={{assetId}}
- 必须携带 Authorization 头（登录状态），否则 401。
- 预期：302；浏览器或 Apifox 将重定向至文件/外链。

步骤 7：收藏/取消收藏（幂等）
- 接口：POST /portal/library/{{libraryId}}/favorite
- 请求体(JSON)：
```json
{ "favorite": true }
```
- 响应(JSON)：
```json
{ "code": 200, "msg": "操作成功" }
```

-步骤 8：后台-上下线
- 下线：PUT /manage/library/{{libraryId}}/offline ；上线（回到待审）：PUT /manage/library/{{libraryId}}/online
- 请求体（offline，必填）(JSON)：
```json
{ "reason": "版权到期/内容更新/其它" }
```
- 响应(JSON)：
```json
{ "code": 200, "msg": "操作成功" }
```

步骤 9：后台-删除/批量删除
- 接口：DELETE /manage/library/{{ids}}
- 示例：/manage/library/1001,1002
- 响应(JSON)：
```json
{ "code": 200, "msg": "操作成功" }
```

步骤 10：后台-图书管理员管理（admin）
- 任命：POST /manage/library/librarian
- 请求体(JSON)：
```json
{ "userId": 2001 }
```
- 卸任：DELETE /manage/library/librarian/2001
- 列表：GET /manage/library/librarian/list
  - 查询参数(JSON)：
```json
{ "pageNum": 1, "pageSize": 10 }
```

常见失败示例（JSON）
- 401 未授权：
```json
{ "code": 401, "msg": "请求访问：未授权" }
```
- 403 无权限：
```json
{ "code": 403, "msg": "没有权限，请联系管理员授权" }
```
- ISBN 重复（RuoYi 默认 ServiceException → code=500）：
```json
{ "code": 500, "msg": "ISBN 已存在" }
```
- 422 资产不合法：
```json
{ "code": 422, "msg": "文件类型或大小不合法" }
```

变量与环境
- 建议变量：`{{token}}` `{{libraryId}}` `{{assetId}}` `{{pdfUrl}}`
- 环境：`local` = `http://localhost:8080`

Apifox 全局配置（强烈建议）
- 环境：新增 `local`，BaseURL 填 `http://localhost:8080`
- 变量：新增 `token`（初始留空），`libraryId`，`assetId`，`pdfUrl`
- 全局请求头（Project → Global → Header）：
```json
{ "Authorization": "Bearer {{token}}" }
```
- 登录接口 Tests（保存 token 到环境变量）：
```js
// 适配返回结构 { code, msg, token }
if (response.body && response.body.code === 200 && response.body.token) {
  apifox.setEnvironmentVariable('token', response.body.token);
}
```

401 常见原因与排查
- 未携带 `Authorization` 头：确认全局 Header 生效且 `{{token}}` 已被登录用例写入。
- 旧 token 失效：重新执行“步骤 0 登录”，覆盖环境变量。
- Redis 未就绪：本系统基于 Redis 存储登录态，请确认 `spring.redis.*` 指向可用实例，并且 Redis 已启动（否则会 401）。
- BaseURL 错误：确认 `http://localhost:8080` 或你实际运行端口。
- 说明：若多次调试，请更换为未使用过且有效的 ISBN-13（示例备用：`9787110000229`）。