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.

Português | English

---

📸 Screenshots

Capturas ilustrativas da interface do Nexus Field.

Ordens de Serviço	Dashboard
Clientes	Técnicos
Agenda	Geolocalização
Financeiro	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 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:

• LICENSE.md — Termos completos de licença
• NOTICE.md — Informações de atribuição
• CONTRIBUTING.md — Diretrizes de contribuição

---

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