Manual de Usuario de SQLVantage (Español)

1. Descripción General del Sistema
2. Instalación y Despliegue (Windows / Linux)
3. Instrucciones de Configuración
4. Guía del Administrador
5. Guía de Diseño de Informes (SQL/FORM/HTML)
6. Guía del Usuario Final
7. Ejecución de Solicitudes y Resultados de Salida
8. Preguntas Frecuentes (FAQ)
9. Apéndice: Almacenamiento de Datos, Copias de Seguridad y Migración

1.1 ¿Qué es SQLVantage?

SQLVantage es un sistema de informes basado en la web. El "administrador" mantiene las definiciones de los informes, mientras que los "usuarios finales" seleccionan un informe en la página web, completan las condiciones de consulta, obtienen los resultados de forma asíncrona y los exportan como Excel / HTML / JSON / TEXT.

1.2 Stack Tecnológico

Este sistema posee una arquitectura web pura: no es necesario instalar ningún cliente o plug-in en el navegador; cualquier navegador moderno puede acceder a él. En el lado del servidor, solo se requiere el programa ejecutable y sus directorios de configuración correspondientes para funcionar, lo que simplifica el despliegue.

1.3 Conceptos Clave

1.4 Roles de Usuario

1.5 Estructura de Directorios

Los archivos principales después de extraer el paquete de lanzamiento:

SQLVantage/
├── SQLVantage.exe / sqlvantage   # Programa principal (Windows / Linux)
├── conf/
│   ├── app.conf        # Configuración del sistema (Puerto / Idioma / Oracle, etc.)
│   ├── data.dat        # Base de datos de negocio (Usuarios / Responsabilidades / Informes / Solicitudes)
│   ├── license.dat     # Archivo de licencia
│   └── locale/         # Paquetes de idioma
├── data/               # Generado en tiempo de ejecución: <ID_Solicitud>.xlsx / <ID_Solicitud>.json
├── docs/               # Documentación de usuario (Multilingüe, incluye images/)
└── tmp/                # Archivos temporales (Sesiones, Tareas)

2.1 Requisitos del Entorno

• Sistema operativo: Windows 7+ / Linux de 64 bits (x86_64)
• Modo de ejecución (recomendado): utilice directamente el ejecutable publicado (SQLVantage.exe o el binario de Linux); no es necesario instalar ningún entorno de ejecución.
• Base de datos Oracle: la ejecución de informes requiere conectividad con Oracle (el sistema se conecta a Oracle EBS por defecto); por favor, confirme la red y la cuenta con antelación.
• Permisos de disco/directorio: el directorio de trabajo del programa debe tener permisos de escritura, ya que durante la ejecución se crean los directorios data/ y tmp/ y se leen/escriben archivos en conf/.

2.2 Instalación en Windows

1. Extraer: extraiga el paquete de lanzamiento (zip) en cualquier directorio, por ejemplo D:\SQLVantage\. Después de la extracción, confirme que existan los siguientes archivos clave:

   D:\SQLVantage\
   ├── SQLVantage.exe      # Programa principal
   ├── conf\app.conf       # Archivo de configuración
   ├── conf\data.dat       # Base de datos (DB vacía incluida en el paquete)
   └── conf\locale\        # Paquetes de idioma
   

2. (Opcional) Modificar la configuración: abra conf\app.conf con el Bloc de notas y modifique la dirección de escucha, el puerto, la conexión a Oracle, etc., según el Capítulo 3.

3. Iniciar el programa: haga doble clic en SQLVantage.exe o ejecútelo en la línea de comandos:

   cd D:\SQLVantage
   SQLVantage.exe
   

   Tras un inicio exitoso, la consola imprimirá la información de la versión y el estado de la licencia, y entrará en estado de escucha.

4. Acceder al sistema: abra http://127.0.0.1:8080 en un navegador (dirección predeterminada; puede modificarse en app.conf).

5. Configuración del Firewall: si se necesita acceso LAN/remoto, abra el puerto correspondiente (como el 8080) en el firewall de Windows:

   netsh advfirewall firewall add rule name="SQLVantage" dir=in action=allow protocol=TCP localport=8080
   

2.3 Instalación en Linux

