Skip to content

README.md

Latest commit

 

History

History
704 lines (567 loc) · 24.2 KB

README.md

File metadata and controls

704 lines (567 loc) · 24.2 KB
Raw

Nexus Field

Field Service Management Platform
Plataforma SaaS Enterprise para gestão completa de equipes técnicas externas, ordens de serviço, geolocalização, agenda, check-in/check-out, estoque móvel, financeiro e relatórios técnicos.

Brasil Português | USA English

License Status TypeScript Node.js Fastify MariaDB React React Native Expo Prisma Tailwind JWT

📸 Screenshots

Capturas ilustrativas da interface do Nexus Field.

Ordens de Serviço

Ordens de Serviço 		Dashboard

Dashboard
Clientes

Clientes 		Técnicos

Técnicos
Agenda

Agenda 		Geolocalização

Geolocalização
Financeiro

Financeiro 		Relatórios

Relatórios

Sobre o Projeto

O Nexus Field é uma plataforma SaaS Enterprise Premium Black Edition desenvolvida para empresas que gerenciam equipes técnicas em campo. O sistema oferece controle total sobre o ciclo de vida dos serviços externos, desde a abertura da ordem de serviço até a conclusão, com recursos avançados de geolocalização, check-in/check-out, gestão de estoque móvel, controle financeiro e relatórios técnicos detalhados.

Problema que resolve

Empresas com equipes técnicas externas enfrentam desafios significativos no dia a dia: controle manual de ordens de serviço, falta de rastreabilidade dos técnicos, ausência de histórico completo de atendimentos, dificuldade em gerenciar estoque em campo, e ausência de dashboards gerenciais para tomada de decisão. O Nexus Field resolve todos esses problemas através de uma plataforma integrada e automatizada.

Público-alvo

  • Empresas de manutenção — Manutenção predial, industrial e equipamentos
  • Assistências técnicas — Eletrônicos, eletrodomésticos e informática
  • Telecom — Provedores de internet, TV e telefonia
  • Energia — Concessionárias e empresas do setor elétrico
  • Segurança eletrônica — Instalação e manutenção de sistemas
  • Climatização — Ar condicionado e refrigeração
  • Field Service — Qualquer prestador de serviços externos
  • Prestadores de serviços externos — Empresas com equipes em campo

Benefícios

  • Centralização operacional — Toda a operação em uma única plataforma
  • Mais produtividade — Eliminação de processos manuais e redundantes
  • Controle de técnicos — Visibilidade completa sobre atividades em campo
  • Rastreabilidade — Histórico detalhado de todos os atendimentos
  • Redução de retrabalho — Processos padronizados e validados
  • Gestão em tempo real — Dashboards atualizados instantaneamente
  • Experiência SaaS Enterprise — Interface premium e profissional

Funcionalidades

Autenticação

  • Login seguro com JWT
  • Controle de sessão por token com keep-alive automático
  • Cadastro com confirmação de senha (show/hide)
  • Recuperação de senha com token criptografado (32 bytes, 1h)

Dashboard

  • Visão gerencial com KPIs
  • Gráficos e métricas em tempo real
  • Cards com estatísticas principais

Clientes

  • Cadastro completo com busca e filtros
  • Histórico de atendimentos
  • Status de cliente (ativo/inativo)

Técnicos

  • Gestão de equipes com perfil
  • Geolocalização em tempo real
  • Status de disponibilidade

Ordens de Serviço

  • Ciclo completo: abertura, atribuição, execução, conclusão
  • Status: pendente, em andamento, concluída, cancelada
  • Vínculo com cliente e técnico

Chamados Técnicos

  • Sistema de tickets com categorias
  • Prioridades: baixa, média, alta, urgente
  • SLA configurável

Agenda

  • Calendário de visitas técnicas
  • Vínculo com clientes e técnicos
  • Filtro por data e status
  • Status: agendado, concluído, cancelado

Check-in e Check-out

  • Rastreamento de início e fim dos atendimentos
  • Registro de localização
  • Histórico completo de check-ins

