# 数字图书馆（需求规格 v3.1 / 冻结候选）

更新时间：2025-11-03（对齐“课程资源分享”的流程与状态）

## 概览
- 目标：为校内用户提供“电子图书/资料”的上传、审核发布与下载访问；用户侧可检索/下载/收藏；管理员侧负责审核与运营（下载榜与贡献榜）。
- 组织：门户（只读 + 用户上传入口）+ 后台（审核/发布/下架/列表管理 + 图书管理员管理）；所有接口需登录。
- 流程差异：不涉及“专业/课程”维度；状态流转/审核规则与“课程资源分享”一致，并参考近期“排行榜与审核改造”。

## 门户信息架构（与课程资源分享一致的导航层级）
- 左侧导航（Portal）
  - 数字图书馆（/portal/library）
    - 全部图书（/portal/library/list）
    - 下载榜单（/portal/library/top）
    - 上传图书（/portal/library/upload）（也在“全部图书”页提供引导按钮）
    - 我的上传（/portal/library/contributions）
    - 我的收藏（/portal/library/fav）
- 顶栏：统一搜索框（标题/作者/ISBN/关键字）；用户头像入口；具备后台权限时展示“管理后台”入口。

## 角色与权限（按钮标识与后端一致）
- user（普通用户）
  - 门户：检索/查看详情/下载、查看下载榜、收藏/取消收藏、上传/编辑/删除“本人图书”并走审核。
  - 按钮：`manage:upload:oss`, `manage:library:add`, `manage:library:edit`, `manage:library:remove`
- librarian（图书管理员）
  - 后台：审核/发布/下架/硬删除、列表管理。
  - 按钮：`manage:library:list|get|approve|reject|offline|online|remove|hardRemove`
- admin/super_admin（管理员）
  - 拥有跨全局管理权限，与 librarian 等效或更高。可任命/卸任图书管理员。

新增：图书管理员管理（与系统角色联动）
- 页面：后台目录“数字图书馆 → 图书管理员”
- 能力：查看当前图书管理员列表、任命（为指定用户赋予 librarian 角色）、卸任（移除角色）
- 权限：`manage:libraryLibrarian:list|add|remove`
- 联动：调用 RuoYi 系统的用户-角色绑定（sys_user_role）完成实际授权/回收，同时维护模块映射表（tb_book_librarian）用于业务判定与审计。

## 状态与业务规则
- 图书状态：0 待审 / 1 已通过（已发布） / 2 驳回 / 3 已下架
- 规则：
  - 创建即待审；任何编辑回到待审；驳回可编辑后再次提交；下架可再次上架（回到待审）。
  - ISBN 必填且全局唯一；仅存储数字字符串（ISBN-13），输入可带连字符，入库前规范化并校验校验位；重复提交需在审核页明显提示并在“驳回原因”中告知。
  - 存储形态：支持“一书多格式”，通过“资产表”承载多文件或外链；文件白名单 pdf/epub/mobi/zip，单文件≤100MB。
  - 下载计数：仅通过受控下载接口计数并 302 跳转；同一用户多次下载均计入（后续可加入节流/限频）。
  - 收藏：同一用户对同一本书仅可收藏一次（幂等）。
  - 硬删除：删除 DB 记录同时删除 OSS 对象（文件型资产）；外链资产不涉及 OSS。

## 数据模型（概览，最终以 book-mis.sql 为准）
- `tb_library_book`：图书主体（ISBN、标题、作者、出版社、出版年、语言、关键词、简介、封面、状态/审核字段、统计、上传者与审计字段）
- `tb_library_book_asset`：图书资产（多格式：pdf/epub/mobi/zip 或外链；含大小/哈希/对象键等）
- `tb_library_book_favorite`：收藏关系（用户-图书，唯一约束）
- `tb_library_book_download_log`：下载日志（审计与统计溯源）
- `tb_library_book_log`：操作日志
- `tb_library_librarian`：图书管理员映射（与系统角色联动）
  预留（非 MVP）：`tb_library_tag` 与 `tb_library_tag_rel`（标签与关联），未来可引入“AI 自动打 Tag”，当前不落表。

## 检索与筛选
- 关键词：标题/作者/ISBN/关键字（OR 匹配）
- 筛选项：格式（从资产聚合）、出版年范围、出版社、状态（后台视角）
- 排序：默认 `publish_time DESC`；可选下载数/更新时间。
- 排行榜（MVP）：
  - 图书下载榜：总榜（按 `download_count DESC`），时间范围留作扩展。
  - 用户贡献榜：仅统计“状态=1 已通过”的书籍数量。

## 接口分层（遵循 RuoYi 风格）
- 门户（登录即可，读为主）：
  - GET `/portal/library/list`：检索/筛选/分页
  - GET `/portal/library/{id}`：详情
  - GET `/portal/library/{id}/download`：计数并跳转（可带 `assetId` 指定格式）
  - GET `/portal/library/top`：下载总榜
  - GET `/portal/library/top/users`：用户贡献榜
  - POST `/portal/library/{id}/favorite`：收藏/取消收藏（Body: `{ "favorite": true|false }`）
  - POST `/portal/library`：用户上传（走待审）
  - PUT `/portal/library`：用户编辑（回到待审）
  - DELETE `/portal/library/{ids}`：用户删除“本人待审/驳回/下架”
