Manual de Administrador

1. Roles y permisos

La plataforma tiene cuatro roles. El sistema los aplica tanto en la interfaz como en cada llamada al servidor, así que un botón oculto también está bloqueado por detrás.

2. Ingresar al sistema

No hay registro abierto: cada cuenta la crea un Administrador o Super Administrador.

1. Entra a /login con el dominio de tu municipalidad.
2. Ingresa el correo y contraseña que te asignaron.
3. La sesión dura 8 horas; pasado ese tiempo deberás volver a iniciar sesión.

3. Dashboard

Es la primera pantalla al iniciar sesión: un resumen en vivo de la situación comunal.

• Tarjetas de estadísticas (total, nuevas, en atención, por prioridad y por tipo) que se actualizan solas sin recargar la página.
• Un indicador discreto muestra si la conexión en vivo está activa, reconectando o con error.
• Listado de emergencias recientes con acceso directo al detalle.
• Botón Nueva emergencia (oculto para Visualizador).

4. Gestión de emergencias

El núcleo del sistema. Todo lo que ocurre queda registrado en el historial de actividad de cada emergencia.

4.1 Listado /emergencias

• Filtros combinables: búsqueda de texto (código, título, dirección, nombre del reportante), estado, prioridad, tipo, sector y rango de fechas.
• Paginado de 50 emergencias por página.
• Exportar CSV respeta los filtros activos en pantalla. Visualizador no ve nombre ni teléfono del reportante, tampoco en el archivo exportado.

4.2 Registrar una nueva emergencia

1. Ve a Emergencias → Nueva emergencia.
2. Completa información general: título, descripción, tipo de emergencia, prioridad y observaciones.
3. Completa ubicación: región y comuna, y la dirección exacta — puedes escribirla con autocompletado, usar el botón GPS, o arrastrar el pin en el mini-mapa. Agrega sector/barrio y fecha/hora de ocurrencia si las conoces.
4. Completa los datos del reportante (nombre, teléfono) y el origen del reporte (Interno o Ciudadano).
5. Define el responsable principal y, si corresponde, co-responsables.
6. Guarda. El sistema genera automáticamente un código único con formato EMG-2026-0001.

4.3 Trabajar el detalle de una emergencia

• Generar reporteAbre una versión imprimible/PDF con todos los datos de la emergencia, lista para respaldo institucional.
• Cambiar estadoNueva → En atención → Resuelta / Cerrada / Descartada. Al resolver o cerrar puedes escribir observaciones de cierre.
• EditarDisponible para Admin y Operador: modifica cualquier campo del registro.
• EvidenciasSube fotos (jpg, png o webp, máximo 5 MB), amplíalas en galería o elimínalas.
• TareasCrea tareas de seguimiento, asígnalas y marca su estado: pendiente, en proceso, completada o cancelada.
• Historial de actividadRegistro automático e inalterable de creación, cambios de estado, asignaciones, tareas, evidencias y correos enviados.
• EliminarAdmin / Super AdminBorra la emergencia junto a sus evidencias y tareas. Pide confirmación explícita y es permanente.

5. Mapa interno /mapa

Visualización geográfica de las emergencias activas de tu municipalidad (excluye Cerradas y Descartadas).

• Los marcadores se colorean por prioridad:
  🟢 Baja🟡 Media🟠 Alta🔴 Crítica
• El mapa se centra automáticamente en el promedio de las emergencias activas; si no hay ninguna, se centra en la región de tu municipalidad.
• Super Administrador ve las emergencias de todas las municipalidades a la vez, con zoom más amplio.
• Haz clic en un marcador para ir directo al detalle de esa emergencia.

6. Usuarios /admin/usuarios Admin Super Admin

Administrador solo ve y gestiona usuarios Operador y Visualizador de su propia municipalidad. Super Administrador ve la lista completa, con la columna Municipalidad.

Crear usuario

