From 05b3c36ed13036c2609c3e50ed041d6e8c549278 Mon Sep 17 00:00:00 2001 From: Rafael Lopes Date: Wed, 22 Jul 2026 17:38:10 -0300 Subject: [PATCH] CHORE: Remove docs/ redundante, conteudo migrado para wiki do Gitea --- docs/README.md | 13 ----- docs/casos-de-uso-rpg.md | 105 -------------------------------------- docs/chat-whatsapp.md | 88 -------------------------------- docs/modulo-attendance.md | 35 ------------- docs/modulo-auth.md | 33 ------------ docs/modulo-call.md | 32 ------------ docs/modulo-chat.md | 37 -------------- docs/modulo-home.md | 40 --------------- docs/visao-geral.md | 83 ------------------------------ 9 files changed, 466 deletions(-) delete mode 100644 docs/README.md delete mode 100644 docs/casos-de-uso-rpg.md delete mode 100644 docs/chat-whatsapp.md delete mode 100644 docs/modulo-attendance.md delete mode 100644 docs/modulo-auth.md delete mode 100644 docs/modulo-call.md delete mode 100644 docs/modulo-chat.md delete mode 100644 docs/modulo-home.md delete mode 100644 docs/visao-geral.md diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index b363d7c..0000000 --- a/docs/README.md +++ /dev/null @@ -1,13 +0,0 @@ -# Documentação do Frontend - -Esta pasta reúne a documentação funcional e conceitual do frontend MVP Omnichannel. - -## Índice - -- [Visão Geral](./visao-geral.md) -- [Módulo Auth / Login](./modulo-auth.md) -- [Módulo Home / Dashboard](./modulo-home.md) -- [Módulo Chat](./modulo-chat.md) -- [Módulo Call](./modulo-call.md) -- [Módulo Attendance / Novo Atendimento](./modulo-attendance.md) -- [Casos de Uso em Formato RPG](./casos-de-uso-rpg.md) diff --git a/docs/casos-de-uso-rpg.md b/docs/casos-de-uso-rpg.md deleted file mode 100644 index 90a1faa..0000000 --- a/docs/casos-de-uso-rpg.md +++ /dev/null @@ -1,105 +0,0 @@ -# Casos de Uso em Formato RPG - -## Introdução - -Imagine o reino de **Sharvus**, onde toda vila, fortaleza e guilda depende de mensagens rápidas para manter ordem, comércio e confiança com seus cidadãos. - -No centro desse reino existe a fortaleza da **Ordem de Sothis**, onde trabalham os guerreiros do suporte, os mensageiros do comercial e os guardiões do financeiro. - -Cada atendimento é uma missão. - -Cada cliente é um personagem importante. - -Cada tela do sistema é uma parte da jornada. - -## O Herói - -Nosso herói é **Aren**, um guerreiro de suporte da Ordem de Sothis. - -Sua missão não é derrotar monstros, mas resolver problemas antes que eles virem caos no reino. - -Para isso, ele usa o grande portal chamado **Omnichannel**. - -## Capítulo 1: O Portal de Entrada - -Aren chega ao salão principal e encontra o **Portal de Login**. - -Ali ele: - -- informa suas credenciais -- entra no sistema -- acessa o centro de comando - -Na prática, este é o caso de uso de autenticação visual do módulo `auth`. - -## Capítulo 2: O Mapa da Operação - -Ao entrar, Aren vê o grande mapa do reino: a **Home / Dashboard**. - -Nesse mapa ele consegue: - -- ver conversas ativas -- trocar entre mensagens e ligações -- buscar contatos -- iniciar novas missões - -Na prática, este é o caso de uso central do módulo `home`. - -## Capítulo 3: A Mensagem do Cidadão - -Uma cidadã chamada **Maria Souza** envia um pedido urgente por WhatsApp. - -Aren abre a conversa no módulo `chat` e pode: - -- ler o histórico -- responder rapidamente -- acompanhar novas mensagens -- transferir o caso para outra guilda, como Financeiro ou Comercial - -Na prática, este módulo representa o caso de uso de atendimento textual em tempo real. - -## Capítulo 4: O Chamado por Voz - -Nem toda missão pode ser resolvida por pergaminhos e mensagens. - -Às vezes, o cidadão precisa ouvir a voz de alguém da Ordem. - -Então Aren inicia uma ligação no módulo `call`, onde ele: - -- visualiza quem está na chamada -- acompanha o tempo da conversa -- usa controles de chamada -- encerra o contato quando a missão termina - -Na prática, este módulo representa o caso de uso de atendimento por voz. - -## Capítulo 5: A Missão Começa Aqui - -Antes de qualquer conversa, Aren pode abrir o módulo `attendance` para iniciar uma nova missão. - -Ele escolhe: - -- quem será atendido -- qual canal usar -- para qual área o caso deve ir - -Depois disso: - -- se for mensagem, ele segue para o chat -- se for voz, ele segue para a chamada - -Na prática, este módulo representa o caso de uso de abertura rápida de atendimento. - -## Moral da História - -O Omnichannel é a mesa de guerra de Sharvus. - -Ele permite que um único guerreiro: - -- veja o cenário -- escolha o canal -- converse com o cidadão -- transfira a missão -- resolva o problema com agilidade - -Em linguagem de produto, o sistema mostra como centralizar operação, comunicação e contexto em uma experiência única. diff --git a/docs/chat-whatsapp.md b/docs/chat-whatsapp.md deleted file mode 100644 index 13c3a68..0000000 --- a/docs/chat-whatsapp.md +++ /dev/null @@ -1,88 +0,0 @@ -# Modulo de Chat WhatsApp (Frontend) - -## Visao geral - -O modulo de Chat no frontend integra as conversas em tempo real do WhatsApp diretamente na tela de atendimento do operador. - -A interface e altamente responsiva, provendo feedback instantaneo de envio (zero latencia) e sincronizando com o backend via WebSockets (Socket.io) para atualizar estados de de-duplicacao, novas mensagens, midias e controle de posse do atendimento. - ---- - -## Componentes Principais - -### 1. Hook de Negocio (`useChat.js`) -Centraliza todo o estado das conversas, conexao WebSocket e operacoes de rede: -* **`contacts`**: Lista de chats ativos sincronizados. Cada contato possui um objeto `assignment` (atribuicao) normalizado. -* **`messagesByContact`**: Map de historico de mensagens por JID/contato. -* **`takeChat()`**: Dispara a requisicao de rede `/whatsapp/assign` enviando o ID do atendente e o ID numerico da area do usuario logado (convertido com seguranca para inteiro). -* **`sendMessage()`**: Trata a de-duplicacao de mensagens em milissegundos e gerencia a concorrência (race condition). - -### 2. Painel de Atendimento (`ChatWindow.jsx`) -O container principal da conversa selecionada. Ele renderiza: -* **Header**: Mostra o nome resolvido do cliente, canal (WhatsApp) e o indicador de quem esta atendendo. -* **Historico**: Area de scroll contendo as bolhas de mensagens do atendente (`agent`) e do cliente (`customer`), incluindo visualizadores para imagens, audios e links de arquivos. -* **Footer de Input**: Caixa de texto com suporte a tecla Enter e icone de anexo de midia (com validacao automatica de tamanho). - ---- - -## Mecanismos de UX e Estabilidade - -### 1. Insercao Instantanea (UX Zero-Latency) -Para evitar que o atendente perceba qualquer latencia de rede, o envio e dividido em duas etapas: -1. **Fase Local**: A bolha de mensagem e inserida na tela imediatamente com um ID temporario (`temp-` + timestamp) e o texto digitado. O input de texto e arquivos e limpo na mesma hora. -2. **Fase de Disparo**: A requisicao HTTP POST e disparada para o backend em segundo plano. - -### 2. De-duplicacao de Mensagens (Prevecao de Race Condition) -Como o backend envia a mensagem recebida via WebSocket assim que o Puppeteer a dispara, a bolha poderia aparecer duplicada na tela se a requisição de envio original ainda estivesse processando. -* **A Solucao**: O hook de WebSocket compara as mensagens recebidas em tempo real. Se o texto bater e a diferenca temporal de timestamp for inferior a 4 segundos, ele identifica a bolha `temp-...` local, remove o prefixo temporario e atualiza-a com o ID oficial do WhatsApp gerado no servidor. **Zero duplicacoes, zero flashes na tela.** - -### 3. Validação de Posse (Type-Safe User IDs) -Para evitar conflitos na exibicao do banner *"⚠️ Atendido por outro colaborador"*, realizamos casting explicito dos IDs dos usuarios envolvidos: -```javascript -const isAssignedToMe = activeContact?.assignment?.userId && String(activeContact.assignment.userId) === String(currentUser.id); -const isAssignedToOthers = activeContact?.assignment && String(activeContact.assignment.userId) !== String(currentUser.id); -``` -Isso impede que comparacoes como `4 === "4"` (inteiro vindo do banco relacional vs string vindo do localStorage/JWT) avaliem incorretamente como falso, mantendo a tela bloqueada ou liberada com precisao. - -### 4. Layout e Rolagem Estrita (680px Scroll) -A interface de mensagens possui limitacoes verticais restritas para evitar que a tela se alongue infinitamente para baixo. -* A bolha de historico e fixada com altura proporcional (`height: 680px` ou `calc`) e controle de transbordo `overflow-y: auto`. -* O hook de chat escuta mudancas na lista de mensagens e realiza rolagem automatica suave (`smooth`) para o fim da tela sempre que uma nova bolha e adicionada. - ---- - -## Novos Fluxos Homologados (WhatsApp / Meta) - -### 1. Novo Atendimento Inteligente (`NewAttendancePage.jsx`) -* **Remoção do Seletor de Área**: O seletor manual foi removido da tela para simplificar a operação. O sistema resolve a área dinamicamente a partir do atendente logado (`currentUser.areaPrincipal` ou `areas[0]`). -* **Bloqueio de Campo**: Ao escolher um contato dos recentes ou da busca lateral, o input do telefone e do nome do cliente ficam bloqueados para escrita. -* **Modo "Novo Número"**: Ao clicar no botão, o operador habilita os inputs de nome e telefone. Caso inicie o chat sem digitar um nome personalizado, o sistema aplica um fallback limpo no formato `Contato Novo (+55...)`. - -### 2. Bloqueio e Envio de Templates Meta (`ChatWindow.jsx`) -Como a API oficial do WhatsApp/Meta exige uma mensagem pré-aprovada para iniciar conversas ativas (sem histórico prévio), a interface aplica travas estritas: -* **Travamento do Input**: Se a conversa selecionada possuir histórico de envio vazio (`!hasAgentMessages`), a caixa de texto principal e o botão "Enviar" ficam bloqueados. -* **Painel de Templates**: Logo acima do rodapé de digitação, renderiza-se um seletor horizontal com os templates oficiais Meta ativos no banco (buscados de `GET /whatsapp/templates`). -* **Substituição Dinâmica**: Ao clicar em um template, as variáveis `|NOME|`, `|DATA|` ou `|PROTOCOLO|` são interpoladas em tempo real com os dados do cliente, populando o input principal e liberando o fluxo de envio da primeira mensagem. - -### 3. Gerenciamento de Templates para Supervisores (`SupervisorPage.jsx`) -Supervisores possuem controle administrativo total sobre as mensagens homologadas: -* **CRUD de Modelos**: Exibe todos os templates de WhatsApp em formato de cards visuais. -* **Painel de Edição**: Permite criar novos templates ou editar identificadores/conteúdos de templates existentes. As alterações persistem imediatamente no banco PostgreSQL por meio dos endpoints `/whatsapp/templates`. - ---- - -## Como Integrar e Rodar - -### Variaveis de Ambiente -O frontend conecta no WebSocket e na API do backend usando a porta padrao do NestJS: -```env -VITE_API_URL=http://localhost:3001 -VITE_WS_URL=http://localhost:3001 -``` - -### Compilando e Rodando localmente -```bash -cd frontend -npm run dev -``` -Ao selecionar uma conversa de canal "WhatsApp" que esteja livre, basta digitar uma mensagem e pressionar Enter. O chat sera automaticamente assumido por voce em tempo real, gravando no PostgreSQL e desbloqueando a janela de chat de forma instantanea. diff --git a/docs/modulo-attendance.md b/docs/modulo-attendance.md deleted file mode 100644 index 8a75ce8..0000000 --- a/docs/modulo-attendance.md +++ /dev/null @@ -1,35 +0,0 @@ -# Módulo Attendance / Novo Atendimento - -## Objetivo - -Permitir que um operador inicie rapidamente um novo atendimento. - -## Tela principal - -- `NewAttendancePage.jsx` - -## Componentes e lógica - -- `RecentContactsList.jsx`: contatos recentes e seleção rápida -- `attendanceMocks.js`: canais, áreas e contatos mockados - -## Funcionalidades simuladas - -- buscar contato -- escolher um contato recente -- informar novo número -- escolher canal: - - WhatsApp - - SMS - - Ligação -- selecionar área opcional -- iniciar atendimento - -## Regras de navegação - -- se o canal escolhido for `WhatsApp` ou `SMS`, a navegação vai para `/chat` -- se o canal escolhido for `Ligação`, a navegação vai para `/call` - -## Papel na apresentação - -Esse módulo deixa muito claro o ganho operacional do produto: o atendente consegue iniciar fluxos rapidamente sem sair da mesma plataforma. diff --git a/docs/modulo-auth.md b/docs/modulo-auth.md deleted file mode 100644 index 2bfb41d..0000000 --- a/docs/modulo-auth.md +++ /dev/null @@ -1,33 +0,0 @@ -# Módulo Auth / Login - -## Objetivo - -Apresentar uma entrada elegante e moderna para o produto, simulando autenticação corporativa sem backend real. - -## Tela principal - -- `LoginPage.jsx` - -## Componentes e lógica - -- `LoginForm.jsx`: formulário visual de acesso -- `useLogin.js`: controla o envio e redirecionamento -- `authService.js`: mock de autenticação - -## Fluxo - -1. O usuário informa usuário e senha -2. Clica em `Entrar` -3. O login mock é executado -4. O usuário é redirecionado para `/home` - -## Elementos importantes - -- branding Sothis -- botão `Entrar com Microsoft` -- link `Esqueci minha senha` -- visual de produto SaaS - -## Papel na apresentação - -A tela de login serve como entrada institucional do MVP e ajuda a criar percepção de maturidade do produto logo no primeiro contato. diff --git a/docs/modulo-call.md b/docs/modulo-call.md deleted file mode 100644 index e236698..0000000 --- a/docs/modulo-call.md +++ /dev/null @@ -1,32 +0,0 @@ -# Módulo Call - -## Objetivo - -Simular uma ligação ativa em modo softphone, com visual de operação em tempo real. - -## Tela principal - -- `CallPage.jsx` - -## Componentes e lógica - -- `CallHeader.jsx`: contexto superior e retorno para home -- `CallControls.jsx`: controles visuais da chamada -- `useCallTimer.js`: timer automático -- `callMocks.js`: dados do cliente e controles - -## Funcionalidades simuladas - -- contagem automática do tempo de chamada -- exibição do cliente ativo -- avatar e fila de atendimento -- controles: - - mudo - - teclado - - alto-falante - - transferir - - encerrar chamada - -## Papel na apresentação - -Este módulo mostra que o produto não é apenas mensageria, mas também cobre voz dentro da mesma proposta omnichannel. diff --git a/docs/modulo-chat.md b/docs/modulo-chat.md deleted file mode 100644 index 067cbc0..0000000 --- a/docs/modulo-chat.md +++ /dev/null @@ -1,37 +0,0 @@ -# Módulo Chat - -## Objetivo - -Simular um atendimento em tempo real com aparência próxima de um produto de operação real. - -## Tela principal - -- `ChatPage.jsx` - -## Componentes e lógica - -- `ChatConversationList.jsx`: lista de contatos e canais -- `ChatWindow.jsx`: header, mensagens e input -- `ChatTransferPanel.jsx`: fluxo visual de transferência -- `useChat.js`: estado do chat, envio e resposta simulada -- `chatMocks.js`: contatos, áreas, atendentes e mensagens iniciais - -## Funcionalidades simuladas - -- alternar entre conversas -- enviar mensagem -- receber resposta mock automática -- rolagem automática -- transferência para outra área -- escolha de atendente de destino -- observação opcional na transferência - -## Canais representados - -- WhatsApp -- SMS -- Email - -## Papel na apresentação - -O módulo de chat demonstra como a plataforma concentra diferentes canais em uma única experiência operacional. diff --git a/docs/modulo-home.md b/docs/modulo-home.md deleted file mode 100644 index e63ffde..0000000 --- a/docs/modulo-home.md +++ /dev/null @@ -1,40 +0,0 @@ -# Módulo Home / Dashboard - -## Objetivo - -Ser o hub central do atendente após o login. - -## Tela principal - -- `HomePage.jsx` - -## Componentes e lógica - -- `HomeTopbar.jsx`: busca, toggle de abas, avatar e contexto superior -- `HomeSidebar.jsx`: navegação lateral e botão de novo atendimento -- `MessagesWorkspace.jsx`: lista de conversas, chat resumido e painel de ações -- `CallsWorkspace.jsx`: visão resumida das ligações -- `homeMocks.js`: dados mockados do dashboard - -## Funcionalidades simuladas - -- trocar entre `Mensagens` e `Ligações` -- buscar conversas mockadas -- abrir rota de chat -- abrir rota de call -- abrir rota de novo atendimento - -## Papel na apresentação - -É a tela que melhor comunica o conceito do produto: - -- múltiplos canais -- visão operacional única -- agilidade no atendimento -- sensação de plataforma pronta para uso - -## Pontos de UX - -- responsividade adaptada para mobile, tablet, desktop e desktop largo -- sidebar separada do conteúdo para leitura mais clara -- cards de contexto e indicadores operacionais diff --git a/docs/visao-geral.md b/docs/visao-geral.md deleted file mode 100644 index 7b5b82b..0000000 --- a/docs/visao-geral.md +++ /dev/null @@ -1,83 +0,0 @@ -# Visão Geral do Projeto - -## Objetivo - -O projeto representa o frontend MVP do Omnichannel Sothis. - -O objetivo principal é demonstrar, de forma visual e convincente, como um atendente pode: - -- entrar na plataforma -- visualizar atendimentos e conversas -- iniciar um novo atendimento -- conversar com clientes em canais diferentes -- simular uma ligação ativa - -## Diretriz do MVP - -Este MVP prioriza percepção de produto acabado. - -Ou seja: - -- os fluxos parecem reais -- os dados são mockados -- a navegação existe -- a experiência é pensada para demonstração, validação e apresentação - -## Stack - -- React -- Vite -- JavaScript -- React Router -- CSS via estilos modernos em componentes - -## Estrutura - -O frontend foi organizado por módulos, seguindo uma abordagem feature-based: - -- `auth` -- `home` -- `chat` -- `call` -- `attendance` - -Cada módulo concentra suas páginas, componentes, hooks e services mockados. - -## Rotas atuais - -- `/login` -- `/home` -- `/chat` -- `/call` -- `/new-attendance` - -## Módulos - -### Auth - -Simula autenticação e entrada no sistema. - -### Home - -É a central do operador, com dashboard, conversas, atalhos e navegação fake para os fluxos principais. - -### Chat - -Simula atendimento em tempo real com mensagens, transferência e respostas automáticas mockadas. - -### Call - -Simula uma ligação ativa com timer automático e controles visuais de softphone. - -### Attendance - -Permite iniciar rapidamente um novo atendimento, escolhendo contato, canal e área. - -## Público da documentação - -Esta documentação serve para: - -- apresentação de produto -- onboarding técnico -- alinhamento entre frontend, backend e deploy -- futura evolução para integração real