# ApiTesterBackend Audit Logging

This backend uses a centralized audit logger in `src/Audit/AuditLogService.php`.

The frontend does not call a separate logging endpoint. Audit entries are written inside the main backend action handlers after the business action runs.

## Audit Table

Expected table:

```sql
CREATE TABLE AuditLogs (
    id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
    action VARCHAR(100) NOT NULL,
    status VARCHAR(20) NOT NULL,
    reason TEXT NULL,
    person_id INT NULL,
    entity_type VARCHAR(100) NULL,
    project_id INT NULL,
    details_json LONGTEXT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_auditlogs_action (action),
    INDEX idx_auditlogs_status (status),
    INDEX idx_auditlogs_project_id (project_id),
    INDEX idx_auditlogs_person_id (person_id),
    INDEX idx_auditlogs_created_at (created_at),
    CONSTRAINT fk_auditlogs_person
        FOREIGN KEY (person_id) REFERENCES users(id)
        ON DELETE SET NULL,
    CONSTRAINT fk_auditlogs_project
        FOREIGN KEY (project_id) REFERENCES Projects(id)
        ON DELETE SET NULL
);
```

## Users Role Requirement

The login flow now reads a `role` value from the `users` table and stores it in the session.
Accepted roles are:

- `admin`
- `employee`

If the stored value is missing or anything other than `admin`, the backend treats the user as `employee`.

Example schema update:

```sql
ALTER TABLE users
ADD COLUMN role VARCHAR(20) NOT NULL DEFAULT 'employee';

UPDATE users
SET role = 'admin'
WHERE email IN ('your-admin-user@example.com');
```

Only users with `role = 'admin'` can call baseline overwrite endpoints.

## What Gets Logged

Logged endpoints and actions:

- `POST /api/endpoint-names`
Reason: creates a business record used by endpoints and baselines.
Logs: success.

- `PUT /api/endpoint-names/{id}`
Reason: renaming affects user-facing endpoint identity and may also rename saved baselines.
Logs: success.

- `DELETE /api/endpoint-names/{id}`
Reason: deletes a business record.
Logs: success.

- `POST /api/endpoints`
Reason: creates a primary API endpoint definition.
Logs: success.

- `PUT /api/endpoints/{id}`
Reason: updates a primary API endpoint definition and may reset or rename baseline state.
Logs: success.

- `DELETE /api/endpoints/{id}`
Reason: deletes a primary API endpoint definition and clears baseline state.
Logs: success.

- `POST /api/endpoints/{id}/execute`
Reason: only the first successful execution that creates a saved baseline is audit-worthy.
Logs: success only when a baseline is created for the endpoint.

- `POST /api/endpoints/execute-preview`
Reason: only the first successful preview run that creates a saved baseline is audit-worthy.
Logs: success only when a baseline is created for the preview name.

- `POST /api/endpoints/overwrite-baseline`
Reason: baseline overwrite is sensitive and changes the stored expected response.
Logs: success and failure.
Also requires a user-provided `reason`.

- `POST /api/audit/overwrite-summary`
Reason: group and all overwrite flows should create one final summary audit row after individual overwrite attempts complete.
Logs: one summary entry for `group` or `all`.

## What Is Exempted

Exempted endpoints:

- `GET /api/user-auth/session`
Reason: read-only session check, high frequency, low audit value.

- `POST /api/user-auth/login`
Reason: authentication flow is intentionally excluded from audit logging for this app.

- `POST /api/user-auth/logout`
Reason: authentication flow is intentionally excluded from audit logging for this app.

- `GET /api/endpoints`
Reason: read-only listing endpoint, high noise, no state change.

- `GET /api/endpoint-names`
Reason: read-only listing endpoint, high noise, no state change.

- `GET /api/endpoints/variations`
Reason: server-computed read-only data, high noise, no state change.

- `GET /api/endpoints/{id}`
Reason: read-only fetch, no state change.

- `POST /api/endpoints/{id}/execute`
Reason: ordinary execution checks are exempt unless they create the first baseline.

- `POST /api/endpoints/execute-preview`
Reason: ordinary preview checks are exempt unless they create the first baseline.

## Audit Entry Shape

Each log row may contain:

- `action`: logical audit action like `endpoint.created`, `endpoint.baseline_created`, or `baseline.overwritten`
- `status`: usually `success` or `failed`
- `reason`: used when provided or when a failure has a meaningful explanation
- `person_id`: current authenticated user id when available
- `entity_type`: entity family such as `endpoint`, `endpoint_name`, `baseline`, or `auth`
- `project_id`: owning project when applicable
- `details_json`: a short `message` plus minimal summary metadata when needed

## Overwrite Reason Rule

`POST /api/endpoints/overwrite-baseline` and `POST /api/audit/overwrite-summary` require `reason`.

Frontend behavior:

- individual overwrite asks for reason
- group overwrite asks for reason
- all overwrite asks for reason
- group and all attempt overwrites individually first
- group and all keep success and failure ids in arrays during the run
- group and all make one final summary audit call after the run completes
- the final summary log stores counts and failed endpoint names, not the id arrays

Backend behavior:

- empty or missing `reason` returns `400`
- single overwrite logs directly inside `POST /api/endpoints/overwrite-baseline`
- group and all send `skip_audit_log` during each individual overwrite attempt
- group and all create one final summary row through `POST /api/audit/overwrite-summary`

## Notes

- The logger is best-effort by design. If audit insertion fails, the main business action is not blocked.