Book-management-system/.trellis/spec/backend/database-guidelines.md

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. The initial scaffold schema exists at src/main/resources/db/schema.sql; future module tables should follow the same DDL style and DAO boundaries.

---

Core Tables

Use primary keys for every table and foreign keys for cross-entity integrity.

Implemented scaffold tables:

• roles: administrator, librarian, reader, and future role definitions.
• permissions: permission definitions for protected actions.
• 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.

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.

---

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 src/main/resources/db.properties loaded by JdbcUtil. The required keys are db.driver, db.url, db.username, and db.password.

---

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.
• 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.

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).
• Servlet route: POST /login with username, password, and optional same-application redirect.
• Protected routes: /dashboard, /admin/home, /librarian/home, and /reader/home.
• Session keys: authenticatedUser, userRole, and userPermissions.
• DB config keys: db.driver, db.url, db.username, and db.password.
• 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.
• users.active: only rows with active = 1 can authenticate.
• roles.code, permissions.code, and role_permissions must match the Java Role and Permission enum codes exactly.
• db.properties must be local configuration. Commit db.properties.example, but do not commit real credentials.
• 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.
• Login redirects must stay inside the current application context. Reject values that do not start with a single / or that contain CR/LF characters.

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.
• Unsafe or blank redirect -> ignore and route to /dashboard after success.
• 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.
• Run AuthServiceCheck or equivalent assertions for required-field failures, invalid credentials, success, permission checks, and DAO failure fallback.
• 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, Servlet, or session code opens JDBC and stores password_hash.

Correct

login.jsp -> LoginServlet -> AuthService -> UserDao -> users/roles tables
session -> AuthenticatedUser snapshot + role/permission codes only