# Visão Geral do Software

Descrição geral do objetivo e interações do projeto para contextualização do time de desenvolvimento e I.A.

# Gerenciador de Download XML

### Objetivo principal

Aplicação desktop (Angular + Electron) que permite aos clientes da Avanço Informática baixar em massa XMLs fiscais (NFe/NFCe) previamente exportados e arquivados em S3. O usuário é guiado por um fluxo em etapas: login/identificação, escolha da pasta de destino, seleção das solicitações de exportação disponíveis, download paralelo com progresso e retomada, e tela de conclusão com estatísticas.

### Principais tecnologias

Angular 21 (standalone/signals) / Angular Material & CDK / Tailwind CSS v4 / Electron 35 + electron-builder / Angular SSR (Express) / RxJS / TypeScript / Vitest / adm-zip

### Principais funcionalidades

- Autenticação JWT: login por e-mail/senha contra a API própria da Avanço
- Resolução dinâmica da API por tenant: consulta um serviço "centralizador" para descobrir a URL da API do cliente antes do login
- Listagem de solicitações de exportação: exibe e filtra por status (disponível, restaurando, expirada, concluída, etc.) com paginação
- Manifesto de arquivos: ao selecionar solicitações, obtém contagem de arquivos, tamanho total e tempo estimado
- Download paralelo em lote: pool de até 50 downloads simultâneos com barra de progresso agregada e log por arquivo
- Retomada incremental: usa HTTP Range para continuar downloads parciais e detectar arquivos já completos
- Checkpoint de resiliência: grava progresso em disco para retomar downloads entre sessões do app
- Renovação automática de URLs assinadas: detecta expiração de links do S3 durante o lote e atualiza as tarefas pendentes
- Cancelamento de downloads em andamento preservando o progresso já realizado
- Organização automática dos arquivos por referência/CNPJ/tipo de documento/modelo fiscal, com descompactação automática de .zip

### Principais integrações

- API própria da Avanço Informática: autenticação, listagem de exportações, manifesto de arquivos e notificação de conclusão do download
- Serviço centralizador: resolve a URL base da API correta por usuário/tenant antes do login
- AWS S3: origem dos arquivos XML/ZIP baixados via URLs assinadas, com suporte a download parcial (Range)
- AWS S3 (deploy): pipeline de CI publica os instaladores (AppImage/deb/exe) em bucket próprio
- GitLab CI/CD: build e deploy automatizados usando imagem Docker própria do projeto

# Novo Avanço (Novo TNFe)

### Objetivo principal

Novo Avanço é um ERP voltado para o varejo supermercadista e panificadoras, oferecendo suporte às áreas fiscal, financeira, logística e de ponto de venda (PDV). O projeto é composto por três repositórios executados em conjunto: uma API backend, uma interface web e um conjunto de funções serverless (lambdas) para processamento fiscal e tarefas assíncronas.

### Principais tecnologias

NestJS / TypeScript / Angular / PostgreSQL (Sequelize) / Redis + Bull / Socket.IO / AWS Lambda (Node.js e Java) / Serverless Framework / Docker

### Principais funcionalidades

- Gestão fiscal: emissão, manifestação e apuração de NFe/NFCe, geração de SPED, SINTEGRA e REINF
- PDV (Ponto de Venda): frente de caixa com sincronização de vendas e suporte a diferentes agentes (PDV, supervisor, balança, terminal de consulta)
- Financeiro: contas a pagar/receber, fechamento de caixa e conciliação bancária
- Cadastros básicos: empresas, filiais, produtos, EAN e classificação mercadológica
- Movimento de estoque: entradas, saídas, recebimento de produtos e produção
- Farol de preços: monitoramento e comparação de preços de mercado
- Restaurante: módulo específico para operação de restaurantes e panificadoras
- Assistente com IA: assistente virtual baseado em IA para apoio aos usuários do sistema
- Aplicativo/App Avanço: aplicativo mobile complementar ao ERP
- Central de integrações: gestão e monitoramento de integrações com sistemas e parceiros externos

### Principais integrações