• Nombre / EmailIdentifican la cuenta; el email es el usuario de acceso.
• Contraseña inicialMínimo 8 caracteres. El usuario puede seguir usándola o pedir que se la cambien después.
• RolAdmin solo puede asignar Operador o Visualizador. Super Admin puede asignar cualquier rol.
• MunicipalidadPara Admin queda fija en la suya. Super Admin elige cualquiera (o ninguna, solo válido para Super Admin).
• Notificaciones por correoAvisar al ser asignado a una emergencia, y avisar al llegar un reporte ciudadano (esta última solo aplica a Administradores).

Editar, activar/desactivar y eliminar

• Editar: mismos campos que al crear, más una sección aparte para cambiar la contraseña (déjala vacía si no quieres cambiarla).
• Activar / Desactivar: interruptor directo en la tabla. Un usuario desactivado no puede iniciar sesión aunque su contraseña sea correcta — se valida contra la base de datos en cada solicitud, no solo al iniciar sesión.
• Eliminar Solo Super Admin: con confirmación inline en la misma fila. No puedes eliminar tu propia cuenta.

7. Municipalidades /admin/municipalidades Solo Super Admin

Cada municipalidad es un tenant independiente: sus emergencias, usuarios y plantillas de correo no se mezclan con las de otras.

• El listado muestra nombre, slug (usado en las URLs públicas), cantidad de usuarios, total de emergencias, emergencias activas y estado.
• Nueva municipalidad: nombre, slug, región y comuna.
• Activar / Desactivar: una municipalidad inactiva desaparece del desplegable del mapa público y deja de aceptar reportes por su slug.
• Editar: actualiza los datos básicos en cualquier momento.

8. Plantillas de correo Solo Super Admin

Cada municipalidad puede personalizar el asunto y cuerpo de sus correos automáticos desde Municipalidades → (una) → Plantillas.

• Correo de asignación: se envía cuando alguien queda como responsable de una emergencia.
• Correo de nuevo reporte ciudadano: se envía a los administradores cuando llega un reporte por el formulario público.
• Ambos aceptan variables como {{code}} {{type}} {{priority}} {{address}} {{description}} {{link}}, que se reemplazan automáticamente al enviar.
• Cada plantilla se puede desactivar de forma independiente; si está apagada, ese correo simplemente no se envía para esa municipalidad.

9. Webhook /admin/municipalidades/[id]/webhook Solo Super Admin

Notifica automáticamente a un sistema externo del municipio (mesa de ayuda, Slack, ERP propio) cuando ocurren eventos, en paralelo al correo — no lo reemplaza.

• Una sola URL https:// por municipalidad. Se puede activar/desactivar por evento: emergencia creada, nuevo reporte ciudadano y asignación de responsable.
• Cada envío llega firmado con un secreto único por municipalidad (header X-AlertaComunal-Signature: sha256=<hmac>) para que el receptor pueda verificar que el evento es auténtico antes de confiar en él.
• Un solo intento por evento, con tiempo de espera corto y sin reintentos: si el sistema del municipio está caído, la emergencia o el reporte se registran igual — nunca se bloquea la operación por un webhook caído.
• Botón Enviar prueba en la misma pantalla, para verificar la integración sin esperar un evento real.

Si el municipio no tiene un sistema propio para recibirlo

El webhook necesita algo del otro lado escuchando esa URL. Dos caminos según su capacidad técnica:

• Sin código: una herramienta de automatización tipo n8n, Pipedream o Zapier les da una URL propia gratis y arman visualmente qué hacer con cada evento (avisar por Slack/WhatsApp, guardar en una planilla, etc.). No verifica la firma automáticamente, pero alcanza para uso interno de baja exigencia.
• Con código: un pequeño servidor (Node/Express, por ejemplo) que valida la firma y reenvía a donde necesiten. Ejemplo mínimo — recibe el evento y lo manda a un canal de Slack:

const express = require('express')
const crypto = require('crypto')

const app = express()
const WEBHOOK_SECRET = process.env.ALERTACOMUNAL_WEBHOOK_SECRET
const SLACK_URL = process.env.SLACK_INCOMING_WEBHOOK_URL

// express.raw(): necesitamos el body crudo para que la firma calce exacto.
app.use(express.raw({ type: 'application/json' }))

