# Logging Guidelines

> Logging and system-log conventions for the library-management backend.

---

## Overview

The project requires system maintenance/log support for key operation logs, data
backup support, and exception tracing. MySQL should include a system log table,
illustratively `system_logs`, for durable audit and troubleshooting records.

---

## What to Log

Record key operations that affect security, data integrity, or inventory:

- Login success/failure and logout for administrator, librarian, and reader
  roles when applicable.
- Permission changes, role changes, and denied protected operations.
- Book create, update, delete, category maintenance, and warehousing/intake.
- Borrow, return, renew, overdue handling, and automatic inventory status
  updates.
- Reader profile, eligibility, and contact information changes.
- Data backup events and restore-related maintenance actions.
- Unhandled exceptions and failed database operations with safe context.

---

## System Log Fields

When the schema is introduced, `system_logs` should preserve enough information
to trace actions without exposing sensitive data. Useful fields include an ID,
operator ID, operator role, operation type, target entity/table, target ID,
result status, message, timestamp, and request IP when available.

---

## Sensitive Data

Do not log passwords, raw credentials, full request bodies, database connection
strings, or unnecessary personal data. Prefer IDs and operation summaries over
large before/after payloads.

---

## Exception Tracing

Server logs may contain technical stack traces for developers. User-facing JSP
pages should receive concise messages. Durable system logs should record the
operation, actor, failure category, and correlation details needed to locate
the server-side exception.

---

## Scenario: Admin User Management Audit And System Log Viewer

### 1. Scope / Trigger

- Trigger: administrator user/account management writes durable audit rows, and
  `/admin/system-logs` reads those rows through a Servlet -> Service -> DAO ->
  MySQL flow.
- The viewer is read-only; mutation belongs to the business service that owns
  the operation being audited.

### 2. Signatures

- DB signature: `system_logs(id, operator_id, operator_role, operation_type,
  target_table, target_id, result_status, message, request_ip, created_at)`.
- DAO signatures: `SystemLogDao.search(criteria)`,
  `SystemLogDao.findOperationTypes()`, and
  `SystemLogDao.create(connection, log)`.
- Service signatures:
  `SystemLogService.searchLogs(AuthenticatedUser actor, SystemLogSearchCriteria criteria)`
  and user-management methods that accept `requestIp` for audit rows.
- Routes: `GET /admin/system-logs`; user-management audit sources include
  `POST /admin/users`, `POST /admin/users/update`, and
  `POST /admin/users/deactivate`.

### 3. Contracts

- `/admin/system-logs` requires `VIEW_SYSTEM_LOGS`; user-management write
  routes require `MANAGE_USERS`.
- Search criteria fields are `operationType`, `keyword`, `createdFrom`, and
  `createdTo`; dates use `YYYY-MM-DD`.
- System-log result rows are newest-first and may include missing joined user
  names. Entity display helpers must render an operator label as display name,
  username, `User #<id>`, or `System` in that order.
- JSPs must use safe JavaBean helpers such as `operatorLabel`,
  `operatorMetaText`, `resultStatusCode`, and `resultStatusName`; do not put raw
  database status strings into CSS class names.
- Audit messages must summarize actions with IDs/usernames/roles, never
  passwords, raw credentials, password hashes, or request bodies.

### 4. Validation & Error Matrix

- Unauthenticated or unauthorized viewer -> `You do not have permission to view
  system logs.`
- `operationType` longer than 64 characters -> field error on `operationType`.
- `keyword` longer than 120 characters -> field error on `keyword`.
- Invalid date text -> `Start date must use YYYY-MM-DD.` or `End date must use
  YYYY-MM-DD.`
- `createdFrom` after `createdTo` -> field error on `createdTo`.
- DAO failure while loading logs -> server-side Java logger entry plus `System
  log service is temporarily unavailable. Please try again later.`
- Audit insert failure inside a user-management transaction -> rollback the
  mutating operation and return the user-management unavailable message.

### 5. Good/Base/Bad Cases

- Good: user creation and its `user.create` audit row commit in the same
  transaction, including `operator_id`, `operator_role`, `target_table=users`,
  `target_id`, `result_status=success`, and `request_ip`.
- Base: a system log with `operator_id` but no joined user displays as
  `User #<id>`, not as `System`.
- Bad: a JSP renders `class="status-${log.resultStatus}"` from an arbitrary
  database value.

### 6. Tests Required

- Service checks for permission denial, criteria validation, date-range
  validation, DAO failure fallback, newest-first/search DAO contract, and empty
  results.
- User-management service checks for audit log creation on create/update/
  deactivate and rollback when audit creation fails inside the transaction.
- Entity/display checks for operator fallback labels and normalized result
  status CSS codes.
- JSP scan confirming no scriptlet, SQL, JDBC, password, or password-hash
  rendering in admin/log pages.

### 7. Wrong vs Correct

#### Wrong

```jsp
<span class="status-${log.resultStatus}">${log.resultStatus}</span>
```

#### Correct

```jsp
<span class="status-${log.resultStatusCode}">
  <c:out value="${log.resultStatusName}" />
</span>
```