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.
• book_categories: category names and descriptions for catalog grouping.
• books: book information, category reference, inventory counts, and catalog status.

Planned module tables:

• readers: reader profiles, borrowing eligibility, contact information.
• borrow_records: book-reader borrowing, return, renew, and overdue data.

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

books/form.jsp -> JDBC -> INSERT INTO books using request parameters

Correct

books/form.jsp -> BookManagementServlet -> BookService -> BookDao -> books

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