# Users Module

## Overview
Manages administrative access to user records. Most mutations (registration/login) are handled by the Auth module, while Users focuses on profile introspection and limited updates.

## Endpoints
- `GET /users/schema`
  - Returns metadata describing the `User` entity and its relations (addresses, activity logs, etc.).
- `GET /users`
  - Requires an admin JWT (`@Private` + `ApiBearerAuth`).
  - Supports query parameters `page`, `limit`, and `status` (`ACTIVE`, `INACTIVE`, `BANNED`).
  - Responds with sanitized user items including numeric `id`, `name`, `email`, `profile_image`, `role`, and derived `status`.
- `GET /users/:id`
  - Accessible to admins or the user themselves.
  - Route parameter `id` is parsed as an integer.
- `PATCH /users/:id`
  - Self-service: may update `name` and `profile_image`.
  - Admins may additionally adjust `role` and `status` (`ACTIVE` toggles `isActive`).

## Data Handling
- `UsersService.paginate` builds dynamic query builder filters and enforces pagination bounds (1 ≤ page, 1–100 limit).
- `getByIdOrThrow` and `updateProfile` operate on numeric identifiers and throw `NotFoundException` when appropriate.
- Responses consistently sanitize out `passwordHash` and return friendly keys (`profile_image`, `status`).

## Integration Notes
- Combine with Auth module responses: tokens embed `id` as a number, aligning with Users service expectations.
- When calling PATCH as a non-admin, ignore `role` and `status` fields—authorization guards enforce this at runtime.