- 后台管理：
  - 图书列表：GET `/manage/library/list`、GET `/manage/library/{id}`
  - 审核流转：PUT `/manage/library/{id}/approve`、PUT `/manage/library/{id}/reject`（Body: `{ reason }`）
  - 上下架：PUT `/manage/library/{id}/offline`、PUT `/manage/library/{id}/online`（回到待审）
  - 删除：DELETE `/manage/library/{ids}`（软删）、DELETE `/manage/library/{ids}/hard`（硬删，连带 OSS 对象）

## 字段要点（tb_library_book 关键字段）
- 编目：`isbn13`（13位数字，唯一，仅存数字）、`title`、`author`、`publisher`、`publish_year`、`language`、`keywords`、`summary`
- 展示：`cover_url`
- 审核：`status`、`audit_by`、`audit_time`、`audit_reason`、`publish_time`
- 统计：`download_count`、`last_download_time`
- 上传者：`uploader_id`、`uploader_name`
- 审计：`create_by/create_time/update_by/update_time/del_flag`

## 资产（tb_library_book_asset）
- 类型：`asset_type`（0 文件 / 1 外链）
- 文件：`format`（pdf/epub/mobi/zip）、`file_url`、`file_size`、`file_hash`、`oss_object_key`
- 外链：`link_url`
- 唯一：文件型 `(book_id, asset_type, format, file_hash)`；外链型 `(book_id, asset_type, link_url)`
- 封面自动生成：当首个 PDF 资产上传成功后，后端尝试抽取第一页为封面图（PDFBox 等），失败则允许手工上传覆盖。

## 用户流程（门户）
- 用户
  1) 登录 → 数字图书馆列表 → 搜索/筛选 → 详情
  2) 上传（选择文件或外链 + 元数据 + 多格式可分多次追加）→ 提交（待审）
  3) 我上传的：查看状态；编辑后回到待审；删除“待审/驳回/下架”；已通过仅能申请下架
- 图书管理员
  - 审核队列：通过/驳回（填写理由）；已通过可下架；已下架可重新上架（回到待审）或执行硬删除（含 OSS）
  - 管理图书管理员：在“图书管理员”页对用户进行任命/卸任（联动系统角色），列表与搜索支持按姓名/账号。

## 边界与异常
- ISBN：校验 ISBN-13 的长度与校验位；仅存 `isbn13`（数字字符串，不含连字符）。
- 审核重复提示：后台审核页若探测到同 ISBN 已存在“已通过/待审”记录，应显著提示并可直接驳回并填写理由。
- 多格式资产：下载接口可指定 `assetId`；默认下载优先顺序 `pdf > epub > mobi > zip`。
- 硬删除：删除 DB 的同时，依 `oss_object_key` 删除 OSS 对象；外链资产不操作 OSS。

## 非功能性与安全
- 文件限制：pdf/epub/mobi/zip；≤100MB；前后端双重校验。
- 性能：分页≤50；总榜按 `download_count` 排序；后续可引入 Redis 缓存（`app:library:top`）。
- 密钥：OSS 凭据通过环境变量注入；不入库不入 Git。

## RuoYi 后台菜单与权限（建议）
- 目录：数字图书馆（/manage/library）
  - 菜单：审核队列（/manage/library/audit）
  - 菜单：图书列表（/manage/library/list）
  - 菜单：图书管理员（/manage/library/librarian）
  - 菜单：下载统计（/manage/library/stat）
  - 按钮：`manage:library:list|get|approve|reject|offline|online|remove|hardRemove`
  - 按钮（管理员）：`manage:libraryLibrarian:list|add|remove`
  - 说明：“图书管理员”角色本身在 RuoYi 的“角色管理”中维护，无需额外“管理员的管理”页面。

## DoD（本模块完成标准）
- 表结构（含注释与示例数据）已写入 `book-mis.sql` 尾部（本次将提交草案供确认）。
- API 文档与 Apifox 指南齐全，可验通过。
- 后端接口与权限可用；前端“列表/上传/下载/收藏/审核流转”可操作。
- 后端测试覆盖成功/失败/权限三类场景。
- 模块报告（ER/流程/权限矩阵/限制与计划）完成。

（说明：本文件为需求冻结候选。请确认后我将继续 API 文档与编码工作。）
## 界面与交互补充
- 书籍详情页：
  - 展示所有已上传格式的“下载”按钮（pdf/epub/mobi/zip），若无该格式则不显示。
  - 封面：若存在 PDF 资产且未设置封面，后端异步抽取第一页缩略图并更新 `cover_url`；失败不影响流程，可人工上传覆盖。