# MANUAL DE USUARIO

## Metafoliador v2.0.0

### Sistema de Gestión Documental e Indexación Electrónica

---

**Autor:** MetaBiblioteca © 2026  
**Versión del documento:** 1.0  
**Fecha de elaboración:** Julio 2026  

---

## ÍNDICE

1. [Introducción](#1-introducción)
   - 1.1 [¿Qué es Metafoliador?](#11-qué-es-metafoliador)
   - 1.2 [¿Para qué sirve?](#12-para-qué-sirve)
   - 1.3 [Requisitos para usar el sistema](#13-requisitos-para-usar-el-sistema)
2. [Primeros Pasos](#2-primeros-pasos)
   - 2.1 [Acceso al sistema](#21-acceso-al-sistema)
   - 2.2 [Inicio de sesión](#22-inicio-de-sesión)
   - 2.3 [Cerrar sesión](#23-cerrar-sesión)
   - 2.4 [Cambiar tema (claro/oscuro)](#24-cambiar-tema-clarooscuro)
3. [El Dashboard (Panel Principal)](#3-el-dashboard-panel-principal)
   - 3.1 [Estadísticas generales](#31-estadísticas-generales)
   - 3.2 [Gráficos interactivos](#32-gráficos-interactivos)
   - 3.3 [Registros de actividad reciente](#33-registros-de-actividad-reciente)
4. [Conexiones a Alfresco](#4-conexiones-a-alfresco)
   - 4.1 [¿Qué es una conexión?](#41-qué-es-una-conexión)
   - 4.2 [Ver conexiones existentes](#42-ver-conexiones-existentes)
   - 4.3 [Crear una nueva conexión](#43-crear-una-nueva-conexión)
   - 4.4 [Editar una conexión](#44-editar-una-conexión)
   - 4.5 [Probar una conexión](#45-probar-una-conexión)
   - 4.6 [Descubrir sitios de Alfresco](#46-descubrir-sitios-de-alfresco)
   - 4.7 [Eliminar una conexión](#47-eliminar-una-conexión)
5. [Sitios de Alfresco](#5-sitios-de-alfresco)
   - 5.1 [¿Qué es un sitio?](#51-qué-es-un-sitio)
   - 5.2 [Ver sitios existentes](#52-ver-sitios-existentes)
   - 5.3 [Crear un sitio manualmente](#53-crear-un-sitio-manualmente)
   - 5.4 [Editar un sitio](#54-editar-un-sitio)
   - 5.5 [Eliminar un sitio](#55-eliminar-un-sitio)
6. [Cuadro de Clasificación y Sincronización](#6-cuadro-de-clasificación-y-sincronización)
   - 6.1 [Navegar el cuadro de clasificación](#61-navegar-el-cuadro-de-clasificación)
   - 6.2 [Iniciar una sincronización](#62-iniciar-una-sincronización)
   - 6.3 [Modos de sincronización: Shallow vs Deep](#63-modos-de-sincronización-shallow-vs-deep)
   - 6.4 [Monitorear el progreso](#64-monitorear-el-progreso)
   - 6.5 [Ver archivos de una Serie, Subserie o Expediente](#65-ver-archivos-de-una-Serie, Subserie o Expediente)
7. [Índices Electrónicos (index.xml)](#7-índices-electrónicos-indexxml)
   - 7.1 [¿Qué es un índice electrónico?](#71-qué-es-un-índice-electrónico)
   - 7.2 [¿Cuándo se genera un índice?](#72-cuándo-se-genera-un-índice)
   - 7.3 [Ver el contenido de un índice](#73-ver-el-contenido-de-un-índice)
   - 7.4 [Ver el Estado de los índices](#74-ver-el-estado-de-los-índices)
8. [Trabajos en Cola](#8-trabajos-en-cola)
   - 8.1 [¿Qué son los trabajos?](#81-qué-son-los-trabajos)
   - 8.2 [Ver trabajos activos](#82-ver-trabajos-activos)
   - 8.3 [Cancelar un trabajo](#83-cancelar-un-trabajo)
   - 8.4 [Limpiar la cola de trabajos](#84-limpiar-la-cola-de-trabajos)
9. [Gestión de Usuarios](#9-gestión-de-usuarios)
   - 9.1 [Ver lista de usuarios](#91-ver-lista-de-usuarios)
   - 9.2 [Crear un nuevo usuario](#92-crear-un-nuevo-usuario)
   - 9.3 [Editar un usuario](#93-editar-un-usuario)
   - 9.4 [Eliminar un usuario](#94-eliminar-un-usuario)
10. [Roles y Permisos (RBAC)](#10-roles-y-permisos-rbac)
    - 10.1 [¿Qué son los roles?](#101-qué-son-los-roles)
    - 10.2 [¿Qué son los permisos?](#102-qué-son-los-permisos)
    - 10.3 [Ver roles existentes](#103-ver-roles-existentes)
    - 10.4 [Crear un nuevo rol](#104-crear-un-nuevo-rol)
    - 10.5 [Editar un rol](#105-editar-un-rol)
    - 10.6 [Lista de permisos disponibles](#106-lista-de-permisos-disponibles)
    - 10.7 [Eliminar un rol](#107-eliminar-un-rol)
11. [Reportes](#11-reportes)
    - 11.1 [Tipos de reportes](#111-tipos-de-reportes)
    - 11.2 [Generar reporte TRD de Tipologías (Excel)](#112-generar-reporte-trd-de-tipologías-excel)
    - 11.3 [Generar reporte de Gráficos por Dependencia (PDF)](#113-generar-reporte-de-gráficos-por-dependencia-pdf)
    - 11.4 [Generar reporte FUID (Excel y PDF)](#114-generar-reporte-fuid-excel-y-pdf)
    - 11.5 [Descargar un reporte generado](#115-descargar-un-reporte-generado)
    - 11.6 [Activar o desactivar reportes](#116-activar-o-desactivar-reportes)
12. [Logs del Webhook Listener](#12-logs-del-webhook-listener)
    - 12.1 [¿Qué son los logs del listener?](#121-qué-son-los-logs-del-listener)
    - 12.2 [Ver los logs](#122-ver-los-logs)
    - 12.3 [Interpretar la información de los logs](#123-interpretar-la-información-de-los-logs)
13. [Solución de Problemas Comunes](#13-solución-de-problemas-comunes)
14. [Glosario](#14-glosario)

---

## 1. INTRODUCCIÓN

### 1.1 ¿Qué es Metafoliador?

**Metafoliador v2** es un sistema web que te permite gestionar documentos almacenados en **Alfresco** (un repositorio de documentos electrónicos) de manera fácil y automatizada. Su nombre viene de "metadatos" + "foliador" (numerador de páginas), porque su función principal es organizar documentos y generar hojas de índice electrónico.

### 1.2 ¿Para qué sirve?

Con Metafoliador puedes:

| Funcionalidad | ¿Qué hace? |
|---------------|------------|
| **Conectar con Alfresco** | Vincular el sistema a uno o varios servidores Alfresco donde están tus documentos |
| **Sincronizar Series, Subseries y Expedientes** | Descargar la estructura de Series, Subseries y Expedientes y archivos desde Alfresco para trabajar con ellos localmente |
| **Generar índices electrónicos** | Crear automáticamente archivos `index.xml` que listan todos los documentos de una Serie, Subserie o Expediente, cumpliendo con el formato exigido por entidades gubernamentales colombianas |
| **Calcular hashes** | Verificar la integridad de cada archivo con huella digital SHA-256 |
| **Contar páginas** | Determinar automáticamente cuántas páginas tiene cada documento |
| **Reportes** | Generar reportes en Excel y PDF con estadísticas de tus documentos |

### 1.3 Requisitos para usar el sistema

- Un navegador web moderno (Chrome, Firefox, Edge, Safari)
- Conexión a internet o a la red donde está instalado el sistema
- Un usuario y contraseña proporcionados por el administrador

---

## 2. PRIMEROS PASOS

### 2.1 Acceso al sistema

Abre tu navegador web y escribe la dirección (URL) del sistema. Por ejemplo:

```
http://servidor-metafoliador:8000
```

La dirección exacta te la proporcionará el administrador del sistema. Una vez ingreses, verás la pantalla de inicio de sesión.

### 2.2 Inicio de sesión

1. En la pantalla de inicio de sesión, verás dos campos:
   - **Correo Electrónico:** Ingresa tu correo electrónico registrado
   - **Contraseña:** Ingresa tu contraseña

2. Haz clic en el botón **"Iniciar Sesión"**

3. Si las credenciales son correctas, serás redirigido al **Dashboard** (panel principal)

4. Si las credenciales son incorrectas, verás un mensaje de error. Verifica que el correo y la contraseña estén bien escritos.

> **NOTA:** La sesión tiene una duración de 8 horas. Después de ese tiempo, deberás iniciar sesión nuevamente.

### 2.3 Cerrar sesión

Para cerrar sesión de forma segura:

1. Haz clic en el botón **"Cerrar Sesión"** que aparece en la barra de navegación superior
2. Serás redirigido a la pantalla de inicio de sesión
3. Ya no podrás acceder al sistema hasta que vuelvas a iniciar sesión

> **IMPORTANTE:** Siempre cierra sesión cuando termines de usar el sistema, especialmente si estás en un computador compartido.

### 2.4 Cambiar tema (claro/oscuro)

El sistema soporta dos temas visuales:

1. En la barra de navegación superior, busca el botón de cambio de tema (ícono de sol/luna)
2. Haz clic para alternar entre:
   - **Tema claro:** Fondo blanco, texto oscuro (recomendado para ambientes iluminados)
   - **Tema oscuro:** Fondo oscuro, texto claro (recomendado para ambientes con poca luz)
3. El sistema recordará tu preferencia mientras tengas la sesión abierta

---

## 3. EL DASHBOARD (PANEL PRINCIPAL)

Al iniciar sesión, llegarás al **Dashboard**, que es el panel de control principal. Aquí tienes una vista general de todo el sistema.

### 3.1 Estadísticas generales

En la parte superior del dashboard encontrarás tarjetas con números resumen:

| Tarjeta | ¿Qué muestra? |
|---------|---------------|
| **Sitios** | Número total de sitios de Alfresco configurados en el sistema |
| **Series, Subseries y Expedientes** | Número total de Series, Subseries y Expedientes sincronizadas desde Alfresco |
| **Archivos** | Número total de archivos registrados en el sistema |
| **Índices** | Número de Series, Subseries y Expedientes que ya tienen su `index.xml` generado |
| **Trabajos activos** | Número de tareas de sincronización en ejecución en este momento |

### 3.2 Gráficos interactivos

El dashboard incluye **3 gráficos estadísticos** que muestran la distribución de datos por sitio:

1. **Series, Subseries y Expedientes por Sitio:** Cuántas Series, Subseries y Expedientes tiene cada sitio
2. **Archivos por Sitio:** Cuántos archivos tiene cada sitio
3. **Índices por Sitio:** Cuántos índices electrónicos se han generado por sitio

**¿Cómo interactuar con los gráficos?**

- **Cambiar tipo de gráfico:** Sobre cada gráfico hay un selector desplegable. Puedes elegir entre 7 tipos diferentes: circular (pastel), barras, lineal, barras horizontales, radar, dona, área polar. El gráfico se actualiza inmediatamente.
- **Ver valores:** Al pasar el mouse sobre cualquier sección del gráfico, aparecerá un tooltip mostrando el valor exacto y el porcentaje.
- **Etiquetas:** Cada sección del gráfico muestra su valor numérico directamente.
- **Leyenda:** Debajo de cada gráfico aparece la leyenda con el nombre de cada sitio, el total y su porcentaje.
- **Top 20:** Los gráficos muestran los 20 sitios con más datos.

### 3.3 Registros de actividad reciente

En la parte inferior del dashboard, verás una tabla con los **registros recientes** de sincronización, mostrando:

- Sitio sincronizado
- Estado (completado, en progreso, fallido)
- Porcentaje de avance
- Mensaje descriptivo
- Fecha y hora

---

## 4. CONEXIONES A ALFRESCO

### 4.1 ¿Qué es una conexión?

Una **conexión** es la configuración que le dice a Metafoliador cómo comunicarse con un servidor Alfresco. Incluye la dirección del servidor, credenciales de acceso y otros parámetros. Sin una conexión configurada, el sistema no puede sincronizar documentos.

### 4.2 Ver conexiones existentes

1. En el menú lateral izquierdo, haz clic en **"Conexiones"**
2. Verás una tabla con todas las conexiones configuradas, mostrando:
   - **Nombre:** Nombre descriptivo de la conexión
   - **URL Base:** Dirección del servidor Alfresco
   - **Tipo de Auth:** basic (usuario/contraseña) u oauth2 (cliente/secreto)
   - **Activo:** Si la conexión está habilitada (verde) o deshabilitada (rojo)
   - **Última verificación:** Fecha y estado del último test de conexión
   - **Acciones:** Botones para editar, probar, descubrir sitios y eliminar

3. Puedes usar el campo de **búsqueda** para filtrar conexiones por nombre o URL

### 4.3 Crear una nueva conexión

Para conectar Metafoliador con un nuevo servidor Alfresco:

1. Ve a **Conexiones** en el menú lateral
2. Haz clic en el botón **"Nueva Conexión"**
3. Completa el formulario:

| Campo | ¿Qué debo poner? | ¿Es obligatorio? |
|-------|-------------------|-------------------|
| **Nombre** | Un nombre descriptivo, ej: "Alfresco Producción" | Sí |
| **URL Base** | La dirección del servidor Alfresco, ej: `https://alfresco.miempresa.com/alfresco` | Sí |
| **IP del Servidor** | Dirección IP del servidor Alfresco (necesaria si se usa el webhook listener) | Sí |
| **Tipo de Autenticación** | Selecciona `basic` (usuario/contraseña) o `oauth2` | Sí |
| **Usuario** | Tu usuario de Alfresco (solo para auth basic) | Solo si auth=basic |
| **Contraseña** | Tu contraseña de Alfresco (solo para auth basic) | Solo si auth=basic |
| **Client ID** | ID de cliente OAuth2 (solo para auth oauth2) | Solo si auth=oauth2 |
| **Client Secret** | Secreto de cliente OAuth2 (solo para auth oauth2) | Solo si auth=oauth2 |
| **Activo** | Dejar marcado para habilitar la conexión | Opcional |
| **Notas** | Información adicional que quieras registrar | Opcional |

4. Haz clic en **"Guardar"**
5. La nueva conexión aparecerá en la tabla

### 4.4 Editar una conexión

1. En la tabla de conexiones, haz clic en el botón **"Editar"** (ícono de lápiz) de la conexión que deseas modificar
2. Se abrirá el formulario de edición con los datos actuales
3. Modifica los campos que necesites actualizar
4. Haz clic en **"Guardar"**

### 4.5 Probar una conexión

Para verificar que la conexión a Alfresco funciona correctamente:

1. En la tabla de conexiones, haz clic en el botón **"Probar"** (ícono de verificación)
2. El sistema intentará conectarse al servidor Alfresco
3. Si la conexión es exitosa, verás un mensaje verde de confirmación y se actualizará la fecha de última verificación
4. Si falla, verás un mensaje de error. Verifica que la URL, usuario y contraseña sean correctos

> **TIP:** Siempre prueba una conexión después de crearla o modificarla para asegurarte de que funciona.

### 4.6 Descubrir sitios de Alfresco

Una vez que la conexión funciona, puedes pedirle al sistema que busque automáticamente todos los sitios disponibles en ese servidor Alfresco:

1. En la tabla de conexiones, haz clic en el botón **"Descubrir Sitios"** (ícono de búsqueda)
2. El sistema consultará Alfresco y registrará todos los sitios encontrados
3. Los sitios descubiertos aparecerán automáticamente en la sección de **Sitios**

### 4.7 Eliminar una conexión

1. En la tabla de conexiones, haz clic en el botón **"Eliminar"** (ícono de papelera)
2. El sistema te pedirá confirmación
3. **ADVERTENCIA:** Al eliminar una conexión, también se eliminarán todos los sitios, Series, Subseries y Expedientes y archivos asociados a esa conexión
4. Si estás seguro, confirma la eliminación

---

## 5. SITIOS DE ALFRESCO

### 5.1 ¿Qué es un sitio?

Un **sitio** en Alfresco es un espacio de trabajo que contiene Series, Subseries y Expedientes y documentos. Por ejemplo: "Contratos", "Historias Laborales", "Nómina". Cada sitio pertenece a una conexión de Alfresco.

### 5.2 Ver sitios existentes

1. En el menú lateral, haz clic en **"Sitios"**
2. Verás una tabla con todos los sitios registrados:
   - **Nombre:** Nombre del sitio
   - **Site ID:** Identificador único en Alfresco
   - **Conexión:** A qué servidor Alfresco pertenece
   - **Activo:** Si está habilitado
   - **Última sincronización:** Cuándo fue la última vez que se sincronizó
   - **Acciones:** Botones para editar, sincronizar y eliminar

3. Puedes filtrar por:
   - **Conexión:** Selecciona una conexión específica
   - **Solo activos:** Muestra solo sitios habilitados
   - **Búsqueda:** Buscar por nombre o site_id

### 5.3 Crear un sitio manualmente

Aunque normalmente los sitios se descubren automáticamente (ver sección 4.6), también puedes crearlos manualmente:

1. Ve a **Sitios** en el menú lateral
2. Haz clic en **"Nuevo Sitio"**
3. Completa el formulario:
   - **Nombre:** Nombre descriptivo del sitio
   - **Site ID:** El identificador exacto del sitio en Alfresco
   - **Conexión:** Selecciona a qué conexión pertenece
   - El resto de campos son opcionales (título, descripción, visibilidad, etc.)
4. Haz clic en **"Guardar"**

### 5.4 Editar un sitio

1. En la tabla de sitios, haz clic en **"Editar"** (ícono de lápiz)
2. Modifica los campos necesarios
3. Haz clic en **"Guardar"**

### 5.5 Eliminar un sitio

1. En la tabla de sitios, haz clic en **"Eliminar"** (ícono de papelera)
2. **ADVERTENCIA:** Se eliminarán todas las Series, Subseries y Expedientes, archivos e índices asociados a este sitio
3. Confirma la eliminación

---

## 6. CUADRO DE CLASIFICACIÓN Y SINCRONIZACIÓN

Esta es la sección más importante del sistema. Aquí es donde sincronizas los documentos desde Alfresco y generas los índices electrónicos.

### 6.1 Navegar el cuadro de clasificación

1. En el menú lateral, haz clic en **"Cuadro de Clasificación"**
2. Primero selecciona un **sitio** del selector desplegable en la parte superior
3. Una vez seleccionado el sitio, verás la estructura de Series, Subseries y Expedientes en forma de cuadro:
   - Las Series, Subseries y Expedientes se muestran con un ícono de Serie, Subserie o Expediente
   - Puedes hacer clic en el nombre de una Serie, Subserie o Expediente para **expandirla** y ver su contenido
   - Cada Serie, Subserie o Expediente muestra su nombre, número de archivos y un indicador de índice (✓ verde si tiene `index.xml`, ○ gris si no)

### 6.2 Iniciar una sincronización

La sincronización descarga la estructura de Series, Subseries y Expedientes y archivos desde Alfresco al sistema local. Hay dos formas de iniciarla:

**Opción A: Sincronizar todo el sitio**
1. En el cuadro de clasificación, selecciona el sitio
2. Haz clic en el botón **"Sincronizar Sitio"**
3. Se abrirá un panel donde puedes elegir las opciones de sincronización

**Opción B: Sincronizar una Serie, Subserie o Expediente específica**
1. Navega hasta la Serie, Subserie o Expediente que deseas sincronizar
2. Haz clic en el botón **"Sincronizar"** junto al nombre de la Serie, Subserie o Expediente
3. Se abrirá el panel de opciones

### 6.3 Modos de sincronización: Shallow vs Deep

Al iniciar una sincronización, debes elegir el modo:

| Modo | ¿Qué hace? | ¿Cuándo usarlo? |
|------|------------|-----------------|
| **Shallow** (Superficial) | Sincroniza solo el primer nivel de Series, Subseries y Expedientes y archivos | Cuando solo necesitas actualizar una Serie, Subserie o Expediente específica rápidamente |
| **Deep** (Profundo) | Sincroniza recursivamente TODAS las Series, Subseries y Expedientes y subseries y expedientes | Para la primera sincronización de un sitio, o cuando necesitas datos completos |

**Opción de generar índice:**
- **Marcado (recomendado):** Después de sincronizar, genera automáticamente el `index.xml` para cada Serie, Subserie o Expediente
- **Desmarcado:** Solo sincroniza la estructura, sin generar índices (más rápido pero no tendrás índices electrónicos)

> **RECOMENDACIÓN:** Para la primera sincronización de un sitio, usa modo **Deep** con **Generar Índice** activado. Esto asegurará que tengas todos los datos completos con sus índices.

### 6.4 Monitorear el progreso

Una vez que inicias una sincronización:

1. Verás una barra de progreso que muestra:
   - **Porcentaje de avance** (0% a 100%)
   - **Series, Subseries y Expedientes procesadas / Total de Series, Subseries y Expedientes**
   - **Mensaje de estado** (ej: "Recorriendo Series, Subseries y Expedientes...", "Generando índices...", "Completado")
2. La sincronización puede tomar varios minutos e incluso **horas** en sitios con muchas Series, Subseries y Expedientes o carpetas con más de 500 archivos (el sistema procesa estos listados en páginas para no perder elementos)
3. Cuando termine, verás el estado **"Completado"** y la barra al 100%
4. Si ocurre un error, verás **"Fallido"** y un mensaje de error

**También puedes ver el progreso desde la sección de [Trabajos en Cola](#8-trabajos-en-cola).**

### 6.5 Ver archivos de una Serie, Subserie o Expediente

1. Expande una Serie, Subserie o Expediente en el cuadro
2. Debajo de la Serie, Subserie o Expediente aparecerá la lista de archivos:
   - **Nombre del archivo**
   - **Tipo:** MIME type (PDF, DOCX, imagen, etc.)
   - **Tamaño:** En formato legible (KB, MB)
   - **Folios:** Número de páginas del documento
   - **Hash SHA-256:** Huella digital del archivo (integridad)
   - **Estado:** Activo o Eliminado

---

## 7. ÍNDICES ELECTRÓNICOS (index.xml)

### 7.1 ¿Qué es un índice electrónico?

Un **índice electrónico** es un archivo XML (llamado `index.xml`) que contiene una lista ordenada y detallada de todos los documentos que hay en una Serie, Subserie o Expediente. Cumple con el formato colombiano `TipoDocumentoFoliado` y contiene para cada documento:

- Nombre del archivo
- Tipología documental (extraída automáticamente del nombre de la Serie, Subserie o Expediente)
- Hash SHA-256 para verificar integridad
- Fecha de creación
- Número de páginas (folios)
- Orden en el expediente
- Estado (Activo/Eliminado)

### 7.2 ¿Cuándo se genera un índice?

Los índices se generan automáticamente durante la sincronización si la opción **"Generar Índice"** está activada. También se regeneran automáticamente cuando:

- Se detecta que un archivo fue eliminado en Alfresco
- Se agrega un nuevo archivo a la Serie, Subserie o Expediente
- Se mueve un archivo de una Serie, Subserie o Expediente a otra
- Se recibe un evento del Webhook Listener (creación/modificación/eliminación)

### 7.3 Ver el contenido de un índice

1. En el cuadro de clasificación, busca una Serie, Subserie o Expediente que tenga el indicador **✓ verde** (índice generado)
2. Haz clic en el botón **"Ver Índice"** (ícono de documento) junto al nombre de la Serie, Subserie o Expediente
3. El sistema mostrará el contenido del archivo `index.xml` en formato XML
4. Puedes ver todos los documentos listados con sus metadatos

### 7.4 Ver el estado de los índices

En el cuadro de clasificación, cada Serie, Subserie o Expediente muestra un indicador visual:
- **✓ Verde:** La Serie, Subserie o Expediente tiene su `index.xml` generado y actualizado
- **○ Gris:** La Serie, Subserie o Expediente aún no tiene índice (necesita sincronización con "Generar Índice" activado)

---

## 8. TRABAJOS EN COLA

### 8.1 ¿Qué son los trabajos?

Cada vez que inicias una sincronización, el sistema crea un **trabajo** (job) que se procesa en segundo plano. Esto permite que puedas seguir usando el sistema mientras la sincronización avanza.

### 8.2 Ver trabajos activos

1. En el menú lateral, haz clic en **"Trabajos"**
2. Verás una tabla con todos los trabajos:

| Columna | Significado |
|---------|------------|
| **ID** | Identificador único del trabajo |
| **Sitio** | Sitio que se está sincronizando |
| **Serie, Subserie o Expediente** | Serie, Subserie o Expediente específica (si es sync de Serie, Subserie o Expediente individual) |
| **Estado** | pending (en espera), running (en progreso), completed (terminado), failed (fallido) |
| **Progreso** | Porcentaje de avance |
| **Mensaje** | Descripción de lo que está haciendo |
| **Creado** | Cuándo se inició el trabajo |
| **Actualizado** | Última vez que se actualizó el progreso |

3. Puedes filtrar por **estado** (todos, pending, running, completed, failed)
4. Puedes ajustar el **límite** de trabajos mostrados (por defecto 50, máximo 200)

### 8.3 Cancelar un trabajo

Si iniciaste una sincronización por error o ya no la necesitas:

1. Ve a la sección de **Trabajos**
2. Busca el trabajo que deseas cancelar (debe estar en estado `pending` o `running`)
3. Haz clic en el botón **"Cancelar"** (ícono de X)
4. El trabajo se detendrá inmediatamente

> **NOTA:** Solo puedes cancelar trabajos que estén pendientes o en ejecución. Los trabajos ya completados o fallidos no se pueden cancelar.

### 8.4 Limpiar la cola de trabajos

Si necesitas limpiar todos los trabajos pendientes y en ejecución:

1. Ve a la sección de **Trabajos**
2. Haz clic en el botón **"Limpiar Cola"**
3. Confirma la acción
4. Todos los trabajos pendientes y en ejecución serán cancelados y eliminados

> **ADVERTENCIA:** Esta acción es irreversible. Las sincronizaciones en curso se detendrán inmediatamente.

---

## 9. GESTIÓN DE USUARIOS

### 9.1 Ver lista de usuarios

1. En el menú lateral, haz clic en **"Usuarios"** (solo visible si tienes el permiso `usuarios.view`)
2. Verás una tabla con todos los usuarios del sistema:
   - **Nombre:** Nombre completo
   - **Correo:** Email de inicio de sesión
   - **Rol:** Rol asignado
   - **Activo:** Si puede iniciar sesión (verde) o no (rojo)
   - **Creado:** Fecha de registro
   - **Acciones:** Editar y eliminar

3. Puedes usar el campo de **búsqueda** para filtrar por nombre o correo

### 9.2 Crear un nuevo usuario

1. En la sección de **Usuarios**, haz clic en **"Nuevo Usuario"**
2. Completa el formulario:

| Campo | Descripción | ¿Obligatorio? |
|-------|-------------|----------------|
| **Correo Electrónico** | Email para iniciar sesión (debe ser único) | Sí |
| **Contraseña** | Contraseña para el usuario | Sí |
| **Nombre** | Nombre completo del usuario | No (default: vacío) |
| **Rol** | Rol del usuario (legacy; el RBAC real usa la sección de Roles) | No (default: "user") |
| **Activo** | Si el usuario puede iniciar sesión | No (default: Sí) |

3. Haz clic en **"Guardar"**
4. El nuevo usuario podrá iniciar sesión inmediatamente con el correo y contraseña proporcionados

### 9.3 Editar un usuario

1. En la tabla de usuarios, haz clic en **"Editar"** (ícono de lápiz)
2. Puedes modificar: nombre, rol, estado activo/inactivo, y contraseña
3. Si dejas el campo de contraseña vacío, la contraseña actual no se modificará
4. Haz clic en **"Guardar"**

### 9.4 Eliminar un usuario

1. En la tabla de usuarios, haz clic en **"Eliminar"** (ícono de papelera)
2. Confirma la eliminación
3. El usuario será eliminado permanentemente del sistema

---

## 10. ROLES Y PERMISOS (RBAC)

### 10.1 ¿Qué son los roles?

Los **roles** determinan qué puede hacer cada usuario en el sistema. Un rol es un conjunto de permisos que se asigna a un usuario. Ejemplos: "Administrador", "Consultor", "Operador de Sincronización".

### 10.2 ¿Qué son los permisos?

Los **permisos** son acciones específicas que un usuario puede realizar. Por ejemplo: "Ver Conexiones", "Crear Usuario", "Sincronizar Series, Subseries y Expedientes". Hay 32 permisos diferentes en el sistema, organizados por módulos.

### 10.3 Ver roles existentes

1. En el menú lateral, haz clic en **"Roles"** (solo visible con permiso `roles.view`)
2. Verás una tabla con todos los roles:
   - **Nombre:** Nombre del rol
   - **Todos los Permisos:** Si es un superusuario (tiene acceso total)
   - **Permisos Asignados:** Cuántos permisos específicos tiene
   - **Usuarios:** Cuántos usuarios tienen este rol
   - **Descripción:** Descripción del rol
   - **Acciones:** Editar y eliminar

### 10.4 Crear un nuevo rol

1. En la sección de **Roles**, haz clic en **"Nuevo Rol"**
2. Completa:

| Campo | Descripción |
|-------|-------------|
| **Nombre** | Nombre del rol, ej: "Operador de Sincronización" |
| **Todos los Permisos** | Si lo activas, este rol tendrá acceso TOTAL al sistema (superusuario). Úsalo con precaución |
| **Descripción** | Explicación de para qué sirve este rol |
| **Permisos** | Si NO marcaste "Todos los Permisos", selecciona uno por uno los permisos que tendrá este rol. Están agrupados por módulos para facilitar la selección |

3. Haz clic en **"Guardar"**

### 10.5 Editar un rol

1. En la tabla de roles, haz clic en **"Editar"** (ícono de lápiz)
2. Modifica nombre, descripción, flag de todos los permisos, o permisos específicos
3. Haz clic en **"Guardar"**

### 10.6 Lista de permisos disponibles

Aquí están los 32 permisos organizados por módulo:

**Dashboard:**
- `dashboard.view` — Ver el panel principal

**Conexiones API:**
- `conexiones.view` — Ver la lista de conexiones
- `conexiones.create` — Crear nuevas conexiones
- `conexiones.edit` — Editar conexiones existentes
- `conexiones.delete` — Eliminar conexiones
- `conexiones.sync` — Iniciar sincronización desde conexiones

**Sitios:**
- `sitios.view` — Ver la lista de sitios
- `sitios.create` — Crear sitios manualmente
- `sitios.edit` — Editar sitios
- `sitios.delete` — Eliminar sitios
- `sitios.sync` — Sincronizar sitios

**Series, Subseries y Expedientes:**
- `carpetas.view` — Ver el cuadro de clasificación
- `carpetas.sync` — Iniciar sincronización de Series, Subseries y Expedientes

**Índice Electrónico:**
- `index.view` — Ver contenido de índices
- `index.generate` — Generar índices

**Usuarios:**
- `usuarios.view` — Ver lista de usuarios
- `usuarios.create` — Crear usuarios
- `usuarios.edit` — Editar usuarios
- `usuarios.delete` — Eliminar usuarios

**Roles:**
- `roles.view` — Ver roles y permisos
- `roles.create` — Crear roles
- `roles.edit` — Editar roles
- `roles.delete` — Eliminar roles

**Trabajos en Cola:**
- `jobs.view` — Ver trabajos
- `jobs.cancel` — Cancelar trabajos
- `jobs.purge` — Limpiar cola

**Logs API:**
- `listener-logs.view` — Ver logs del webhook listener

**Reportes:**
- `reportes.generate` — Generar cualquier reporte (TRD Tipologías, Gráficos por Dependencia, reportes externos)
- `reportes.create` — Crear reportes externos
- `reportes.edit` — Editar reportes externos
- `reportes.delete` — Eliminar reportes externos
- `reportes.toggle` — Activar/inactivar reportes

### 10.7 Eliminar un rol

1. En la tabla de roles, haz clic en **"Eliminar"** (ícono de papelera)
2. Confirma la eliminación
3. Los usuarios que tenían este rol ya no tendrán esos permisos

---

## 11. REPORTES

### 11.1 Tipos de reportes

El sistema ofrece **tres tipos de reportes**:

| Reporte | Formato | ¿Qué contiene? |
|---------|---------|----------------|
| **TRD de Tipologías** | Excel (.xlsx) | Cuadro jerárquico de clasificación con conteo de archivos por tipología documental |
| **Gráficos por Dependencia** | PDF (.pdf) | Gráficos estadísticos por dependencia: tipologías, extensiones de archivo y series documentales |
| **FUID** | Excel (.xlsx) y PDF (.pdf) | Formato Único de Inventario Documental según lineamientos AGN: códigos TRD, series, subseries, fechas extremas, folios totales |

### 11.2 Generar reporte TRD de Tipologías (Excel)

Este reporte te muestra cuántos archivos hay en cada Serie, Subserie o Expediente, organizados por la tipología documental (identificada automáticamente desde los nombres de Serie, Subserie o Expediente).

1. En el menú lateral, haz clic en **"Reportes"**
2. En la sección **"TRD de Tipologías"**:
   a. Selecciona el **sitio** del cual quieres el reporte
   b. Define el **nivel máximo** de profundidad (por defecto 3). Esto controla cuántos niveles de subseries y expedientes se incluyen
   c. Haz clic en **"Generar Reporte"**
3. El sistema comenzará a generar el reporte. Verás un indicador de progreso
4. Cuando el estado sea **"Completado"**, aparecerá el botón **"Descargar Excel"**
5. Haz clic en **"Descargar Excel"** para obtener el archivo

**Columnas del reporte:**
- Nivel 1, Nivel 2, Nivel 3... — Jerarquía de Series, Subseries y Expedientes
- Archivos — Cantidad de documentos en esa Serie, Subserie o Expediente o "SIN TIPOLOGIA - N archivos" si la Serie, Subserie o Expediente no sigue el patrón de tipología

### 11.3 Generar reporte de Gráficos por Dependencia (PDF)

Este reporte genera un PDF con gráficos estadísticos para cada dependencia (Serie, Subserie o Expediente de primer nivel del sitio).

1. En la sección de **"Reportes"**, busca **"Gráficos por Dependencia"**
2. Selecciona el **sitio** del cual quieres el reporte
3. Selecciona el **tipo de gráfico** deseado:

| Tipo de gráfico | ¿Cómo se ve? |
|----------------|--------------|
| **barras** | Barras verticales comparativas |
| **circular** | Gráfico de pastel con porcentajes |
| **lineal** | Líneas de tendencia |
| **barras_horizontal** | Barras horizontales |
| **area** | Áreas acumulativas |
| **dispersion** | Puntos de dispersión |
| **histograma** | Barras de frecuencia |

4. Puedes seleccionar **múltiples tipos** separándolos por coma (ej: `barras,circular`)
5. Haz clic en **"Generar Reporte"**
6. Espera a que el estado sea **"Completado"**
7. Haz clic en **"Descargar PDF"**

**Contenido del PDF por cada dependencia:**
1. Tabla resumen: nombre de dependencia y cantidad de índices
2. Gráfico de tipologías documentales (Series, Subseries y Expedientes con patrón N.N)
3. Gráfico de extensiones de archivo (PDF, DOCX, etc.)
4. Gráfico de series documentales (subseries y expedientes del siguiente nivel)

### 11.4 Generar reporte FUID (Excel y PDF)

El **FUID (Formato Único de Inventario Documental)** es un reporte que cumple con los lineamientos del Archivo General de la Nación (AGN) para la elaboración de inventarios documentales. Se puede generar en formato **Excel** o **PDF**.

El reporte organiza la información en la estructura de **Tabla de Retención Documental (TRD)** de 3 niveles:
1. **Dependencia** (primer nivel)
2. **Serie documental** (segundo nivel)
3. **Subserie documental** (tercer nivel)

Los códigos TRD se extraen automáticamente del nombre de las carpetas (formato `X-XXXX-X-XX.N`).

**Instrucciones:**

1. En el menú lateral, haz clic en **"Reportes"**
2. Busca el reporte **"FUID (Formato Único de Inventario Documental)"** y haz clic en **"Generar"**
3. En el modal que se abre:
   a. Selecciona el **sitio Alfresco** del cual quieres el reporte
   b. Selecciona una **dependencia** específica o deja "Todas las dependencias" para generar el reporte completo del sitio
   c. Elige el **formato de salida**: Excel (.xlsx) o PDF
   d. Haz clic en **"Generar Reporte"**
4. El sistema comenzará a generar el reporte en segundo plano. Verás un indicador de progreso
5. Cuando el estado sea **"Completado"**, aparecerá el botón **"Descargar Reporte FUID"**
6. Haz clic para descargar el archivo

**Comportamiento según dependencia seleccionada:**
- **Con dependencia**: genera el reporte solo para esa dependencia
- **Sin dependencia (Todas)**: genera para todas las dependencias del sitio. En Excel, cada dependencia en una hoja separada. En PDF, cada dependencia en una página separada.

**Columnas del reporte:**

| Columna | Descripción |
|---------|-------------|
| No. | Número secuencial |
| CÓDIGO DEPENDENCIA | Código TRD de la dependencia |
| DEPENDENCIA | Nombre de la dependencia |
| CÓDIGO SERIE | Código TRD de la serie documental |
| SERIE DOCUMENTAL | Nombre de la serie |
| CÓDIGO SUBSERIE | Código TRD de la subserie |
| SUBSERIE DOCUMENTAL | Nombre de la subserie |
| FECHA INICIAL | Fecha del primer documento en la unidad |
| FECHA FINAL | Fecha del último documento en la unidad |
| NÚMERO DE FOLIOS | Total de folios (páginas) de todos los archivos |
| SOPORTE | Tipo de soporte (Digital) |
| NOTAS | Campo para observaciones manuales |

**Datos importantes:**
- Los archivos `index.xml` (índices electrónicos) se excluyen del conteo
- Las fechas extremas abarcan desde el primer hasta el último documento dentro de cada serie+subserie
- Los folios se suman para todas las carpetas bajo la misma serie y subserie
- Las carpetas sin archivos también aparecen (con 0 folios)
- Los códigos TRD se extraen del formato `X-XXXX-X-XX.N` en el nombre de carpeta; si no tiene este formato, el código queda vacío

**Encabezado y pie de página (estilo AGN):**
- **Encabezado**: ENTIDAD REMITENTE, ENTIDAD PRODUCTORA, UNIDAD ADMINISTRATIVA, OFICINA PRODUCTORA, OBJETO
- **Esquina derecha**: HOJA N° ___ DE ___, REGISTRO DE ENTRADA (AÑO, MES, DÍA, Nº T)
- **Pie**: ELABORADO POR, ENTREGADO POR, RECIBIDO POR (cada uno con Cargo, Firma, Lugar y Fecha)

### 11.5 Descargar un reporte generado

Cada reporte que generes queda disponible para descarga. Si cierras la página o el navegador, el reporte seguirá estando disponible en la lista. Simplemente vuelve a la sección de reportes, busca el tuyo por su estado ("Completado") y descárgalo.

### 11.6 Activar o desactivar reportes

Algunos reportes pueden activarse o desactivarse según las necesidades de la organización. Consulta con tu administrador si un tipo de reporte no está disponible.

---

## 12. LOGS DEL WEBHOOK LISTENER

### 12.1 ¿Qué son los logs del listener?

Cuando Alfresco detecta cambios en documentos o Series, Subseries y Expedientes, envía notificaciones automáticas al sistema (llamadas **webhooks**). El sistema registra cada una de estas notificaciones en un log, permitiendo hacer seguimiento de toda la actividad en tiempo real.

### 12.2 Ver los logs

1. En el menú lateral, haz clic en **"Logs API"** (solo visible con permiso `listener-logs.view`)
2. Verás una tabla paginada con el historial de notificaciones recibidas:

| Columna | Significado |
|---------|------------|
| **ID** | Número único del registro |
| **IP Remota** | Dirección IP del servidor Alfresco que envió la notificación |
| **URL** | Endpoint que recibió la notificación |
| **Método** | Método HTTP (siempre POST) |
| **Estado** | Código HTTP de respuesta (200 = éxito, 403 = no autorizado, 500 = error) |
| **Autorizado** | ✓ si la IP estaba autorizada, ✗ si no |
| **Duración** | Tiempo que tomó procesar la notificación (en milisegundos) |
| **Creado** | Fecha y hora en que se recibió |
| **Detalles** | Botón para ver el cuerpo completo de la solicitud y respuesta |

3. Puedes navegar entre páginas usando los controles de paginación

### 12.3 Interpretar la información de los logs

- **Estado 200 + Autorizado ✓:** La notificación se recibió y procesó correctamente
- **Estado 403 + Autorizado ✗:** La notificación fue rechazada porque la IP no está en la lista de autorizadas. Revisa la configuración de `ip_server` en la conexión Alfresco
- **Estado 500:** Ocurrió un error al procesar la notificación. Revisa los detalles del error
- **Duración alta:** Si el tiempo de procesamiento es muy alto (>5000ms), puede indicar problemas de rendimiento

---

## 13. SOLUCIÓN DE PROBLEMAS COMUNES

### No puedo iniciar sesión

- Verifica que estás usando el **correo electrónico correcto** (no un nombre de usuario)
- Asegúrate de que las **mayúsculas/minúsculas** son correctas
- Pregunta al administrador si tu cuenta está **activa**
- Si olvidaste tu contraseña, contacta al administrador del sistema

### Una sincronización se queda en 0% o no avanza

- Ve a la sección de **Trabajos** y revisa el estado del trabajo
- Si dice `running` pero no avanza, puede que haya mucha carga. Espera unos minutos
- Una sincronización de un sitio grande puede durar **horas**: es normal que esté `running` mucho tiempo. Solo cancela si el porcentaje baja de golpe (indica reinicio) o si lleva varios días sin cambios
- Verifica que la **conexión a Alfresco** esté funcionando (prueba la conexión)

### No veo el botón de "Sincronizar"

- Necesitas el permiso `carpetas.sync` o `sitios.sync`. Contacta al administrador

### El índice no se genera (el indicador sigue en gris ○)

- Asegúrate de que al sincronizar marcaste la opción **"Generar Índice"**
- Vuelve a sincronizar la Serie, Subserie o Expediente con la opción activada
- Verifica que el usuario de Alfresco tenga **permisos de escritura** en esa Serie, Subserie o Expediente

### No puedo ver ciertas secciones del menú

- El menú se adapta según tus **permisos**. Si no ves una sección, significa que tu usuario no tiene el permiso correspondiente
- Contacta al administrador para que te asigne los permisos necesarios

### El reporte no se descarga

- Asegúrate de que el estado sea **"Completado"**
- Si el estado es "Fallido", intenta generar el reporte de nuevo
- Verifica que el sitio seleccionado tenga Series, Subseries y Expedientes sincronizadas (no vacío)
- Revisa que tengas el permiso `reportes.generate`

### Los gráficos del dashboard no cargan

- Recarga la página (F5)
- Asegúrate de tener conexión a internet (los gráficos usan las librerías Chart.js desde CDN)
- Verifica que tengas al menos un sitio sincronizado con datos

---

## 14. GLOSARIO

| Término | Significado |
|---------|-------------|
| **Alfresco** | Sistema de gestión de documentos donde se almacenan los archivos originales |
| **Conexión** | Configuración que permite a Metafoliador comunicarse con un servidor Alfresco |
| **Dashboard** | Panel principal con estadísticas y gráficos del sistema |
| **Deep Sync** | Sincronización recursiva: recorre todas las Series, Subseries y Expedientes y subseries y expedientes |
| **Folio** | Página de un documento |
| **Hash SHA-256** | Huella digital única de un archivo para verificar que no ha sido alterado |
| **Índice Electrónico** | Archivo index.xml que lista todos los documentos de una Serie, Subserie o Expediente en formato colombiano |
| **JWT** | Token de autenticación que mantiene tu sesión iniciada |
| **MIME Type** | Tipo de archivo (PDF, DOCX, imagen, etc.) |
| **RBAC** | Control de acceso basado en roles (determina qué puede hacer cada usuario) |
| **Shallow Sync** | Sincronización superficial: solo el primer nivel de Series, Subseries y Expedientes |
| **Sitio** | Espacio de trabajo en Alfresco que contiene Series, Subseries y Expedientes y documentos |
| **Soft Delete** | Un archivo marcado como eliminado pero que aún conserva su información |
| **Tipología Documental** | Clasificación del tipo de documento según su función |
| **TRD** | Tabla de Retención Documental |
| **Webhook** | Notificación automática que envía Alfresco cuando hay cambios |
| **XML** | Formato de archivo estructurado usado para los índices electrónicos |

---

**Fin del Manual de Usuario — Metafoliador v2.0.0**