新增书籍表、列表/搜索、管理员/馆员维护入口

.trellis/spec/backend/database-guidelines.md

@@ -24,14 +24,14 @@ Implemented scaffold tables:
 - `role_permissions`: role-to-permission mapping.
 - `users`: login accounts for administrator, librarian, and reader roles.
 - `system_logs`: key operation logs, backup events, and exception traces.
+- `book_categories`: category names and descriptions for catalog grouping.
+- `books`: book information, category reference, inventory counts, and catalog
+  status.
 
 Planned module tables:
 
-- `books`: book information, inventory count/status, category reference.
-- `book_categories`: category names and descriptions.
 - `readers`: reader profiles, borrowing eligibility, contact information.
 - `borrow_records`: book-reader borrowing, return, renew, and overdue data.
-- `system_logs`: key operation logs, backup events, and exception traces.
 
 Record new schema changes in `src/main/resources/db/schema.sql` and update this
 spec with exact table names, key columns, and DAO/service contracts.
@@ -76,8 +76,116 @@ spec with exact table names, key columns, and DAO/service contracts.
 - `users.role_code` must reference `roles.code`.
 - `role_permissions.role_code` must reference `roles.code`.
 - `role_permissions.permission_code` must reference `permissions.code`.
-- Prefer explicit status columns/enums for inventory and borrowing states, then
-  document the chosen values once code exists.
+- `books.status` must match `BookStatus` enum codes: `available`,
+  `unavailable`, and `archived`.
+
+## Scenario: Book Catalog And Management Slice
+
+### 1. Scope / Trigger
+
+- Trigger: the first concrete business module introduced catalog search and
+  basic book management across MySQL, DAO, service, Servlet, and JSP layers.
+- Schema path: `src/main/resources/db/schema.sql`.
+- JSP paths: `WEB-INF/jsp/books/catalog.jsp`, `books/manage.jsp`, and
+  `books/form.jsp`.
+
+### 2. Signatures
+
+- DAO signatures: `BookDao.findAllCategories()`,
+  `BookDao.search(BookSearchCriteria criteria)`, `findById(long id)`,
+  `findByIdentifier(String identifier)`, `create(Book book)`,
+  `update(Book book)`, and `delete(long id)`.
+- Entity/search signatures: `Book` fields are `id`, `identifier`, `title`,
+  `author`, `categoryId`, `categoryName`, `totalCopies`, `availableCopies`,
+  `status`, `createdAt`, and `updatedAt`; `BookSearchCriteria` fields are
+  `identifier`, `title`, `author`, and nullable `categoryId`.
+- Service signatures: `BookService.listCategories()`,
+  `searchBooks(BookSearchCriteria criteria)`, `findBook(long id)`,
+  `createBook(AuthenticatedUser actor, Book book)`,
+  `updateBook(AuthenticatedUser actor, Book book)`, and
+  `deleteBook(AuthenticatedUser actor, long id)`, all returning
+  `ServiceResult<T>`.
+- Read route: `GET /catalog` with optional `identifier`, `title`, `author`,
+  and `categoryId` query fields.
+- Management routes: `GET /books`, `GET /books/new`, `GET /books/edit?id=...`,
+  `POST /books`, `POST /books/update`, and `POST /books/delete`.
+- Protected permissions: `/catalog` requires `VIEW_CATALOG`; `/books*`
+  requires `MANAGE_BOOKS`.
+- DB signatures:
+  - `book_categories(id, name, description, created_at, updated_at)`, with
+    unique key `uk_book_categories_name(name)`.
+  - `books(id, book_identifier, title, author, category_id, total_copies,
+    available_copies, status, created_at, updated_at)`, with unique key
+    `uk_books_identifier(book_identifier)`, indexes on title, author, category,
+    and status, foreign key `fk_books_category`, and checks for non-negative
+    copy counts and allowed status values.
+
+### 3. Contracts
+
+- `book_categories.name` is unique and displayed through category selectors.
+- `books.book_identifier` is the unique user-facing book ID.
+- `books.category_id` references `book_categories.id`.
+- `books.total_copies` and `books.available_copies` are non-negative, and
+  available copies cannot exceed total copies.
+- `books.status` stores the Java `BookStatus` code exactly.
+- Servlet controllers parse request fields and set JSP attributes such as
+  `criteria`, `categories`, `books`, `book`, `statuses`, `errors`,
+  `errorMessage`, and `successMessage`.
+- `ServiceResult<T>` is the service-to-controller response contract:
+  `successful`, nullable `data`, nullable `message`, and field-level
+  `errors`. Controllers must pass validation errors to JSPs so form/search
+  redisplay can highlight the exact field, for example `errors.categoryId`.
+- JSP pages render JavaBean properties only; they must not call DAOs or embed
+  SQL.
+
+### 4. Validation & Error Matrix
+
+- Missing identifier, title, author, category, copy counts, or status -> return
+  to `books/form.jsp` with field errors.
+- Negative total or available copies -> return a field error.
+- Available copies greater than total copies -> return
+  `Available copies cannot exceed total copies.`
+- Duplicate `book_identifier` -> return a field error on `identifier`.
+- Reader or unauthenticated actor attempts write -> HTTP 403 through
+  authorization filter or service denial.
+- DAO failure during list/search/write -> log server-side details and return
+  `Book service is temporarily unavailable. Please try again later.`
+- Successful create/update/delete -> redirect to `/books` with a short flash
+  message.
+
+### 5. Good/Base/Bad Cases
+
+- Good: a librarian creates `BK-1002`, sees it in `/books`, and readers can
+  find it from `/catalog` without write controls.
+- Base: catalog search with no filters lists available records ordered by
+  title, author, and identifier.
+- Bad: a JSP opens JDBC, builds SQL from request parameters, or renders a stack
+  trace from a failed DAO call.
+
+### 6. Tests Required
+
+- Run `BookServiceCheck` or equivalent assertions for invalid inventory,
+  duplicate identifiers, reader write denial, successful librarian CRUD, search,
+  and DAO failure fallback.
+- Run `PermissionPolicyCheck` to confirm readers lack `MANAGE_BOOKS` and retain
+  `VIEW_CATALOG`.
+- Scan 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
+books/form.jsp -> JDBC -> INSERT INTO books using request parameters
+```
+
+#### Correct
+
+```text
+books/form.jsp -> BookManagementServlet -> BookService -> BookDao -> books
+```
 
 ## Scenario: Login And Permission Scaffold Schema