# DH Inspección V2 — Fase A4

## Versión

```text
v0.4.0 · Fase A4 · Administración de usuarios y roles
```

## Usuarios

```text
GET   /api/v3/users
POST  /api/v3/users
GET   /api/v3/users/:id
PATCH /api/v3/users/:id
PATCH /api/v3/users/:id/status
PUT   /api/v3/users/:id/roles
```

El listado acepta `page`, `pageSize`, `search` y `status`. No existe endpoint de
borrado físico. La desactivación revoca todas las sesiones del usuario.

Los usuarios se crean con una contraseña temporal de al menos 12 caracteres.
El password se transforma a Argon2id antes de persistir y nunca aparece en la
respuesta ni en auditoría. Cuando `mustChangePassword` está activo, los guards
bloquean endpoints administrativos hasta completar el cambio de contraseña.

## Roles

```text
GET   /api/v3/roles
GET   /api/v3/roles/permissions
GET   /api/v3/roles/:id
POST  /api/v3/roles
PATCH /api/v3/roles/:id
PUT   /api/v3/roles/:id/permissions
```

Los códigos de rol son inmutables después de su creación. Los nombres,
descripciones y permisos se administran por API. No existe borrado de roles en
A4.

## Permisos requeridos

```text
users.read
users.create
users.update
users.change_status
users.assign_roles
roles.read
roles.manage
```

Cada endpoint usa `@RequirePermissions(...)` y el backend siempre valida la
matriz actual almacenada en PostgreSQL.

## Integridad y auditoría

- todas las mutaciones son transaccionales;
- se registran `USER_CREATED`, `USER_UPDATED`, `USER_STATUS_CHANGED`,
  `USER_ROLES_CHANGED`, `ROLE_CREATED`, `ROLE_UPDATED` y
  `ROLE_PERMISSIONS_CHANGED`;
- no se auditan passwords, hashes, tokens ni cookies;
- no se permite la autodesactivación;
- no se puede dejar el sistema sin al menos un usuario activo con
  `roles.manage` y `users.assign_roles`;
- cambios de roles y permisos tienen efecto en el siguiente request.

## Migraciones

A4 no modifica el esquema y no incluye migraciones.