前端优化

2026-04-28 19:26:08 +08:00
parent 36db197e75
commit 0a386b81f9
10 changed files with 607 additions and 424 deletions
@@ -45,6 +45,9 @@ image-first design and preserve the Servlet/JSP layered architecture.
 - Do not implement UI only from text descriptions when an approved image
  reference exists.
 - Do not put SQL, DAO calls, or business workflows in JSP pages.
+- Do not hard-code operational dashboard/report metrics, sample people, fixed
+  borrow dates, or fake table rows in JSP pages; use Servlet-provided request
+  attributes and empty states.
 - Do not rely only on browser validation for protected workflows.

 ---
@@ -36,6 +36,100 @@ changes the frontend architecture.

 ---

+## Scenario: Dashboard Workbench Request Contract
+
+### 1. Scope / Trigger
+
+- Trigger: the authenticated workbench spans Servlet request attributes,
+  service-derived report/catalog/borrowing data, and role-specific JSP display.
+- Route: `GET /dashboard`.
+- JSP path: `WEB-INF/jsp/dashboard.jsp`.
+
+### 2. Signatures
+
+- Servlet: `DashboardServlet.doGet(HttpServletRequest, HttpServletResponse)`.
+- Services used for page data:
+  - `BookService.listCategories()`.
+  - `BookService.searchBooks(new BookSearchCriteria())`.
+  - `ReaderService.searchReaders(new ReaderSearchCriteria())` for staff reader
+    totals.
+  - `ReportService.loadReportCenter(AuthenticatedUser actor)` for
+    administrator/librarian users.
+  - `BorrowingService.searchRecords(actor, new BorrowRecordSearchCriteria())`
+    for administrator/librarian users.
+- Request attributes:
+  - `currentUser: AuthenticatedUser`.
+  - `categories: List<BookCategory>`.
+  - `dashboardBooks: List<Book>`.
+  - `dashboardMetrics: List<DashboardMetric>`.
+  - `reportCenter: ReportCenter` for staff users when report loading succeeds.
+  - `dashboardBorrowRecords: List<BorrowRecord>` for staff users.
+  - `errorMessage: String` when a service returns a safe failure.
+
+### 3. Contracts
+
+- Workbench values must come from request attributes populated by the Servlet;
+  JSP must not embed operational sample rows, fixed dates, or fake totals.
+- Staff metrics use `ReportCenter` values derived from `books` and
+  `borrow_records`, plus reader totals from `ReaderService`; reader fallback
+  metrics may derive from `dashboardBooks`.
+- Popular ranking, overdue rows, and borrowing rows render only real service
+  results and show empty states when lists are empty.
+- Category filters render from `categories`, the same source used by catalog and
+  book-management pages.
+- Role-gated sections stay in JSP conditionals based on `sessionScope.userRole`;
+  staff-only data is not requested for reader users.
+
+### 4. Validation & Error Matrix
+
+- Category load failure -> `categories` is an empty list and `errorMessage` is
+  set.
+- Book search failure -> `dashboardBooks` is an empty list and `errorMessage`
+  is set.
+- Reader total load failure -> staff metrics fall back to another real
+  service-derived metric and `errorMessage` is set.
+- Staff report load failure -> report-backed sections show empty states and
+  `errorMessage` is set.
+- Staff borrowing search failure -> `dashboardBorrowRecords` is an empty list
+  and `errorMessage` is set.
+- Empty service result -> render a stable empty state, not hard-coded fallback
+  sample data.
+
+### 5. Good/Base/Bad Cases
+
+- Good: a librarian opens `/dashboard` and sees report-backed metrics, current
+  borrowing rows, overdue rows, popular ranking, and real book rows.
+- Base: no borrow records exist; the workbench keeps the layout and shows empty
+  states for ranking, borrowing, and overdue panels.
+- Bad: `dashboard.jsp` contains names, book IDs, 2024 dates, or counts that do
+  not come from request attributes.
+
+### 6. Tests Required
+
+- Run Maven compile/test for Servlet and JavaBean contract checks.
+- Run standalone service checks covering report, borrowing, catalog/book, and
+  permission policy behavior when available.
+- Scan `dashboard.jsp` for static sample names, fixed dates, and decorative
+  sample-only values after dashboard changes.
+- Verify staff and reader role conditionals still show only the intended
+  sections.
+
+### 7. Wrong vs Correct
+
+#### Wrong
+
+```text
+dashboard.jsp -> hard-coded metric "12,586" and fixed rows like "L20240521001"
+```
+
+#### Correct
+
+```text
+dashboard.jsp <- DashboardServlet <- ReportService/BookService/ReaderService/BorrowingService
+```
+
+---
+
 ## Page Scripts

 Small JavaScript can improve interaction, such as confirm dialogs or local form