Initial commit

2026-04-27 18:40:30 +08:00
commit 2120774b05
112 changed files with 12308 additions and 0 deletions
@@ -0,0 +1,141 @@
+# Database Guidelines
+
+> MySQL data and DAO conventions for the library-management system.
+
+---
+
+## Overview
+
+MySQL is the project data layer. DAO classes perform CRUD and query operations
+against MySQL. Application source and schema files are not present yet, so table
+and class names here are illustrative conventions for future implementation.
+
+---
+
+## Core Tables
+
+Use primary keys for every table and foreign keys for cross-entity integrity.
+Illustrative table names:
+
+- `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.
+- `administrators`: administrator/librarian login and profile data.
+- `roles`: administrator, librarian, reader, and future role definitions.
+- `permissions`: permission definitions for protected actions.
+- `role_permissions`: role-to-permission mapping.
+- `system_logs`: key operation logs, backup events, and exception traces.
+
+When schema files are introduced, record the actual path, DDL style, and exact
+table names here.
+
+---
+
+## DAO Responsibilities
+
+- DAOs own database CRUD and query details.
+- Use parameterized SQL or prepared-statement style access; never concatenate
+  raw request parameters into SQL.
+- Keep transaction boundaries in the service layer for workflows that span
+  multiple DAO calls, such as borrow/return operations that also update
+  inventory status.
+- Return entities or small query result objects to services, not HTML or
+  servlet response objects.
+- Keep MySQL connection details in a shared configuration/helper once one
+  exists, for example `JdbcUtil` plus `db.properties`.
+
+---
+
+## Query Guidance
+
+- Book search must support combined lookup by title, author, category, and ID.
+- Statistics queries should cover borrowing rankings, inventory reports, and
+  overdue reports.
+- Borrowing records should preserve enough dates/status fields for borrow,
+  return, renew, overdue calculation, and automatic collection status updates.
+- Permission queries should support role-based checks for administrator,
+  librarian, and reader workflows.
+
+---
+
+## Integrity Constraints
+
+- `books.category_id` should reference `book_categories`.
+- `borrow_records.book_id` should reference `books`.
+- `borrow_records.reader_id` should reference `readers`.
+- Administrator-role and role-permission mapping tables should use foreign keys
+  to preserve authorization integrity.
+- Prefer explicit status columns/enums for inventory and borrowing states, then
+  document the chosen values once code exists.
+
+## Scenario: Login And Permission Scaffold Schema
+
+### 1. Scope / Trigger
+
+- Trigger: the initial Java Web scaffold introduced a concrete MySQL schema and
+  login contract.
+- Schema path: `src/main/resources/db/schema.sql`.
+- Example configuration path: `src/main/resources/db.properties.example`.
+
+### 2. Signatures
+
+- DAO signature: `UserDao.findActiveByUsername(String username)`.
+- Service signature: `AuthService.authenticate(String username, String password)`.
+- Permission signature: `AuthService.hasPermission(AuthenticatedUser user, Permission permission)`.
+- Login tables: `roles`, `permissions`, `role_permissions`, `users`, and
+  `system_logs`.
+
+### 3. Contracts
+
+- `users.username`: unique login identifier submitted by `LoginServlet`.
+- `users.password_hash`: PBKDF2 hash in
+  `pbkdf2_sha256$iterations$saltBase64$hashBase64` format.
+- `users.role_code`: foreign key to `roles.code`; supported scaffold values
+  are `administrator`, `librarian`, and `reader`.
+- Session state stores an `AuthenticatedUser` snapshot, role code, and
+  permission-code set. It must not store raw passwords or DAO result objects
+  with password hashes.
+
+### 4. Validation & Error Matrix
+
+- Missing username or password -> request returns to login JSP with
+  `Username and password are required.`
+- Unknown user, inactive user, or hash mismatch -> request returns to login JSP
+  with `Invalid username or password.`
+- Missing `db.properties`, JDBC failure, or unsupported role code -> request
+  returns a generic service-unavailable message and logs server-side details.
+- Authenticated user missing a required permission -> HTTP 403 and
+  `WEB-INF/jsp/auth/unauthorized.jsp`.
+
+### 5. Good/Base/Bad Cases
+
+- Good: `admin` resolves to `administrator`, receives all scaffold
+  permissions, and can access `/admin/home`.
+- Base: `reader` resolves to `reader`, can access `/reader/home`, and cannot
+  access `/admin/home`.
+- Bad: a JSP reads SQL or password hashes directly from the database. Keep that
+  logic in DAO/service code.
+
+### 6. Tests Required
+
+- Compile service/DAO/entity/util classes with `javac` when Maven is
+  unavailable.
+- Run `PermissionPolicyCheck` or equivalent assertions for administrator,
+  librarian, and reader permissions.
+- When Maven/Tomcat dependencies are installed, run `mvn test` or
+  `mvn clean package` to compile Servlet and JSP integration.
+
+### 7. Wrong vs Correct
+
+#### Wrong
+
+```java
+// JSP or Servlet opens JDBC and checks passwords directly.
+```
+
+#### Correct
+
+```text
+login.jsp -> LoginServlet -> AuthService -> UserDao -> users/roles tables
+```