# 按顺序继续完成程序

## Goal

继续完成 MZH Library Management 的下一组核心功能，让现有 JSP + Servlet + JDBC 图书馆系统从已完成的基础业务链路继续向完整后台能力推进。

## What I already know

* 用户要求“按顺序继续完成程序”，当前没有 active task，因此本任务用于恢复开发方向并确认下一步范围。
* 用户已选择下一步做 **报表中心**。
* 项目是 Java 11 Maven WAR，使用 JSP + Servlet + MySQL/JDBC。
* 已有认证、权限过滤、角色首页、图书目录、图书管理、读者管理、借书/还书/续借/逾期、读者借阅历史。
* 最近提交顺序显示功能推进为：认证/权限 -> 图书 -> 读者 -> 借还续借逾期。
* 数据库和权限模型中还预留了 `manage_users`、`view_reports`、`view_system_logs` 等能力。
* 当前后台 Administration 卡片文案提到账号、角色、权限、系统维护入口，但实际还没有独立用户管理和系统日志页面。

## Assumptions (temporary)

* “按顺序”优先遵循现有业务链和权限模型：借阅链路完成后，应补齐统计报表或管理后台缺口。
* 本轮应选择一个清晰、可验收的 MVP 模块，不把用户管理、报表、日志全部混在一次任务里。

## Open Questions

* None for this MVP.

## Requirements

* 继续沿用现有 Servlet -> Service -> DAO -> JSP 分层。
* 新增报表中心，面向拥有 `view_reports` 权限的管理员和馆员。
* 报表中心应至少展示：
  * 图书库存概览：总书目数、总册数、可借册数、不可借/归档或无可借库存的提示统计。
  * 借阅概览：当前借出、已归还、已逾期数量。
  * 逾期清单：展示读者、图书、应还日期、逾期天数等关键字段。
  * 热门借阅排行：按借阅记录数量展示 Top 图书。
* 新页面入口应出现在 dashboard / role-home 的管理员和馆员工作区中。
* 新功能必须接入现有角色权限体系；读者不能访问报表中心。
* 新功能应包含 focused service checks，维持当前项目的轻量测试风格。
* 报表数据应基于现有 `books`、`readers`、`borrow_records` 表，不引入新表。

## Acceptance Criteria

* [x] 明确下一步 MVP 模块：报表中心。
* [x] 新模块有受权限保护的入口和页面。
* [x] 新模块使用现有分层和错误处理风格。
* [x] 管理员和馆员可打开报表中心，读者访问会被拒绝。
* [x] 报表页面展示库存概览、借阅概览、逾期清单、热门借阅排行。
* [x] 新增或更新服务层检查。
* [ ] Maven 构建通过（当前环境未安装 `mvn`，已用 `javac` fallback 和轻量 checks 验证）。

## Definition of Done (team quality bar)

* Tests added/updated where appropriate.
* Maven compile/package checks pass where available.
* Docs/notes updated if behavior changes.
* Rollout/rollback considered if risky.

## Out of Scope (explicit)

* 暂不一次性实现用户管理和系统日志页面。
* 暂不实现图表库、导出 Excel/PDF、按日期筛选等高级报表能力。
* 暂不引入新框架或前后端分离。
* 暂不修改现有认证和核心借阅规则，除非所选模块必须依赖。

## Technical Approach

Add a reports slice consistent with the existing architecture: entity/value objects for report summaries, DAO queries for aggregate data, a service facade for report composition and permission checks, a servlet mapped to `/reports`, and a JSP under `WEB-INF/jsp/reports/`. Reuse existing CSS patterns for compact dashboard cards and tables.

## Decision (ADR-lite)

**Context**: The borrowing workflow is now implemented, and the permission model already contains `view_reports`.

**Decision**: Implement a server-rendered report center as the next MVP module, focused on operational summaries that can be derived from existing tables.

**Consequences**: This gives administrators and librarians immediate visibility into inventory and borrowing health without introducing reporting infrastructure. Date filters, exports, and charts remain future enhancements.

## Technical Notes

* `README.md` 描述当前项目结构和本地部署方式。
* `src/main/resources/db/schema.sql` 已有 `system_logs` 表、`view_reports` 和 `view_system_logs` 权限。
* `src/main/webapp/WEB-INF/web.xml` 当前未映射 reports、logs 或 users 管理 servlet。
* `src/main/webapp/WEB-INF/jsp/dashboard.jsp` 和 `role-home.jsp` 是新增入口的主要位置。
* 语义代码检索 MCP 返回 403 权限错误；本轮自动上下文改用本地只读文件检查。