维护入口

2026-04-27 23:38:19 +08:00
parent 4155d5b1ea
commit 63738f108a
21 changed files with 1009 additions and 8 deletions
@@ -190,6 +190,95 @@ books/form.jsp -> JDBC -> INSERT INTO books using request parameters
 books/form.jsp -> BookManagementServlet -> BookService -> BookDao -> books
 ```

+## Scenario: Book Category Maintenance Slice
+
+### 1. Scope / Trigger
+
+- Trigger: category maintenance completes the book-management core requirement
+  by adding staff-managed CRUD for `book_categories`, while existing book forms
+  and catalog searches continue to consume the same category source.
+- Schema path: `src/main/resources/db/schema.sql`.
+- JSP paths: `WEB-INF/jsp/books/categories.jsp` and
+  `WEB-INF/jsp/books/category-form.jsp`.
+
+### 2. Signatures
+
+- DAO signatures: `BookDao.findAllCategories()`, `findCategoryById(long id)`,
+  `findCategoryByName(String name)`, `createCategory(BookCategory category)`,
+  `updateCategory(BookCategory category)`, `deleteCategory(long id)`, and
+  `countBooksByCategoryId(long categoryId)`.
+- Entity signature: `BookCategory(id, name, description)`.
+- Service signatures: `BookService.listCategories()`,
+  `findCategory(long id)`, `createCategory(AuthenticatedUser actor,
+  BookCategory category)`, `updateCategory(AuthenticatedUser actor,
+  BookCategory category)`, and `deleteCategory(AuthenticatedUser actor,
+  long id)`, all returning `ServiceResult<T>`.
+- Routes: `GET /book-categories`, `GET /book-categories/new`,
+  `GET /book-categories/edit?id=...`, `POST /book-categories`,
+  `POST /book-categories/update`, and `POST /book-categories/delete`.
+- Protected permission: `/book-categories*` requires `MANAGE_BOOKS`.
+
+### 3. Contracts
+
+- `book_categories.name` is unique and is the display value used in book forms,
+  catalog filters, and management filters.
+- `book_categories.description` is optional and limited to the database column
+  size.
+- Book category deletes must check `books.category_id` usage before deletion
+  and return a safe validation result when the category is in use.
+- Servlet controllers set JSP attributes such as `categories`, `category`,
+  `formTitle`, `formAction`, `formValues`, `errors`, `errorMessage`, and
+  `successMessage`.
+- JSP pages render JavaBean properties only; they must not call DAOs or embed
+  SQL.
+
+### 4. Validation & Error Matrix
+
+- Missing category name -> field error on `name`.
+- Category name longer than 96 characters -> field error on `name`.
+- Description longer than 255 characters -> field error on `description`.
+- Duplicate category name -> field error on `name`.
+- Missing or non-positive category id for edit/delete -> `Select a valid
+  category.`
+- Delete category used by any `books` row -> `Category is used by existing
+  books and cannot be deleted.`
+- Reader or unauthenticated actor attempts mutation -> permission denial through
+  filter/service.
+- DAO failure during list/search/write -> log server-side details and return
+  `Book service is temporarily unavailable. Please try again later.`
+
+### 5. Good/Base/Bad Cases
+
+- Good: a librarian creates `Architecture`, selects it on a book form, and sees
+  it in catalog filters.
+- Base: `/book-categories` lists seed categories ordered by name.
+- Bad: deleting a category with existing books surfaces a MySQL foreign-key
+  stack trace or lets JSP code perform the delete.
+
+### 6. Tests Required
+
+- Run `BookServiceCheck` assertions for reader category-write denial, duplicate
+  category names, successful create/update/delete, and used-category delete
+  rejection.
+- Run `PermissionPolicyCheck` to confirm `MANAGE_BOOKS` remains staff-only.
+- Scan category JSPs for scriptlets and SQL/JDBC references.
+- When Maven/Tomcat dependencies are installed, run `mvn clean package` to
+  compile Servlets and package JSP resources.
+
+### 7. Wrong vs Correct
+
+#### Wrong
+
+```text
+categories.jsp -> JDBC -> DELETE FROM book_categories WHERE id = request.id
+```
+
+#### Correct
+
+```text
+categories.jsp -> BookManagementServlet -> BookService -> BookDao -> book_categories
+```
+
 ## Scenario: Reader Information Management Slice

 ### 1. Scope / Trigger