Geolocalização

  • Mapa interativo Leaflet
  • Localização em tempo real dos técnicos
  • Marcadores personalizados
  • Popups com informações do técnico

Estoque Móvel

  • Controle de peças por técnico
  • Movimentações de entrada e saída
  • Alerta de estoque baixo
  • Histórico completo de movimentações

Financeiro

  • Receitas e despesas
  • Fluxo de caixa
  • Categorias personalizáveis
  • Status: pendente, pago, vencido, cancelado

Relatórios

  • Relatórios gerenciais de produtividade
  • Relatórios financeiros
  • Exportação em JSON, PDF e Excel

Notificações

  • Central de alertas do sistema
  • Alertas de ordens de serviço
  • Marcar como lida / ler todas

Controle de Acesso (RBAC)

  • Hierarquia de permissões: superadmin, admin, supervisor, technician, operator, client, user
  • Super Admin (marcelolimadez@gmail.com) protegido contra alteração/exclusão
  • Admin de demonstração (admin@nexusfield.com) com acesso somente leitura
  • Rotas de escrita bloqueadas via checkNotDemo

Auditoria

  • Registro completo de ações (criação, edição, exclusão)
  • Tabela dedicada audit_logs no banco
  • Consulta via GET /api/audit
  • Registro de userId, ação, entidade, IP e detalhes

Configurações

  • Personalização de tema (Dark/Light Mode com preto 100%)
  • Dados da empresa
  • Configurações de segurança

Módulos Implementados

Módulo Status
Autenticação (login, cadastro, forgot/reset) ✅
Dashboard ✅
Clientes ✅
Técnicos ✅
Ordens de Serviço ✅
Chamados Técnicos ✅
Agenda ✅
Check-in/Check-out ✅
Geolocalização ✅
Estoque Móvel ✅
Financeiro ✅
Relatórios ✅
Notificações ✅
Configurações ✅
Auditoria ✅
Sobre Nexus Field ✅
App Mobile (React Native) ✅
Evidências e Assinatura Digital ✅
Assistente IA (Nexus AI Assistant) ✅
Mobile API (Config) ✅

Tecnologias

Backend

Tecnologia Finalidade
Node.js 22.x Runtime JavaScript
Fastify 5 Framework HTTP
TypeScript 5.8 Tipagem estática
Prisma 6.6 ORM
JWT Autenticação stateless
Zod Validação de schemas
Helmet Headers de segurança HTTP
Rate Limiting Proteção contra abuso de API
@fastify/swagger Documentação OpenAPI

Frontend

Tecnologia Finalidade
React 18.3 Biblioteca de UI
Vite 5 Bundler e dev server
Tailwind CSS 3 Framework de estilos
React Router Roteamento
Zustand Gerenciamento de estado
React Query Cache e sincronização de dados
Lucide Icons Biblioteca de ícones
Leaflet Biblioteca de mapas
Recharts Biblioteca de gráficos
React Hook Form Gerenciamento de formulários
date-fns Manipulação de datas

Mobile

Tecnologia Finalidade
React Native 0.85 Aplicativo nativo multiplataforma
Expo SDK 56 Framework de desenvolvimento mobile
React Navigation 7 Navegação entre telas
Axios Comunicação com API
AsyncStorage Armazenamento local offline
react-native-svg Ícones e gráficos vetoriais
react-native-maps Mapas e geolocalização nativa

Banco de Dados

Tecnologia Finalidade
MySQL/MariaDB Banco relacional
Prisma Migrations Evolução do schema
Prisma Seed Dados iniciais

Identidade Visual

