fatimaashar666-web/MCPpractice

Skill do Agente para Helpdesk do Campus

Esta skill define os padrões técnicos, fluxos de trabalho e práticas recomendadas para desenvolver, melhorar e manter o aplicativo web Campus Helpdesk. Use este guia sempre que adicionar funcionalidades, refatorar componentes, atualizar fluxos de status ou modificar modelos de dados neste projeto.

---

1. Escrevendo Componentes React Limpos e Reutilizáveis

Mantenha uma arquitetura de componentes modular e desacoplada:

• Princípio da Responsabilidade Única: Cada componente deve fazer bem uma coisa.
  • Lógica e entradas de formulário pertencem a IssueForm.jsx.
  • Pesquisa pública, filtragem e exibição de cartões de ticket pertencem a TicketList.jsx.
  • Métricas analíticas, barras de progresso visuais e tabelas administrativas pertencem a AdminDashboard.jsx.
  • Inspeções modais e linhas do tempo de histórico pertencem a TicketModal.jsx.
  • Notificações pertencem a Toast.jsx.
• Design de Props & State:
  • Mantenha o estado o mais local possível. Eleve o estado para App.jsx apenas quando compartilhado entre visualizações distintas (por exemplo, tickets, activeTab, toasts globais).
  • Use componentes filhos apresentacionais puros sempre que possível, passando callbacks (onSelectTicket, onUpdateStatus, onDeleteTicket) de forma limpa.
  • Evite estado duplicado; calcule valores derivados (por exemplo, tickets filtrados, estatísticas KPI) usando useMemo.
• Convenções de Nomenclatura & Código Limpo:
  • Arquivos de componente usam PascalCase (AdminDashboard.jsx, IssueForm.jsx).
  • Arquivos de utilitários e constantes usam camelCase (storage.js, constants.js).
  • Manipuladores de eventos devem seguir o padrão handle[Ação] (por exemplo, handleSubmit, handleStatusChange).
  • Preserve comentários e docstrings. Escreva código autoexplicativo com nomes de variáveis descritivos e limpos.
• Zero Dependências Externas Pesadas:
  • Mantenha a arquitetura leve: use hooks nativos do React, SVGs inline puros para ícones e classes CSS com escopo em vez de incluir bibliotecas de componentes de terceiros volumosas.

---

2. Criando UI Responsiva e Acessível

O portal de Helpdesk do Campus deve fornecer uma experiência de usuário sem atritos em todos os dispositivos (celulares, tablets, laptops, monitores grandes):

• Layouts Fluidos & Breakpoints:
  • Projete mobile-first ou desktop-down com breakpoints consistentes:
    • Desktop: Largura máxima do container 1240px com grids de várias colunas (5 cartões de métrica, análises de 2 colunas, formulários de 2 colunas).
    • Tablet (<= 1024px): Reduza grids de 5 colunas de métricas para 3 ou 2 colunas; empilhe gráficos de análise em uma única coluna.
    • Mobile (<= 768px): Empilhe navegação do cabeçalho, entradas de formulário em 1 coluna; ative rolagem horizontal em tabelas de dados.
    • Telas Pequenas (<= 480px): Cartões de métrica de largura total, botões de ação empilhados e notificações toast fixadas na parte inferior.
• Acessibilidade (a11y):
  • Todos os elementos interativos devem ter HTML semântico apropriado (<button>, <input>, <select>, <textarea>).
  • Controles de formulário devem ter elementos <label htmlFor="..."> associados com atributos id correspondentes.
  • Diálogos modais devem ter role="dialog", aria-modal="true" e suportar dispensa via cliques no fundo e teclas de escape.
  • Ícones interativos ou botões apenas com ícone devem incluir atributos descritivos aria-label ou title.
  • Mantenha taxas de contraste de cor acessíveis para texto em emblemas de status e tags de prioridade.