app.post('/webhooks/alertacomunal', async (req, res) => {
  const signature = req.headers['x-alertacomunal-signature']
  const expected = 'sha256=' + crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex')

  if (signature !== expected) return res.status(401).send('Firma inválida')

  const { event, emergency } = JSON.parse(req.body.toString('utf8'))
  const text = {
    EMERGENCY_CREATED: `🆕 Nueva emergencia ${emergency?.code}`,
    NEW_CITIZEN_REPORT: `📣 Reporte ciudadano ${emergency?.code}`,
    EMERGENCY_ASSIGNED: `👤 Emergencia ${emergency?.code} asignada`,
    TEST: '✅ Ping de prueba recibido',
  }[event]

  if (SLACK_URL && text) {
    await fetch(SLACK_URL, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ text }),
    })
  }
  res.status(200).send('OK')
})

app.listen(3001)

1. Desplegar este servidor donde sea (debe quedar accesible por https://).
2. Crear un Incoming Webhook de Slack gratis y poner esa URL en SLACK_INCOMING_WEBHOOK_URL.
3. Pegar la URL del servidor en /admin/municipalidades/[id]/webhook, guardar, y copiar el secreto generado a ALERTACOMUNAL_WEBHOOK_SECRET del servidor.
4. Usar el botón Enviar prueba y confirmar que llega el mensaje a Slack.

10. Auditoría /admin/auditoria Solo Super Admin

Registro de seguridad global e independiente del historial de cada emergencia: no se borra aunque se elimine una emergencia.

• Incluye eventos como inicios de sesión fallidos, bloqueos por exceso de intentos, emergencias eliminadas y correos enviados o fallidos.
• Filtrable por tipo de evento, con paginado de 50 registros.

11. Enlaces públicos que puedes compartir

Estos enlaces no requieren iniciar sesión; puedes difundirlos en redes, avisos municipales o folletería.

• /reportarFormulario ciudadano general (pide región y comuna).
• /reportar/tu-slugRecomendado: precompleta tu municipalidad y oculta región/comuna.
• /consultaConsulta pública de estado por código de seguimiento.
• /mapa-publicoMapa público con desplegable para elegir municipalidad.
• /mapa-publico/tu-slugMapa público centrado directamente en tu municipalidad.

12. Privacidad y retención de datos

• Token de consulta: al enviar un reporte, el ciudadano recibe un token de seguimiento aleatorio (no el código interno EMG-2026-0001) para usar en /consulta. El código interno sigue apareciendo en tus correos, exportaciones y webhooks, pero nunca se lo entregues a un ciudadano como si fuera su código de seguimiento — no sirve para consultar por esa vía.
• Nota de cierre visible al público: lo que escribas en las observaciones al resolver o cerrar una emergencia (Cambiar estado, sección 4.3) se muestra tal cual en /consulta a quien tenga el token. No incluyas ahí comentarios internos, nombres de terceros ni evaluaciones que no correspondan compartir públicamente.
• Datos del reportante ocultos para Visualizador: el rol Visualizador nunca ve el nombre ni el teléfono del reportante — ni en el listado, ni en el detalle, ni en el reporte imprimible. Cuando Admin/Operador/Super Admin sí los consultan, queda un registro en Auditoría (EMERGENCY_PII_VIEWED).
• Consentimiento: el formulario ciudadano exige aceptar el tratamiento de sus datos de contacto antes de enviar el reporte.
• CAPTCHA adaptativo: si un mismo origen envía varios reportes en pocos minutos, el formulario exige una verificación de seguridad antes de aceptar el envío. La gran mayoría de los ciudadanos, que envían un solo reporte, nunca la ven.
• Retención: el nombre y teléfono del reportante deberían anonimizarse 24 meses después del cierre de la emergencia. Esta limpieza automática todavía no está implementada — es un pendiente técnico, no algo que debas hacer manualmente hoy.

13. Buenas prácticas

• No compartas tu contraseña ni dejes tu sesión abierta en equipos compartidos.
• Al desvincular a alguien de la institución, desactiva su usuario; reserva la eliminación (Super Admin) para casos excepcionales.
• Usa el rol Visualizador por defecto para quien solo necesita seguimiento — protege los datos de contacto de los reportantes.
• Super Admin: revisa la auditoría periódicamente para detectar intentos de acceso anómalos.