chore: import DH V2 D5.6.4 production baseline

docs/PHASE_A4.md

@@ -0,0 +1,72 @@
+# 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.