1. Extraer: extraiga el paquete de lanzamiento (tar.gz o zip) en el directorio de destino, por ejemplo /opt/sqlvantage:

   mkdir -p /opt/sqlvantage
   tar -xzf sqlvantage-linux-amd64.tar.gz -C /opt/sqlvantage
   cd /opt/sqlvantage
   

2. Otorgar permisos de ejecución:

   chmod +x sqlvantage
   

3. (Opcional) Modificar la configuración: edite conf/app.conf (igual que en Windows).

4. Probar el inicio en primer plano:

   ./sqlvantage
   

   Cuando vea la información de la versión y el registro de escucha, el inicio habrá tenido éxito; presione Ctrl+C para detenerlo.

5. Ejecutar en segundo plano (se recomienda systemd o nohup):

   Método A: nohup

   cd /opt/sqlvantage
   nohup ./sqlvantage > sqlvantage.log 2>&1 &
   

   Método B: systemd (crear /etc/systemd/system/sqlvantage.service):

   [Unit]
   Description=SQLVantage Report System
   After=network.target
   
   [Service]
   WorkingDirectory=/opt/sqlvantage
   ExecStart=/opt/sqlvantage/sqlvantage
   Restart=always
   RestartSec=5
   User=sqlvantage
   
   [Install]
   WantedBy=multi-user.target
   

   Luego ejecute:

   systemctl daemon-reload
   systemctl enable sqlvantage
   systemctl start sqlvantage
   systemctl status sqlvantage
   

6. Firewall / Grupo de seguridad: abra el puerto (como el 8080):

   firewall-cmd --permanent --add-port=8080/tcp && firewall-cmd --reload
   

2.4 Compilación desde el Código Fuente (Opcional)

Disponible solo para usuarios que hayan obtenido el código fuente: ejecute el comando de compilación en el directorio de origen para producir un ejecutable para la plataforma actual. Para un entorno de despliegue formal, se recomienda utilizar directamente el ejecutable publicado oficialmente.

2.5 Primer Inicio

En el primer inicio, el sistema completa automáticamente la siguiente inicialización:

1. Comprobar el archivo de datos: lee conf/data.dat (incluido en el paquete; si falta, el programa indica "conf/data.dat is not found" y sale — por favor, no elimine este archivo).
2. Creación automática de tablas: las cuatro tablas user, responsibility, report y request se crean automáticamente.
3. Creación automática de la cuenta de administrador: en la primera visita a /admin/login, si el usuario root no existe, el sistema lo crea automáticamente:
   • Nombre de usuario: root
   • Contraseña inicial: SQLVantage
   • Rol: admin (administrador)
   • Recordatorio de seguridad: cambie esta contraseña inmediatamente después del primer inicio de sesión (el administrador puede cambiarla en "Gestión de Usuarios").
4. Comprobar el archivo de licencia: si conf/license.dat falta o es inválido, la consola imprime una advertencia; el sistema puede seguir funcionando, pero está sujeto a las restricciones de licencia en la Sección 4.7.

3.1 Ubicación del Archivo de Configuración

El archivo de configuración es conf/app.conf (formato INI). Hay dos formas de modificarlo:

• Método 1 (recomendado, vía interfaz de usuario): tras iniciar sesión como administrador, vaya a "Configuración del Sistema" (/admin/setting), complete los valores y guarde; el sistema escribirá automáticamente los cambios en app.conf.
• Método 2 (editar el archivo directamente): modifique conf/app.conf con un editor de texto y luego reinicie el programa.

3.2 Tabla de Referencia de Parámetros

3.3 Cuándo Entran en Vigor los Cambios

• sessiongcmaxlifetime: entra en vigor inmediatamente después de guardar.
• Otros parámetros (puerto, Oracle, etc.): el programa debe reiniciarse para que los cambios surtan efecto.

3.4 Cambio de Idioma

• El sistema tiene 12 idiomas integrados: zh-CN, zh-TW, en-US, ja-JP, ko-KR, fr-FR, de-DE, es-ES, th-TH, vi-VN, ru-RU, pt-PT.
• Cómo cambiar: añada ?lang=zh-CN a la URL (ej. /?lang=zh-CN), o cambie a través del menú de idiomas en la esquina superior derecha de la consola de administración; tras la selección, se escribe en una Cookie válida por 1 año.

4.1 Inicio de Sesión del Administrador