- SEFAZ: comunicação para emissão, manifestação e consulta de NFe/NFCe (via funções lambda dedicadas)
- Scanntech: integração para sincronização de preços e cadastro com parceiro do varejo
- Panamah: integração com plataforma de dados/gestão Panamah
- OpenAI: modelo de IA utilizado pelo módulo de assistente virtual
- Sentry: monitoramento e rastreamento de erros da aplicação
- AWS (S3, Lambda, SQS/SSM): infraestrutura de armazenamento, processamento serverless e configuração
- Smart TEF: integração com meios de pagamento via TEF (webhooks de transação)
- Tecnospeed Pagador: integração para emissão e processamento de pagamentos/boletos
- Discord: envio de alertas operacionais via webhook
- Redis: cache distribuído e filas de processamento assíncrono (Bull)

# Novo Agente

### Objetivo principal

Agente daemon Node.js/TypeScript que roda como serviço Windows ou daemon Linux em pontos de venda do varejo brasileiro, lendo saídas de impressoras fiscais/ECF (cupons e reduções Z) e sincronizando dados de vendas, produtos e promoções com o backend do Novo Avanço.

### Principais tecnologias

Node.js / TypeScript / Express / Socket.io / lowdb / superagent

### Principais funcionalidades

- Daemon multiplataforma de PDV: roda como serviço Windows ou Linux, com tipos (novoAvanco, cupom, novoAvancoOutros, supervisor) e subtipos (PDV, balança, terminal)
- Leitura e envio de cupons fiscais: monitora pastas geradas pelo ECF e envia cupons e reduções Z ao backend em tempo real
- Sincronização com o ERP/backend: recebe cargas de produtos e preços e grava localmente em DBF (Linux) ou SQLite (Windows) para o PDV consumir
- Sincronização de balança e terminal de consulta: fluxos equivalentes para esses periféricos
- Promoções Scanntech: busca periodicamente promoções ativas/rejeitadas e gera arquivos lidos pelo PDV para aplicar descontos
- Consulta de clientes: expõe busca local de clientes cadastrados a partir de base exportada pelo ERP
- Atualização automática: verifica e baixa novas versões do próprio agente via S3, com canais prod/qas/beta
- Status em tempo real: reporta conexão, autenticação e progresso de sincronização via Socket.io e SSE local
- Instalação e gestão como serviço: instala, remove e configura via linha de comando (flags --servico, --instalar, --remover, --config)

### Principais integrações

- API Novo Avanço: autenticação, dados de usuário, lojas/filiais e configuração de integrações
- API CDV: integração com sistema legado de varejistas (obtenção e validação de token)
- Centralizador Infovarejo: resolve dinamicamente a URL do ambiente do cliente a partir do e-mail
- API Scanntech: consulta promoções ativas e rejeitadas por loja/empresa
- Socket.io (backend Novo Avanço): canal bidirecional para eventos de cupom, carga e redução Z
- SSE local: expõe status de sincronização em tempo real para consumidores locais
- Amazon S3: distribuição de binários para atualização automática do agente
- Banco SQLite de clientes (dblite): leitura local de base exportada pelo ERP para consulta de clientes

# Impressão Local

### Objetivo principal

Aplicativo desktop (Windows e Linux) para impressão local de etiquetas de produtos do ecossistema NovoAvanço. Busca produtos via API, monta uma fila de impressão e envia comandos ZPL/EPL diretamente para impressoras térmicas locais, sem depender de spool gráfico ou impressão pelo navegador.

### Principais tecnologias

Angular 19 / Electron / TypeScript / Angular Material

### Principais funcionalidades

- Busca de produtos: por EAN/código de barras ou por descrição
- Impressão em lote: busca e imprime todos os produtos de um lote pendente
- Fila de impressão: lista de produtos com edição inline de quantidade antes de imprimir
- Autoimpressão: envia o produto direto para a impressora após cada busca bem-sucedida
- Modo Teste: opera com dados simulados (100 produtos mock), sem depender de API ou configuração
- Configuração de impressora: seleção da impressora e calibração de mídia (largura/altura/gap da etiqueta)
- Layouts ZPL/EPL somente leitura: sincronizados com o NovoAvanço, com identificação visual do tipo (EPL2/ZPL)
- Autenticação multi-etapa: e-mail/senha, resolução de ambiente e seleção de filial
- Modo homologação (QAS): expõe layouts de teste embutidos para validação antes de produção
- Consulta de promoções: exibe preço promocional vinculado ao produto buscado

### Principais integrações

