Argus-Sheet: Sistema de Gestão de Promoções

O Projeto Argus-Sheet é uma aplicação web monolítica construída sobre a plataforma Google Apps Script. A sua missão é servir como uma interface de utilizador rica (Rich User Interface - RUI) para a gestão do ciclo de vida de promoções, utilizando uma Planilha Google como a sua base de dados principal.

✨ Funcionalidades

• Dashboard Centralizado: Visualização de todas as solicitações de promoção com paginação, busca e filtros por status.
• Criação de Solicitações: Formulário para criação de solicitações de promoção individuais.
• Gestão em Massa:
  • Importação de Solicitações: Upload de um ficheiro CSV para criar múltiplas promoções de uma só vez, com validação prévia.
  • Ciclo de Decisão em Massa: Exportação de todas as promoções pendentes para um CSV, permitindo que as decisões (e.g., "Cadastro Efetuado", "Recusado") sejam preenchidas offline e depois importadas de volta para o sistema para atualização em massa.
• Detalhes e Auditoria: Modal de detalhes para cada solicitação, incluindo uma trilha de auditoria completa que regista todas as alterações de status, quem as fez e quando.
• Ações Administrativas: Um menu especial para administradores (disponível na Planilha Google associada) para realizar ações como aprovação de exceções, atualizações de status forçadas e reprocessamento de lotes.

🏗️ Arquitetura

• Backend: Google Apps Script (Code.ts, Config.ts), executando a lógica de negócio em TypeScript nos servidores do Google.
• Frontend: Uma única página web (index.html) servida pelo Apps Script, utilizando HTML, CSS (Bootstrap) e JavaScript.
• Base de Dados: Uma Planilha Google, onde cada aba serve como uma "tabela" (e.g., db_itens_validados, log_auditoria).
• Desenvolvimento Local: O projeto está configurado para usar o clasp, a ferramenta de linha de comando do Google para desenvolvimento local de projetos Apps Script.

🛡️ Governança e Segurança

A integridade e a rastreabilidade dos dados são pilares fundamentais do Argus-Sheet, garantidos através de múltiplos mecanismos:

• Trilha de Auditoria Imutável: Todas as ações críticas, como criação, alteração de status ou modificação de dados financeiros, são registadas na aba log_auditoria. Este registo inclui o autor da ação, a data, e os detalhes da alteração, fornecendo uma visão completa e transparente do ciclo de vida de cada promoção.
• Controlo de Acesso Granular: O sistema implementa um controlo de acesso baseado em permissões detalhadas, para além dos papéis de "Admin" e "Analista". Funcionalidades sensíveis, como a gestão de utilizadores (can_manage_users) ou a aprovação de exceções (can_approve_exceptions), são protegidas e apenas acessíveis a utilizadores com a permissão específica, configurada na aba config_usuarios.
• Validação de Dados na Entrada: Nenhuma solicitação é criada sem passar por uma rigorosa validação de regras de negócio. O sistema verifica a coerência de preços e datas e cruza informações com a base de dados de produtos (Info_Mat) para garantir a exatidão dos dados antes de serem persistidos no sistema.
• Transações Seguras: Para operações críticas de escrita, como a criação de novas solicitações ou atualizações de status, o sistema utiliza o LockService do Google Apps Script. Isso previne condições de corrida e garante que as operações sejam atómicas, mantendo a consistência da base de dados.

🚀 Guia de Instalação e Configuração

1. Pré-requisitos

• Ter o Node.js instalado.
• Instalar o clasp globalmente via npm:

  npm install -g @google/clasp

2. Setup Inicial

1. Faça login com sua conta Google na linha de comando:

   clasp login

2. Clone este repositório para a sua máquina local.
3. Crie as Planilhas Google que servirão como base de dados, logs e configurações, conforme especificado no arquivo Config.ts.
4. Atualize o arquivo Config.ts com os IDs de cada Planilha Google criada.
5. Crie um novo projeto no dashboard do Google Apps Script.
6. No seu projeto Apps Script, vá para Configurações do Projeto > Informações Gerais e copie o ID do Script.
7. No seu repositório local, atualize o ficheiro .clasp.json com o seu scriptId.

3. Enviar os Ficheiros

• No terminal, na raiz do projeto, execute o comando para enviar todos os seus ficheiros locais para o projeto Apps Script na nuvem:

  clasp push

