Book-management-system/.trellis/tasks/archive/2026-04/04-28-04-28-rebuild-current-frontend/prd.md

# Fix Frontend Encoding And Layout

## Goal

Fix the authenticated JSP frontend so Simplified Chinese text renders correctly in the browser, then refine the shared application frame and dashboard layout so navigation, role workbench links, search, user identity, and page content look coordinated at common desktop and mobile widths.

## What I Already Know

* The user wants to view the actual frontend UI after the frontend refactor.
* The running Tomcat application appears to show the pre-refactor UI.
* The project is a Java 11 Maven WAR application.
* Maven produces `target/library-management.war`.
* Frontend assets and JSPs live under `src/main/webapp`.
* Local Tomcat path is `/home/sjy/apps/tomcat/apache-tomcat-9.0.117/apache-tomcat-9.0.117`.
* Local MySQL is running at `127.0.0.1:3306`.
* The user now sees severe mojibake such as `书 图书管理系统`, which is UTF-8 Chinese content being decoded as a non-UTF-8 encoding.
* The visible broken area is the authenticated shell: sidebar brand, role workbench, module navigation, topbar search, notification, user pill, and role label.
* JSP pages already declare `contentType="text/html;charset=UTF-8"` and `<meta charset="UTF-8">`; `CharacterEncodingFilter` currently sets request/response character encoding but does not force an HTML content type.
* Follow-up user screenshot shows the authenticated shell still renders as ordinary document-flow text: the dark fixed sidebar is missing, the topbar is loose, and the dashboard metric cards collapse into a vertical text column. HTML and CSS endpoint checks alone are not sufficient.

## Requirements

* Ensure every JSP-rendered HTML response is explicitly served as UTF-8 so Chinese labels, placeholders, headings, and role names do not render as mojibake.
* Preserve the JSP + Servlet + CSS stack; do not introduce a frontend framework.
* Keep all user-facing JSP copy in Simplified Chinese.
* Refine the shared authenticated frame in `header.jspf`/CSS:
  * Sidebar brand and role workbench should be readable and not visually crowded.
  * Navigation links should align consistently and avoid repeated glyph/text collisions.
  * Topbar search, notification, user display, and role label should fit without overlap.
* Refine dashboard layout in CSS so metric cards, search/ranking panels, tables, and shortcut cards have balanced spacing and degrade cleanly on narrower viewports.
* Rebuild and redeploy the WAR to the local Tomcat instance after source changes.
* Verify `/library-management/login` is reachable and a known login reaches `/library-management/dashboard`.
* Verify the dashboard HTML/headers indicate UTF-8 and the rendered shell text is readable Chinese.
* Verify the rendered page visually in a browser at desktop width:
  * A dark fixed left sidebar must be visible.
  * The topbar must start to the right of the sidebar and align search/user controls.
  * Dashboard content must start below the topbar and to the right of the sidebar.
  * Metrics must render as cards in a grid on desktop, not as plain vertical text.
  * No overlapping, no unstyled header text, and no horizontal crowding at 1920px-wide desktop.

## Acceptance Criteria

* [x] `mvn clean package` succeeds after the frontend/encoding changes.
* [x] Tomcat `webapps/library-management.war` is refreshed from `target/library-management.war`.
* [x] Old expanded deployment directory is removed before restart.
* [x] Tomcat listens on port `8080`.
* [x] `/library-management/login` returns HTTP 200.
* [x] `admin/admin123` login redirects to `/library-management/dashboard`.
* [x] Authenticated dashboard response uses UTF-8 and no longer displays mojibake for Chinese UI text.
* [ ] Sidebar, role chips, topbar search/actions, dashboard panels, and responsive layout avoid obvious overlap, clipping, duplicated visual noise, and unstyled document-flow rendering in an actual browser screenshot.

## Definition Of Done

* Encoding fix implemented in source.
* Layout refinement implemented in JSP/CSS source.
* Rebuild and deploy completed.
* Verification results reported to the user.
* No database schema changes or unrelated backend behavior changes.

## Out Of Scope

* Replacing the JSP/CSS frontend with React, Vue, or another SPA framework.
* Changing database schema or seed data.
* Committing build artifacts.
* Reworking business workflows beyond what is needed to render the current pages correctly.

## Technical Notes

* Build command from README: `/home/sjy/.sdkman/candidates/maven/current/bin/mvn clean package` if `mvn` is unavailable.
* Deployment target: `/home/sjy/apps/tomcat/apache-tomcat-9.0.117/apache-tomcat-9.0.117/webapps/library-management.war`.
* Rebuild completed at 2026-04-28 16:55 +0800; deployed WAR size is 4,489,937 bytes.
* Previous deployment was moved to `/home/sjy/apps/tomcat/apache-tomcat-9.0.117/apache-tomcat-9.0.117/deploy-backups/_pre-rebuild-20260428-1656/`.
* Deployed `static/css/app.css` is byte-for-byte identical to `src/main/webapp/static/css/app.css`.
* Likely impacted files from inspection:
  * `src/main/java/com/mzh/library/filter/CharacterEncodingFilter.java`
  * `src/main/webapp/WEB-INF/jsp/common/header.jspf`
  * `src/main/webapp/WEB-INF/jsp/dashboard.jsp`
  * `src/main/webapp/static/css/app.css`
* Final verification completed at 2026-04-28 17:34 +0800:
  * `/library-management/login` returns `200` with `Content-Type: text/html;charset=UTF-8`.
  * `admin/admin123` login reaches `/library-management/dashboard` with UTF-8 content.
  * Dashboard HTML contains readable Chinese markers including `图书管理系统`, `角色工作台`, `管理员工作台`, `馆藏检索`, `用户管理`, `系统日志`, and `退出登录`.
* Follow-up visual regression reported after that verification: screenshot shows the authenticated shell unstyled at desktop width despite readable Chinese. Future verification must include a browser screenshot or equivalent computed-style/layout assertion, not only `curl`.