# Acciones

El modulo `Acciones` de AnimalCharlie. gestiona tareas correctivas, seguimientos y trabajo pendiente enlazable con informes, proyectos y empleados.

## Uso operativo

- Acceso: barra lateral, panel inicial, lanzador ERP o `#acciones`.
- Entrada: `Acciones` muestra primero el trabajo pendiente, con búsqueda y estado como controles diarios. Prioridad permanece disponible dentro de `Más filtros`, que indica cuándo hay un filtro avanzado activo y permite restablecer búsqueda, estado y prioridad. La cola usa páginas de diez filas y diferencia `Mostrando 1-10 de 14` del total filtrado; cambiar a `Todas` recupera cerradas y canceladas sin mezclarlas con el trabajo diario.
- Estados: la lista publica `aria-busy` mientras carga y diferencia carga, error recuperable, instalación vacía y filtros sin coincidencias. Un fallo de red conserva filas ya cargadas, avisa de que pueden estar desactualizadas y ofrece `Reintentar`; nunca se presenta como una cola vacía.
- Ficha: seleccionar una fila abre `Ficha` a ancho completo. `Cerrar` o `Reabrir` es la única acción primaria. `Editar` queda visible como secundaria y `Histórico`/`Borrar` viven una sola vez dentro de `Más`; las filas no repiten botones. Histórico, cerrar/reabrir y borrar existen una sola vez sobre la acción activa.
- Alta y edición segura: `Nueva acción` sustituye la ficha por un formulario exclusivo y vuelve a la ficha guardada al terminar. `Editar` usa el mismo formulario con los datos actuales y conserva estado y relaciones. Cancelar un formulario sin cambios vuelve directamente; si existe un borrador modificado, exige confirmación antes de descartarlo. El alta cancelada regresa al índice y la edición cancelada vuelve a la ficha sin escribir datos.
- Filtros API: `reportId` y `status` siguen disponibles en `GET /api/actions` para consumidores internos.
- Campos principales: titulo, descripcion, responsable, prioridad, vencimiento, estado, evidencia, informe, proyecto y empleado.
- Responsable: la UI carga `GET /api/module-user-access?module=actions&permission=actions.write&status=active` y usa `options[]` para ofrecer usuarios con permiso efectivo de escritura en Acciones. Tambien conserva `links.history` y `userHistoryUrl` para mostrar un único `Histórico` en la ficha cuando el responsable es un usuario global; esa accion abre `Usuarios > Auditoria` filtrada a `actions`. Si no se elige nadie, el backend mantiene el comportamiento anterior y asigna el usuario que crea la accion.
- Relacion con otros modulos: Certificacion puede crear acciones desde informes, Proyectos y Personal permiten asignar contexto, y Charlie puede preparar acciones confirmables.

La UI usa el `master-detail` común documentado en `UI.md`: `Acciones / Ficha`, `data-ac-focus-both="hidden"`, filas con `data-ac-focus-open` y una sola tarea visible cada vez. No crea rutas, persistencia ni componentes paralelos.

## Estados y seguridad de escritura

- `Pendientes` agrupa todo lo que no esté `done`, `closed` o `cancelled`.
- Una fecha anterior al día real se marca como vencida solo mientras la acción siga pendiente.
- Cerrar usa `PUT /api/actions/{id}` con `status=done`; la misma acción permite reabrir con `status=open`.
- Borrar exige confirmación en navegador antes de ejecutar `DELETE`.
- La lectura respeta `actions.read`/`actions.write`; crear, cambiar estado y borrar permanecen desactivados sin acceso de escritura.

## API interna

Todas las rutas privadas requieren sesion con token.

