chore(release): versão 2.0.5 - Refatoração do osModal e SGP Cache

Author: Vituali

.gitignore

@@ -24,3 +24,4 @@ secrets.*.js
 build.zip
 src/background/files.zip
 estrutura.txt
+refactoring_tracklist.md

CHANGELOG.md

@@ -9,6 +9,18 @@ Summary
   5. version timestamp follow the yyyy.MM.dd format
 ```
 
+## 2.0.5 [2026.03.13]
+
+### 🔥 Novidades & Refatoração (Major Update)
+- **Refatoração do Modal de O.S**: O antigo arquivo gigante `osModal.ts` foi completamente desmembrado em diversos módulos menores (`osModal.ts`, `osModalUI.ts`, `osModalSgp.ts`, `osModalHandlers.ts`, `osModalTypes.ts`). Manutenção e detecção de bugs muito mais ágil.
+- **Prevenção de Memory Leaks**: Implementado o padrão de `AbortController` em todos modais injetados na tela. Quando um modal é fechado, todos os event listeners daquele modal anexados no documento são destruídos instantaneamente.
+- **SGP Caching System (Anti-Rate Limit)**: A busca por dados do cliente no SGP ocorre **apenas uma vez por cliente** baseado na URL do chat (`chatId`). O recarregamento contínuo das rotas do SGP foi encerrado, reduzindo chamadas silenciosas e prevenindo bloqueios do provedor.
+- Limpeza automática de cache residual do SGP ao finalizar os atendimentos via clique no botão "Encerrar atendimento" no ChatMix.
+
+### 🐛 Correções de Bugs
+- **Case-sensitivity no Build**: O arquivo corrompido ou referenciado erroneamente como `Quickreply` foi padronizado em todo o projeto para `quickReply.ts`, previnindo falhas severas de carregamento em sistemas de pacote que diferenciam maiúsculas (Vite/Linux).
+- Correção de dupla importação de Tipos de Domínio TypeScript.
+
 ## 0.0.0 [2026.03.10]
 
 - feat: initial

CLAUDE.md

@@ -0,0 +1,66 @@
+# Documentação do Projeto — Extensão ATI V2
+
+## 🎯 Objetivo do Projeto
+Uma extensão para Google Chrome criada para integrar o sistema de chat de atendimento (**ChatMix**) com o Sistema de Gestão de Provedores (**SGP**). A extensão automatiza processos repetitivos para os atendentes, como inserção de respostas rápidas e, principalmente, a criação de Ordens de Serviço (O.S.) cruzando dados do cliente entre as duas plataformas.
+
+## 🛠️ Stack Tecnológico
+- **Linguagem**: TypeScript
+- **Build Tool**: Vite com plugin CRXJS (`@crxjs/vite-plugin`) para manifest V3.
+- **Banco de Dados/Backend**: Firebase Realtime Database (Acessado via REST API, sem SDK pesado).
+- **Estilização**: CSS puro injetado via content scripts.
+
+## 📂 Arquitetura de Pastas
+O projeto segue a separação estrita exigida pelo Manifest V3 do Chrome:
+
+- `src/background/`: **Service Worker**. Roda isolado em background.
+  - Único lugar permitido para fazer requisições externas críticas (SGP e Firebase) para evitar bloqueios de CORS.
+  - `sgp/`: Lógica de extração e submissão silenciosa ('scraping' via endpoints internos) para o site do SGP.
+  - `firebase.ts`: Comunicação (Auth e Database via REST) com o Firebase.
+- `src/contentScript/`: **Scripts injetados na página do ChatMix** (`chatmix.com.br`).
+  - Lida exclusivamente com manipulação do DOM e UI da extensão.
+  - `chatmix/`: Módulos específicos para atuar no ChatMix (observadores de DOM, injeção de botões).
+  - `chatmix/os/`: Contém a lógica do Modal de O.S. (recentemente modularizado em `osModal.ts`, `osModalSgp.ts`, `osModalUI.ts`, `osModalHandlers.ts`, `osModalTypes.ts`).
+  - `chatmix/auth/`: Lida com banners de login do Firebase sobrepostos ao ChatMix.
+- `src/popup/`: Interface HTML do ícone da extensão (caso necessário).
+
+## 🧠 Regras de Negócio Críticas
+
+### 1. Autenticação SGP (Cookies)
+A extensão **não** guarda senhas do SGP. Ela se aproveita do fato de o atendente já estar logado no SGP em outra aba do navegador.
+- As requisições em `background/sgp` usam `fetch` com `credentials: 'include'`.
+- Isso envia os cookies da sessão ativa do usuário para o SGP silenciosamente.
+
+### 2. SGP Cache Policy (Prevenção de Rate Limit)
+Para evitar que a ATI seja bloqueada pelo SGP devido a múltiplas buscas automáticas:
+- **Regra**: O estado e dados de formulário do SGP (contratos do cliente, status online/offline, tipos de ocorrência) devem ser gerados **uma vez por cliente/chat**.
+- A extensão usa o `chatId` (ID da URL do ChatMix) como chave de cache principal.
+- O cache do SGP (`clearSgpCache`) **só deve ser limpo** quando:
+  1. O atendente gera a O.S. ("Preencher no SGP" ou "Copiar").
+  2. O atendente clica no botão "Encerrar atendimento" no ChatMix.
+  3. A URL do chat muda drasticamente (mudança de sessão).
+
+### 3. Comunicação Content Script ↔ Background
+- O `contentScript` **nunca** faz requisições diretas ao SGP ou Firebase (evita CORS e garante segurança de contexto).
+- Usa-se `chrome.runtime.sendMessage` com interfaces padronizadas (ver `src/background/types.ts`).
+- Exemplo: Content Script descobre o CPF no ChatMix → Pede ao Background `getSgpFormParams` → Background faz a busca no SGP com cookies cruzados → Retorna JSON para o Content Script renderizar o Modal.
+
+### 4. Firebase (Templates e Respostas)
+- O `idToken` do Firebase tem validade (1 hora).
+- Respostas rápidas e Templates de O.S. (`modelos_os`, `respostas`) são cacheados em memória no service worker no início do plantão para máxima performance.
+- O Content script deve enviar o `chatId` e context data para o background hidratar os *placeholders* dinâmicos (`[SAUDACAO]`, `[HOJE]`) antes de jogar no DOM.
+
+## 📝 Regras de Código e Boas Práticas (Para IAs)
+
+1. **Sem tipo `any`**: O projeto utiliza TypeScript estrito. Se for criar código novo, declare e exporte as `Interfaces` apropriadas no respectivo arquivo `types.ts`.
+2. **Modularização do UI**: Arquivos que manipulam o DOM (`contentScript`) devem ser mantidos curtos e focados. Se um arquivo passar de 200-300 linhas (como era o `osModal.ts`), ele deve ser dividido em módulos lógicos (ex: `arquitetura_ui`, `arquitetura_api`, `arquitetura_eventos`).
+3. **Gerenciamento de Listeners**: Modais criados via ejetamento no DOM (`document.createElement`) que anexam eventos no `document` ou `body` **sempre** devem usar um `AbortController` (passando o `signal`) que é abortado quando o modal é destruído, evitando memory leaks.
+4. **Tratamento Seguro de HTML (XSS)**: Sempre que receber textos do Firebase ou do SGP para renderizar no ChatMix (via `.innerHTML`), garanta que o dado interno (`text`) passe por uma função de `escape` ou seja inserido via `.textContent` para evitar XSS.
+
+## 🗄️ Integração com Banco de Dados
+Sempre consulte o arquivo `FIREBASE_SCHEMA.md` na raiz deste repositório para entender a estrutura em JSON da base de dados e as regras de segurança aplicáveis.
+
+## 🕷️ Pontos de Falha Críticos (Dependência do DOM do ChatMix)
+A extensão dependende fortemente do HTML da página do ChatMix. Qualquer atualização no frontend deles pode quebrar a extensão.
+1. **Seletores CSS (`src/contentScript/chatmix/state.ts`)**: É ali que está o mapa do tesouro (ex: `#actionsContainerV2`, `.flex-none.p-4`). Se os botões ou o campo de texto (textarea) sumirem, o problema está nos seletores. Aja sempre atualizando-os.
+2. **Mutation Observers (`index.ts`)**: A extensão usa um `MutationObserver` para varrer alterações na tela e reinjetar os botões (O.S e Copy) toda vez que a URL ou o painel do chat muda.
+3. **Extração de Dados (`getClientData.ts` e `tryVisualIdentification.ts`)**: A extensão raspa o CPF/CNPJ ou Nome do cliente lendo o texto lateral ou o histórico do chat usando **Regex**. Novamente, uma mudança no layout ou formatação do texto no ChatMix vai requerer ajuste nas Regex nesses arquivos.

