dh-inspeccion-v2/docs/PHASE_B4.md

Fase B4 — Fotografías y documentos de activos

Versión: 0.11.0

Objetivo

Adjuntar evidencia visual y documental a cada activo, conservando el archivo original en almacenamiento privado y relacionando toda operación con el historial inmutable y la auditoría.

Modelo y almacenamiento

La tabla asset_media guarda los metadatos, el hash SHA-256 y el vínculo con el activo. Los binarios se almacenan fuera de la imagen de la API, en el volumen Docker persistente dhv2_asset_media.

Formatos permitidos:

• fotografías JPEG, PNG y WebP;
• documentos PDF;
• tamaño máximo de 15 MB por archivo.

La API inspecciona la firma real del contenido y no confía en la extensión ni en el MIME informado por el navegador. Cada original recibe un nombre interno aleatorio y permisos de archivo restringidos.

API

• GET /api/v3/assets/:assetId/media: lista archivos activos;
• POST /api/v3/assets/:assetId/media: incorpora un archivo multipart;
• PATCH /api/v3/asset-media/:mediaId: actualiza metadatos;
• DELETE /api/v3/asset-media/:mediaId: retiro lógico;
• GET /api/v3/asset-media/:mediaId/content: visualización o descarga protegida.

Los archivos no se publican desde Nginx. Toda lectura atraviesa autenticación y autorización en la API.

Seguridad y permisos

• assets.read_media: admin, director, supervisor, inspector y auditor;
• assets.manage_media: admin, supervisor e inspector.

El usuario runtime puede consultar, insertar y actualizar asset_media, pero no recibe DELETE. Retirar un archivo es una baja lógica: el registro y el original físico se conservan.

Trazabilidad

Incorporar, editar o retirar un archivo:

• genera un evento específico en audit_events;
• incrementa assets.current_version;
• produce un snapshot B3 con los metadatos vigentes de fotografías y documentos, sin duplicar los binarios dentro de PostgreSQL.

Interfaz

Cada activo incluye una sección de fotografías y documentos con:

• captura desde la cámara o selección de archivo;
• fecha, título y descripción opcionales;
• captura GPS explícita con precisión;
• previsualización autenticada de fotografías;
• descarga protegida;
• edición de metadatos y retiro lógico;
• cantidad de archivos en el listado maestro.

Fuera de B4

• miniaturas y transformaciones derivadas;
• antivirus externo;
• importación masiva de archivos;
• sincronización Android offline.