Book-management-system/.trellis/tasks/archive/2026-04/04-27-core-function-gap-check/prd.md

Core Function Gap Check

Goal

Check the current MZH Library Management implementation against the documented core modules and complete the highest-confidence missing core feature slice without broad redesign.

What I Already Know

• The user asked to check whether core functionality is still missing and to complete it.
• The app is a Java 11 Maven WAR using JSP + Servlet + MySQL and JDBC DAOs.
• Existing implemented slices cover login/permissions, dashboard navigation, book catalog/search, book CRUD, reader management, borrowing circulation, reader loan history, reports, administrator user management, and system-log viewing.
• Existing lightweight checks pass with javac -Xlint:all for non-Servlet layers and all service check mains.
• Maven is available in this workspace at /home/sjy/.sdkman/candidates/maven/current/bin/mvn.
• The clearest missing core requirement is book category maintenance. The schema and selectors already have book_categories, but there is no route, controller, JSP, DAO/service mutation API, or test coverage for maintaining categories.

Requirements

• Preserve the existing JSP -> Servlet -> Service -> DAO -> MySQL layering.
• Keep category maintenance under the existing MANAGE_BOOKS permission.
• Add a staff-only category management flow for listing, creating, editing, and deleting book categories.
• Validate required category name, name length, description length, duplicate names, and invalid IDs with field-level service errors.
• Prevent deleting categories that still have book records, returning a safe validation message instead of surfacing a database constraint failure.
• Reuse the existing book management visual patterns, flash messages, and table/form conventions.
• Link category maintenance from the book management surface and staff navigation where appropriate.
• Update focused service checks and fallback validation commands.

Acceptance Criteria

• A user with MANAGE_BOOKS can open a category management page.
• Staff can create and update category names/descriptions.
• Duplicate category names are rejected with a field error.
• Categories used by books cannot be deleted.
• Readers or unauthenticated users cannot mutate categories.
• Book forms/search continue to load categories from the shared DAO/service path.
• JSPs do not contain SQL/JDBC/scriptlet logic.
• Existing lightweight checks pass and Maven package succeeds through the workspace Maven path.

Definition of Done

• Tests/checks updated where practical.
• Lint/type-check/compile equivalent checks pass in this environment.
• Docs/notes updated if behavior changes.
• No broad framework or visual redesign.

Out of Scope

• Role/permission editor UI.
• Full database dump/restore execution from the web app.
• Audit logging expansion for every non-user operation.
• Automatic reader-account/profile linking changes.

Technical Notes

• Relevant specs: .trellis/spec/backend/index.md, .trellis/spec/backend/database-guidelines.md, .trellis/spec/backend/error-handling.md, .trellis/spec/backend/logging-guidelines.md, .trellis/spec/backend/quality-guidelines.md, .trellis/spec/frontend/index.md, .trellis/spec/frontend/component-guidelines.md, .trellis/spec/frontend/quality-guidelines.md.
• Current files most likely affected: BookDao, JdbcBookDao, BookService, BookServiceImpl, BookManagementServlet, web.xml, book JSPs, shared CSS, and BookServiceCheck.
• Initial verification before implementation: javac -Xlint:all over non-Servlet app layers and tests passed; all eight service check mains passed.
• Final verification after implementation: javac -Xlint:all over non-Servlet app layers and tests passed; PermissionPolicyCheck, AuthServiceCheck, BookServiceCheck, ReaderServiceCheck, BorrowingServiceCheck, ReportServiceCheck, UserAccountServiceCheck, and SystemLogServiceCheck passed; JSP/static scriptlet and SQL/JDBC scan returned no matches; git diff --check passed.
• Maven verification on 2026-04-27: /home/sjy/.sdkman/candidates/maven/current/bin/mvn clean package passed and produced target/library-management.war.