- Centralizador (Infovarejo): resolve o ambiente/URL base da empresa a partir do e-mail informado no login
- NovoAvanço API — Autenticação: login e troca do token geral por um token de filial com permissões específicas
- NovoAvanço API — Produtos: busca de produtos por EAN (fichaFinanceira) ou por descrição
- NovoAvanço API — Promoções: consulta o preço promocional vigente de um produto
- NovoAvanço API — Lotes de impressão: lista lotes pendentes, produtos do lote e atualização de status para impresso
- NovoAvanço API — Etiquetas: sincroniza os layouts ZPL/EPL cadastrados e gerenciados no sistema NovoAvanço
- NovoAvanço API — Filiais: lista as filiais associadas à empresa para seleção no login
- Impressoras térmicas locais: envio de comandos ZPL/EPL brutos via winspool (Windows) ou CUPS `lp -o raw` (Linux)

# Centralizador

### Objetivo principal

Sistema de backoffice que cadastra e administra os múltiplos ambientes do sistema Novo Avanço hospedados na AWS (um ambiente por conta/cliente), controlando empresas, usuários, grupos e permissões, e funcionando como ponto único para sistemas externos descobrirem a URL do ambiente correto de um cliente a partir de e-mail ou hash.

### Principais tecnologias

NestJS / TypeScript / Prisma + PostgreSQL / Redis / Angular 17 + Angular Material / JWT

### Principais funcionalidades

- Autenticação: Login/logout com JWT e sessão do usuário logado
- Ambientes AWS: CRUD dos ambientes (nome, URL base, access key, homepage)
- Grupos de Ambientes: Agrupamento de ambientes AWS, associados a labels e perfis
- Usuários por Ambiente: Vínculo de usuários a ambientes específicos, com upsert em lote
- Empresas: CRUD de empresas clientes vinculadas a um ambiente AWS (CNPJ, endereço, produtos, bloqueio)
- Perfis de acesso: Perfis de permissão associados a grupos de ambientes
- Labels: Etiquetas visuais (cor/ícone) para organizar grupos de ambientes
- Usuários do sistema: CRUD de usuários administradores/operadores do Centralizador
- Resolução de ambiente: Endpoint que descobre a URL base do ambiente de um usuário a partir de e-mail ou hash
- Configurações: Tela de configurações do sistema no frontend

### Principais integrações

- PostgreSQL: Banco de dados principal da aplicação, via Prisma ORM
- Redis: Presente na infraestrutura Docker do projeto (uso específico no código não confirmado)
- Autenticação via hash (header authorizationhash / HASHGUARD): Canal usado por sistemas externos para consultar/cadastrar hashes e resolver o ambiente do cliente
- Endpoint "listForCotacao": Lista de ambientes consumida por um sistema externo de Cotação (integração não totalmente confirmada apenas pelo código)

# IA Classificação Mercadológica

### Objetivo principal

API Django que classifica produtos em uma estrutura mercadológica (departamento > categoria > subcategoria) usando IA generativa. Recebe descrição/EAN/NCM de um produto, consulta a base local antes de acionar a IA (evitando reprocessamento) e cadastra automaticamente o produto quando classificado com sucesso. Suporta classificação unitária e em lote, registra telemetria de uso (tokens e quantidade de produtos por empresa/grupo) e gera/envia mensalmente uma planilha de bilhetagem por e-mail.

### Principais tecnologias

Python / Django 5 / Django REST Framework / LangChain (integração plugável com provedores de LLM) / PostgreSQL (pgvector) / Docker

### Principais funcionalidades

- Classificação unitária de produtos: recebe descrição/EAN/NCM e retorna departamento, categoria e subcategoria, usando a base existente ou acionando a IA quando necessário
- Classificação em lote (v1 e v2): permite enviar múltiplos produtos para classificação, com modelo v2 baseado em lotes assíncronos com status (criado, pendente, processando, concluído, falhou) e callback de retorno
- Cadastro automático de produtos: quando um produto com EAN é classificado com sucesso, é inserido na base para consultas futuras sem nova chamada à IA
- Votação de classificação: endpoint para aprovar/reprovar a classificação de um produto, com comentário obrigatório em caso de reprovação
- Normalização de descrições de produtos: upsert em lote de descrições normalizadas por GTIN/NCM, usadas para enriquecer o prompt enviado à IA
- Configuração dinâmica de modelo de IA: cadastro via admin do modelo ativo (biblioteca, parâmetro de chave de API, prompts unitário e de lote), com instalação automática do pacote pip necessário
- Telemetria de uso de IA: registro de tokens consumidos, tipo de operação (recuperação em base, unitário, em massa) e quantidade de produtos por usuário/grupo (empresa)
- Bilhetagem mensal: comando agendado (cron) que gera planilha XLSX de consumo por empresa e envia por e-mail via SMTP
- Multiempresa via grupos: cadastro de empresas/usuários com token de API, associados a grupos que segmentam a telemetria por ambiente/empresa
- Importação de classificações: comando de management para carregar a estrutura de departamentos/categorias/subcategorias a partir de um arquivo JSON

