# 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.