app-frontend — Mapeamento

Documentação técnica • Autor: Leonardo Norbiato - Equipe de Engenharia

Cliente: Aster Technology / UVA Última Atualização: 15/09/2025 Autores: Leonardo Norbiato - Equipe de Engenharia

Índice

1. Objetivo
2. Última Revisão
3. Tecnologias Utilizadas
4. Funcionalidades e Domínios
5. Arquitetura Frontend
6. Arquitetura Backend
7. Rotas e Endpoints
8. Estrutura de dados, Tabelas e Views
9. Configuração e Variáveis
10. Treeview da Arquitetura
11. Integrações e Dependências
12. Integrações externas
13. Controle de Versão
14. Segurança e Acesso
15. Considerações Finais

1. OBJETIVO DO REPOSITÓRIO

O app-frontend é a interface de usuário principal do ecossistema Aster/UVA, desenvolvida em Next.js 14 com App Router. Sua função é fornecer uma experiência de usuário completa e integrada para gerenciamento de projetos de energia solar, incluindo módulos comerciais, contratos, projetos, produção, obras, financeiro, recursos humanos e administração. O frontend atua como ponto de entrada único para todos os microserviços do sistema, proporcionando uma interface unificada e responsiva para operações complexas de gestão empresarial.

2. ÚLTIMA REVISÃO

15/09/2025 - Revisão e atualização da documentação (Equipe)

3. TECNOLOGIAS UTILIZADAS

Frontend: Next.js 14.0.4 (App Router), React 18.2.0, MUI 5.16.14, Emotion; TanStack React Query 5.51.16, Notistack 3.0.1, Zustand 5.0.5; React Hook Form 7.48.2 + Yup 1.3.2, Framer Motion 10.16.16; Integrações: Firebase 10.7.1, Supabase 2.39.0, Mapbox GL 3.0.1; React-PDF 9.1.1, Docx 9.0.3, AWS Amplify 6.0.6, Auth0 2.2.3; FullCalendar 6.1.10, ApexCharts 3.44.2, React Joyride 2.7.1
Backend: Não aplicável (frontend puro)
Banco de Dados: Não aplicável (frontend puro)
Ferramentas de Conexão e Infraestrutura: Dockerfile (multi-stage build; porta 3032; output standalone); SVGR para .svg; modularizeImports MUI; trailingSlash; eslint ignore; Husky 8.0.0 (git hooks), ESLint 8.55.0, Prettier 3.1.0; Commitlint 19.8.0 (conventional commits)

4. FUNCIONALIDADES E DOMÍNIOS

Comercial: Gestão completa do funil de vendas, clientes, orçamentos, propostas, unidades consumidoras, tags e workflow de vendas com integração de irradiação solar.
Contratos: Emissão, criação, dashboard, gestão de contratos, anexos, cronogramas, inspeções e workflow completo de contratos.
Projetos: Gestão de projetos, vistorias técnicas, workflow de projetos e acompanhamento detalhado de execução.
Produção: Cadastro extenso de produtos, categorias, ordem de produção, gestão de fornecedores e workflow de produção.
Obras: Gestão de obras, cronogramas, inspeções e workflow de execução.
Financeiro: Contas a pagar/receber, caixas e bancos, movimentações, categorias, clientes/fornecedores e relatórios financeiros.
Suprimentos: Gestão de fornecedores e controle de suprimentos.
Recursos Humanos: Gestão de colaboradores, folha de pagamento e controle de recursos humanos.
Administração: Unidades de negócio, usuários, modelos de proposta/contrato, natureza de operação, configurações da empresa e assinantes.
Backoffice: Gestão de customers, plans, subscriptions, instances e controle administrativo do sistema.
Autenticação e Perfil: Login, registro, recuperação de senha, verificação e perfil do usuário.
Dashboard: Visão geral do sistema com métricas e indicadores principais.

5. ARQUITETURA FRONTEND

