Zzzz
142 lines
5.1 KiB
Markdown
142 lines
5.1 KiB
Markdown
# 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
|
|
```
|