Book-management-system/.trellis/tasks/archive/2026-04/04-27-continue-development/prd.md

Borrowing circulation management

Goal

Implement the next core library-management slice: borrowing circulation for borrow, return, renew, overdue visibility, and reader loan history.

What I already know

• The project is a Java 11 Maven WAR application using JSP + Servlet on Tomcat and MySQL through JDBC DAO classes.
• Existing implemented slices cover login, role/permission checks, dashboard navigation, book catalog/search, book management, and reader profile/eligibility management.
• Current routes include /login, /logout, /dashboard, role homes, /catalog, /books, and /readers.
• The schema already defines roles, permissions, role permissions, users, system logs, readers, book categories, and books.
• Permissions already include manage_borrowing and borrow_books.
• Dashboard copy mentions borrowing, return, renewal, and overdue workflows, but there are no borrowing tables, Servlet routes, JSP pages, DAO classes, services, or tests for that workflow yet.
• The user selected borrowing circulation as the next feature slice.
• AuthorizationFilter currently protects /librarian/** with MANAGE_BORROWING and /reader/** with VIEW_CATALOG.
• PermissionPolicy grants MANAGE_BORROWING to administrators and librarians, and BORROW_BOOKS to readers.

Scope

• Administrators and librarians can manage circulation records from a borrowing management screen.
• Readers can view their own borrowing records from the reader area when their account is linked to a reader profile.
• Borrowing workflow covers borrow, return, renew, active loans, returned loans, and overdue loans.
• Overdue handling should be visible in lists and service results; no background scheduler is required for this task.
• The implementation should preserve the existing Servlet -> Service -> DAO boundary and JSP view style.

Requirements

Persistence

• Add a borrowing/loan table to src/main/resources/db/schema.sql.
• Store the borrowing record id, reader id, book id, borrow date/time, due date/time, optional return date/time, renewal count, status, and timestamps.
• Relate borrowing rows to readers and books with foreign keys.
• Add useful indexes for reader, book, status, and due date lookups.
• Keep seed data safe and optional; do not require destructive schema resets.

Business Rules

• Borrowing a book requires an active reader.
• Borrowing a book requires the book status to allow borrowing and available_copies > 0.
• Borrowing must reject readers at or above max_borrow_count for active, non-returned loans.
• Successful borrowing creates a borrowing record and decrements books.available_copies.
• Returning an active loan marks it returned, records the return time, and increments books.available_copies without exceeding total_copies.
• Renewing an active loan extends the due date and increments the renewal count.
• Renewal should be limited to a small, explicit maximum, preferably one renewal per loan for this MVP.
• Overdue records are records not returned by their due date. They should be searchable or filterable.
• Service methods should return ServiceResult style validation errors instead of throwing user-facing exceptions for normal validation failures.

Backend

• Add entity, DAO, JDBC DAO, service, and service implementation classes for borrowing circulation.
• Add Servlet routes for borrowing management under an administrator/librarian-accessible path such as /borrowing, /borrowing/new, /borrowing/create, /borrowing/return, and /borrowing/renew.
• Add a reader-facing route for own borrowing records under the existing reader area or another path protected appropriately.
• Update web.xml and authorization rules as needed.
• Keep transaction-sensitive borrow/return/renew operations consistent. If the existing JDBC helper does not provide transactions, implement the smallest safe local transaction pattern needed for multi-table updates.

Frontend

• Add JSP pages for borrowing list/history and the borrow form.
• Add navigation entries from dashboard, role home, and header where appropriate.
• Keep the UI consistent with existing card, table, form, alert, and button patterns.
• Show clear success and validation messages for borrow, return, and renew actions.
• Lists should show reader identifier/name, book identifier/title, borrow date, due date, return date when present, renewal count, and status.

Tests

• Add or update service-level check classes for borrowing rules.
• Update permission tests if new path/permission logic changes.
• Build with Maven after implementation if Maven is available.

Acceptance Criteria

• Administrator/librarian can open a borrowing management page.
• Administrator/librarian can create a valid borrowing record by selecting or entering an existing active reader and borrowable book.
• Borrowing decrements available copies and blocks unavailable books.
• Borrowing blocks inactive/suspended readers and readers over their max active borrowing count.
• Administrator/librarian can return an active loan; the book copy count is restored.
• Administrator/librarian can renew an active loan within the configured renewal limit.
• Borrowing lists can distinguish active, returned, and overdue records.
• Reader can view their own borrowing records when logged in with a linked reader profile.
• Relevant service checks pass.
• Maven build/check commands pass where available.

Definition of Done

• Tests added/updated where appropriate.
• Lint/typecheck/build checks are green.
• Docs/notes updated if behavior changes.
• Rollback considered if risky.

Out of Scope (explicit)

• Reader self-service borrow requests/reservations are not part of this MVP.
• Email/SMS notifications are out of scope.
• Fine calculation/payment is out of scope.
• Background jobs/schedulers are out of scope.
• Full reports/rankings remain out of scope.
• No unrelated refactors or visual redesigns.

Technical Notes

• README.md confirms implemented scaffold slices and project stack.
• src/main/webapp/WEB-INF/web.xml defines current Servlet mappings.
• src/main/resources/db/schema.sql has no borrowing/loan table yet.
• src/main/webapp/WEB-INF/jsp/dashboard.jsp and role-home.jsp already refer to borrowing workflows in UI copy.
• src/main/java/com/mzh/library/entity/Permission.java already defines MANAGE_BORROWING and BORROW_BOOKS.
• src/main/java/com/mzh/library/filter/AuthorizationFilter.java may need a /borrowing rule mapped to MANAGE_BORROWING and reader borrowing history should not expose other readers' records.
• The local codebase-retrieval MCP call was rejected by the approval layer, so context was gathered from targeted repo file reads instead.