# 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.