Manual do Utilizador do SQLVantage (Português)

1. Visão Geral do Sistema
2. Instalação e Implantação (Windows / Linux)
3. Instruções de Configuração
4. Guia do Administrador
5. Guia de Design de Reportes (SQL/FORM/HTML)
6. Guia do Usuário Final
7. Execução de Solicitações e Resultados de Saída
8. Perguntas Frequentes (FAQ)
9. Apêndice: Armazenamento de Dados, Backup e Migração

Este é o sistema de relatórios SQLVantage. O "Administrador" mantém as definições dos relatórios, enquanto "usuários finais" selecionam um relatório na página da web, preenchem as condições de consulta, obtêm resultados de forma assíncrona e os exportam como Excel / HTML / JSON / TEXT.

SQLVantage é um sistema de relatórios baseado na web. O "Administrador" mantém as definições dos relatórios, enquanto os "usuários finais" selecionam um relatório na página da web, preenchem as condições de consulta, obtêm resultados de forma assíncrona e os exportam como Excel / HTML / JSON / TEXT.

Este sistema tem uma arquitetura web pura: não é necessário instalar nenhum cliente ou plug-in no navegador — qualquer navegador moderno pode acessá-lo. Do lado do servidor, apenas o executável do programa e seus diretórios de configuração acompanhantes são necessários para rodar, o que facilita o déploiement.

Após extrair o pacote de lançamento:

SQLVantage/
├── SQLVantage.exe / sqlvantage   # Programa principal (Windows / Linux)
├── conf/
│   ├── app.conf        # Arquivo de configuração do sistema (porta/idioma/Oracle etc.)
│   ├── data.dat        # Banco de dados de negócios (usuários/responsabilidades/relatórios/solicitações)
│   ├── license.dat     # Arquivo de licença
│   └── locale/         # Pacotes de idioma
├── data/               # Gerado em tempo de execução: <ID_Solicitação>.xlsx / <ID_Solicitação>.json
├── docs/                 # Documentação do usuário (multilíngue, inclui images/)
└── tmp/                # Arquivos temporários (sessões, tarefas)

2.1 Requisitos do Ambiente

• Sistema operacional: Windows 7+ / Linux de 64 bits (x86_64)
• Modo de execução (recomendado): use diretamente o executável lançado (SQLVantage.exe ou o binário do Linux); não é necessário instalar nenhum ambiente de execução adicional
• Banco de dados Oracle: a execução de relatórios requer conectividade com Oracle (o sistema se conecta por padrão ao Oracle EBS); por favor, confirme a rede e a conta antecipadamente
• Permissões de disco/diretório: o diretório de trabalho do programa deve ter permissão de escrita (writable), pois durante a execução o sistema cria os diretórios data/ e tmp/ e lê/escreve arquivos em conf/

2.2 Instalação no Windows

1. Extrair: extraia o pacote de lançamento (zip) para qualquer diretório, por exemplo C:\\SQLVantage\\. Após a extração, verifique se os seguintes arquivos-chave existem:

C:\\SQLVantage\\
├── SQLVantage.exe      # Programa principal
├── conf\\app.conf      # Arquivo de configuração
├── conf\\data.dat      # Dados (base de dados vazia incluída no pacote)
└── conf\\locale\\      # Pacotes de idioma

2. (Opcional) Configuração: abra conf\\app.conf com o Bloco de notas e modifique o endereço de escuta, porta, conexão Oracle etc. de acordo com o Capítulo 3.

3. Iniciar o programa: dê dois cliques em SQLVantage.exe, ou execute no prompt de comando:

cd C:\\SQLVantage
SQLVantage.exe

Após um início bem-sucedido, o console imprimirá informações da versão, estado da licença e entrará no estado de escuta.

4. Acessar o sistema: abra http://127.0.0.1:8080 no navegador (endereço padrão; pode ser modificado em app.conf).

5. Configuração do Firewall: se for necessário acesso LAN/remoto, abra o porta correspondente (como 8080) no firewall do Windows:

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

