chore: import DH V2 D5.6.4 production baseline

2026-09-05 10:12:35 -03:00
commit 82213e72f5
757 changed files with 84218 additions and 0 deletions
@@ -0,0 +1,73 @@
+# 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.