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.

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

// JSP or Servlet opens JDBC and checks passwords directly.

Correct

login.jsp -> LoginServlet -> AuthService -> UserDao -> users/roles tables

5.1 KiB Raw Blame History