| Ruta | Acceso | Descripcion |
| --- | --- | --- |
| `GET /api/actions` | roles `admin`, `technician`, `reviewer` o permisos `actions.read` / `actions.write` | Lista acciones, con filtros opcionales `reportId` y `status`. |
| `POST /api/actions` | roles `admin`, `technician`, `reviewer` o permiso `actions.write` | Crea o actualiza una accion cuando el payload incluye `id`. |
| `PUT /api/actions/{id}` | roles `admin`, `technician`, `reviewer` o permiso `actions.write` | Actualiza la accion indicada. |
| `DELETE /api/actions/{id}` | roles `admin`, `technician`, `reviewer` o permiso `actions.write` | Borra la accion indicada. |

El permiso `actions.write` tambien permite leer acciones para que un perfil operativo no tenga que duplicar `actions.read`.

## Payload de accion

Campos aceptados por el backend:

| Campo | Uso |
| --- | --- |
| `id` | Identificador opcional. Si no existe en alta, se genera `act-...`. |
| `title` | Titulo obligatorio de la accion. |
| `description` | Descripcion o contexto operativo. |
| `owner` | Responsable guardado como `username` cuando viene del selector global de usuarios; por defecto el usuario que crea la accion. Valores legacy de texto libre se conservan y se muestran sin romper la lista. |
| `priority` | Prioridad, por defecto `media`. |
| `dueDate` / `due_date` | Fecha de vencimiento. |
| `status` | Estado, por defecto `open`. |
| `evidence` | Evidencia o referencia documental. |
| `reportId` / `report_id` | Informe vinculado. |
| `projectId` / `project_id` | Proyecto vinculado. |
| `employeeId` / `employee_id` | Empleado vinculado. |

## Auditoria

Acciones registra actividad normalizada en `audit_log`:

- `action_save` al crear o guardar desde `POST /api/actions`.
- `action_update` al actualizar desde `PUT /api/actions/{id}`.
- `action_delete` al borrar desde `DELETE /api/actions/{id}`.

El modulo queda como `actions` por `entity_type`, por accion `action_*` y por `details.module` cuando otros modulos lo envien de forma explicita. Esto permite que `/api/activity?module=actions` y `GET /api/users/{username}/history?module=actions` agrupen la actividad sin reglas duplicadas en la UI.

## Consumo por otros modulos

Los modulos que necesiten leer tareas deben pedir `actions.read` o `actions.write`. Los modulos que creen o actualicen tareas deben enviar el payload anterior a `POST /api/actions` o `PUT /api/actions/{id}` y dejar que el backend aplique permisos, auditoria y persistencia.

Para enlazar una accion desde otro modulo, guardar `report_id`, `project_id` o `employee_id` en la propia accion en vez de duplicar campos de seguimiento.

Para elegir responsables operativos desde otro modulo, consumir `GET /api/module-user-access?module=actions&permission=actions.write` igual que hace la UI de `Acciones`; asi se reutilizan permisos, estado de cuenta, actividad reciente y enlaces de historico sin recomponer reglas locales.

Los modulos que quieran abrir trazabilidad acotada deben usar `links.history` o `userHistoryUrl` del selector y navegar a `Usuarios > Auditoria` con el filtro del modulo, en vez de construir una vista propia de auditoria.

## Verificacion de navegador

`tools/verify_actions_ui.py` recorre PC `1920x1080`, PC `1280x800`, Galaxy Tab A9+ e iPad Air horizontal/vertical. Comprueba índice inicial, carga máxima, prioridad cerrada dentro de `Más filtros`, estados de carga/error/vacío/sin coincidencias, ausencia de botones por fila, altura interna completa de cada fila, targets táctiles, búsqueda, filtros, paginación, selección, ficha, alta, edición segura y falta de overflow horizontal. Si la copia temporal no contiene suficientes acciones, crea por API las mínimas para probar dos páginas y las elimina al terminar. En el primer preset crea además una acción temporal, descarta un borrador editado, guarda una segunda edición, conserva descripción y evidencia, la cierra, reabre, abre el histórico del responsable y la elimina; un `finally` usa la API para limpiar cualquier alta si la prueba se interrumpe. Toda captura reutiliza el harness común y conserva `capture-manifest.json` con índice, ficha, edición y alta en los cinco viewports.