1. En un navegador, visite http://<dirección del servidor>:<puerto>/admin/login.
2. Inicie sesión con la cuenta de administrador (inicialmente root / SQLVantage).
3. Tras un inicio de sesión exitoso, se abre la consola de administración (/admin); el menú izquierdo contiene: Gestión de Informes, Gestión de Responsabilidades, Gestión de Usuarios, Gestión de Solicitudes, Gestión de Licencias, Configuración del Sistema, Panel de Control, Acerca de.

Nota: la cuenta de administrador debe cumplir con Rol = admin y Estado = active; de lo contrario, no podrá acceder a la consola de administración.

4.2 Panel de Control y Navegación Superior

• La navegación superior permite saltos rápidos: Panel de Control (/admin), Ejecución de Informes (/request, ventana nueva) y Portal de Inicio (/).
• En la esquina superior derecha, puede cambiar el idioma o cerrar la sesión (/admin/logout).

4.3 Gestión de Usuarios

Acceso: /admin/user (menú izquierdo "Gestión de Usuarios").

Referencia de campos de usuario:

Operaciones:

• Crear: haga clic en el botón "Nuevo" $\rightarrow$ complete el nombre de usuario/email/rol/estado/contraseña/confirmar contraseña $\rightarrow$ enviar.
• Editar: haga clic en "Editar" en la fila $\rightarrow$ se pueden cambiar el email, el rol y el estado; dejar la contraseña en blanco significa que no hay cambios.
• Eliminar: haga clic en "Eliminar" en la fila. Nota:
  • La cuenta root no puede eliminarse.
  • Un usuario que sea propietario de informes no puede eliminarse (sus informes deben eliminarse o transferirse primero).

Consejos de gestión:

• El acceso de inicio de sesión para usuarios finales es /login (página de inicio), y el de administrador es /admin/login; ambos son diferentes.
• Establecer un usuario final como inactive es suficiente para bloquear su acceso; no es necesario eliminar la cuenta.
• root se oculta automáticamente en la lista de usuarios.

4.4 Gestión de Responsabilidades

Acceso: /admin/responsibility (menú izquierdo "Gestión de Responsabilidades").

Referencia de campos de responsabilidad:

Operaciones:

• Crear: haga clic en "Nuevo" $\rightarrow$ seleccione una responsabilidad de un usuario desde el desplegable (los datos provienen de la interfaz de consulta de Oracle EBS /api/user/responsibilities/); tras la selección, RespId / RespKey / Name se completan automáticamente; también puede completarse manualmente $\rightarrow$ enviar.
• Editar / Eliminar: botones en la fila. Nota: una responsabilidad referenciada por un informe no puede eliminarse.

Propósito: cada informe debe pertenecer a una responsabilidad; el "Menú de Informes" para el usuario final se agrupa por responsabilidad (los informes sin responsabilidad se colocan en el grupo "Sin categoría").

4.5 Gestión de Informes

Acceso: /admin/report (menú izquierdo "Gestión de Informes").

Campos del informe:

Ciclo de vida del informe (Importante):

Draft (Borrador, fase de diseño) ──▶ Release (Publicado, visible para el usuario)
       │                        │
       │                        └──▶ No puede eliminarse directamente, debe cambiarse primero a Draft/Discard
       └──▶ Discard (Descartado, no visible para el usuario)

• Solo los informes con estado Release aparecen en el menú de informes del usuario final.
• Los informes publicados (Release) no pueden eliminarse; primero cambie el estado a Draft o Discard en la lista y luego elimine.
• Las columnas "Nombre", "Descripción" y "Estado" admiten la edición directa haciendo doble clic en la celda (guardado automático).

Operaciones:

4.6 Gestión de Solicitudes (Vista del Administrador)

Acceso: /admin/request (menú izquierdo "Gestión de Solicitudes").

Los administradores pueden ver las solicitudes de informes de todos los usuarios (los usuarios finales solo ven las suyas) y pueden:

• Ver por nombre de informe/estado/fase;
• Ver parámetros, remitente, dirección IP y fecha de creación/finalización;
• Usar el desplegable "Salida" para descargar directamente el resultado en Excel / HTML / JSON / TEXT de una solicitud;
• Eliminar individualmente o marcar varias para el "borrado masivo".

Para el significado de los estados de solicitud, consulte el Capítulo 7.

