fluig-sql-docs

Licença MIT · Como contribuir · Histórico

Catálogo comunitário do banco de dados do Fluig 1.8.2, com documentação por tabela e uma camada de planejamento de SQL para agentes de IA.

333 tabelas · 2.809 colunas · 28 recipes SQL · 1.218 queries de referência

O projeto ajuda desenvolvedores, analistas e agentes a localizar dados, escolher o grain do resultado, montar joins completos e validar consultas antes de usá-las em uma instância. É um projeto independente, sem vínculo oficial com a TOTVS.

Autor: Isaac Figueiredo (@isacfg).

Comece aqui

• Consultar o schema: abra o índice de tabelas e carregue a ficha em by_table/.
• Gerar SQL com um agente: siga o protocolo de planejamento, começando por agent/intents.json.
• Adaptar uma consulta: escolha um dos exemplos SQL e confira seus parâmetros, grain e suposições.
• Contribuir: leia CONTRIBUTING.md.

Para humanos

Quer aprender as tabelas do Fluig lendo, sem JSON nem ferramentas? Tudo abaixo é Markdown e abre direto no GitHub:

1. Veja o mapa geral: o índice de tabelas lista as 333 tabelas com domínio, chave primária e uma frase sobre a finalidade. Use a busca do navegador (Ctrl+F) para achar uma tabela ou um assunto.
2. Leia o domínio da tabela: cada arquivo em domains/ reúne as tabelas de uma área funcional. Cada tabela tem finalidade, ciclo de vida, pontos de atenção, colunas com tipo e significado, e relacionamentos. Para começar:
   • Workflow (bpm-workflow): solicitações (PROCES_WORKFLOW), tarefas (TAR_PROCES) e histórico.
   • Documentos do GED (ecm-documents): DOCUMENTO e tabelas vizinhas.
   • Usuários e acesso (foundation-identity-access): FDN_USER e FDN_USERTENANT.
3. Entenda como as tabelas se ligam: relationships.md traz a lista de relações e um diagrama ER por domínio.
4. Veja um SQL pronto: as recipes são consultas comentadas por assunto (workflow, ecm, users, forms).

Duas ressalvas ao ler: relações marcadas como probable não foram comprovadas por constraint, e nenhuma recipe foi executada em uma instância real. Detalhes em Cobertura e limites.

As fichas em by_table/ e o schema.json são JSON para máquinas; a leitura humana está nos arquivos acima.

Instalação e uso

A documentação e os arquivos JSON podem ser lidos diretamente, sem instalar dependências. Os scripts de geração e validação usam Python 3.10 ou superior; os testes foram executados com Python 3.14, e o template de CI usa Python 3.12.

git clone https://github.com/isacfg/fluig-sql-docs.git
cd fluig-sql-docs
python3 -m venv .venv
.venv/bin/python -m pip install -r method_scripts/requirements.txt

Valide uma recipe de tarefas pendentes:

.venv/bin/python method_scripts/validate_sql.py \
  agent/recipes/workflow/pending_tasks_by_user.sql

Para consultar versões históricas, declare a intenção temporal:

.venv/bin/python method_scripts/validate_sql.py \
  agent/recipes/ecm/document_versions.sql --document-mode historical

O validador retorna JSON. Erros produzem código de saída 1; --strict também trata avisos como falha. A validação é estática: ela não conecta ao banco nem executa SQL.

As recipes usam MySQL e parâmetros nomeados como :tenant_id e :user_code. Adapte o binding ao seu driver e passe valores como parâmetros. Oracle e SQL Server exigem conferir o dialeto e o schema da instância.

Um exemplo: solicitações sem duplicação

Para listar solicitações com tarefas pendentes de um usuário, use a solicitação como raiz e EXISTS para testar tarefas. Isso preserva uma linha por (COD_EMPRESA, NUM_PROCES) mesmo quando existem várias tarefas para a mesma solicitação.

SELECT PROCES_WORKFLOW.COD_EMPRESA, PROCES_WORKFLOW.NUM_PROCES, PROCES_WORKFLOW.COD_DEF_PROCES
FROM PROCES_WORKFLOW
WHERE PROCES_WORKFLOW.COD_EMPRESA = :tenant_id
  AND PROCES_WORKFLOW.LOG_ATIV = 1
  AND EXISTS (
    SELECT 1
    FROM TAR_PROCES
    WHERE TAR_PROCES.COD_EMPRESA = PROCES_WORKFLOW.COD_EMPRESA
      AND TAR_PROCES.NUM_PROCES = PROCES_WORKFLOW.NUM_PROCES
      AND TAR_PROCES.CD_MATRICULA = :user_code
      AND TAR_PROCES.LOG_ATIV = 1
      AND TAR_PROCES.IDI_STATUS IN (0, 1)
  );

A recipe completa inclui metadados e ordenação. Veja o protocolo do agente para escolher joins, versões e filtros.

Conteúdo do repositório