Layout & Providers: src/app/layout.js com Theme, Settings, Snackbar, Motion, Permissions, i18n, React Query e Firebase Auth.; Sub-layouts por domínio: src/app/comercial/layout.js, src/app/financeiro/layout.js, etc.; Configuração de tema: modo escuro padrão, direção LTR, layout vertical.
Componentização: src/components (UI genérica: tabelas, dialogs, formulários, gráficos, mapas); src/sections (telas por domínio: comercial, financeiro, contratos, etc.); src/assets (recursos: ícones, ilustrações, imagens, fontes); src/theme (tema MUI customizado), src/global.css (estilos globais + mapbox-gl.css)
Rotas: App Router em src/app/* com page.js, layout.js e loading.js; Mapeamento utilitário em src/routes/paths.js e src/routes/paths/* por domínio; Rotas dinâmicas com parâmetros: [id], [billId], [propostaId]
Camada de Dados: Conector HTTP em src/api/api.js (axios + Authorization: Bearer, x-tenant-id); Hooks React Query por domínio: administrator, backoffice, commercial, contract, financial, inventory, facilities, common, workflow
Estado e Permissões: React Query como cache principal; Zustand para estado pontual (form store); src/providers/permission-provider.js e guardas em src/auth/guard/*; Sistema de permissões baseado em roles e recursos
Autenticação: Firebase ativo (src/auth/context/firebase/* e AuthProvider); Suporte para Auth0 e AWS Amplify (configurados mas não ativos); Contextos de autenticação em src/auth/context/*

6. ARQUITETURA BACKEND

Não aplicável - Frontend puro sem backend próprio

7. ROTAS E ENDPOINTS

Autenticação e Perfil: /login, /register, /forgot-password, /verify, /meu-perfil
Comercial: /comercial/visao-geral, /comercial/visao-geral-2; /comercial/orcamento, /comercial/orcamento/novo, /comercial/orcamento/[id], /comercial/orcamento/[id]/editar; /comercial/orcamento/[id]/proposta/nova-proposta, /comercial/orcamento/[id]/proposta/[propostaId]/editar; /comercial/orcamento/[id]/proposta/[propostaId]/proposta-detalhada; /comercial/orcamento/[id]/unidade-consumidora/novo, /comercial/orcamento/[id]/unidade-consumidora/[idUnidade]/editar; /comercial/orcamento/workflow, /comercial/orcamento/workflow/finalizados; /comercial/funil-de-vendas, /comercial/funil-de-vendas/funil-e-tags; /comercial/clientes, /comercial/clientes/novo, /comercial/clientes/[id], /comercial/clientes/[id]/editar
Contratos: /contratos/visao-geral, /contratos/dashboard, /contratos/gestao-contratos; /contratos/gestao-contratos/workflow, /contratos/gestao-contratos/workflow/finalizados; /contratos/emitir-contrato/[id], /contratos/criar-contrato, /contratos/[id]
Projetos: /projetos/visao-geral, /projetos/gestao-projetos, /projetos/gestao-projetos/workflow; /projetos/gestao-projetos/workflow/finalizados, /projetos/vistorias, /projetos/vistorias/[id]; /projetos/vistorias/workflow, /projetos/vistorias/workflow/finalizados, /projetos/[id]
Produção: /producao/visao-geral, /producao/produtos, /producao/produtos/novo, /producao/produtos/[id]; /producao/produtos/[id]/editar, /producao/produtos/categorias, /producao/ordem; /producao/gestao-producao, /producao/gestao-producao/workflow, /producao/gestao-producao/workflow/finalizados; /producao/fornecedores, /producao/fornecedores/novo, /producao/fornecedores/[id], /producao/fornecedores/[id]/editar; /producao/fornecedores/list, /producao/[id]
Obras: /obras/visao-geral, /obras/gestao-obras, /obras/gestao-obras/workflow; /obras/gestao-obras/workflow/finalizados, /obras/[id]
Financeiro: /financeiro/visao-geral, /financeiro/contas, /financeiro/contas/nova-conta; /financeiro/contas/[billId], /financeiro/contas/[billId]/editar, /financeiro/contas/dar-baixa/[billId]; /financeiro/movimentacoes, /financeiro/movimentacoes/nova-movimentacao, /financeiro/movimentacoes/[id]; /financeiro/categorias, /financeiro/caixas-e-bancos, /financeiro/caixas-e-bancos/nova-conta; /financeiro/caixas-e-bancos/[id], /financeiro/caixas-e-bancos/[id]/editar; /financeiro/clientes, /financeiro/clientes/novo, /financeiro/clientes/[id], /financeiro/clientes/[id]/editar; /financeiro/fornecedores, /financeiro/fornecedores/novo, /financeiro/fornecedores/[id], /financeiro/fornecedores/[id]/editar
Suprimentos: /suprimentos/visao-geral, /suprimentos/fornecedores, /suprimentos/fornecedores/novo; /suprimentos/fornecedores/[id], /suprimentos/fornecedores/[id]/editar
Recursos Humanos: /recursos-humanos/visao-geral, /recursos-humanos/colaboradores, /recursos-humanos/colaboradores/novo; /recursos-humanos/colaboradores/[id], /recursos-humanos/colaboradores/[id]/editar
Administração: /administracao/visao-geral, /administracao/modelo-de-proposta, /administracao/modelo-de-contrato; /administracao/minha-empresa, /administracao/unidades-de-negocio, /administracao/unidades-de-negocio/nova; /administracao/natureza-de-operacao, /administracao/natureza-de-operacao/nova; /administracao/usuarios, /administracao/usuario/novo, /administracao/usuarios/[id]/detalhes; /administracao/usuario/[id]/editar
Backoffice: /backoffice, /backoffice/customers, /backoffice/customers/novo, /backoffice/customers/[id]; /backoffice/customers/[id]/editar, /backoffice/plans, /backoffice/subscriptions; /backoffice/instances, /backoffice/instances/[id]
Gerais: / (home), /dashboard, /error/403, /error/404, /error/500

8. ESTRUTURA DE DADOS, TABELAS E VIEWS

Não aplicável - Frontend puro sem persistência própria

9. CONFIGURAÇÃO E VARIÁVEIS

APIs e Gateway: NEXT_PUBLIC_HOST_API, NEXT_PUBLIC_ASSETS_API, NEXT_PUBLIC_GATEWAY_BASE_URL
Microserviços: NEXT_PUBLIC_MS_PRODUCTS_BASE_URL, NEXT_PUBLIC_ADMIN_BASE_URL, NEXT_PUBLIC_BACKOFFICE_BASE_URL; NEXT_PUBLIC_COMERCIAL_BASE_URL, NEXT_PUBLIC_CONTRACT_BASE_URL, NEXT_PUBLIC_FINANCIAL_BASE_URL; NEXT_PUBLIC_COMMON_BASE_URL, NEXT_PUBLIC_FACILITIES_BASE_URL
Storage e Arquivos: NEXT_PUBLIC_S3_BASEURL (armazenamento de arquivos)
Firebase (Ativo): NEXT_PUBLIC_FIREBASE_API_KEY, NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN, NEXT_PUBLIC_FIREBASE_PROJECT_ID; NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET, NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID; NEXT_PUBLIC_FIREBASE_APPID, NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID
Auth0 (Configurado): NEXT_PUBLIC_AUTH0_CLIENT_ID, NEXT_PUBLIC_AUTH0_DOMAIN, NEXT_PUBLIC_AUTH0_CALLBACK_URL
AWS Amplify (Configurado): NEXT_PUBLIC_AWS_AMPLIFY_USER_POOL_ID, NEXT_PUBLIC_AWS_AMPLIFY_USER_POOL_WEB_CLIENT_ID; NEXT_PUBLIC_AWS_AMPLIFY_REGION
Supabase (Configurado): NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY
Mapbox: NEXT_PUBLIC_MAPBOX_API (integração de mapas)
Build e Runtime: NODE_OPTIONS (configurações do Node.js); NEXT_PUBLIC_BASE_URL (URL base da aplicação)

10. TREEVIEW DA ARQUITETURA

app-frontend/
├── src/
│   ├── app/                          # App Router: páginas, layouts, loading, not-found
│   │   ├── administracao/            # Gestão administrativa
│   │   ├── backoffice/               # Painel administrativo
│   │   ├── comercial/                # Módulo comercial
│   │   ├── contratos/                # Gestão de contratos
│   │   ├── dashboard/                # Dashboard principal
│   │   ├── error/                    # Páginas de erro (403, 404, 500)
│   │   ├── financeiro/               # Módulo financeiro
│   │   ├── login/, register/         # Autenticação
│   │   ├── obras/                    # Gestão de obras
│   │   ├── producao/                 # Módulo de produção
│   │   ├── projetos/                 # Gestão de projetos
│   │   ├── recursos-humanos/         # RH
│   │   ├── suprimentos/              # Gestão de suprimentos
│   │   └── layout.js                 # Layout raiz
│   ├── api/                          # Serviços por domínio com axios + React Query
│   │   ├── administrator/            # Administração (usuários, unidades, modelos)
│   │   ├── backoffice/               # Customers, plans, subscriptions, instances
│   │   ├── commercial/               # Orçamentos, propostas, funil, clientes
│   │   ├── contract/                 # Contratos, estágios, projetos, documentos
│   │   ├── financial/                # Contas, transações, categorias, clientes/fornecedores
│   │   ├── inventory/                # Fornecedores
│   │   ├── facilities/, common/, workflow/ # Arquivos, atividades, status
│   │   └── api.js                    # axios + interceptors + addTenantIdHeader
│   ├── auth/                         # Contextos, guards, hooks; Firebase/Auth0/Amplify
│   ├── components/                   # UI genérica, tabelas, mapas, dialogs, etc.
│   ├── sections/                     # Telas por domínio + formulários e hooks
│   ├── routes/                       # Paths utilitários, hooks de navegação
│   ├── theme/                        # MUI ThemeProvider, overrides e tipografia
│   ├── providers/                    # React Query, permissões, localização
│   ├── hooks/                        # Hooks utilitários e stores pontuais
│   ├── assets/, _mock/, data/        # Recursos, mocks e dados auxiliares
│   ├── config-global.js              # Exporta variáveis de ambiente e configs
│   └── global.css                    # Estilos globais + import Mapbox CSS
├── public/                           # Assets estáticos (imagens, ícones, fontes)
├── Dockerfile                        # Multi-stage build; porta 3032; output standalone
├── next.config.js                    # SVGR, modularizeImports MUI, trailingSlash
├── jsconfig.json                     # Aliases como @api/*, @config/*, @sections/*
├── package.json                      # Dependências e scripts
└── README.md                         # Documentação do projeto

11. INTEGRAÇÕES E DEPENDÊNCIAS

API Gateway: NEXT_PUBLIC_GATEWAY_BASE_URL (axios; header Authorization via cookie access_token); Interceptors para adicionar token JWT automaticamente; Suporte a multi-tenant via header x-tenant-id
Microserviços (via gateway): Contracts: rotas base /contracts/* (projetos, estágios, documentos, anexos, inspeções); Financial: rotas /financial/* (contas, transações, categorias, clientes, fornecedores); Commercial: rotas /commercial/* (clientes, budgets, proposals, funil, tags, irradiação); Administrator: rotas /administrator/* (unidades, modelos, empresas, usuários, assinantes); Backoffice: rotas /backoffice/* (customers, plans, subscriptions, instances); Inventory: rotas /inventory/* (fornecedores); Facilities/Common/Workflow: /facilities/*, /common/*, /workflow/* (arquivos, atividades, status, uploads)
Firebase (Ativo): Inicialização via FIREBASE_API de src/config-global.js; Autenticação e serviços Firebase integrados; Provider ativo no layout principal
Supabase (Configurado): Cliente criado em src/auth/context/supabase/lib.js (chaves em ENV); Configurado mas não ativo no layout principal
Mapbox GL: react-map-gl e estilos importados em global.css; Integração de mapas e geolocalização
PDF/Documentos: react-pdf (pdfjs worker), @react-pdf/renderer, docx e docx-preview; Geração e visualização de documentos
Armazenamento S3: Uso de NEXT_PUBLIC_S3_BASEURL; Upload via URLs pré-assinadas (registradas por endpoints em common/files)
Auth0 e AWS Amplify: Configurados mas não ativos no layout principal; Suporte para múltiplos provedores de autenticação

12. INTEGRAÇÕES EXTERNAS

API Gateway: Integração principal com gateway HTTP para comunicação com microserviços; Balanceamento de carga e roteamento de requisições
Firebase: Autenticação e serviços Firebase (ativo); Gerenciamento de usuários e sessões
Supabase: Cliente Supabase para funcionalidades específicas (configurado); Banco de dados e autenticação alternativa
Mapbox: Integração de mapas e geolocalização; Visualização de dados geográficos
AWS S3: Armazenamento de arquivos via URLs pré-assinadas; Upload e download de documentos e imagens
Auth0 e AWS Amplify: Provedores de autenticação alternativos (configurados); Suporte para múltiplas estratégias de autenticação

13. CONTROLE DE VERSÃO

Repositório: Local/GitHub
Versionamento: Semântico (atual: v5.7.0)
Ferramentas: Husky para git hooks e commitlint para conventional commits; ESLint e Prettier para qualidade de código; Scripts de build e deploy automatizados

14. SEGURANÇA E ACESSO

Autenticação: Tokens JWT lidos de cookie access_token e enviados em Authorization: Bearer; Firebase como provedor principal de autenticação; Suporte a múltiplos provedores (Auth0, AWS Amplify, Supabase)
Autorização: Sistema de permissões baseado em roles e recursos; Guards de rota para controle de acesso; Multi-tenant via header x-tenant-id quando aplicável
Segurança: Segredos e chaves somente via variáveis de ambiente (não versionadas); Interceptors para validação automática de tokens; CORS configurado para domínios específicos

15. CONSIDERAÇÕES FINAIS

O app-frontend representa uma solução robusta e escalável para gestão de projetos de energia solar, desenvolvida com tecnologias modernas e seguindo boas práticas de desenvolvimento. A arquitetura modular e orientada a domínios facilita a manutenção e evolução do sistema, enquanto as integrações com múltiplos microserviços proporcionam uma experiência de usuário unificada e completa.

Principais características:

Frontend modular com App Router, tema MUI e React Query para gerenciamento de estado
Autenticação via Firebase com suporte a múltiplos provedores
Conectores padronizados (axios) para microserviços através do API Gateway
Integrações de mapa, geração de documentos e armazenamento de arquivos
Sistema de permissões robusto e suporte a multi-tenant
Build otimizado com Docker e deploy automatizado