4.7 Gestión de Licencias

Acceso: /admin/license (menú izquierdo "Gestión de Licencias").

4.7.1 ¿Qué es un archivo de licencia?

El archivo de licencia es conf/license.dat, un breve fragmento de texto emitido por el proveedor que contiene la siguiente información:

El sistema valida automáticamente el archivo de licencia al iniciar y al importar; cualquier alteración (modificación de la información de registro o de la fecha de vencimiento) invalidará la licencia.

4.7.2 Proceso de Compra

1. Contacte con el proveedor/desarrollador de SQLVantage y proporcione la siguiente información:
   • Nombre de la organización/empresa (company);
   • El ID de registro del servidor a licenciar (reg_id, asignado por el proveedor);
   • El periodo de licencia deseado.
2. El proveedor genera un archivo de licencia (un fragmento de texto) con una herramienta de generación de licencias y lo entrega al cliente.
3. Tras recibir el archivo, el cliente lo importa como se describe en 4.7.3.

4.7.3 Importación de Licencia

1. Inicie sesión como administrador $\rightarrow$ Gestión de Licencias (/admin/license).
2. La página muestra el estado actual de la licencia (ID de registro / empresa / fecha de vencimiento; se muestra un aviso rojo si es inválida o falta).
3. Haga clic en "Seleccionar Archivo", elija el archivo de licencia recibido (puede tener cualquier nombre, ej. license.dat) $\rightarrow$ haga clic en "Importar".
4. Tras una importación exitosa, el sistema valida y actualiza la página automáticamente, mostrando la información de la licencia válida.

También puede colocarse manualmente: guarde el contenido del archivo de licencia como conf/license.dat y reinicie el programa.

4.7.4 Restricciones sin Licencia Válida / Tras el Vencimiento

4.8 Configuración del Sistema

Acceso: /admin/setting (menú izquierdo "Configuración del Sistema"), edición visual de conf/app.conf:

• Ajustes de aplicación: dirección de escucha, puerto, modo de ejecución, idioma predeterminado, tiempo máximo de ejecución;
• Ajustes de sesión: tiempo de expiración de la sesión (segundos);
• Ajustes de base de datos Oracle: servidor, puerto, nombre de servicio, nombre de usuario, contraseña (con botón de alternancia texto plano/cifrado).

Tras guardar, algunos parámetros surten efecto inmediatamente; otros, como el puerto, requieren el reinicio del programa.

4.9 Acerca de

Acceso: /admin/aboutus; vea la versión del sistema, información de lanzamiento, etc.

Esta es la característica más importante de SQLVantage. Un informe consta de tres partes:

• SQL: define qué datos consultar (consulta SQL fuente + configuración de metadatos de columna)
• FORM: define qué condiciones de consulta llenan los usuarios (formulario de parámetros)
• HTML: define cómo se muestran los resultados (tabla/gráfica/KPI tarjeta layout)

Cada uno de los tres tiene dos piezas de datos — "código" y "formato JSON" — que finalmente se guardan en el registro del informe.

5.1 Centro de Trabajo para el Diseño

5.1.1 Entrar al Diseñador

1. Inicie sesión como administrador → Gestión de Informes (/admin/report).
2. Encuentre el informe objetivo y haga clic en el botón "Código" (morado).
3. Se abre una gran ventana de diseñador (aproximadamente el 98% de la pantalla), con la interfaz dividida en paneles izquierdo y derecho:

┌────────────────────────────────────────────────────────┐
│ [下拉：SQL设计 | FORM设计 | HTML设计]   [保存全部]        │
├───────────────────────────────┬────────────────────────┤
│ Izquierda: Editor de Código                │ Panel Derecho: Diseño Dinámico │
│ (Código SQL / Código FORM /              │ (cambia según el modo izquierdo) │
│  Código HTML) comparten un editor         │   · SQL: Tabla de metadatos de columna │
│                               │   · FORM: Tabla de configuración de parámetros │
│                               │   · HTML: Tabla de configuración de bloques │
└───────────────────────────────┴────────────────────────┘

5.1.2 Los Tres Modos

La barra desplegable arriba cambia el modo de diseño; el editor izquierdo y el panel derecho se sincronizan:

5.1.3 Guardar