• Feedback Visual & Transições:
  • Elementos interativos devem mostrar estados claros :hover, :focus e :active.
  • Campos de formulário em foco devem exibir um anel de foco de alto contraste (var(--primary-ring)).
  • Use microanimações (toast deslizante, escala modal, spinners de botão) para informar o usuário sobre ações em segundo plano sem causar mudança de layout.

---

3. Validando Formulário de Problema do Estudante

Todas as submissões de problemas através de IssueForm.jsx devem seguir regras de validação rigorosas do lado do cliente antes da mutação ou armazenamento de estado:

Matriz de Regras de Validação

Campo	Regra	Mensagem de Erro
Nome Completo	Obrigatório, sem espaços no início/fim, não vazio	"Por favor, forneça seu nome completo."
Email do Campus	Obrigatório, padrão regex válido /^[^\s@]+@[^\s@]+\.[^\s@]+$/	"Por favor, insira um endereço de email válido."
Localização / Sala	Obrigatório, sem espaços no início/fim, não vazio	"Especifique o prédio, corredor ou localização do campus."
Categoria	Obrigatório, deve corresponder à lista CATEGORIES	Selecionado automaticamente por padrão
Prioridade	Obrigatório, deve corresponder a PRIORITIES (Low, Medium, High, Urgent)	Padrão 'Medium'
Título do Problema	Obrigatório, sem espaços no início/fim, comprimento mínimo $\ge 5$ caracteres	"O título deve ter pelo menos 5 caracteres."
Descrição Detalhada	Obrigatório, sem espaços no início/fim, comprimento mínimo $\ge 15$ caracteres	"A descrição deve ter pelo menos 15 caracteres."

Etapas de Implementação da Validação

1. Mantenha um objeto de estado errors mapeando nomes de campos para strings de erro.
2. Limpe o erro do campo específico quando o usuário modificar sua entrada (handleChange).
3. Verifique todas as regras no handleSubmit. Impedir a submissão e destaque campos inválidos com .input-error e .field-error se houver erros.
4. Em caso de sucesso:
   • Gere um ID único (por exemplo, TCK-XXXX).
   • Atribua status inicial Pending.
   • Registre timestamp de submissão inicial e nó de histórico.
   • Redefina campos do formulário e estado de erro.
   • Acione um toast de sucesso e navegue para a visualização do rastreador de tickets.

---

4. Gerenciando Status Pendente, Em Andamento e Resolvido

O Helpdesk do Campus segue um ciclo de vida de 3 estágios estritamente definido:

[ Pending ]  ───►  [ In Progress ]  ───►  [ Resolved ]
    ▲                      ▲                     │
    └──────────────────────┴─────────────────────┘ (Pode ser reaberto se necessário)

Definições de Status & Sistema de Design Visual