2.3 Instalação no Linux

1. Extrair: extraia o pacote de lançamento (tar.gz ou zip) para o diretório de destino, por exemplo /opt/sqlvantage:

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

2. Conceder permissão de execução:

chmod +x sqlvantage

3. (Opcional) Configuração: edite conf/app.conf (igual ao Windows).

4. Teste de inicialização no primeiro plano:

./sqlvantage

Quando você vir a informação da versão e o registro de escuta, o início foi bem-sucedido; pressione Ctrl+C para parar.

5. Execução em segundo plano (recomenda-se systemd ou nohup):

   Método A: nohup

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

Método B: systemd (criar /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

Depois execute:

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

6. Firewall / Security Group: abra o porta (como 8080):

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

2.4 Compilação a partir do código fonte (Não obrigatório)

Apenas para usuários que obtiveram o código fonte: execute o comando de compilação no diretório de origem para produzir um executável para a plataforma atual. Para um ambiente de deploy formal, recomenda-se usar diretamente o executável lançado.

2.5 Primeira Execução

Na primeira execução, o sistema completará automaticamente a seguinte inicialização:

1. Verificar arquivo de dados: lê conf/data.dat (incluído no pacote; se faltar, o programa indica "conf/data.dat is not found" e sai — por favor, não delete este arquivo).
2. Criação automática de tabelas: 4 tabelas user, responsibility, report, request são criadas automaticamente.
3. Criação automática da conta do administrador: na primeira visita a /admin/login, se o usuário root não existir, o sistema o cria automaticamente:
   • Nome de usuário: root
   • Senha inicial: SQLVantage
   • Função: administrador
   • Aviso de segurança: mude esta senha imediatamente após o primeiro login (o administrador pode alterá-la em "Gestão de Usuários").
4. Verificar arquivo de licença: se conf/license.dat estiver faltando ou inválido, o console imprimirá um aviso; o sistema ainda pode rodar, mas estará sujeito às restrições de licença descritas na Seção 4.7.

3.1 Posicionamento do Arquivo de Configuração

O arquivo de configuração é conf/app.conf (formato INI). Existem duas formas de modificá-lo:

• Método 1 (recomendado, via interface de usuário): após fazer login como administrador, acesse "Configurações do Sistema" (/admin/setting), preencha os valores e salve; o sistema grava automaticamente de volta em app.conf.
• Método 2 (editar o arquivo diretamente): modifique conf/app.conf com um editor de texto e, em seguida, reinicie o programa.

3.2 Tabela de Referência de Parâmetros

| oracle_server | Exemplo: 192.168.10.13 | IP/Hostname do servidor de banco de dados Oracle | | oracle_port | 1521 | Porta de escuta do Oracle | | oracle_database | test | Nome do serviço Oracle (SERVICE_NAME) | | oracle_username | apps | Nome de usuário para conexão Oracle | | oracle_password | nenhum | Senha de conexão Oracle (por favor, digite a senha real) |

3.3 Quando as alterações entraram em vigor

• sessiongcmaxlifetime: entra em vigor imediatamente após o salvamento.
• Outros parâmetros (porta, Oracle etc.): é necessário reiniciar o programa para as alterações terem efeito.

3.4 Mudança de Idioma

• O sistema tem 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.
• Como mudar: adicione ?lang=pt-PT na URL (ex: /?lang=pt-PT), ou mude através do menu de idiomas no canto superior direito da console do administrador; após a escolha, será gravado em um Cookie, com validade de 1 ano.

4.1 Entrada do Administrador

1. Em um navegador, visite http://<endereço do servidor>:<porta>/admin/login.
2. Entre com a conta do administrador (inicialmente root / SQLVantage).
3. Após um login bem-sucedido, a console do administrador (/admin) abre; o menu esquerdo contém: Gestão de Relatórios, Gestão de Responsabilidades, Gestão de Usuários, Gestão de Solicitações, Gestão de Licenças, Configuração do Sistema, Painel de Controle, Sobre Nós.

Nota: A conta do administrador deve satisfazer Rol = admin e Estado = active; caso contrário, não será possível entrar na console do administrador.

4.2 Painel de Controle e Navegação Superior

• A navegação superior permite saltos rápidos: Painel de Controle (/admin), Execução de Relatórios (/request, janela nova) e Página Inicial do Portal (/).
• No canto superior direito, é possível mudar o idioma ou sair da sessão (/admin/logout).

4.3 Gestão de Usuários

Entrada: /admin/user (menu esquerdo "Gestão de Usuários").

Detalhes do Campo de Usuário:

Ações:

• Criação: clique no botão "Criação" → preencha Nome de usuário/Email/Papel/Status/Senha/Confirmação de senha → envie.
• Edição: clique em "Edição" na linha → pode alterar Email, Papel e Status; deixando o campo Senha em branco significa que não há alterações.
• Exclusão: clique em "Exclusão" na linha. Observação importante:
  • A conta root não pode ser excluída.
  • Um usuário que tenha relatórios não pode ser excluído (seus relatórios devem ser excluídos ou transferidos primeiro).

Pontos de Gestão:

• A ponto de entrada para usuários finais é /login (página inicial), e para administrador é /admin/login; os dois são diferentes.
• Definir um usuário final como inactive é suficiente para bloquear seu login, não é necessário excluir o conta.
• root é automaticamente ocultado na lista de usuários.

4.4 Gestão de Responsabilidade (Responsibility)

Entrada: /admin/responsibility (menu esquerdo "Gestão de Responsabilidade**.

Detalhes do Campo de Responsabilidade:

Ações:

• Criação: clique em "Criação" → selecione uma responsabilidade do usuário do dropdown (os dados vêm da interface de consulta Oracle EBS /api/user/responsibilities/); após a seleção, RespId / RespKey / Nome serão preenchidos automaticamente; também pode ser preenchido manualmente → envie.
• Edição / Exclusão: operações através dos botões na linha. Observação importante: Uma responsabilidade referenciada por um relatório não pode ser excluída.

Finalidade: Cada relatório deve pertencer a uma responsabilidade; o "Menu de Relatórios" para o usuário final é agrupado por responsabilidade (relatórios que não pertencem a nenhuma responsabilidade são agrupados no grupo "Sem Categoria").

4.5 Gestão de Relatórios

Entrada: /admin/report (menu esquerdo "Gestão de Relatórios**.

Campos do Relatório:

Ciclo de vida do Relatório (Importante):

Draft (Rascunho, fase de projeto) ──▶ Release (Publicado, visível para usuários)
       │                        │
       │                        └──▶ Não pode excluir diretamente, precisa primeiro mudar para Draft/Discard
       └──▶ Discard (Cancelado, usuários não vêem)

• Apenas relatórios com status Release aparecem no menu de relatórios para usuários finais.
• Relatórios Publicados (Release) não podem ser excluídos; primeiro altere o status na lista para Draft ou Discard, e depois exclua.
• As colunas "Nome", "Descrição" e "Status" na lista suportam clicar duas vezes em uma célula para editar diretamente (salvamento automático).

Ações:

4.6 Gestão de Solicitações (Vista do Administrador)

Entrada: /admin/request (menu esquerdo "Gestão de Solicitações**.

Administradores podem ver os solicitações de relatórios de todos os usuários (usuários finais só podem ver os seus próprios), e podem:

• Filtrar por nome do relatório/Status/Fase;
• Ver parâmetros, remetente, endereço IP e tempo de criação/Conclusão;
• No dropdown "Saída" pode baixar diretamente o resultado do solicitação em Excel / HTML / JSON / TEXT;
• Excluir individualmente, ou marcar vários e "Exclusão em Massa".

O significado dos status de solicitação veja Capítulo 7.

4.7 Gestão de Licença (License)

Entrada: /admin/license (menu esquerdo "Gestão de Licenças**.

4.7.1 O que é um arquivo de licença?

O arquivo de licença é conf/license.dat, um breve fragmento de texto emitido pelo fornecedor, contendo a seguinte informação:

O sistema verifica automaticamente a validade do arquivo de licença ao iniciar e ao importar; qualquer manuseio (modificação das informações de registro ou da data de validade) tornará a licença inválida.

4.7.2 Processo de Compra

1. Entre em contato com o fornecedor/desenvolvedor do SQLVantage e forneça as seguintes informações:
   • Nome/Nome da empresa (company);
   • ID de registro do servidor a ser licenciado (reg_id, atribuído pelo fornecedor);
   • O período de licença desejado.
2. O fornecedor usa uma ferramenta de geração de licença para criar um arquivo de licença (um fragmento de texto) e o entrega ao cliente.
3. Após receber o arquivo, o cliente segue a instrução 4.7.3 para importar.

4.7.3 Importação de Licença

1. Administrador faz login → Gestão de Licenças (/admin/license).
2. A página mostra o estado atual da licença (ID de registro / Nome da empresa / Data de validade; se inválido ou ausente, mostrará um aviso vermelho).
3. Clique em "Selecionar Arquivo" e escolha o arquivo de licença recebido (pode ser nomeado como quiser, ex: license.dat) → clique em "Importar".
4. Após um import bem-sucedido, o sistema verifica automaticamente e atualiza a página, mostrando as informações da licença válida.

Também pode ser colocado manualmente: salve o conteúdo do arquivo de licença como conf/license.dat e, em seguida, reinicie o programa.

4.7.4 Quando não há licença / Licença expirada

4.8 Configurações do Sistema

Entrada: /admin/setting (menu esquerdo "Configurações do Sistema"), edição visual de conf/app.conf:

• Configurações de aplicação: endereço de escuta, porta, modo de execução, idioma padrão, tempo máximo de execução;
• Configurações de sessão: tempo de expiração da sessão (segundos);
• Configurações de banco de dados Oracle: servidor, porta, nome da serviço, nome de usuário, senha (com botão de alternância entre texto/plain e cifrado).

Após salvar, alguns parâmetros entram em efeito imediatamente; parâmetros como porta exigem reinicialização do programa.

4.9 Sobre Nós

Entrada: /admin/aboutus, visualizar versão do sistema, informações de lançamento e etc.

Esta é a função mais importante do SQLVantage. Um relatório consiste em três partes:

• SQL: define quais dados consultar (fonte SQL + configuração de metadados de coluna)
• FORM: define quais condições de consulta o usuário preenche (formulário de parâmetros)
• HTML: define como os resultados são exibidos (tabela / gráfico / layout KPI card)

Cada um dos três tem dois pedaços de dados — "código" e "formato JSON" — que são salvos no registro do relatório no final.

5.1 Espaço de Trabalho do Construtor

5.1.1 Entrada no Construtor

1. Entre como administrador → Gestão de Relatórios (/admin/report).
2. Encontre o relatório alvo e clique na botão "Code" (roxo).
3. Um grande espaço de construtor aparece (cerca de 98% da tela), o interface dividido em painéis esquerdo e direito:

┌────────────────────────────────────────────────────────┐
│ [下拉：SQL设计 | FORM设计 | HTML设计]   [保存全部]        │
├───────────────────────────────┬────────────────────────┤
│ Esquerda: Editor de Código          │ Direita: Layout Dinâmico │
│ (Código SQL / Código FORM /       │ (mudança conforme o modo esquerdo) │
│  Código HTML) comparten um editor         │   · SQL: Tabela de metadados de coluna │
│                               │   · FORM: Tabela de configuração de parâmetros │
│                               │   · HTML: Tabela de configuração de blocos │
└───────────────────────────────┴────────────────────────┘

5.1.2 Os Três Modos

A barra desplegável em cima alterna o modo de projeto; o editor esquerdo e o painel direito se sincronizam:

5.1.4 Salvando

• Enquanto projetar: mudanças no painel direito são automaticamente gravadas nos campos ocultos (sql_code/sql_format/form_code/form_format/html_code/html_format).
• Salvamento Oficial: clique no botão "Salvar Tudo" no canto superior esquerdo para enviar todos os seis conjuntos de dados para /admin/report/code/ e salvá-los na base de dados.

Importante: Depois de editar SQL / FORM / HTML, certifique-se de clicar em "Salvar Tudo"; caso contrário, as mudanças serão perdidas ao fechar a janela.

5.2 Módulo SQL (Projeto da Fonte de Dados do Relatório)

5.2.1 Escreva o SQL Query

• SQL usa syntax Oracle; escreva diretamente um comando SELECT (FROM/JOIN/WHERE/GROUP BY e etc. podem ser incluídos).
• As condições de query usam marcadores de posição nomeados :nome_do_parâmetro, e o nome do parâmetro deve corresponder ao field definido no modo FORM. Por exemplo, se no modo FORM definido o parâmetro P_OU_ID, escreva o seguinte em SQL:

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

• Todos os nomes de coluna selecionados no SQL são os identificadores de campo do Excel-export e da tabela HTML da página (recomenda-se usar maiúsculas uniformemente, por exemplo COMPANY_NAME).

5.2.2 Tabela de Metadados de Coluna SQL (Chave: Excel-Export)

"A Tabela de Metadados de Coluna SQL" à direita tem 1 linha para cada coluna saída por SQL：

Ações: clique em "Adicionar linha" para adicionar um coluna → dois cliques em uma célula para preencher →Snapshot JSON será automaticamente criado (a área de visualização de código negra à direita) e imediatamente gravado em sql_format em tempo real.

5.3 Mãozinha entre a Configuração de Coluna SQL e Excel-Export

O sistema gera o arquivo Excel (xlsx) em segundo plano de acordo com as seguintes regras de mãozinha：

Em resumo: A Tabela de Metadados de Coluna SQL é a definição completa de "cabeçalho + tipo de coluna + formato numérico + alinhamento" do Excel-Export. Mesmo sem nenhuma configuração, o Excel ainda pode ser exportado (tipo de texto padrão, alinhado à esquerda, os títulos das colunas usam os nomes de colunas originais), mas o Excel exportado depois de configuração será mais profissional.

5.3 Módulo FORM (Projeto da Forma de Parâmetros de Query)

5.3.1 Tabela de Configuração de Parâmetros

"A Tabela de Configuração de Parâmetros" à direita define 1 linha 1 parâmetro de query：

Tabela de Tipos:

5.3.2 Apoio de Parâmetros (Filtro Dependente)

• api_url / query_sql suporta {nome_da_variável} marcadores: quando o usuário muda um parâmetro upstream (por exemplo, seleciona uma organização), o sistema automaticamente substitui o marcador pelo valor real na forma atual e solicita dinamicamente as opções do dropdown downstream.

• Se o parâmetro upstream não for preenchido, o dropdown downstream mostrará "Primeiro complete os filtros acima" e limpará as opções, evitando dados sujos.

• Escolha um dos dois: Dropdown estático (static_options) e dropdown dinâmico (api_url / query_sql).

Requisito de formato de dados para dropdowns dinâmicos: cada registro retornado pelo API/SQL deve conter 2 campos: val (valor) e txt (texto exibido).

5.3.3 Previsão Direta e Geração de Código

• Debaixo da tabela fica o "Pré-visualização Direta": enquanto configura parâmetros, o formulário (incluindo controladores de data, dropdowns dependentes etc.) é exibido em tempo real.
• "Rascunho de Código de Formulário" embaixo gera automaticamente o código HTML do formulário em tempo real.
• Clique no botão "Copiar e Aplicar": o rascunho de código é escrito no editor (modo FORM) e sincronizado com form_code / form_format.

Você também pode pular a direita e escrever manualmente HTML Form (syntax de formulário) diretamente no editor esquerdo; também funciona ao salvar.

5.3.4 Tempo Real

Depois que o usuário final submeter o formulário, o sistema ligará os dados do formulário com SQL como parâmetros nomeados e executará; os parâmetros também serão registrados no solicitação, para que a página de resultados/arquivo de exportação possa refletir as condições de query.

5.4 Módulo HTML (Projeto de Exibição de Resultados)

5.4.1 Tabela de Configuração de Blocos HTML

Cada linha "Tabela de Configuração de Blocos HTML" à direita define 1 bloco de exibição：

Gíria dos Elementos:

5.4.2 Pré-visualização Direta e Geração de Código

• "Pré-visualização Direta" exibe um imagens de alta fidelidade de cada bloco em tempo real (título + tipo de bloco + largura).
• "Rascunho de Código HTML" gera automaticamente o código HTML em tempo real (incluindo atributos tempo real como data-component, data-subtotal, data-charttype, data-xfield, data-yfields).
• Clique em "Copiar e Aplicar": escreve no editor e sincroniza html_code / html_format.

Você também pode escrever manualmente HTML Template direto no editor esquerdo (suporte a sintaxe de template popular). Para os dados objetos disponíveis ao renderizar, veja 5.4.3.

5.4.3 Mecanismo de Exibição da Página de Resultado

Quando o usuário final carrega/x-ray resultados HTML (/request/output?ext=html), o sistema combinará o código do relatório com o resultado JSON da query, metadata coluna e etc.:

A página automaticamente将容器 com data-component="table" em tabela de dados, chart em gráfico e card em card KPI.

5.5 Processo de Lançamento de Relatório (Recomendado para Administrador)

1. Gestão de Relatórios → Criar novo relatório (selecionar responsabilidade, preencher Nome, selecionar status Draft)
2. Clique em "Code" para entrar no Construtor
3. SQL-Design: Escreva SQL + configure metadados de coluna (é a base para Excel-Export)
4. FORM-Design: Configure parâmetros (compatível 1-1 com SQL parâmetros)
5. HTML-Design: Configure layout de exibição (Tabela/Gráfico/KPI card)
6. Clique em "Salvar Tudo" → Feche o Construtor
7. Volte à lista de relatórios, altere o status para Release (publicado)
8. Usuário comum login instantaneamente pode ver este relatório no menu de relatórios e executá-lo

5.5 G sobre Projeto

• Os nomes dos parâmetros em SQL e FORM devem coincidir exatamente (SQL usa :nome_do_parâmetro, FORM usa field).
• Os nomes das colunas SQL devem ser letras maiúsculas; a tabela de metadados de coluna automaticamente将 field transformar em letras maiúsculas.
• SQL do relatório deve ser pre-compilável por Oracle (db.Prepare); erros de sintaxe levarão ao fracasso da execução do pedido (Status Error).
• Sem licença válida, o número de relatórios está limitado a 3; antes de projetar, verifique o estado da licença.
• Após salvar, é possível executar um pedido uma vez em "Gestão de Solicitações" ou no lado do usuário final para verificar se SQL e a exibição estão corretos.

6.1 Entrada em Sistema

1. Método um: ERP autenticação (Oracle EBS Single Sign-On)
2. Método dois: Conta local

6.2 Página Inicial do Portal

6.3 Criando novo Solicitação de Relatório

6.4 Minha página de Solicitações

6.5 Mudança de Senha

6.6 Alguns Avisos Adicionais

7.1 Processo de Execução (Assíncrono)

7.2 Formato de Saída

7.3 Controle de Acesso

7.3 Perguntas Frequentes

9.1 Endereço de Armazenamento de Dados

9.2 Recomendações de Backup

9.3 Migração para novo Servidor

9.4 Documentação Multilíngue (Multilingual Document) Migração e Leitura Online