• Durante el diseño: los cambios en el panel derecho se escriben automáticamente en los campos ocultos (sql_code/sql_format/form_code/form_format/html_code/html_format).
• Guardado formal: haga clic en el botón "Guardar Todo" en la esquina superior izquierda para enviar todas las seis piezas de datos a /admin/report/code/ y guardarlas en la base de datos.

Recuerde: Después de editar SQL / FORM / HTML, asegúrese de hacer clic en "Guardar Todo"; de lo contrario, los cambios se perderán al cerrar la ventana.

5.2 Módulo SQL (Diseño de la Fuente de Datos del Informe)

5.2.1 Escribir la Consulta SQL

• El SQL usa sintaxis Oracle; escriba directamente una sentencia SELECT (FROM/JOIN/WHERE/GROUP BY, etc. pueden incluirse).
• Las condiciones de consulta usan Marcadores de posición de parámetros nombrados :nombre_del_parámetro, y el nombre del parámetro debe coincidir con el field definido en el módulo FORM. Por ejemplo, si en FORM se define el parámetro P_OU_ID, escriba lo siguiente en SQL:

SELECT company_name, ou_id, amount
  FROM fnd_ou_tl
 WHERE ou_id = :P_OU_ID

• Todos los nombres de columna seleccionados en el SQL son las identificaciones de campo del Excel-Export y la tabla HTML de la página (se recomienda usar mayúsculas de manera uniforme, ej. COMPANY_NAME).

5.2.2 Tabla de Configuración de Metadatos de Columna SQL (Clave: Excel-Export)

La "Tabla de configuración de metadatos de columna SQL" a la derecha tiene una fila por cada columna salida por el SQL:

Operaciones: haga clic en "Agregar fila" para agregar una columna → haga doble clic en una celda para rellenarla → se genera automáticamente un snapshot JSON (el área de vista previa de código negra a la derecha), y se escribe de vuelta a sql_format en tiempo real.

5.2.3 Correlación entre la Configuración de Columnas SQL y el Excel-Export

El sistema genera el archivo Excel (xlsx) en segundo plano según las siguientes reglas de correlación:

En otras palabras: La tabla de configuración de columnas SQL es la definición completa de la "cabeza + tipo de columna + formato numérico + alineación" del Excel-Export. Incluso sin ninguna configuración, Excel todavía puede exportarse (tipo de texto predeterminado, alineado a la izquierda, los encabezados de columna usan los nombres de columna originales), pero el Excel exportado después de la configuración es más profesional.

5.2.4 Un Ejemplo Completo de Diseño SQL

Supongamos que queremos construir un "Informe de Costos por Departamento":

1. Código SQL (Editor):

SELECT DEPT_NAME, MONTH, TOTAL_AMOUNT, RATE
  FROM DEPT_COST_V
 WHERE MONTH = :P_MONTH
 ORDER BY DEPT_NAME

2. Configuración de Metadatos de Columna:

3. El resultado del Excel exportado: Los encabezados son "Nombre de Departamento / Mes / Monto Total / Razón de Costo"; los montos están alineados a la derecha con separador de miles y 2 decimales, y la razón se muestra como porcentaje.

5.3 Módulo FORM (Diseño del Formulario de Parámetros de Consulta)

5.3.1 Tabla de Configuración de Parámetros

La "Tabla de Configuración de Parámetros" a la derecha define cada fila un parámetro de consulta:

Tabla de tipos de componentes:

5.3.2 Cascada de Parámetros (Filtros Dependientes)

• api_url / query_sql soporta {nombre_de_variable} marcadores de posición: Cuando el usuario cambia un parámetro upstream (por ejemplo, seleccionando una organización), el sistema reemplaza automáticamente el marcador de posición por el valor real en el formulario actual y solicita dinámicamente las opciones del menú desplegable downstream.
• Si el parámetro upstream no se ha completado, el menú desplegable downstream muestra "Por favor complete los filtros arriba primero" y limpia sus opciones, evitando datos sucios.
• Elija una de las dos: menú desplegable estático (static_options) y menú desplegable dinámico (api_url / query_sql).

Requisito de formato de datos para opciones de menú desplegable dinámico: cada registro devuelto por la API/SQL debe contener dos campos: val (valor) y txt (texto de visualización).

5.3.3 Vista previa en vivo y Generación de Código