### Principais integrações

- Provedores de LLM via LangChain: modelo de IA plugável e configurável em runtime (ex: OpenAI, Google), definido por classe/pacote cadastrados no admin
- PostgreSQL com pgvector: banco de dados principal, preparado para buscas vetoriais
- SMTP: envio automático da planilha mensal de bilhetagem de uso da IA por e-mail
- API de cadastro de empresas/usuários: endpoint de integração para provisionamento automático de empresas e emissão de token de acesso
- Callback HTTP (api\_callback\_url): notificação de sistemas externos sobre a conclusão de um lote de classificação

# Frente Avanço (PDV Legado)

### Objetivo principal

Sistema de frente de caixa (PDV) para varejo, executado em Linux nas lojas. Cuida da operação de vendas no caixa, emissão de documentos fiscais (cupom fiscal ECF, SAT ou NFC-e conforme o modelo da loja), fechamento de caixa, cadastro de clientes, pré-venda em tela touchscreen e integração com os equipamentos da loja (balanças, pinpad, leitor biométrico, impressoras fiscais e TEF).

### Principais tecnologias

xHarbour (Clipper) / C / DBF (dBase) / Shell Script / Linux

### Principais funcionalidades

- Frente de caixa (PDV): registro de vendas, itens e formas de pagamento no módulo principal (pdv.prg)
- Fechamento de caixa: apuração e fechamento dos valores do caixa por operador
- Emissão de cupom fiscal: geração do documento fiscal via impressora ECF, SAT ou NFC-e, conforme o modelo fiscal da loja
- Cadastro e consulta de clientes: manutenção de dados de clientes e consulta de produtos/preços
- Controle de contas e cheques: lançamento e controle de cheques recebidos e contas correntes de clientes
- Pré-venda: geração de pedidos antecipados que depois são finalizados no caixa
- Tela touchscreen: interface alternativa por toque para seleção de produtos e finalização da venda
- Programa de fidelidade: consulta e acúmulo de pontos/benefícios do cartão fidelidade
- Autenticação biométrica: identificação de operadores por biometria
- Atualização remota: baixa e aplica atualizações de versão do sistema nas lojas

### Principais integrações

- SAT Fiscal: emissão do CF-e (cupom fiscal eletrônico) via módulos de SAT (Bematech/Urano)
- NFC-e / SEFAZ: geração, correção e contingência do XML/JSON da nota fiscal de consumidor eletrônica
- TEF SiTef: pagamento com cartão de crédito/débito via protocolo SiTef (Software Express)
- Impressoras fiscais ECF: emissão de cupom fiscal em múltiplas marcas (Bematech, Daruma, Data Regis, Epson, Sweda, ZPM)
- Balanças eletrônicas: leitura de peso de produtos pesáveis (Filizola, Urano, UPX/UPX USB)
- Pinpad/teclado Gertec: leitura de cartão e senha via teclado Gertec Tec65c4
- Assinatura digital de XML: assinatura dos XMLs fiscais via AssinaXML
- Programa de fidelidade Lealtex: consulta e resgate de benefícios do cartão fidelidade

# NovoErp (TNFe)

### Objetivo principal

O NovoErp é um sistema de gestão empresarial (ERP) para varejo, com PDV, controle de estoque, financeiro e módulo fiscal completo de emissão e gestão de NF-e/NFC-e. O repositório reúne a API/cliente principal (LoopBack + AngularJS) e um conjunto de funções AWS Lambda responsáveis pelo processamento fiscal (SEFAZ, DANFe, SPED/REINF/Sintegra) e por tarefas assíncronas do ERP. Também inclui o NovoCentral, módulo para gestão de compras e pedidos de supermercados associados.

### Principais tecnologias

Node.js / LoopBack / AngularJS / PostgreSQL / Redis / Socket.io / AWS Lambda (Node.js e Java) / Serverless Framework / Docker

### Principais funcionalidades

