图书管理系统详细设计文档——图书管理服务产品大全文华时代（北京）国际文化发展有限公司

1. 引言

1.1 编写目的

本文档旨在详细描述图书管理系统中图书管理服务的详细设计，为开发人员、测试人员和维护人员提供清晰的实现指导。文档涵盖服务架构、模块划分、接口定义、数据模型、关键流程、异常处理及非功能性需求等。

1.2 范围

图书管理服务是图书管理系统的核心微服务之一，负责图书信息的增删改查、库存管理、分类管理以及图书状态维护。本设计不涉及用户管理、借阅流通、通知等其它服务。

1.3 术语定义

图书：系统中可被借阅的实体，包含ISBN、书名、作者、出版社等元数据。
馆藏副本：同一图书的多个物理副本，每个副本有唯一条码。
分类：图书的分类体系（如中图法）。
服务：独立部署的Spring Boot应用，对外提供RESTful API。

2. 总体设计

2.1 服务架构

图书管理服务采用分层架构：

接口层：REST Controller，接收HTTP请求，进行参数校验。
应用层：Service，实现业务逻辑，事务控制。
领域层：实体、值对象、领域服务。
基础设施层：Repository（JPA/MyBatis）、消息队列（可选）、缓存（Redis）。

服务注册与发现采用Nacos，配置中心采用Nacos Config。

2.2 模块划分

| 模块 | 职责 |
|------|------|
| 图书信息管理 | 图书元数据的CRUD、搜索 |
| 馆藏副本管理 | 副本的增删改查、状态变更 |
| 分类管理 | 分类树的维护 |
| 库存管理 | 副本入库、出库、盘点 |
| 文件管理 | 图书封面上传、下载 |

3. 接口设计

所有接口遵循RESTful风格，返回JSON格式。基础路径：/api/v1/books。

3.1 图书信息接口

3.1.1 创建图书

- URL: POST /api/v1/books
- 请求体:
`json
{
"isbn": "9787115428028",
"title": "鲁迅全集",
"author": "鲁迅",
"publisher": "人民文学出版社",
"publishDate": "2005-11-01",
"categoryId": 123,
"price": 99.00,
"description": "..."
}
`

响应: 201 Created，返回包含id的图书对象。
错误: 400参数错误，409 ISBN重复。

3.1.2 更新图书

URL: PUT /api/v1/books/{id}
请求体同创建，成功返回200。

3.1.3 删除图书

URL: DELETE /api/v1/books/{id}
需校验无在借副本，否则409。成功返回204。

3.1.4 查询图书详情

URL: GET /api/v1/books/{id}
返回图书及副本数量统计。

3.1.5 分页搜索图书

URL: GET /api/v1/books
参数: keyword, categoryId, page, size, sort
返回分页列表。

3.2 馆藏副本接口

POST /api/v1/books/{bookId}/copies 新增副本
GET /api/v1/books/{bookId}/copies 列出副本
PUT /api/v1/copies/{copyId}/status 变更副本状态（在架、借出、丢失、维修）
DELETE /api/v1/copies/{copyId} 删除副本

3.3 分类接口

POST /api/v1/categories 创建分类
GET /api/v1/categories/tree 获取分类树
PUT /api/v1/categories/{id}
DELETE /api/v1/categories/{id}

4. 数据模型

4.1 实体关系

Book (1) —— (n) BookCopy
Category (1) —— (n) Book

4.2 表结构

book表
| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| isbn | varchar(20) | 唯一 |
| title | varchar(200) | |
| author | varchar(100) | |
| publisher | varchar(100) | |
| publishdate | date | |
| categoryid | bigint | 外键 |
| price | decimal(10,2) | |
| description | text | |
| coverurl | varchar(255) | |
| createdat | datetime | |
| updated_at | datetime | |

bookcopy表
| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| bookid | bigint | 外键 |
| barcode | varchar(50) | 唯一 |
| status | varchar(20) | 枚举 |
| location | varchar(50) | 架位 |
| created_at | datetime | |

category表
| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| name | varchar(50) | |
| parentid | bigint | 自关联 |
| sortorder | int | |

4.3 缓存设计

图书详情缓存：key = book:{id}，TTL 10分钟，更新时删除。
分类树缓存：key = category:tree，TTL 1小时。

5. 关键流程

5.1 创建图书流程

接口层校验参数（ISBN格式、必填字段）。
应用层检查ISBN唯一性，若重复抛异常。
校验分类ID是否存在。
保存图书实体。
清除相关缓存。
返回创建结果。

5.2 删除图书流程

检查图书是否存在。
检查是否存在状态为“借出”的副本，如有则拒绝。
删除所有副本（逻辑删除或物理删除）。
删除图书记录。
清除缓存。

5.3 库存盘点

接收盘点任务（一批副本ID及实际状态）。
对比系统状态与实际状态。
生成差异报告。
批量更新副本状态。

6. 异常处理

统一异常处理通过@ControllerAdvice实现。

| 异常 | HTTP状态 | 错误码 | 描述 |
|------|----------|--------|------|
| MethodArgumentNotValidException | 400 | 1001 | 参数校验失败 |
| BusinessException | 400 | 1002 | 业务异常，message自定义 |
| EntityNotFoundException | 404 | 1003 | 资源不存在 |
| ConflictException | 409 | 1004 | 数据冲突 |
| Exception | 500 | 2000 | 系统内部错误 |

返回体格式：
`json
{
"code": 1004,
"message": "ISBN已存在",
"timestamp": "2023-10-01T12:00:00Z"
}
`