Módulos do Sistema

Telas e regras de negócio da área industrial. As permissões citadas vêm da matriz em Usuários, Cargos e Permissões. Todas as operações de escrita geram registro em Logs e Auditoria.

Home (/)

• Busca rápida com sugestões enquanto se digita. Enter abre o dispositivo selecionado ou a lista filtrada (/dispositivos?q=...).
• Cartões com o total de dispositivos (D), de reutilizações (U) e, para quem cadastra ou edita, de categorias (C).
• Botão de novo dispositivo, para quem pode cadastrar.
• Botão "Encontrou algum bug?", que abre o formulário de reporte de bugs (Google Forms). Ver Guia do Desenvolvedor → Scripts.
• Link para a tela Sobre (/sobre): objetivo, equipe, orientador, instituição e empresa parceira.

Dispositivos (/dispositivos)

Lista

• Busca por nome, código, descrição, família, produto, categoria e palavras-chave. Ignora acentos e maiúsculas e trata vírgula como ponto.
• Filtros:
  • Categoria, pelo campo categoriaId;
  • Processo Industrial (Shotblaster, Coping, Sawing, Drilling). Não é um campo próprio: busca o termo em nome, descrição e palavras-chave.
• Paginação: 5, 10 ou 15 itens por página, ou todos.
• Importar planilha (quem pode cadastrar) e Ações em Massa (quem pode excluir): excluir ou desativar vários dispositivos, com barra de progresso.

Cadastro e edição

Formulário em modal (DispositivoForm), aberto pelo botão + (ou pela ação de editar). Restrito a quem pode cadastrar e editar (Administração e Projetista).

Campo	Campo no Firestore	Observação
Nº dispositivo	nome
Código da peça	codigo	Também é a chave da propagação de imagens
Família do produto	familiaId	Pode ser criada no próprio formulário
Produto	produtoId	Idem
Categoria	categoriaId	Idem
Peso do dispositivo	peso	Texto, em gramas
Palavras-chave	palavrasChave	Lista; Enter ou vírgula adicionam
Descrição da peça	descricao
Imagem da peça / do dispositivo	imagemPeca / imagemDispositivo	URL do arquivo no Storage
Documentos PDF	anexos	Metadados dos arquivos no Storage

Nenhum campo é obrigatório: o sistema aceita dados incompletos por design.

Arquivos: imagens JPG, PNG ou WEBP até 10 MB; PDFs até 25 MB. Os arquivos vão para retool/dispositivos/{dispositivoId}/{categoria}/ no Storage (detalhes em Firebase e Firestore).

Propagação automática de imagens

Uma imagem enviada para um dispositivo preenche as células vazias dos demais dispositivos com o mesmo código da peça. A comparação ignora maiúsculas e espaços nas pontas.

• Nunca substitui imagem existente e nunca altera dispositivos de outro código.
• Na criação, um dispositivo novo com campos de imagem vazios herda a imagem que já exista na linha.
• Limpar a imagem de um dispositivo não dispara nada.
• Cada dispositivo alterado recebe um registro de auditoria, e um aviso informa quantos foram sincronizados.
• Implementação: calcularPropagacaoImagens() em src/domain/entities/dispositivo.ts (lógica pura, com testes) e propagarImagensPorCodigo() em src/context/ReToolContext.tsx.

Detalhes (/dispositivos/:id)

• Dados da peça e do dispositivo, imagens e PDFs.
• Resumo: número de reutilizações e hard saving total.
• Histórico de reutilizações do dispositivo, em tabela com linha expansível.
• Ações por cargo:
  • editar — Administração e Projetista;
  • nova reutilização (registro direto) — Administração e Projetista;
  • solicitar reutilização — Engenharia;
  • excluir reutilização — Administração.

Exclusão

Somente a Administração exclui dispositivos. A exclusão apaga também a pasta de arquivos do dispositivo no Storage. "Desativar" apenas marca ativo: false.

Classificações (/categorias)

Tela Gestão de Classificações, acessível à Administração e ao Projetista. Mantém três cadastros usados nos dispositivos:

Cadastro	Coleção	Exemplo da tela
Categorias	categorias	Ferramentas de Corte, EPIs, Gabaritos
Famílias de produto	familias	Grupo de manufatura
Produtos	produtos	Nome comercial ou modelo

• Criar, editar e reativar um item inativo: Administração e Projetista.
• Excluir ou desativar, individualmente ou em massa: Administração.
• A coleção tipos também existe no código (contexto, repositório e regras), mas nenhuma tela a utiliza hoje.

Importação em lote

Aberta pelo botão Importar da lista de dispositivos. Aceita .csv ou .xlsx; há uma planilha de exemplo em retool/docs/RETOOL import test.xlsx.