- PDV (Frente de Caixa): módulo de ponto de venda integrado ao ERP.
- Gestão de produtos e preços: cadastro de produtos, tabelas de preço e promoções.
- Controle de estoque: acerto de estoque e histórico de movimentações.
- Financeiro: categorias financeiras, contas a pagar/receber e boletos.
- Fiscal (NF-e/NFC-e): emissão, consulta, cancelamento, carta de correção e manifestação do destinatário.
- Pedidos de compra e venda: fluxo completo entre fornecedores, clientes e vendedores.
- Cadastros gerais: clientes, fornecedores, transportadoras, filiais e vendedores.
- Relatórios e painel de vendas: dashboards gerenciais e relatórios de vendas.
- Obrigações acessórias: geração de arquivos SPED, Sintegra e REINF.
- NovoCentral: portal de compras e pedidos para supermercados associados.

### Principais integrações

- SEFAZ: emissão, consulta e cancelamento de NF-e/NFC-e via webservice SOAP com assinatura digital (lambda nfe4).
- Pagar.me: geração de boletos bancários e recebimento de postback de pagamento.
- SendGrid (SMTP): envio de e-mails transacionais do ERP.
- AWS SES: disparo de e-mails via função Lambda dedicada.
- AWS S3: armazenamento de arquivos (XMLs, DANFEs, planilhas e uploads).
- AWS SQS: fila para processamento assíncrono de manifestação de notas fiscais.
- Lambda DANFe (Java): geração da representação gráfica (DANFe) a partir do XML autorizado, com mais de 40 modelos.
- IMAP: importação automática de XMLs de notas recebidas por e-mail.

# Carga NFe

### Objetivo principal

Agente Node.js instalado nas máquinas do cliente que faz a ponte entre o ERP Integral (PDV/fiscal local) e os tramitadores fiscais da Avanço (TNFE/NovoTNFE e Novo Avanço). Monitora diretórios locais em busca de arquivos posicionais gerados pelo ERP (NF-e, cancelamento, inutilização, cupons, etc.), envia esse conteúdo para a API do tramitador configurado e, no sentido inverso, baixa XML/DANFE, NF-e destinadas, inutilizações e configurações de promoção, gravando-os de volta para o ERP consumir.

### Principais tecnologias

Node.js (7/8/11 conforme etapa) / chokidar / superagent / async / cron / dblite (SQLite) / winston / forever-monitor / Java (jar para NF-e offline e DANFE) / NSSM (serviço Windows)

### Principais funcionalidades

- Envio de NF-e: monitora arquivos .nfe, monta o JSON da nota e envia ao tramitador ativo, disparando download de DANFE/XML de retorno
- Cancelamento de NF-e: monitora arquivos .pcn e envia o pedido de cancelamento, gravando o retorno em .rcn
- Inutilização de numeração: monitora arquivos .pin e consulta periodicamente inutilizações homologadas
- Conciliação de chaves: monitora arquivos .con e envia consultas de conciliação ao tramitador
- Consulta de cupom fiscal: monitora arquivos .cac e envia consultas de arquivo de cupom, gravando retorno em .rca
- Manifestação do destinatário: monitora arquivos .mnf e envia manifestações de NF-e via carga
- EFD-Reinf: monitora arquivos .reinf, envia eventos ao tramitador e consulta periodicamente o processamento
- NF-e destinadas: consulta periodicamente NF-e recebidas de terceiros e grava os XML localmente
- Processamento de cupons fiscais: mantém banco SQLite local, valida cupons e envia ao Novo Avanço, com suporte a reprocessamento
- Promoções Scanntech: consulta configuração e promoções vigentes por loja e grava arquivos posicionais para o PDV/ECF

### Principais integrações

- TNFE / NovoTNFE: API REST do tramitador legado, autenticada por apikey/token, usada para envio e consulta de NF-e, cancelamentos, inutilizações, DANFE, manifestação e Reinf
- Novo Avanço: API REST do tramitador mais novo, autenticada via Bearer token, usada para processamento de NF-e, manifestação, inutilização, Reinf, consulta de comandos pendentes e processamento de cupons
- Scanntech: configuração e promoções por loja, consumidas de forma mediada pelo backend Novo Avanço
- SEFAZ (indireto): tabelas de webservices por UF/modelo e lógica de contingência, usadas pelo módulo de emissão offline
- Atualização automática via S3: download periódico de pacotes de atualização (zip) e versão a partir de bucket na Amazon S3
- ERP Integral local: sistema de PDV/fiscal do cliente que gera os arquivos posicionais consumidos e recebe os retornos processados