Tecnologia Finalidade
Enterprise SaaS Premium Black Edition Design premium
Preto Premium Base escura sofisticada
Verde Nexus (#19B44A) Cor principal da marca
Dourado Premium (#F4B400) Destaques e elementos premium
Dark/Light Mode Suporte completo a temas

Estrutura de Pastas

nexusfield/
├── backend/              → API REST (Fastify + TypeScript)
│   ├── prisma/
│   │   ├── schema.prisma              # Modelo de dados (12 tabelas)
│   │   ├── seed.ts                    # Dados de exemplo completos
│   │   └── migrations/                # Histórico de migrações
│   ├── src/
│   │   ├── middleware/permissions.ts  # RBAC + checkNotDemo
│   │   ├── plugins/                   # Auth JWT, Prisma, Helmet
│   │   ├── routes/                    # 15 módulos de rotas CRUD + audit + mobile
│   │   ├── utils/
│   │   │   ├── audit.ts              # Registro de auditoria
│   │   │   └── validation.ts          # Schemas Zod
│   │   ├── services/                  # (reservado)
│   │   └── index.ts                   # Servidor Fastify 5
│   ├── uploads/evidences              # Fotos de evidências (before/after)
│   ├── .env.example
│   ├── .gitignore
│   ├── package.json
│   └── tsconfig.json
├── mobile/               → App mobile (React Native + Expo)
│   ├── src/
│   │   ├── api/                       # Axios client + endpoints
│   │   ├── components/                # Componentes reutilizáveis
│   │   ├── navigation/                # React Navigation stack
│   │   ├── screens/                   # Telas do app
│   │   ├── storage/                   # AsyncStorage helpers
│   │   ├── theme/                     # Cores e estilos globais
│   │   ├── types/                     # TypeScript types
│   │   └── utils/                     # Helpers e formatters
│   ├── App.tsx                        # Entry point
│   ├── index.ts                       # Expo registerRootComponent
│   ├── app.json                       # Expo config
│   ├── package.json
│   └── tsconfig.json
├── frontend/             → Aplicação web (React + Vite)
│   ├── public/
│   │   └── logo-nexus.png             # Logo oficial
│   ├── src/
│   │   ├── api/                       # Axios client + endpoints
│   │   ├── components/
│   │   │   ├── DemoAccessModal.jsx    # Bloqueio de demo
│   │   │   ├── FeedbackModal.jsx      # Toasts + ConfirmModal
│   │   │   ├── Footer.jsx             # Rodapé simplificado
│   │   │   ├── Layout.jsx             # Layout principal
│   │   │   ├── Navbar.jsx             # Topo com boas-vindas
│   │   │   ├── ProtectedRoute.jsx     # Rota protegida
│   │   │   ├── OSConclusaoModal.jsx   # Evidências + Assinatura
│   │   │   ├── Sidebar.jsx            # Navegação com logo
│   │   │   └── ui/
│   │   │       └── Modal.jsx          # Modal genérico
│   │   ├── context/                   # ThemeContext (dark/light)
│   │   ├── pages/                     # 17 páginas funcionais
│   │   ├── store/authStore.js         # Zustand + keep-alive
│   │   ├── utils/constants.js         # Helpers e formatters
│   │   ├── App.jsx                    # Rotas
│   │   ├── main.jsx                   # Entry point
│   │   └── index.css                  # Variáveis CSS + dark mode
│   ├── package.json
│   ├── vite.config.js
│   └── tailwind.config.js
├── publicar.ps1           → Script de automação git
├── CHANGELOG.md
├── README.md
└── README.en.md

Segurança

O projeto implementa múltiplas camadas de segurança:

Camada Descrição
JWT Tokens com expiração configurável, sem fallback para secret padrão
RBAC Hierarquia de permissões com 7 níveis de acesso
Demo Block Admin de demonstração bloqueado em todas as operações de escrita
Super Admin Protegido contra alteração e exclusão (e-mail imutável)
Auditoria Registro completo de ações com userId, IP e detalhes
Rate Limit 10 req/min no login, 5 req/min no forgot-password
Helmet Headers HTTP de segurança (XSS, CSP, HSTS)
Zod Validação rigorosa de todas as entradas
Body Limit 1MB, maxParamLength 500

Arquitetura

┌─────────────────────┐  ┌─────────────────────┐
│   Frontend Web      │  │   App Mobile        │
│ React + JavaScript  │  │ React Native + Expo │
└──────────┬──────────┘  └──────────┬──────────┘
           │ HTTP + JWT            │ HTTP + JWT
           ▼                       ▼
┌─────────────────────────────────────────────┐
│               API REST                      │
│         Fastify + Node.js                   │
│         TypeScript + Zod                    │
└───────────────────┬─────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────┐
│         15 Rotas de API                     │
│  Auth • Clientes • Técnicos                 │
│  Ordens de Serviço • Chamados • Agenda      │
│  Check-in/Check-out • Geolocalização        │
│  Financeiro • Estoque Móvel                 │
│  Notificações • Configurações               │
│  Dashboard • Auditoria • Users • Mobile     │
└───────────────────┬─────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────┐
│              MySQL/MariaDB                  │
│               Prisma ORM                    │
└─────────────────────────────────────────────┘

Segurança

  • JWT Authentication
  • Rate Limiting
  • Helmet
  • CORS
  • Validação Zod

Arquitetura

  • Frontend React
  • Backend Fastify
  • Banco MySQL/MariaDB
  • API REST
  • Prisma ORM

Escalabilidade

  • Arquitetura modular
  • Separação por domínio
  • Preparado para SaaS
  • Preparado para integrações futuras

Banco de Dados

O projeto utiliza MariaDB 11.4 (porta 3307) como banco de dados relacional. O banco é nomeado nexusfield.

Migrations

As migrations são gerenciadas pelo Prisma:

npx prisma migrate dev --name <nome>

Seed

O seed inicial cria dados de exemplo:

npx tsx prisma/seed.ts

Instalação

Pré-requisitos

  • Node.js >= 22
  • MariaDB >= 10.x (porta 3307 no WAMP)
  • Git
  • npm (incluído com Node.js)

Passo a passo

# 1. Clone o repositório
git clone https://github.com/claytonmarcelo/Nexus-Field.git
cd Nexus-Field

# 2. Configure o banco de dados MariaDB
# Crie um banco de dados chamado nexusfield (porta 3307 no WAMP)

# 3. Instale e inicie o backend
cd backend
cp .env.example .env
# Edite o .env: DATABASE_URL, JWT_SECRET, PORT, FRONTEND_URL

npm install
npx prisma generate
npx prisma migrate dev --name init
npx tsx prisma/seed.ts
npx tsx src/index.ts

# 4. Em outro terminal, instale e inicie o frontend
cd frontend
npm install
npx vite --host

# 5. Em outro terminal, instale e inicie o app mobile
cd mobile
npm install
npx expo start

A API estará disponível em http://localhost:3001, o frontend web em http://localhost:5173 e o app mobile via Expo Go no dispositivo físico ou emulador.

Configuração

Variáveis de Ambiente

Crie um arquivo .env na pasta backend/ baseado no .env.example:

DATABASE_URL="mysql://usuario:senha@localhost:3307/nexusfield"
JWT_SECRET="sua-chave-secreta-jwt-aqui"
PORT=3001
FRONTEND_URL="http://localhost:5173"
NODE_ENV="development"

Frontend

Crie um arquivo .env na pasta frontend/:

VITE_API_URL="http://localhost:3001/api"

⚠️ Importante: Nunca exponha valores reais de .env em repositórios públicos. Use o arquivo .env.example como template.

Roadmap

Completed

  • Project foundation (structure, design system, database)
  • Authentication (login, JWT, permissions, cadastro, forgot/reset)
  • Dashboard with KPIs and charts
  • Full Clients management
  • Technicians management with geolocation
  • Service Orders (full cycle)
  • Technical Tickets system
  • Scheduling (calendar, events)
  • Check-in/Check-out tracking
  • Geolocation with Leaflet map (logo customizada)
  • Mobile Inventory control
  • Financial management
  • Reports
  • Notifications
  • Settings (theme, company, security)
  • Dark/Light Mode (preto 100%)
  • RBAC (hierarquia de 7 níveis)
  • Demo Admin read-only (checkNotDemo)
  • Auditoria (tabela dedicada + rota de consulta)
  • Super Admin protegido (imutável)
  • Keep-alive de sessão (20 min)
  • Página Sobre Nexus Field

Future

Fase 9 — Fotos e Assinatura Digital

Implementado:

  • Upload de fotos antes/depois do serviço com preview
  • Assinatura digital via Canvas (mouse/touch) para conclusão de OS
  • Galeria de evidências fotográficas com exclusão
  • Validação de assinatura obrigatória antes de concluir

Status: ✅ Implementado (OSConclusaoModal.jsx)

Fase 10 — App Mobile para Técnicos

Implementado:

  • Aplicativo nativo React Native + Expo SDK 56
  • Recebimento e visualização de ordens de serviço
  • Check-in/Check-out mobile com geolocalização
  • Upload de fotos no campo (expo-image-picker)
  • Assinatura digital touch
  • Geolocalização em tempo real (expo-location)
  • Navegação por abas com React Navigation
  • Modo escuro nativo
  • Armazenamento offline (AsyncStorage)

Status: ✅ Implementado (mobile/)

Fase 11 — Nexus AI Assistant

Implementado:

  • Chatbot inteligente com detecção de sintomas por keyword scoring
  • 5 categorias de diagnóstico (compressor, vazamento, elétrico, ruído, refrigeração)
  • Previsão de problemas com alertas preditivos
  • Geolocalização integrada no chat
  • Detecção de off-topic e perguntas sobre agendamento de OS
  • Respostas formatadas com negrito e quebras de linha

Status: ✅ Implementado (AssistenteIA.jsx)

👨🏻‍💻Desenvolvedor

Clayton Marcelo Clayton Marcelo
C. Marcelo Dev. Brasil
📍 Brasil



Desenvolvedor Full Stack especializado em React, Node.js, Fastify, TypeScript, Prisma, MySQL e desenvolvimento de soluções SaaS Enterprise para Field Service Management.

Licença

Este projeto está licenciado sob Propriedade Intelectual — veja LICENSE.md para os termos completos.

Avaliação Técnica

Este repositório é disponibilizado para fins de avaliação técnica, demonstração de arquitetura, portfólio profissional e processos seletivos.

Empresas, recrutadores e avaliadores estão autorizados a clonar, executar e analisar o projeto localmente para conhecer sua arquitetura e qualidade de implementação.

Os direitos autorais permanecem pertencentes ao autor. A reprodução parcial ou integral para fins comerciais, redistribuição ou criação de produtos concorrentes não é autorizada sem consentimento expresso.

Para mais detalhes, consulte:

Direitos Autorais e Propriedade Intelectual

Nexus Field — Field Service Management

Copyright © 2026 Clayton Marcelo Tavares de Lima. Todos os direitos reservados.

Este software é protegido pelas Leis nº 9.609/1998 (Lei do Software) e nº 9.610/1998 (Lei de Direitos Autorais) do Brasil.

Termos de Uso

  • A análise, estudo e avaliação do código-fonte são permitidos para fins não comerciais;
  • A execução local do projeto é permitida para demonstração e avaliação técnica;
  • A utilização em processos seletivos e entrevistas técnicas é autorizada;
  • A reprodução para fins comerciais, redistribuição e criação de produtos derivados requer autorização expressa do autor;
  • A remoção de créditos de autoria, marca ou identidade visual não é permitida.

Licenciamento

O Nexus Field é um software proprietário. Qualquer uso comercial, distribuição ou modificação requer licença explícita do autor.

Para informações sobre licenciamento, entre em contato através do GitHub: claytonmarcelo

Documentos Relacionados

Documento Descrição
LICENSE.md Termos completos de licença
NOTICE.md Informações de atribuição e propriedade
SECURITY.md Política de reporte de vulnerabilidades
CONTRIBUTING.md Diretrizes para contribuições
CODE_OF_CONDUCT.md Código de conduta da comunidade

Desenvolvido com dedicação por Clayton Marcelo | C. Marcelo Dev. Brasil.
🔗 GitHub

Última atualização do README: 17/06/2026