@@ -1,30 +1,336 @@
# MZH Library Management
# MZH 图书馆管理系统
Initial JSP + Servlet + MySQL scaffold for the library-management system.
MZH Library Management 是一个基于 Java 11、Maven WAR、JSP、Servlet、JDBC DAO 和 MySQL 的 B/S 图书馆管理系统。项目以 Tomcat 部署为目标，采用传统 Java Web 分层结构，适合用于课程设计、Java Web 实训、图书馆业务原型验证，以及学习 Servlet -> Service -> DAO -> MySQL 的完整数据流。
## Stack
当前仓库已经包含登录认证、角色权限、馆藏检索、图书管理、分类管理、读者档案、借阅流通、读者借阅历史、报表中心、管理员用户管理和系统日志查看等功能切片。
- Java 11
- Maven WAR project layout
- JSP + Servlet on Tomcat
- MySQL through JDBC DAO classes
## 核心功能
## Local Setup
- 登录与会话管理：通过 `/login` 登录，认证成功后进入 `/dashboard` ；会话中只保存安全的 `AuthenticatedUser` 快照、角色代码和权限代码集合。
- 角色工作台：管理员、馆员、读者分别通过 `/admin/home` 、`/librarian/home` 、`/reader/home` 进入对应区域。
- 馆藏检索：通过 `/catalog` 按图书编号、书名、作者和分类检索图书。
- 图书管理：通过 `/books` 维护图书信息，支持新增、编辑、删除和库存状态管理。
- 图书分类管理：通过 `/book-categories` 维护图书分类，并防止删除仍被图书引用的分类。
- 读者管理：通过 `/readers` 维护读者档案、联系方式、状态和最大借阅数量。
- 借阅流通：通过 `/borrowing` 完成借书、还书、续借、逾期筛选和库存联动更新。
- 读者借阅历史：读者通过 `/reader/loans` 查看自己的借阅记录。
- 报表中心：通过 `/reports` 查看馆藏汇总、借阅汇总、逾期列表和热门图书排行。
- 用户管理：管理员通过 `/admin/users` 维护管理员、馆员和读者登录账户。
- 系统日志：管理员通过 `/admin/system-logs` 查询关键操作、审计和异常日志。
1. Create a MySQL database and run `src/main/resources/db/schema.sql` .
2. Copy `src/main/resources/db.properties.example` to `src/main/resources/db.properties` .
3. Fill in the MySQL URL, username, and password.
4. Build with Maven when available:
## 技术栈
| 类别 | 当前配置 |
| --- | --- |
| Java | Java 11， `maven.compiler.release=11` |
| 构建工具 | Maven，
| Web 技术 | Servlet 4.0、JSP、JSTL |
| Servlet API | `javax.servlet:javax.servlet-api:4.0.1` ， `provided` |
| JSP 标签库 | `javax.servlet:jstl:1.2` |
| 数据库 | MySQL，
| MySQL 驱动 | `com.mysql:mysql-connector-j:8.0.33` ， `runtime` |
| 部署产物 | `target/library-management.war` |
| Web 配置 | `src/main/webapp/WEB-INF/web.xml` ， `web-app` 版本 4.0 |
| 编码 | Maven 源码编码 UTF-8； `CharacterEncodingFilter` 使用 UTF-8 |
建议使用兼容 Servlet 4.0 的 Tomcat 9.x 运行该 WAR。数据库脚本使用 InnoDB、`utf8mb4` 字符集和检查约束，建议使用 MySQL 8.x。
## 项目结构
``` text
.
├── pom.xml
├── README.md
├── src
│ ├── main
│ │ ├── java/com/mzh/library
│ │ │ ├── controller/ Servlet 控制器，负责路由、参数读取和 JSP 转发/重定向
│ │ │ ├── dao/ DAO 接口
│ │ │ ├── dao/impl/ JDBC DAO 实现
│ │ │ ├── entity/ JavaBean、枚举、查询条件和报表对象
│ │ │ ├── exception/ DAO 异常
│ │ │ ├── filter/ 编码、登录认证、权限过滤器
│ │ │ ├── service/ Service 接口、权限策略和通用结果对象
│ │ │ ├── service/impl/ 业务服务实现
│ │ │ └── util/ JDBC、密码哈希、Session 常量等工具
│ │ ├── resources
│ │ │ ├── db/schema.sql
│ │ │ └── db.properties.example
│ │ └── webapp
│ │ ├── WEB-INF/web.xml
│ │ ├── WEB-INF/jsp/ 受保护的 JSP 页面和 JSP 片段
│ │ ├── static/css/app.css
│ │ ├── static/images/library-login.svg
│ │ └── index.jsp
│ └── test/java/com/mzh/library/service
│ └── *Check.java 服务层和权限策略自检类
└── target/ Maven 构建输出，已被 .gitignore 忽略
```
本地数据库配置文件 `src/main/resources/db.properties` 也已被 `.gitignore` 忽略。不要提交真实数据库地址、账号或密码。
## 分层设计
项目遵循以下边界：
``` text
JSP/CSS 页面 -> Servlet 控制器 -> Service 业务层 -> DAO 数据访问层 -> MySQL
```
- JSP 只负责展示、表单和用户交互，不直接访问数据库，不编写业务流程。
- Servlet 负责读取请求参数、做基础格式校验、调用 Service，并决定转发 JSP 或重定向。
- Service 负责权限检查、业务规则、事务边界和跨 DAO 工作流，例如借书、还书、续借和库存更新。
- DAO 负责 SQL、JDBC 资源访问和 MySQL CRUD，不返回 HTML 或 Servlet 对象。
- 过滤器统一处理 UTF-8 编码、登录拦截和基于权限的访问控制。
## 数据库初始化
数据库脚本位于：
``` text
src/main/resources/db/schema.sql
```
脚本会创建并使用数据库 `mzh_library` ，包含以下核心表：
- `roles` ：角色定义。
- `permissions` ：权限定义。
- `role_permissions` ：角色与权限的关联。
- `users` ：登录账户，密码字段保存 PBKDF2 哈希。
- `system_logs` ：系统操作、审计和异常日志。
- `readers` ：读者档案、联系方式、状态和借阅上限。
- `book_categories` ：图书分类。
- `books` ：图书基础信息、分类、总册数、可借册数和状态。
- `borrow_records` ：借阅、归还、续借和逾期判断所需记录。
初始化示例：
``` bash
mysql -u root -p < src/main/resources/db/schema.sql
```
脚本内包含本地验证用的演示角色、权限、用户、读者、分类和图书数据。演示账户只用于本地脚手架验证；在非本地数据库中使用前应更换或删除这些数据。本文档不提供任何登录明文密码。
## 本地配置
复制配置模板：
``` bash
cp src/main/resources/db.properties.example src/main/resources/db.properties
```
模板内容使用以下键：
``` properties
db.driver = com.mysql.cj.jdbc.Driver
db.url = jdbc:mysql://localhost:3306/mzh_library?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai
db.username = library_user
db.password = change_me
```
按本机 MySQL 环境调整 `db.url` 、`db.username` 和 `db.password` 。实际配置文件不应提交到版本库。
如果你希望单独创建应用数据库用户，可以在 MySQL 中按需授权，例如：
``` sql
CREATE USER ' library_user ' @ ' localhost ' IDENTIFIED BY ' <your-local-password> ' ;
GRANT ALL PRIVILEGES ON mzh_library . * TO ' library_user ' @ ' localhost ' ;
FLUSH PRIVILEGES ;
```
请将示例中的占位密码替换为本地安全密码，不要把真实密码写入 README、提交记录或共享截图。
## 构建与部署
在项目根目录执行：
``` bash
mvn clean package
```
5. Deploy `target/library-management.war` to Tomcat.
如果当前 shell 找不到 `mvn` ，本工作区规范记录的 Maven 路径为：
The implemented scaffold slices now cover login/permission checks, catalog and
book management, book category maintenance, reader profile management,
borrowing circulation, reader loan history, the staff report center,
administrator user management, and system-log viewing. Authentication stores
only a safe authenticated-user snapshot in the HTTP session, and business
workflows stay in Servlet -> Service -> DAO boundaries.
``` bash
/home/sjy/.sdkman/candidates/maven/current/bin/mvn clean package
```
构建成功后会生成：
``` text
target/library-management.war
```
部署到 Tomcat 的常见方式：
1. 确认 MySQL 已启动，`mzh_library` 已初始化。
2. 确认 `src/main/resources/db.properties` 已写入本地数据库连接信息。
3. 执行 Maven 打包。
4. 将 `target/library-management.war` 放入 Tomcat 的 `webapps/` 目录，或通过 Tomcat Manager 上传。
5. 启动或重启 Tomcat。
6. 默认情况下，WAR 文件名会形成访问上下文 `/library-management` ，实际路径以 Tomcat 配置为准。
示例访问地址：
``` text
http://localhost:8080/library-management/login
```
## 主要路由
以下路由来自 `src/main/webapp/WEB-INF/web.xml` 、welcome-file 配置和对应 Servlet：
| 路由 | 处理者 | 用途 |
| --- | --- | --- |
| `/` （ `index.jsp` ） `index.jsp` | 欢迎入口，页面会重定向到 `/login` |
| `/login` | `LoginServlet` | 登录页和登录提交 |
| `/logout` | `LogoutServlet` | 退出登录 |
| `/dashboard` | `DashboardServlet` | 登录后的总览页 |
| `/admin/home` | `RoleAreaServlet` | 管理员区域首页 |
| `/librarian/home` | `RoleAreaServlet` | 馆员工作台 |
| `/reader/home` | `RoleAreaServlet` | 读者中心 |
| `/catalog` | `BookCatalogServlet` | 馆藏检索 |
| `/books` 、`/books/new` 、`/books/edit` 、`/books/update` 、`/books/delete` | `BookManagementServlet` | 图书管理 |
| `/book-categories` 、`/book-categories/new` 、`/book-categories/edit` 、`/book-categories/update` 、`/book-categories/delete` | `BookManagementServlet` | 图书分类管理 |
| `/readers` 、`/readers/new` 、`/readers/edit` 、`/readers/update` 、`/readers/delete` | `ReaderManagementServlet` | 读者档案管理 |
| `/borrowing` 、`/borrowing/new` 、`/borrowing/create` 、`/borrowing/return` 、`/borrowing/renew` | `BorrowingManagementServlet` | 借阅、归还、续借 |
| `/reader/loans` | `ReaderLoanHistoryServlet` | 当前读者借阅历史 |
| `/reports` | `ReportServlet` | 报表中心 |
| `/admin/users` 、`/admin/users/new` 、`/admin/users/edit` 、`/admin/users/update` 、`/admin/users/deactivate` | `UserManagementServlet` | 管理员用户管理 |
| `/admin/system-logs` | `SystemLogServlet` | 系统日志查询 |
| `/unauthorized` | `UnauthorizedServlet` | 无权限提示 |
静态资源路径 `/static/` 不要求登录。除 `/` 、`/login` 、`/unauthorized` 、`/favicon.ico` 和静态资源外，其他页面会经过 `AuthenticationFilter` 和 `AuthorizationFilter` 。
## 角色与权限
系统当前包含三类角色。运行时权限由 `PermissionPolicy` 根据 `Role` 枚举授予；`schema.sql` 同时保留 `roles` 、`permissions` 、`role_permissions` 表和本地种子数据，但当前登录流程不会从 `role_permissions` 动态加载权限。
| 角色代码 | 显示名称 | 权限概览 |
| --- | --- | --- |
| `administrator` | 管理员 | 运行时策略授予全部 `Permission` 枚举权限；具体入口仍受路由规则约束 |
| `librarian` | 馆员 | 可管理图书、读者、借阅流通，查看报表和馆藏 |
| `reader` | 读者 | 可查看馆藏，并访问读者自己的借阅历史 |
权限代码包括：
- `manage_users`
- `manage_books`
- `manage_readers`
- `manage_borrowing`
- `view_reports`
- `view_system_logs`
- `view_catalog`
- `borrow_books`
访问控制重点：
- `/admin/system-logs` 需要 `view_system_logs` 。
- `/admin/**` 用户管理入口需要 `manage_users` 。
- `/books/**` 和 `/book-categories/**` 需要 `manage_books` 。
- `/readers/**` 需要 `manage_readers` 。
- `/borrowing/**` 需要 `manage_borrowing` 。
- `/reports` 需要 `view_reports` 。
- `/catalog` 需要 `view_catalog` 。
- `/reader/loans` 需要 `borrow_books` ，并且必须是 `reader` 角色。
当前代码中的读者自助入口是 `/reader/loans` 借阅历史查看；借书、还书和续借操作由管理员或馆员通过 `/borrowing` 工作台处理。
## 业务规则摘要
- 图书以 `book_identifier` 作为面向用户的唯一编号。
- 图书分类名称唯一，已被图书引用的分类不能直接删除。
- 图书状态使用 `available` 、`unavailable` 、`archived` 。
- 读者以 `reader_identifier` 作为面向用户的唯一编号。
- 读者状态使用 `active` 、`suspended` 、`inactive` ，最大借阅数量范围为 1 到 50。
- 借阅记录状态使用 `active` 、`returned` ；逾期不是单独状态，而是由未归还且 `due_at` 早于当前时间的记录推导。
- 借书会在同一事务中创建借阅记录并减少图书可借册数。
- 还书会在同一事务中标记归还并恢复可借册数。
- 续借会延长应还时间并增加续借次数，当前 MVP 对单笔借阅限制一次续借。
- 用户管理变更会写入系统日志，审计信息不应记录密码、明文凭据或密码哈希。
## 开发约定
- 保持 Servlet -> Service -> DAO -> MySQL 的层次边界。
- JSP 页面只渲染 Servlet 设置的 request/session 属性，避免 JSP scriptlet、SQL、JDBC 或业务流程。
- 受保护操作必须经过服务层权限校验，不能只依赖页面按钮是否显示。
- 新增数据库访问时使用参数化 SQL 或 PreparedStatement 风格，避免拼接用户输入。
- 多表一致性操作放在服务层事务边界中，DAO 只处理具体 SQL。
- 用户可见的页面文案、表单标签、按钮、空状态和服务反馈消息使用简体中文。
- URL、请求参数名、Java 标识符、数据库枚举值和权限代码保持现有代码形式。
- 本地私密配置只放在 `src/main/resources/db.properties` ，不要提交真实凭据。
## 测试与检查
当前仓库在 `src/test/java/com/mzh/library/service/` 下包含多个自检类：
- `AuthServiceCheck`
- `BookServiceCheck`
- `BorrowingServiceCheck`
- `PermissionPolicyCheck`
- `ReaderServiceCheck`
- `ReportServiceCheck`
- `SystemLogServiceCheck`
- `UserAccountServiceCheck`
这些自检类使用 `public static void main` 和内部断言。当前 `pom.xml` 没有引入 JUnit/TestNG，也没有配置 Surefire 执行 `*Check` ，因此 `mvn test` 会编译测试源码，但不会自动运行这些自检类。
常用编译和打包检查命令：
``` bash
mvn test
mvn clean package
```
如需手动运行自检类，可在 `mvn test` 编译完成后执行：
``` bash
for check in AuthServiceCheck BookServiceCheck BorrowingServiceCheck PermissionPolicyCheck ReaderServiceCheck ReportServiceCheck SystemLogServiceCheck UserAccountServiceCheck; do
java -cp target/classes:target/test-classes " com.mzh.library.service. ${ check } "
done
```
如果 Maven 不在 `PATH` 中，可使用：
``` bash
/home/sjy/.sdkman/candidates/maven/current/bin/mvn test
/home/sjy/.sdkman/candidates/maven/current/bin/mvn clean package
```
文档或页面调整后的人工自查建议：
- README 中的路径、路由和依赖版本是否与 `pom.xml` 、`web.xml` 、`schema.sql` 一致。
- 是否意外写入真实数据库账号、密码、连接串或生产部署信息。
- JSP 中是否出现 SQL、JDBC、密码字段展示或业务逻辑 scriptlet。
- 管理入口是否仍与 `AuthorizationFilter` 的权限规则一致。
## 常见问题
### 访问页面时跳回登录页
除 `/` 、`/login` 、`/unauthorized` 、`/favicon.ico` 和 `/static/` 外，系统默认要求登录。请确认已经登录，并检查 Tomcat 会话是否过期。当前登录会话超时时间为 30 分钟。
### 登录或数据库操作提示服务不可用
优先检查：
- MySQL 是否启动。
- `mzh_library` 是否已经通过 `schema.sql` 初始化。
- `src/main/resources/db.properties` 是否存在。
- `db.url` 、`db.username` 、`db.password` 是否与本地 MySQL 一致。
- MySQL Connector/J 依赖是否已被 Maven 正确下载。
### 打包后访问路径不是 `/library-management`
Maven 当前将 WAR 产物命名为 `library-management.war` 。Tomcat 通常会用 WAR 文件名作为上下文路径，但如果你在 Tomcat 中手动配置了 Context，最终访问路径以 Tomcat 配置为准。
### 可以把 `db.properties` 提交吗？
不可以。`src/main/resources/db.properties` 是本地私密配置，已经被 `.gitignore` 忽略。只应提交 `src/main/resources/db.properties.example` 。
### README 为什么不列出演示账号密码？
数据库脚本包含本地验证用演示数据，但项目要求 README 不写入未经确认的默认登录明文密码，也不扩散任何凭据。需要本地调试时，请由维护者按当前数据库脚本和安全要求单独确认或重置账号。
## 维护提示
当 `pom.xml` 、`web.xml` 、数据库表结构、角色权限、主要 JSP 路径或测试入口变化时，应同步更新本 README，避免部署步骤和功能说明与实际代码脱节。
Zzzz