Zzzz
109 lines
6.6 KiB
Markdown
109 lines
6.6 KiB
Markdown
# 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.
|