• Debajo de la tabla se encuentra el "Área de Vista previa en vivo": el formulario (incluyendo controladores de fecha, menús desplegables dependientes, etc.) se renderiza en tiempo real mientras se configuran los parámetros.
• El "Bocódigo de Formulario" texto abajo genera el código HTML FORM completo en tiempo real.
• Haga clic en el botón "Copiar y Aplicar": el código de bocado se escribe en el editor (modo FORM) y se sincroniza con form_code / form_format.

También puede omitir el panel derecho y escribir manualmente HTML FORM (sintaxis de formulario) directamente en el editor izquierdo; también funciona al guardar.

5.3.4 Comportamiento en tiempo de ejecución

Después de que un usuario final envíe el formulario, el sistema vincula los datos del formulario como parámetros nombrados con SQL y los ejecuta; los parámetros también se registran en la solicitud, de modo que la página de resultados / archivo exportado pueden reflejar las condiciones de consulta.

5.4 Módulo HTML (Diseño de la Visualización de Resultados)

5.4.1 Tabla de Configuración de Bloques de Visualización HTML

Cada fila de la "Tabla de configuración de componentes de vista HTML" a la derecha define un bloque de visualización:

Explicación de Componentes:

5.4.2 Vista previa de diseño y Generación de Código

• El "Área de vista previa de diseño en vivo" muestra en tiempo real un esqueleto de alta fidelidad de cada bloque (título + tipo de bloque + ancho).
• "Bocódigo de HTML" genera el código HTML completo en tiempo real (incluyendo atributos en tiempo de ejecución como data-component, data-subtotal, data-charttype, data-xfield, data-yfields).
• Haga clic en "Copiar y Aplicar": escríbalo en el editor y sincronice html_code / html_format.

También puede escribir fragmentos de plantilla HTML directamente en el editor izquierdo (sintaxis de plantilla compatible). Para los objetos de datos disponibles al renderizar, consulte 5.4.3.

5.4.3 Mecanismo de Renderizado de la Página de Resultados

Cuando un usuario final descarga/visualiza un resultado HTML (/request/output?ext=html), el sistema renderiza el código HTML del informe junto con el resultado JSON de la consulta, la configuración de columnas, etc.:

La página convierte automáticamente los contenedores con data-component="table" en tablas de datos, chart en gráficos y card en KPI cards.

5.5 Proceso de Publicación de Reportes ( Flujo de trabajo recomendado para el Administrador)

1. Gestión de Informes → Crear Nuevo Informe (Seleccionar Responsabilidad, completar Nombre, elegir estado Draft)
2. Haga clic en "Code" para entrar al Diseñador
3. Diseño SQL: Escriba la Consulta SQL + configure Metadatos de Columna (base para Excel-Export)
4. Diseño FORM: Configure Parámetros de Consulta (correspondencia uno a uno con SQL parámetros)
5. Diseño HTML: Configure el Layout de visualización (Tabla/Gráfica/KPI Card)
6. Haga clic en "Guardar Todo" → Cierre el Diseñador
7. Vuelva a la lista de Reportes, cambie el estado a Release (Publicar)
8. Un usuario normal hace login y puede ver este informe en el menú de Reportes y ejecutarlo

5.6 Notas de Diseño

• Los nombres de los parámetros en SQL y FORM deben coincidir exactamente (SQL usa :nombre_del_parámetro, FORM usa field).
• Los nombres de columnas SQL deben ponerse en mayúsculas; la tabla de configuración de metadatos de columna convierte field automáticamente a mayúsculas.
• El SQL del informe debe poder ser precompilado por Oracle (db.Prepare); los errores de sintaxis provocarán el fallo de la ejecución de la solicitud (Estado Error).
• Sin una licencia válida, el límite de reportes es 3; comience el diseño después de confirmar el estado de la licencia.
• Después de guardar, ejecute una solicitud una vez en "Gestión de Solicitudes" o en el lado del usuario final para verificar si SQL y la visualización son correctos.

6.1 Inicio de Sesión

6.2 Página de Inicio del Portal

6.3 Crear una Nueva Solicitud de Informe

6.4 Mi Lista de Solicitudes

6.5 Cambiar la Contraseña

7.1 Flujo de Ejecución (asincrónico)

7.2 Formato de Salida

7.3 Control de Permisos