# brainstorm: 继续完成程序

## Goal

Continue the MZH Library Management system from the current scaffold by implementing the next focused business slice after login/permission and book catalog/management: reader information management.

## What I already know

* User asked to "继续完成程序" without specifying the next target module.
* The project is a Java 11 Maven WAR application using JSP, Servlet, Tomcat, MySQL, and JDBC DAOs.
* Current code includes login/logout, authentication and authorization filters, role-aware dashboard/home pages, book catalog search, and administrator/librarian book management.
* The previous completed task explicitly left reader profile management, borrowing/returning/renewing/overdue handling, and full reports/statistics out of scope.
* Project requirements list these remaining core modules:
  * Reader information management for profiles, borrowing eligibility, and contact information.
  * Borrowing and return management for borrow, return, renew, overdue handling, and automatic collection status updates.
  * Book search/statistics for borrowing rankings, inventory reports, and overdue reports.
  * System maintenance/logs for key operation logs, backup support, and exception tracing.
* Existing permissions already include `manage_readers`, `manage_borrowing`, `view_reports`, `view_system_logs`, and `borrow_books`.
* Existing database schema already includes users, roles, permissions, system logs, book categories, and books.
* User selected option 1: reader information management.

## Assumptions (temporary)

* The next slice should stay consistent with the existing layered structure: JSP/CSS presentation -> Servlet controller -> Service -> DAO -> MySQL.
* The work should remain small enough to implement and verify in one Trellis task.
* The next module should build on the completed book and permission foundation instead of redesigning the application.

## Open Questions

* None currently blocking. Default scope is administrator/librarian reader profile management.

## Requirements (evolving)

* Preserve existing login, role permission, dashboard, catalog, and book-management behavior.
* Implement reader information management for reader profiles, contact information, borrowing eligibility, and borrowing limits.
* Add a `readers` table to `src/main/resources/db/schema.sql`, linked to reader users when applicable.
* Support listing/searching readers by reader identifier, name, phone/email, and status.
* Provide administrator/librarian reader-management actions for creating, editing, and deleting or deactivating reader profiles.
* Track eligibility/status fields needed for later borrowing work, such as active/suspended status and max borrow count.
* Link reader management from the existing dashboard or role workspace for users with `MANAGE_READERS`.
* Protect reader-management routes with `MANAGE_READERS`; normal readers must not access management screens.
* Add or update database schema, DAO, service, servlet, JSP, and checks for the selected slice.
* Keep protected workflows guarded by the existing permission model.
* Add focused checks for service rules that can run without Tomcat.

## Acceptance Criteria (evolving)

* [x] Administrators and librarians can reach reader management pages and create, edit, and delete or deactivate reader profiles.
* [x] Reader profiles persist and load through DAO/service layers, not directly from JSPs.
* [x] Reader search supports reader identifier, name, contact fields, and status.
* [x] Readers cannot reach reader-management write or list actions.
* [x] Invalid identifier, name, contact, status, and borrow-limit values return clear user-facing errors.
* [x] Existing completed workflows continue to compile and pass checks.
* [x] Local compile/test checks pass or blockers are documented.

## Definition of Done (team quality bar)

* Tests added/updated where appropriate.
* Lint / typecheck / compile checks green where available.
* Docs/notes updated if behavior changes.
* Rollout/rollback considered if risky.

## Out of Scope (explicit)

* Replacing JSP/Servlet with another framework.
* Production deployment automation.
* Large visual redesign unrelated to the selected workflow.
* Implementing every remaining module in one task.
* Borrowing, returning, renewing, overdue handling, and borrowing statistics.
* Full reader self-service profile editing.

## Technical Approach

Use the same layered pattern established by the book module:

* `readers` schema and demo reader data in `src/main/resources/db/schema.sql`.
* Reader entity/search criteria, DAO, JDBC DAO, service interface, and service implementation.
* A `ReaderManagementServlet` mapped to `/readers`, `/readers/new`, `/readers/edit`, `/readers/update`, and `/readers/delete` or equivalent.
* JSPs under `WEB-INF/jsp/readers/` for list/search and form workflows.
* Service-level checks for validation, permission denial, duplicate identifiers, DAO failure fallback, and successful CRUD-like operations.

## Decision (ADR-lite)

**Context**: The project already has authentication, permissions, catalog search, and book management. Borrowing workflows need reader profile and eligibility data before they can be implemented cleanly.

**Decision**: Implement reader information management as the next focused slice.

**Consequences**: This adds the reader data foundation needed for future borrow/return/renew modules while keeping borrowing workflows and reports out of scope for this task.

## Technical Notes

* Current task directory: `.trellis/tasks/04-27-continue-program`.
* Relevant previous task: `.trellis/tasks/archive/2026-04/04-27-continue-improve-program/prd.md`.
* Project requirements source: `.trellis/tasks/archive/2026-04/00-bootstrap-guidelines/research/project-requirements.md`.
* Spec indexes available:
  * `.trellis/spec/backend/index.md`
  * `.trellis/spec/frontend/index.md`
* File inventory inspected:
  * `README.md`
  * `pom.xml`
  * `src/main/resources/db/schema.sql`
  * `src/main/webapp/WEB-INF/web.xml`
  * `src/main/webapp/WEB-INF/jsp/dashboard.jsp`
  * `src/main/webapp/WEB-INF/jsp/role-home.jsp`
  * `src/main/java/com/mzh/library/filter/AuthorizationFilter.java`
  * `src/main/java/com/mzh/library/entity/Permission.java`
  * Existing book/auth service and check classes under `src/main/java` and `src/test/java`.
* Reader-management implementation should reuse:
  * `Permission.MANAGE_READERS`
  * Existing service result and DAO exception patterns
  * Existing book-module controller/JSP/check structure as the closest local pattern
* Final verification notes:
  * `trellis-implement` completed the reader-management slice across schema, DAO, service, servlet, JSP, CSS, README, spec, and checks.
  * `trellis-check` fixed a phone-validation gap and added service assertions for missing contact, symbol-only phone, and DAO fallback on write paths.
  * Available fallback Java compile and service checks passed.
  * `mvn clean package` remains blocked because Maven is not installed in this environment and local servlet/JSTL jars were not available.