# Guía de Solución de Errores
## Sistema de Gestión de Armamento y Elementos

Esta guía resume fallos frecuentes de la versión actual del sistema y las acciones recomendadas para diagnóstico.

## 1. Acceso, sesión y pantallas de error

### 1.1 La aplicación no carga o muestra `500`, `502`, `503` o `504`
**Diagnóstico:**
- Verifique que el servidor esté levantado.
- Confirme conectividad con MySQL, R2 y SMTP.
- Valide variables de entorno (`DB_*`, `R2_*`, etc.).

### 1.2 Aparece página `403` (Prohibido)
**Causa:**
- El usuario no tiene permisos para el módulo o la empresa/sede seleccionada.
- **Nuevo:** Si un usuario tiene `sede_id` asignado, solo puede ver datos de esa sede.

**Solución:**
- Verifique el rol y la sede asociada al usuario en el panel de Administración.

## 2. Base de datos y Migraciones

### 2.1 Error `Unknown column` o `Table doesn't exist`
**Causa:**
- Falta aplicar migraciones recientes.

**Acción:**
Verifique que se hayan ejecutado los scripts en `database/migrations/`:
- `add_sedes.sql`
- `add_sede_to_armas.sql`
- `add_sede_to_ubicaciones.sql`
- `cadena_custodia_trazabilidad.sql`
- `add_fotos_evidencia_inventarios.sql`

## 3. Cadena de Custodia y Trazabilidad

### 3.1 El arma no aparece disponible para traslado
**Causa:**
- El arma ya tiene un traslado `en_transito`.
- El arma está asignada a un empleado (debe devolverse primero para traslados de almacén).

**Solución:**
- Verifique la trazabilidad del arma para ver su estado actual.

### 3.2 Error "No se pudo registrar el ingreso/traslado"
**Diagnóstico:**
- Verifique que la Ubicación de destino y el Custodio de destino pertenezcan a la misma empresa.
- Si es un traslado externo, verifique que la Empresa destino esté activa.

## 4. Inventarios

### 4.1 Error al subir fotos de evidencia
**Causas:**
- El archivo excede los **5 MB**.
- Formato no soportado (use JPG, PNG, WebP).
- **Nuevo:** El sistema bloquea la subida de archivos idénticos (mismo contenido) en el mismo registro.

### 4.2 El inventario no se puede cerrar
**Causa:**
- Hay armas esperadas que no han sido verificadas.

**Solución:**
- Registre el resultado para todas las armas o marque como "Con Novedades" si el proceso fue parcial.

### 4.3 No se genera el PDF de Inventario
**Diagnóstico:**
- Verifique que el inventario esté en estado `completado` o `con_novedades`.
- Revise que la empresa tenga un logo cargado en R2.

## 5. Sedes y Ubicaciones

### 5.1 No puedo crear una ubicación en una sede
**Causa:**
- La sede seleccionada pertenece a una empresa diferente a la del usuario (salvo Superadmin).

### 5.2 Error de sincronización de ubicaciones
**Causa:**
- Se eliminó una sede que tenía ubicaciones activas.

**Solución:**
- Use la herramienta "Sincronizar Ubicaciones y Custodios" en el panel Admin (si está disponible).

## 6. Archivos y Cloudflare R2

### 6.1 `npm run test:r2` falla
**Acción:**
- Revise `R2_ACCESS_KEY_ID` y `R2_SECRET_ACCESS_KEY`.
- Confirme que el bucket tiene habilitado el acceso público si usa `R2_PUBLIC_URL`.

## 7. Soporte Técnico
Si el problema persiste, proporcione:
1. ID del Registro (Arma, Inventario, Traslado).
2. Captura de la consola del navegador (F12).
3. Logs del servidor (`pm2 logs`).