Colunas reconhecidas (qualquer um dos nomes):

Dado	Colunas aceitas
Nº dispositivo	Dispositivo, Nº Dispositivo, N Dispositivo, Nome
Código	Código, Codigo, Código da Peça, Codigo da Peca
Descrição	Descrição, Descricao, Descrição da Peça, Descricao da Peca
Categoria	Categoria, CATEGORIA, Tipo de Dispositivo, Tipo Dispositivo, Tipo
Família	Familia, Familia_do_Produto, Familia do Produto
Produto	Produto, PRODUTO
Peso	Peso, Peso (Kg), Peso Dispositivo (Kg)
Palavras-chave	Palavra chave, Palavras chaves, Palavras-chave, Palavras chave

Regras:

• Linhas sem código e sem nome são ignoradas.
• Categorias, famílias e produtos inexistentes são criados sem duplicar nomes. A comparação ignora maiúsculas e espaços nas pontas.
• Um dispositivo com o mesmo código (comparação exata) é atualizado. Se a linha não tem código, vale o mesmo nome. Caso contrário, é criado um novo.
• A importação gera um registro de auditoria do tipo Importação com totais de sucesso e erro.
• Implementação: ImportModal, ImportarLoteUseCase e FirestoreDispositivosRepository.importarLote.

Reutilizações (/reutilizacoes)

Fluxo de reutilização de dispositivos entre a Engenharia (quem solicita) e o Projetista – Ferramentaria (quem analisa). A máquina de estados fica em src/domain/entities/reutilizacao.ts e é repetida nas regras do Firestore.

stateDiagram-v2
  [*] --> EmAnaliseEngenharia: Engenharia cria a solicitação
  EmAnaliseEngenharia --> EmAnaliseProjetista: Engenharia envia (1º filtro)
  EmAnaliseProjetista --> Aprovada: Projetista aprova
  EmAnaliseProjetista --> NaoAprovada: Projetista não aprova (motivo)
  NaoAprovada --> AguardandoNovoFiltro: Engenharia solicita dispositivo novo
  AguardandoNovoFiltro --> EmAnaliseProjetista: Projetista encontra similar (2º filtro)
  AguardandoNovoFiltro --> LiberadoFabricacao: Projetista libera fabricação
  Aprovada --> [*]
  LiberadoFabricacao --> [*]
  EmAnaliseEngenharia: Em análise (Engenharia)
  EmAnaliseProjetista: Em análise (Projetista)
  Aprovada: Reutilização aprovada
  NaoAprovada: Reutilização não aprovada
  AguardandoNovoFiltro: Aguardando novo filtro (Projetista)
  LiberadoFabricacao: Liberado para fabricação (novo dispositivo)

Transição	Quem executa
Em análise (Engenharia) → Em análise (Projetista)	Engenharia, Administração
Em análise (Projetista) → Aprovada / Não aprovada	Projetista, Administração
Não aprovada → Aguardando novo filtro	Engenharia, Administração
Aguardando novo filtro → Em análise (Projetista) / Liberado para fabricação	Projetista, Administração

• Abas:
  • Fila do Projetista (Projetista e Administração) — em análise pelo Projetista e aguardando novo filtro;
  • Fila da Engenharia (Engenharia e Administração) — rascunhos em análise pela Engenharia e retornos aprovados ou não aprovados;
  • Histórico Geral (todos os cargos) — tabela com filtros por texto, status e dispositivo, linhas expansíveis e ações em massa para a Administração.
• Administração e Projetista também registram reutilizações diretamente, já como histórico, pela tela do dispositivo.
• Registros antigos com status pendente, aprovado, rejeitado ou Em andamento - OS são convertidos na leitura para os estados atuais.
• Cada transição notifica a fila seguinte ou o solicitante (ver Notificações) e é auditada.
• O botão "Como funciona o fluxo" abre um modal com etapas, estados e permissões.

Atalhos de teclado

Globais (src/hooks/useHotkeys.tsx), ignorados enquanto se digita em um campo:

Tecla	Ação
H	Home
D	Dispositivos
U	Reutilizações
C	Classificações (quem cadastra ou edita)
A	Administração (somente Administração)
/	Foco na busca da Home
Esc	Fecha o modal aberto (tratado pelos próprios modais)

Limitação conhecida: a tecla N aparece na interface ("Atalho: N" e no quadro de atalhos da barra lateral), mas nenhuma tela registra a ação de novo registro no useHotkeys, então ela não faz nada hoje. O cadastro é aberto pelo botão +.

Nas listas navegáveis (FocusableList): setas e Home/End movem o foco, Enter abre o item, E edita e D exclui, quando o cargo permite.