Caminho	Conteúdo
index.md	Tabela → domínio, PK e finalidade
by_table/	Fichas completas de cada tabela: tipos, colunas, chaves, índices e relações
domains/	Documentação agrupada por domínio funcional
relationships.md	Relações estruturais e diagramas ER
schema.json	Catálogo completo para consumo por máquina
agent/index.json	Índice das 333 fichas compactas para agentes
agent/intents.json	Intenção de negócio → tabelas → recipe
agent/tables/	Grain, tenant, filtros, joins canônicos e riscos
agent/join_graph.json	Grafo direcional com completude de chaves e efeito sobre o grain
agent/query_rules.json	Regras de planejamento e validação
agent/terminology.json	Conceitos e sinônimos de negócio
agent/recipes/	28 consultas: workflow, GED, usuários e formulários
agent/observed_queries/	Queries SQL/HQL de referência, com linguagem e proveniência
method_scripts/	Fontes editáveis, geração, validação e template de CI
tests/	Regressões do parser, do validador e das recipes

Para economizar contexto, carregue primeiro a intenção e as fichas pertinentes. Consulte o schema.json completo apenas quando necessário.

Conceitos importantes

• Grain: a unidade representada por uma linha. Solicitação, atribuição de tarefa, movimentação e versão de documento são unidades diferentes.
• Tenant: delimite COD_EMPRESA nas tabelas legadas e TENANT_ID nas tabelas de plataforma. Consulte a ficha para outros identificadores de escopo.
• Documentos: DOCUMENTO guarda versões. Para estado corrente, use VERSAO_ATIVA = 1 AND LOG_DELETE = 0; anexos históricos podem exigir uma versão específica.
• Usuários: FDN_USER representa a pessoa global; FDN_USERTENANT guarda seu vínculo com tenant, login e matrícula. (TENANT_ID, USER_CODE) não possui UNIQUE declarado neste catálogo.
• Joins: um relacionamento documentado pode estar incompleto ou multiplicar linhas. Confira canonical, superseded_by, confidence e preserves_grain antes de usá-lo.
• HQL: queries de referência com language = "hql" usam entidades e propriedades Java; precisam de tradução antes de execução como SQL.

Cobertura e limites

A referência estrutural usa o DDL MySQL de instalação do Fluig 1.8.2 e mapeamentos JPA. Chaves físicas, relações de aplicação e relações lógicas possuem classificação e confiança explícitas.

• As 333 tabelas têm grain estrutural documentado; o grain de negócio foi revisado nas 22 tabelas principais. Uma tabela não tem PK declarada e recebe aviso específico.
• Há 707 colunas sem correspondência com campo JPA e 136 colunas com confiança baixa. Valores de enum desconhecidos ficam vazios.
• As 28 recipes passaram nas verificações estáticas. Duas mantêm avisos documentados de relação provável; nenhuma foi executada em uma instância real do Fluig.
• Migrações e hotfixes não foram reaplicados ao catálogo. Tipos e colunas podem diferir no banco de uma instalação.
• Tabelas dinâmicas de formulários (ml...) e datasets internos estão fora do mapa.
• O validador sinaliza casos que precisam de revisão manual, como linhagem de CTEs e certos outer joins. Não estima desempenho nem comprova autorização.

Confira sempre os resultados e o plano de execução na instância que será consultada. Este repositório contém documentação e ferramentas; não distribui instaladores, JARs ou dados de produção do Fluig.

Desenvolvimento

# Regenerar a camada agent/ a partir do catálogo versionado
python3 method_scripts/generate_agent.py

# Validar todas as fichas e recipes
.venv/bin/python method_scripts/check_catalog.py

# Executar a suíte de regressão
.venv/bin/python -m unittest discover -s tests -v

Os detalhes do pipeline e as fontes editáveis estão em method_scripts/README.md. A configuração de GitHub Actions está disponível como template.

Comunidade

Correções de relações, novos exemplos e evidências de versões são bem-vindos. Use as issues para discutir alterações e abra um pull request seguindo o guia de contribuição.

A convivência segue o Código de Conduta. Para questões de segurança, consulte SECURITY.md. Consulte também CHANGELOG.md para acompanhar a evolução do catálogo e THIRD_PARTY.md para referências de terceiros.

Licença

As contribuições originais de código e documentação deste projeto são disponibilizadas sob a licença MIT. Referências e materiais de terceiros mantêm seus próprios direitos e avisos; veja THIRD_PARTY.md.

Autoria e atribuição

Ao redistribuir cópias ou partes substanciais do código ou da documentação original, preserve o aviso de copyright de Isaac Figueiredo (@isacfg) e o texto completo da licença MIT. Preserve também os avisos aplicáveis de outros autores e de terceiros.

Para citar o projeto publicamente, recomendamos:

fluig-sql-docs, de Isaac Figueiredo (@isacfg), disponível em https://github.com/isacfg/fluig-sql-docs, sob licença MIT.

O crédito público e o link acima são recomendações de citação, não condições adicionais à MIT. A licença exige preservar o aviso de copyright e seu texto nas cópias ou partes substanciais; ela não exige crédito público em todo uso. Metadados de autoria para ferramentas de citação estão em CITATION.cff.