Book-management-system/.trellis/tasks/04-28-sidebar-layout-management-ux/prd.md

Sidebar Active State And Management UX Cleanup

Goal

Fix several visible JSP/CSS navigation and layout issues in the authenticated library-management UI, and reduce confusion between reader profile management and user account management without changing the backend data model.

What I Already Know

• The application is a Java 11 Maven WAR using JSP, Servlet, JSTL, CSS, and Tomcat.
• Authenticated navigation lives in src/main/webapp/WEB-INF/jsp/common/header.jspf.
• Sidebar active state currently uses fn:contains(currentUri, ...), but rendered JSP paths can differ from public servlet paths after RequestDispatcher.forward.
• This explains reported false positives and false negatives:
  • /catalog can render through /WEB-INF/jsp/books/catalog.jsp, causing the books nav item to look active.
  • /book-categories renders through /WEB-INF/jsp/books/categories.jsp, causing books to look active while categories may not.
  • /reports renders reports/dashboard.jsp, which can make dashboard/workbench look active.
  • /admin/system-logs renders maintenance/system-logs.jsp, so the system log item may not activate.
• The catalog, book management, and reader management hero sections put eyebrow/title/body/actions directly under a flex container; pages that wrap text in a child <div> avoid the horizontal layout break.
• dashboard.jsp contains the small technical sentence the user wants removed.
• ReaderManagementServlet manages reader profiles/eligibility/contact/borrowing limits; UserManagementServlet manages login accounts/roles/active status. These are overlapping concepts to users but distinct backend workflows.

Requirements

• Sidebar active state must be based on the original public servlet path, not the forwarded JSP path.
• Only the matching sidebar item should be active for catalog, books, book categories, reports, and system logs.
• Remove the sidebar "角色工作台" block.
• Remove the sidebar "工作台" nav item.
• Move "报表中心" to the top of the main module navigation for administrator/librarian roles.
• Fix the header/hero layout on catalog, book management, and reader management so eyebrow/title/description stay grouped vertically.
• Remove the dashboard sentence: 登录后进入 Dashboard，会话仅保存安全的 AuthenticatedUser 快照、角色代码与权限代码集合。
• Reduce the perceived duplication between reader management and user management using conservative UI changes:
  • Treat reader management as reader profile/borrowing eligibility management.
  • Treat user management as account/role/login status management.
  • Prefer clearer labels, descriptions, and cross-links over merging backend flows.

Acceptance Criteria

• Opening /catalog highlights only "馆藏检索".
• Opening /books highlights only "图书管理".
• Opening /book-categories highlights only "图书分类管理".
• Opening /reports highlights only "报表中心" and does not highlight "工作台".
• Opening /admin/system-logs highlights "系统日志".
• The sidebar no longer displays the role workbench cards or a "工作台" nav item.
• "报表中心" appears before catalog/books/readers/borrowing for administrator/librarian navigation.
• Catalog, book management, and reader management hero copy is vertically grouped and does not lay out as separate horizontal items.
• The dashboard technical session sentence is absent.
• Reader/user management labels and descriptions make the distinction between reader profiles and user accounts clearer.
• Maven verification passes or the closest available build command is reported.

Definition Of Done

• Focused JSP/CSS changes only unless a backend change is required by verification.
• Existing Servlet/JSP rendering and JSTL escaping behavior remains intact.
• Maven build/test verification run where available.
• Trellis quality check completed before final response.

Technical Approach

• In header.jspf, derive a currentPath from requestScope['javax.servlet.forward.servlet_path'] with a fallback to pageContext.request.servletPath.
• Replace broad fn:contains checks with exact or prefix checks against public servlet paths.
• Reorder and trim sidebar markup according to the requested information architecture.
• Wrap catalog/book/reader hero text in a child <div> to match pages that already render correctly.
• Remove only the requested dashboard small text, leaving role-specific workbench headings and metrics intact.
• Use copy changes and cross-links to clarify reader profiles versus user accounts without changing controllers, entities, DAOs, or database schema.

Out Of Scope

• Merging reader and user management into a single page.
• Changing authentication, authorization, database schema, or service-layer behavior.
• Redesigning the whole dashboard or adding new frontend libraries.

Technical Notes

• Relevant frontend spec index: .trellis/spec/frontend/index.md.
• Relevant files inspected:
  • src/main/webapp/WEB-INF/jsp/common/header.jspf
  • src/main/webapp/WEB-INF/jsp/dashboard.jsp
  • src/main/webapp/WEB-INF/jsp/books/catalog.jsp
  • src/main/webapp/WEB-INF/jsp/books/manage.jsp
  • src/main/webapp/WEB-INF/jsp/books/categories.jsp
  • src/main/webapp/WEB-INF/jsp/readers/manage.jsp
  • src/main/webapp/WEB-INF/jsp/admin/users/manage.jsp
  • src/main/webapp/static/css/app.css
• Build command from README: mvn clean package; fallback path documented as /home/sjy/.sdkman/candidates/maven/current/bin/mvn clean package if mvn is not on PATH.
• Verification on 2026-04-28:
  • git diff --check passed.
  • Search for removed sidebar role/workbench and old active-state patterns returned no matches.
  • /home/sjy/.sdkman/candidates/maven/current/bin/mvn clean package passed with BUILD SUCCESS.