前端修复，日志功能加入

2026-04-28 18:26:28 +08:00
parent dc192e8223
commit cc32c222a4
35 changed files with 874 additions and 132 deletions
@@ -144,3 +144,74 @@ the server-side exception.
  <c:out value="${log.resultStatusName}" />
 </span>
 ```
+
+## Scenario: Login Diagnostic Logging
+
+### 1. Scope / Trigger
+
+- Trigger: Windows deployment login failures need server-side diagnostics across
+  `LoginServlet -> AuthServiceImpl -> JdbcUserDao -> JdbcUtil` without changing
+  the generic user-facing login messages.
+
+### 2. Signatures
+
+- Servlet route: `POST /login` with `username`, `password`, and optional
+  same-application `redirect`.
+- Service signature: `AuthService.authenticate(String username, String password)`.
+- DAO signature: `UserDao.findActiveByUsername(String username)`.
+- DB config keys: `db.driver`, `db.url`, `db.username`, and `db.password`.
+
+### 3. Contracts
+
+- Login request logs may include remote address, context path, redirect presence,
+  username presence/length, sanitized username, and whether normalization changed
+  the username.
+- Authentication logs must distinguish missing required fields, active user not
+  found, password mismatch, service error, and success.
+- JDBC logs must confirm `db.properties` loading, required key resolution,
+  connection attempts, successful connections, and driver/connection failures.
+- Logs must never include raw passwords, password hashes, salts, database
+  passwords, or unredacted password-like JDBC URL parameters.
+
+### 4. Validation & Error Matrix
+
+- Missing username or password -> log missing-field category and return the
+  existing required-field message.
+- Unknown or inactive username -> log `active-user-not-found` and return the
+  existing invalid-credentials message.
+- Existing user with bad password -> log `password-mismatch` and return the
+  existing invalid-credentials message.
+- Missing DB config or JDBC failure -> log server-side details with credentials
+  redacted and return the existing service-unavailable message.
+
+### 5. Good/Base/Bad Cases
+
+- Good: a failed login shows whether the request reached the servlet, whether
+  the username was normalized, whether the active user row was found, and
+  whether password verification failed.
+- Base: successful login keeps logging user ID and role only.
+- Bad: a diagnostic log writes `password`, `password_hash`, salt, or a JDBC URL
+  containing `password=secret`.
+
+### 6. Tests Required
+
+- Run `mvn test` or the documented Maven path to compile Servlet, service, DAO,
+  and utility code.
+- Scan changed logs for password/hash/salt/database-password output before
+  finishing.
+- Keep `AuthServiceCheck` behavior expectations unchanged for required fields,
+  invalid credentials, success, permission checks, and DAO failure fallback.
+
+### 7. Wrong vs Correct
+
+#### Wrong
+
+```java
+LOGGER.info("Login failed password=" + password + " hash=" + user.getPasswordHash());
+```
+
+#### Correct
+
+```java
+LOGGER.info("Login failed reason=password-mismatch userId=" + user.getId());
+```
@@ -20,6 +20,13 @@ the reusable UI units.
  application frame lives in `src/main/webapp/WEB-INF/jsp/common/header.jspf`
  and owns the dark sidebar, top utility bar, role workbench links, module
  navigation, global search, user display, and logout link.
+- Any `.jspf` fragment that contains user-visible Simplified Chinese text must
+  declare `<%@ page pageEncoding="UTF-8" %>` at the top. Do not rely only on the
+  including JSP page or response `Content-Type`; Tomcat/Jasper can otherwise
+  compile the fragment with a non-UTF-8 default and render mojibake.
+- JSP-rendered HTML responses must be served as `text/html;charset=UTF-8` by
+  the encoding filter or the JSP page directive. Request/response character
+  encoding alone is not enough for browsers to decode Simplified Chinese safely.
 - Preserve role-conditioned navigation in that shared frame: administrator-only
  links stay inside `sessionScope.userRole == 'administrator'`; staff links stay
  inside `administrator or librarian`; reader-only links stay inside
@@ -0,0 +1,4 @@
+{"file": ".trellis/spec/backend/index.md", "reason": "Check backend architecture boundaries for login diagnostics."}
+{"file": ".trellis/spec/backend/logging-guidelines.md", "reason": "Verify logs avoid passwords, hashes, salts, and credentials while remaining useful."}
+{"file": ".trellis/spec/backend/database-guidelines.md", "reason": "Verify login/authentication and database config contracts remain intact."}
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "Verify Maven checks and backend quality expectations."}
@@ -0,0 +1,4 @@
+{"file": ".trellis/spec/backend/index.md", "reason": "Backend Servlet/JSP/JDBC architecture context for login diagnostics."}
+{"file": ".trellis/spec/backend/logging-guidelines.md", "reason": "Logging safety rules, sensitive-data redaction, and diagnostic expectations."}
+{"file": ".trellis/spec/backend/database-guidelines.md", "reason": "Login/authentication and database configuration contracts."}
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "Backend quality and Maven verification requirements."}
@@ -0,0 +1,70 @@
+# Add Windows Login Diagnostic Logs
+
+## Goal
+
+Add safe server-side diagnostic logs to the login/authentication path so a Windows-built deployment that returns `用户名或密码不正确。` can be diagnosed without exposing passwords, password hashes, or database credentials.
+
+## What I Already Know
+
+* The previous frontend rebuild task is solved and has been archived.
+* On the Windows system build, login now reaches the invalid-credentials path: `用户名或密码不正确。`
+* The user believes the database connection is probably already working.
+* Existing login flow is `LoginServlet` -> `AuthServiceImpl` -> `JdbcUserDao.findActiveByUsername` -> `JdbcUtil`.
+* `AuthServiceImpl` currently logs only generic login failure/success/service-error messages.
+* Existing backend specs require login failures to keep the same generic user-facing message and to log server-side details for unavailable services.
+
+## Requirements
+
+* Add diagnostic logging around login POST handling, authentication lookup, password verification outcome, and database configuration/connection attempts.
+* Logs must help distinguish:
+  * request reached `LoginServlet`;
+  * username normalization changed the submitted username;
+  * active user row was not found;
+  * user row was found but password verification failed;
+  * database configuration was loaded and which JDBC URL/user key were used, with secrets redacted;
+  * JDBC driver/connection failures if they happen.
+* Do not log raw passwords, password hashes, salts, database passwords, or full sensitive config values.
+* Preserve the current user-facing Chinese error message and login behavior.
+* Keep the implementation in the existing Servlet + service + DAO + JDBC stack.
+* Prefer `java.util.logging` patterns already used in the project.
+
+## Acceptance Criteria
+
+* [x] Login failure logs identify whether the username was absent, not found, or found with password mismatch.
+* [x] Login request logs include safe request diagnostics such as remote address, context path, redirect presence, and submitted username length or sanitized username.
+* [x] Database logs confirm `db.properties` loading and JDBC connection attempts with password redacted.
+* [x] No log statement outputs a raw password, password hash, salt, or database password.
+* [x] Existing login success/failure behavior remains unchanged for users.
+* [x] `mvn test` or the closest available Maven verification command succeeds.
+
+## Definition Of Done
+
+* Diagnostic logging implemented in source.
+* Maven verification run and results reported.
+* No database schema changes.
+* No unrelated frontend/layout changes.
+
+## Out Of Scope
+
+* Changing password hashing rules or seed user credentials.
+* Adding a new logging framework.
+* Changing database schema or production credentials.
+* Reworking the login UI.
+* Committing generated build artifacts.
+
+## Technical Notes
+
+* Likely impacted files:
+  * `src/main/java/com/mzh/library/controller/LoginServlet.java`
+  * `src/main/java/com/mzh/library/service/impl/AuthServiceImpl.java`
+  * `src/main/java/com/mzh/library/dao/impl/JdbcUserDao.java`
+  * `src/main/java/com/mzh/library/util/JdbcUtil.java`
+* Relevant specs:
+  * `.trellis/spec/backend/logging-guidelines.md`
+  * `.trellis/spec/backend/database-guidelines.md`
+  * `.trellis/spec/backend/quality-guidelines.md`
+* Verification completed at 2026-04-28 18:22 +0800:
+  * `/home/sjy/.sdkman/candidates/maven/current/bin/mvn test` passed with `BUILD SUCCESS`.
+  * `/home/sjy/.sdkman/candidates/maven/current/bin/mvn package` passed with `BUILD SUCCESS` and produced `target/library-management.war`.
+  * `git diff --check` passed.
+  * Sensitive logger scan only found boolean password state fields, `password=<redacted>`, and `password-mismatch` category labels.
@@ -0,0 +1,26 @@
+{
+  "id": "windows-login-diagnostic-logs",
+  "name": "windows-login-diagnostic-logs",
+  "title": "Add Windows login diagnostic logs",
+  "description": "",
+  "status": "in_progress",
+  "dev_type": null,
+  "scope": null,
+  "package": null,
+  "priority": "P2",
+  "creator": "Zzzz",
+  "assignee": "Zzzz",
+  "createdAt": "2026-04-28",
+  "completedAt": null,
+  "branch": null,
+  "base_branch": "master",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
@@ -0,0 +1,6 @@
+{"file": ".trellis/spec/frontend/index.md", "reason": "Frontend checklist for reviewing JSP/CSS presentation changes."}
+{"file": ".trellis/spec/frontend/component-guidelines.md", "reason": "Verify shared frame role navigation and Simplified Chinese copy remain correct."}
+{"file": ".trellis/spec/frontend/quality-guidelines.md", "reason": "Verify layout, accessibility basics, and no obvious overlap/clipping."}
+{"file": ".trellis/spec/backend/index.md", "reason": "Verify encoding changes remain within Servlet/JSP architecture."}
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "Verify layer boundaries and Maven build/test expectations."}
+{"file": ".trellis/tasks/archive/2026-04/00-bootstrap-guidelines/research/project-requirements.md", "reason": "Confirm the change preserves the agreed JSP + Servlet + Tomcat stack."}
@@ -0,0 +1,7 @@
+{"file": ".trellis/spec/frontend/index.md", "reason": "Frontend JSP/CSS presentation conventions and checklist for authenticated UI work."}
+{"file": ".trellis/spec/frontend/directory-structure.md", "reason": "JSP fragment and static asset placement constraints."}
+{"file": ".trellis/spec/frontend/component-guidelines.md", "reason": "Shared header/sidebar fragment rules, role-conditioned navigation, and Simplified Chinese copy requirements."}
+{"file": ".trellis/spec/frontend/quality-guidelines.md", "reason": "UI quality checks for JSP/CSS layout, accessibility basics, and visual consistency."}
+{"file": ".trellis/spec/backend/index.md", "reason": "Servlet/JSP/Tomcat architecture context for the encoding filter change."}
+{"file": ".trellis/spec/backend/quality-guidelines.md", "reason": "Layer-boundary and Maven verification requirements for backend-adjacent changes."}
+{"file": ".trellis/tasks/archive/2026-04/00-bootstrap-guidelines/research/project-requirements.md", "reason": "Original project stack and presentation-layer requirements."}
@@ -0,0 +1,83 @@
+# 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`.
@@ -0,0 +1,26 @@
+{
+  "id": "04-28-rebuild-current-frontend",
+  "name": "04-28-rebuild-current-frontend",
+  "title": "rebuild and redeploy current frontend",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "package": null,
+  "priority": "P2",
+  "creator": "Zzzz",
+  "assignee": "Zzzz",
+  "createdAt": "2026-04-28",
+  "completedAt": "2026-04-28",
+  "branch": null,
+  "base_branch": "master",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}