Mini site de documentaçãoDeveloper Atlas

Entrada rápida para navegar arquitetura, APIs, operação e guias técnicos do projeto sem depender da estrutura do repositório.

44 notas

Procure por módulo, API, rota, fluxo operacional ou termo do projeto.

Guias técnicos/docs/guias/painel-data-studio-modelagem-importacao-e-pacote-base

Painel - Data Studio Modelagem Importacao e Pacote Base

Explicar como o novo módulo de dados do `EcommPanel` foi organizado para servir como base de banco do produto.

Recorte da seçãoGuia orientado por fluxo

Leitura pensada para explicar responsabilidades, ordem de execução e trechos reais do código com foco no fluxo da implementação.

Atualizado19 de mar. de 2026
Seções20
Tags4
guiadadosbootstrapimportacao

Objetivo

Explicar como o novo módulo de dados do EcommPanel foi organizado para servir como base de banco do produto.

Fluxo principal

  1. o usuário acessa /ecommpanel/admin/data;
  2. ajusta a conexão principal, engine, SSH e referências de senha;
  3. inspeciona a VPS quando a operação for SSH + PostgreSQL oficial na VPS;
  4. provisiona instalação do PostgreSQL quando necessário, banco, usuário do app e boilerplate inicial do painel;
  5. modela entidades e campos;
  6. importa registros em JSON quando precisar;
  7. gera o pacote base;
  8. usa esse pacote para implementar e popular a camada real de banco.

O que a UI opera

Conexão e bootstrap

O topo da tela agora cobre:

  • perfis de conexão;
  • engine e método de provisão;
  • host SSH, usuário SSH e dados administrativos do banco;
  • teste básico de alcance de host e porta;
  • inspeção remota do ambiente;
  • instalação automática do PostgreSQL quando necessário;
  • criação inicial de banco e usuário do app;
  • aplicação do boilerplate de autenticação do painel;
  • indicação da conexão principal;
  • estado detectado e também estado declarado de bootstrap.

Entidades

Cada entidade guarda:

  • slug;
  • nome;
  • nome de tabela;
  • descrição;
  • status;
  • lista de campos.

Campos

Cada campo guarda:

  • nome técnico;
  • rótulo;
  • tipo;
  • descrição;
  • obrigatoriedade;
  • unicidade;
  • índice;
  • visibilidade em listagem;
  • valor padrão.

Imports

O painel aceita:

  • importação de registros para uma entidade específica;
  • importação de pacote completo com entidades e cargas.

CSV por tabela

Além das entidades modeladas, o painel agora também consegue operar diretamente a estrutura física do PostgreSQL:

  • listar tabelas disponíveis na base conectada;
  • ler colunas, tipos e primary key;
  • exportar o conteúdo da tabela em CSV;
  • importar CSV em modo append ou upsert.

Isso atende cenários de:

  • extração de dados para análise externa;
  • carga manual de apoio;
  • transição entre planilhas e banco;
  • manutenção controlada sem depender de CLI.

O que a API faz

Rota:

  • /api/ecommpanel/data-studio

Operações:

  • GET: carrega snapshot e bundle atual;
  • POST com saveEntity: cria ou atualiza entidade;
  • POST com deleteEntity: remove entidade e imports relacionados;
  • POST com saveConnection: cria ou atualiza conexão;
  • POST com deleteConnection: remove conexão;
  • POST com probeConnection: testa alcance básico de rede;
  • POST com inspectProvisioning: inspeciona a VPS remota via SSH e verifica banco, usuário e boilerplate;
  • POST com provisionConnection: cria banco, usuário do app e tabelas iniciais do painel via SSH;
  • POST com updateBootstrap: atualiza o estado declarado do ambiente;
  • POST com importRows: registra carga em JSON;
  • POST com importBundle: aplica pacote completo;
  • POST com generateBundle: regenera o material de bootstrap.
  • POST com refreshDatabaseTables: recarrega a estrutura física da base;
  • POST com exportTableCsv: gera CSV de uma tabela existente;
  • POST com importTableCsv: aplica um CSV em tabela existente.

O que o bundle entrega

`schema.json`

Representa o modelo de dados operado pelo painel.

`postgres-content-bootstrap.sql`

Entrega a primeira tradução do modelo para PostgreSQL, com:

  • tabelas;
  • tipos básicos;
  • índices;
  • unicidade.

`postgres-panel-bootstrap.sql`

Representa o boilerplate oficial do painel em PostgreSQL para:

  • usuários;
  • sessões;
  • reset de senha;
  • auditoria.

`mysql-content-bootstrap.sql`

Entrega a tradução inicial das entidades para MySQL/MariaDB.

`mysql-panel-bootstrap.sql`

Mantém o mesmo boilerplate para o caminho de compatibilidade em MySQL/MariaDB.

`seed-imports.json`

Leva os documentos importados para uso como carga inicial.

Limite atual

O módulo ainda não substitui toda a persistência real do produto.

Ele é uma camada de:

  • modelagem;
  • preparação;
  • governança inicial;
  • exportação/importação.

Foreign keys, transações críticas, estoque concorrente e constraints finais ainda serão fechados quando o backend dedicado e o banco real entrarem na arquitetura.

O provisionamento automático desta fase foi fechado primeiro no fluxo oficial de:

  • PostgreSQL via SSH;
  • instalação e configuração do serviço na própria VPS;
  • criação inicial do ambiente do painel.

MySQL/MariaDB continua disponível apenas como compatibilidade.

Perfis de acesso

O painel separa a operação desta área em quatro níveis:

  1. main_admin: conexão, bootstrap, entidades, registros e pacote;
  2. data_manager: entidades, registros e pacote;
  3. data_editor: registros;
  4. data_viewer: leitura.

Arquivos centrais

  • src/app/ecommpanel/admin/data/page.tsx
  • src/app/api/ecommpanel/data-studio/route.ts
  • src/features/ecommpanel/components/DataStudioManager.tsx
  • src/features/ecommpanel/server/dataStudioStore.ts
  • src/features/ecommpanel/types/dataStudio.ts

Leitura seguinte