# Admin User Management And System Logs

## Goal

Implement the next administrator feature slice for the JSP + Servlet + MySQL library-management system: user/account management and system log viewing.

## What I already know

* The user asked to continue developing the program.
* The project is a Java 11 Maven WAR application using JSP + Servlet on Tomcat and MySQL through JDBC DAO classes.
* Existing implemented slices include login, role/permission checks, dashboard navigation, book catalog/search, book management, reader profile/eligibility management, borrowing circulation, reader loan history, overdue visibility, and a report center.
* Recent commits show the latest completed feature slices were borrowing circulation and the report center.
* Current routes include `/login`, `/logout`, `/dashboard`, role homes, `/catalog`, `/books`, `/readers`, `/borrowing`, `/reader/loans`, and `/reports`.
* The schema already defines `users`, `roles`, `permissions`, `role_permissions`, `system_logs`, `readers`, `book_categories`, `books`, and `borrow_records`.
* Permissions already include `manage_users` and `view_system_logs`, but there are no dedicated user-management or system-log UI/controller/service/DAO slices in the current codebase.
* The user asked whether user/account management and system-log viewing can be completed together; they are closely related administrator backend features and should be implemented in one task.

## Assumptions (temporary)

* The feature should build on the existing library-management roadmap rather than refactor unrelated infrastructure.
* User/account management and system logs should share the administrator area, navigation pattern, and authorization style where practical.

## Open Questions

* None blocking. MVP scope is locked to user/account management plus read-only system-log viewing.

## Requirements (evolving)

* Preserve the existing JSP -> Servlet -> Service -> DAO -> MySQL layering.
* Keep authorization consistent with `PermissionPolicy` and `AuthorizationFilter`.
* Reuse existing card, form, table, alert, and header patterns for JSP/CSS work.
* Add or update schema/data-access/service/controller/JSP pieces only for user/account management and system-log viewing.

### User / Account Management

* Administrators can open a user-management page from the administrator dashboard/header area.
* Administrators can list users with username, display name, role, active state, created time, and updated time.
* Administrators can search/filter users by keyword, role, and active state.
* Administrators can create user accounts for administrator, librarian, and reader roles.
* Account creation requires username, display name, role, active state, and password.
* Account update allows display name, role, active state, and password reset when a new password is provided.
* Usernames must be unique and normalized consistently with login behavior.
* Passwords must use the existing `PasswordHasher`; no plain-text password storage.
* Deactivation should be supported through the same user edit/update path or a clear action; physical deletion is out of scope.
* Reader-account creation does not need to automatically create or link a reader profile in this MVP. Existing reader profile management may continue to link by user id.
* Administrators should not accidentally lock out all administrator access. At minimum, block deactivating the currently logged-in administrator's own account and block changing their own role away from administrator.

### System Log Viewing

* Administrators can open a system-log page from the administrator dashboard/header area.
* System-log viewing is read-only in this MVP.
* Logs should show operator id/name when available, operation type, detail, IP address when available, and created time.
* Logs can be filtered by operation type, keyword, and date range when practical within existing schema.
* The newest logs should appear first.
* Empty and error states should use existing JSP alert/empty-state conventions.

### Audit Logging

* User-management create/update/deactivate actions should write system-log rows.
* Login/logout logging can remain as existing Java logger output unless implementing database audit logging is cheap and consistent.
* Log write failures should not make normal user-management operations appear successful if the business transaction depends on the log row; otherwise, keep behavior conservative and explain in code via service result/logging.

## Acceptance Criteria (evolving)

* [ ] Administrator can open user management from the admin area.
* [ ] Administrator can list, search, create, update, and deactivate user accounts.
* [ ] User create/update validation handles required fields, duplicate username, valid role, active state, and optional password reset.
* [ ] User passwords are hashed with the existing password hashing utility.
* [ ] The current administrator cannot deactivate their own account or change their own role away from administrator.
* [ ] Administrator can open read-only system logs from the admin area.
* [ ] System logs show newest entries first and support practical filtering.
* [ ] User-management changes create system-log entries.
* [ ] Routes are protected by `manage_users` / `view_system_logs` authorization as appropriate.
* [ ] Feature follows existing validation and `ServiceResult` behavior.
* [ ] Maven build/check commands pass where available.

## Definition of Done (team quality bar)

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

## Out of Scope (explicit)

* No unrelated visual redesign.
* No broad framework migration.
* No destructive database reset requirement.
* No role/permission editor UI.
* No automatic reader-profile creation/linking from user creation.
* No system-log deletion/export/retention policy.
* No password self-service or email reset workflow.

## Technical Notes

* `src/main/webapp/WEB-INF/web.xml` defines the current Servlet mappings.
* `src/main/resources/db/schema.sql` already contains user, permission, and system log tables.
* `src/main/java/com/mzh/library/entity/Permission.java` includes `MANAGE_USERS` and `VIEW_SYSTEM_LOGS`.
* `src/main/java/com/mzh/library/filter/AuthorizationFilter.java` maps `/admin` to `MANAGE_USERS`.
* `src/main/webapp/WEB-INF/jsp/dashboard.jsp` and `role-home.jsp` describe administrator account, role, permission, and system-maintenance entry points, but those are not fully implemented yet.