FIREBASE_SCHEMA.md

@@ -0,0 +1,118 @@
+# Firebase — Regras e Estrutura de Dados
+
+Este arquivo documenta as regras de segurança e a estrutura do Realtime Database usado pela extensão.
+
+## 🔒 Regras de Segurança (`.rules`)
+
+```json
+{
+  "rules": {
+    "admins": {
+      "$uid": {
+        ".read": "auth != null && auth.uid === $uid",
+        ".write": "auth != null && auth.uid === $uid"
+      }
+    },
+    "atendentes": {
+      ".read": true,
+      "$username": {
+        ".write": "auth != null && ( (!data.exists() && newData.child('uid').val() === auth.uid) || (data.exists() && (root.child('admins').child(auth.uid).exists() || data.child('uid').val() === auth.uid)) )",
+        ".validate": "newData.hasChildren(['uid', 'nomeCompleto', 'role', 'status', 'email'])"
+      }
+    },
+    "respostas": {
+      ".read": true,
+      "$username": {
+        ".write": "root.child('atendentes').child($username).child('uid').val() === auth.uid"
+      }
+    },
+    "modelos_os": {
+      ".read": true,
+      "$username": {
+        ".write": "root.child('atendentes').child($username).child('uid').val() === auth.uid"
+      }
+    },
+    "os_templates_master": {
+      ".read": "auth != null",
+      ".write": "auth != null && root.child('admins').child(auth.uid).exists()"
+    },
+    "sgp_cache": {
+      ".read": true,
+      ".write": "auth != null"
+    }
+  }
+}
+```
+
+## 🗄️ Estrutura do Banco de Dados (Schema)
+
+Abaixo está o mapeamento dos nós do banco de dados e os tipos de dados armazenados.
+
+```json
+{
+  // Lista de administradores globais do sistema
+  "admins": {
+    "$uid": true // Ex: "E7tiKEeA5AhwWHeqI9ilzbN2ofe2": true
+  },
+
+  // Cadastro de atendentes associando Usuário do ChatMix (username) ao Firebase Auth UID
+  "atendentes": {
+    "$username": { // Ex: "victorh", "igormagalhaes", "helio"
+      "email": "string",
+      "nomeCompleto": "string",
+      "role": "admin" | "usuario",
+      "status": "ativo" | "inativo", // (Opcional)
+      "uid": "string" // Firebase Auth UID associado ao username
+    }
+  },
+
+  // Templates de Ordens de Serviço INDIVIDUAIS por atendente
+  "modelos_os": {
+    "$username": {
+      "$templateId": { // ID gerado pelo Firebase ou customizado (ex: "-Oa_o7t1m41WsIs4lzba" ou "old_2")
+        "id": "string",
+        "category": "string", // Ex: "Suporte", "Financeiro", "GERAL"
+        "title": "string",
+        "text": "string", // Texto do template (pode conter placeholders [HOJE], [SAUDACAO])
+        "occurrenceTypeId": "string", // ID numérico em string referente ao Tipo de Ocorrência no SGP (ex: "1", "3", "42")
+        "keywords": ["string"] // (Opcional) Lista de palavras-chave para busca/integração
+      }
+    }
+  },
+
+  // Templates de O.S GLOBAIS (apenas leitura para usuários comuns, gravação para admins)
+  "os_templates_master": {
+    "os_templates": [
+      {
+        "title": "string",
+        "category": "string",
+        "text": "string",
+        "occurrenceTypeId": "string",
+        "keywords": ["string"] // (Opcional)
+      }
+    ]
+  },
+
+  // Respostas Rápidas (Quick Replies) INDIVIDUAIS por atendente
+  "respostas": {
+    "$username": [ // Array de quick replies
+      {
+        "title": "string",
+        "category": "quick_reply", // Sempre "quick_reply"
+        "subCategory": "string", // Subcategoria (ex: "Suporte", "Financeiro", "Geral", "Desastres", "Planos")
+        "text": "string" // Texto da resposta rápida
+      }
+    ]
+  },
+
+  // Cache gerenciado pelo script de background (Tipos de Ocorrência do SGP)
+  "sgp_cache": {
+    // Definido dinamicamente pela extensão
+  }
+}
+```
+
+### Notas sobre o Modelo Estrutural:
+- O banco é centrado na chave `$username` (nome do usuário no ChatMix).
+- A relação entre o `uid` (Firebase) e o `$username` (ChatMix) reside no nó `/atendentes/$username/uid`.
+- Regras de gravação de segurança exigem que o usuário autenticado só possa escrever nas respostas e modelos de OS que pertençam ao `$username` correspondente ao seu `uid` mapeado no nó `atendentes`.

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "ati-auxiliar-de-atendimentos",
   "displayName": "ATI - Auxiliar de Atendimentos",
-  "version": "2.0.4",
+  "version": "2.0.5",
   "author": "Vituali",
   "description": "Extensão para auxiliar atendentes do suporte ATI Internet no ChatMix",
   "type": "module",