Book-management-system/.trellis/tasks/archive/2026-04/04-27-admin-user-management-system-logs/prd.md

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.