4. Implementação (Deploy)

1. No editor do Apps Script online, clique em Implementar > Nova implementação.
2. Selecione o tipo App da Web.
3. Em "Executar como", selecione "Utilizador que acede à app".
4. Em "Quem pode aceder", selecione "Qualquer pessoa no domínio [seu domínio]" (ou a opção mais apropriada).
5. Clique em Implementar. Copie a URL do App da Web gerada - este é o link para aceder ao Argus.

🗺️ Roadmap (Próximos Passos)

✅ Principais Features

• Otimização de Performance: Implementação de cache avançado para imagens e dados de produtos.
• Validação de Produtos: Integração com a base Info_Mat para validar SKU, descrição e fornecedor, com autopreenchimento no formulário.
• Fluxo de Correção de Dados: Funcionalidade de "Corrigir Dados Automaticamente" para analistas, com pré-visualização e dupla confirmação.
• Gestão de Regras de Negócio: Interface completa para criar, editar, ativar e desativar regras de negócio do sistema.
• Notificações Detalhadas: E-mails de "Ajuste Necessário" com tabela comparando os dados informados vs. os dados corretos.
• Gestão de Utilizadores: Interface para gerir perfis e permissões granulares diretamente na aplicação.
• Imagens de Produtos: Exibição otimizada das imagens de cada produto na UI.

---

🚀 Próximos Passos (Curto Prazo)

• Configurações do Utilizador: Página para configurar preferências de notificação (e-mail, chat).
• Lógica Específica das Regras de Negócio: Implementar a lógica detalhada para as regras (ex: "Promoções Imperdíveis devem terminar no Domingo").

---

🔭 Futuro (Médio/Longo Prazo)

• Dashboard de Analytics: Implementar a secção de Analytics com gráficos e KPIs.
• Módulos de Governação: Desenvolver as interfaces para gestão de "Famílias SKU" e "Grupos de Lojas".
• Notificações Inteligentes: Aprimorar notificações com links diretos e ações rápidas.
• Melhorias de UX:
  • Permitir a edição de mais campos diretamente no modal de detalhes.
  • Adicionar um seletor de tema "claro/escuro".
  • Refinamento contínuo da experiência do utilizador.

🧪 Testes e Monitoramento de Performance

Para garantir a qualidade e a estabilidade do Argus, adotamos uma estratégia de testes e monitoramento contínuo.

1. Testes Unitários

O projeto pode ser expandido para incluir testes unitários para funções de lógica de negócio puras (que não dependem de APIs do Google como SpreadsheetApp).

2. Testes de Integração e End-to-End (E2E)

Devido às limitações do ambiente Apps Script, os testes que envolvem a interface do utilizador e a interação com serviços Google são realizados através de um roteiro de teste manual estruturado.

Roteiro de Testes Essenciais:

Cenário	Passos	Resultado Esperado
Criação Individual	1. Abrir a UI. 2. Clicar em "Nova Solicitação". 3. Preencher todos os campos. 4. Salvar.	A solicitação aparece no dashboard com status "PENDENTE".
Upload em Massa	1. Clicar em "Importar Solicitações". 2. Baixar o template. 3. Preencher com 5 linhas válidas e 2 inválidas. 4. Fazer upload.	A pré-visualização mostra 5 linhas verdes e 2 vermelhas com o motivo do erro.
Ciclo de Decisão	1. Clicar em "Exportar Pendentes". 2. Preencher o CSV com decisões. 3. Clicar em "Importar Decisões" e fazer o upload.	Os status dos itens no dashboard são atualizados.
Edição Financeira	1. Abrir os detalhes de um item. 2. Alterar o "Valor do Rebate". 3. Salvar.	Mensagem de sucesso é exibida. A trilha de auditoria reflete a mudança.

3. Monitoramento de Performance

A performance de operações críticas é monitorada através dos logs do Google Cloud Platform.

Como Verificar:

1. Vá para a página do seu projeto no Google Cloud Platform.
2. No menu de navegação, vá para Logging > Explorador de Registos.
3. Filtre pelos logs do seu projeto Apps Script.
4. Procure por mensagens como Performance: <FunctionName> executou em XXXms.. Isso indica o tempo de execução de funções críticas e ajuda a identificar gargalos.