1. Pending:
   • Significado: Novo problema enviado por estudante/funcionário, aguardando triagem ou atribuição.
   • Tema de Cor: Âmbar (#d97706), fundo #fef3c7, borda #fde68a.
   • Estágio de Progresso: Etapa 1 ativa.
2. In Progress:
   • Significado: Técnico ou departamento do campus assumiu o ticket e está investigando ou reparando ativamente.
   • Tema de Cor: Azul Real (#2563eb), fundo #dbeafe, borda #bfdbfe.
   • Estágio de Progresso: Etapas 1 e 2 ativas.
3. Resolved:
   • Significado: O reparo está concluído, equipamento substituído ou serviço restaurado.
   • Tema de Cor: Verde Esmeralda (#059669), fundo #d1fae5, borda #a7f3d0.
   • Estágio de Progresso: Etapas 1, 2 e 3 ativas.

Regras do Ciclo de Vida & Histórico de Auditoria

• Cada transição de status deve anexar um evento ao array history do ticket:

  {
    status: newStatus,
    timestamp: new Date().toISOString(),
    note: `Status atualizado para ${newStatus}`
  }
  

• Atualizar notas internas da equipe deve atualizar adminNote e updatedAt sem redefinir o createdAt original do ticket.
• As atualizações devem sincronizar imediatamente para localStorage (campus_helpdesk_tickets_v1).

---

5. Mantendo Estatísticas do Painel Precisas

O Painel Administrativo fornece visibilidade operacional em tempo real. Todas as métricas KPI e cálculos de gráfico devem ser derivados dinamicamente da fonte de verdade, o array tickets:

Cálculos de Métricas

1. Total de Tickets: $$\text{Total} = \text{tickets.length}$$
2. Contagem Pendente: $$\text{Pending} = \text{tickets.filter}(t \Rightarrow t.\text{status} === \text{STATUSES.PENDING}).\text{length}$$
3. Contagem Em Andamento: $$\text{In Progress} = \text{tickets.filter}(t \Rightarrow t.\text{status} === \text{STATUSES.IN_PROGRESS}).\text{length}$$
4. Contagem Resolvida: $$\text{Resolved} = \text{tickets.filter}(t \Rightarrow t.\text{status} === \text{STATUSES.RESOLVED}).\text{length}$$
5. Taxa de Resolução (%): $$\text{Taxa de Resolução} = \begin{cases} \text{Math.round}\left(\frac{\text{Resolved}}{\text{Total}} \times 100\right), & \text{se Total} > 0 \ 0, & \text{caso contrário} \end{cases}$$
6. Fila de Alta & Prioridade Urgente: $$\text{Urgente/Alta} = \text{tickets.filter}(t \Rightarrow t.\text{priority} === 'Urgent' \lor t.\text{priority} === 'High').\text{length}$$
7. Distribuições de Categoria & Prioridade:
   • Calcule contagens para todas as categorias e prioridades predefinidas, mesmo que a contagem seja 0, para evitar cintilação da interface ou divisão por zero.
   • Garanta que as porcentagens de largura da barra de progresso sempre somem $\le 100%$.

Envolva todos os cálculos estatísticos dentro do hook useMemo do React com [tickets] como dependência para manter o desempenho.

---

6. Testando Alterações e Executando Build

Antes de enviar qualquer alteração de código ou marcar uma tarefa como concluída, verifique o aplicativo através de análise estática e etapas de build de produção:

Protocolo de Verificação

1. Navegue para o Diretório do Projeto:

   cd "campus-helpdesk"
   

2. Execute a Análise Estática de Código (Lint):

   npm run lint
   

   • Deve sair com código 0.
   • Certifique-se de que não há imports não utilizados, variáveis ou entidades JSX sem escape.

3. Execute o Build de Produção:

   npm run build
   

   • Verifique se o Vite conclui o empacotamento de assets de produção sem erros ou avisos.
   • Verifique se dist/index.html, dist/assets/*.css e dist/assets/*.js são criados com sucesso.

4. Verifique a Persistência no localStorage:

   • Teste se enviar um ticket atualiza localStorage.getItem('campus_helpdesk_tickets_v1').
   • Teste se atualizar o status do ticket persiste após atualizar a página.
   • Teste a funcionalidade "Reset Sample Data" e "Clear All".

---

7. Relatando Erros com Honestidade

Integridade e honestidade são essenciais ao relatar status do sistema ou erros:

• Não Masque Falhas: Se ocorrer um erro de build, erro de sintaxe ou falha de lint, relate a mensagem de erro exata, nome do arquivo e número da linha.
• Explique a Causa Raiz: Explique por que o erro ocorreu (por exemplo, import ausente, caso nulo não tratado no analisador de armazenamento, contrato de prop quebrado).
• Apenas Correções Verificadas: Não afirme que um problema foi corrigido sem executar novamente o comando de verificação (npm run lint / npm run build) e confirmar o código de saída 0.
• Transparência com o Usuário: Se ocorrer uma limitação inesperada do navegador ou problema de cota do localStorage, explique proativamente a limitação ao usuário e apresente opções técnicas claras.