fatimaashar666-web/MCPpractice

Skill de Agente para Campus Helpdesk

Este skill define los estándares técnicos, flujos de trabajo y mejores prácticas para desarrollar, mejorar y mantener la aplicación web Campus Helpdesk. Utiliza esta guía cada vez que agregues funcionalidades, refactorices componentes, actualices flujos de estado o modifiques modelos de datos en este proyecto.

---

1. Escribir Componentes React Limpios y Reutilizables

Mantén una arquitectura de componentes modular y desacoplada:

• Principio de Responsabilidad Única: Cada componente debe hacer una sola cosa bien.
  • La lógica y los campos del formulario pertenecen a IssueForm.jsx.
  • La búsqueda pública, el filtrado y la visualización de tarjetas de tickets pertenecen a TicketList.jsx.
  • Las métricas analíticas, las barras de progreso visuales y las tablas administrativas pertenecen a AdminDashboard.jsx.
  • Las inspecciones modales y las líneas de tiempo del historial pertenecen a TicketModal.jsx.
  • Las notificaciones pertenecen a Toast.jsx.
• Diseño de Props y Estado:
  • Mantén el estado lo más local posible. Eleva el estado a App.jsx solo cuando sea compartido entre vistas distintas (por ejemplo, tickets global, activeTab, toasts).
  • Utiliza componentes hijos puramente de presentación cuando sea posible, pasando callbacks (onSelectTicket, onUpdateStatus, onDeleteTicket) de forma limpia.
  • Evita el estado duplicado; calcula valores derivados (por ejemplo, tickets filtrados, estadísticas KPI) usando useMemo.
• Convenciones de Nomenclatura y Código Limpio:
  • Los archivos de componentes usan PascalCase (AdminDashboard.jsx, IssueForm.jsx).
  • Los archivos de utilidades y constantes usan camelCase (storage.js, constants.js).
  • Los manejadores de eventos deben seguir el patrón handle[Acción] (por ejemplo, handleSubmit, handleStatusChange).
  • Conserva los comentarios y las cadenas de documentación. Escribe código autoexplicativo con nombres de variables descriptivos y limpios.
• Cero Dependencias Externas Pesadas:
  • Mantén la arquitectura ligera: utiliza hooks nativos de React, iconos SVG puros en línea y clases CSS con ámbito en lugar de incorporar bibliotecas de componentes de terceros voluminosas.

---

2. Crear una UI Responsiva y Accesible

El portal Campus Helpdesk debe proporcionar una experiencia de usuario fluida en todos los dispositivos (teléfonos móviles, tabletas, portátiles, monitores grandes):

• Diseños Fluidos y Puntos de Corte:
  • Diseña mobile-first o desktop-down con puntos de corte consistentes:
    • Escritorio: Ancho máximo del contenedor 1240px con cuadrículas de varias columnas (5 tarjetas de métricas, 2 columnas de análisis, 2 columnas de formularios).
    • Tableta (<= 1024px): Colapsa las cuadrículas de 5 columnas de métricas a 3 o 2 columnas; apila los gráficos de análisis en una sola columna.
    • Móvil (<= 768px): Apila la navegación del encabezado, las entradas del formulario en 1 columna; habilita el desplazamiento horizontal en las tablas de datos.
    • Pantallas Pequeñas (<= 480px): Tarjetas de métricas de ancho completo, botones de acción apilados y notificaciones de brindis fijadas en la parte inferior.
• Accesibilidad (a11y):
  • Todos los elementos interactivos deben tener el HTML semántico apropiado (<button>, <input>, <select>, <textarea>).
  • Los controles de formulario deben tener elementos <label htmlFor="..."> asociados con atributos id correspondientes.
  • Los diálogos modales deben tener role="dialog", aria-modal="true" y admitir el cierre mediante clics en el fondo y teclas de escape.
  • Los iconos interactivos o los botones de solo icono deben incluir atributos aria-label o title descriptivos.
  • Mantén relaciones de contraste de color accesibles para el texto en las insignias de estado y las etiquetas de prioridad.
• Comentarios Visuales y Transiciones:
  • Los elementos interactivos deben mostrar estados :hover, :focus y :active claros.
  • Los campos de formulario enfocados deben mostrar un anillo de enfoque de alto contraste (var(--primary-ring)).
  • Utiliza microanimaciones (deslizamiento de brindis, escalado modal, spinners de botones) para informar al usuario de las acciones en segundo plano sin causar cambios en el diseño.

---

3. Validar el Formulario de Incidencias del Estudiante

Todas las presentaciones de incidencias a través de IssueForm.jsx deben seguir reglas de validación estrictas del lado del cliente antes de la mutación del estado o el almacenamiento:

Matriz de Reglas de Validación

Campo	Regla	Mensaje de Error
Nombre Completo	Obligatorio, recortado, no vacío	"Por favor, proporciona tu nombre completo."
Correo Electrónico del Campus	Obligatorio, patrón regex válido /^[^\s@]+@[^\s@]+\.[^\s@]+$/	"Por favor, introduce una dirección de correo electrónico válida."
Ubicación / Sala	Obligatorio, recortado, no vacío	"Especifica el edificio, pasillo o ubicación del campus."
Categoría	Obligatorio, debe coincidir con la lista CATEGORIES	Seleccionado automáticamente por defecto
Prioridad	Obligatorio, debe coincidir con PRIORITIES (Low, Medium, High, Urgent)	Por defecto 'Medium'
Asunto / Título de la Incidencia	Obligatorio, recortado, longitud mínima $\ge 5$ caracteres	"El título debe tener al menos 5 caracteres."
Descripción Detallada	Obligatorio, recortado, longitud mínima $\ge 15$ caracteres	"La descripción debe tener al menos 15 caracteres."

Pasos de Implementación de la Validación

1. Mantén un objeto de estado errors que asigne nombres de campo a cadenas de error.
2. Borra el error del campo específico cuando el usuario modifique su entrada (handleChange).
3. Verifica todas las reglas en handleSubmit. Evita el envío y resalta los campos no válidos con .input-error y .field-error si existen errores.
4. En caso de éxito:
   • Genera un ID único (por ejemplo, TCK-XXXX).
   • Asigna el estado inicial Pending.
   • Registra la marca de tiempo de envío inicial y el nodo del historial.
   • Restablece los campos del formulario y el estado de error.
   • Activa un brindis de éxito y navega a la vista del rastreador de tickets.

---

4. Gestionar los Estados Pendiente, En Progreso y Resuelto

Campus Helpdesk sigue un ciclo de vida estrictamente definido de 3 etapas:

[ Pending ]  ───►  [ In Progress ]  ───►  [ Resolved ]
    ▲                      ▲                     │
    └──────────────────────┴─────────────────────┘ (Se puede reabrir si es necesario)

Definiciones de Estado y Sistema de Diseño Visual

1. Pending:
   • Significado: Nueva incidencia enviada por estudiante/personal, esperando clasificación o asignación.
   • Tema de Color: Ámbar (#d97706), fondo #fef3c7, borde #fde68a.
   • Etapa de Progreso: Paso 1 activo.
2. In Progress:
   • Significado: El técnico o departamento del campus ha reclamado el ticket y está investigando o reparando activamente.
   • Tema de Color: Azul Real (#2563eb), fondo #dbeafe, borde #bfdbfe.
   • Etapa de Progreso: Pasos 1 y 2 activos.
3. Resolved:
   • Significado: La reparación está completa, el equipo ha sido reemplazado o el servicio ha sido restaurado.
   • Tema de Color: Verde Esmeralda (#059669), fondo #d1fae5, borde #a7f3d0.
   • Etapa de Progreso: Pasos 1, 2 y 3 activos.

Reglas del Ciclo de Vida e Historial de Auditoría

• Cada transición de estado debe añadir un evento al array history del ticket:

  {
    status: newStatus,
    timestamp: new Date().toISOString(),
    note: `Estado actualizado a ${newStatus}`
  }
  

• La actualización de notas internas del personal debe actualizar adminNote y updatedAt sin restablecer el createdAt original del ticket.
• Las actualizaciones deben sincronizarse inmediatamente con localStorage (campus_helpdesk_tickets_v1).

---

5. Mantener las Estadísticas del Panel Correctas

El Panel de Administración proporciona visibilidad operativa en tiempo real. Todas las métricas KPI y los cálculos de gráficos deben derivarse dinámicamente del array tickets como fuente de verdad:

Cálculos de Métricas

1. Total de Tickets: $$\text{Total} = \text{tickets.length}$$
2. Recuento de Pendientes: $$\text{Pendientes} = \text{tickets.filter}(t \Rightarrow t.\text{status} === \text{STATUSES.PENDING}).\text{length}$$
3. Recuento de En Progreso: $$\text{En Progreso} = \text{tickets.filter}(t \Rightarrow t.\text{status} === \text{STATUSES.IN_PROGRESS}).\text{length}$$
4. Recuento de Resueltos: $$\text{Resueltos} = \text{tickets.filter}(t \Rightarrow t.\text{status} === \text{STATUSES.RESOLVED}).\text{length}$$
5. Tasa de Resolución (%): $$\text{Tasa de Resolución} = \begin{cases} \text{Math.round}\left(\frac{\text{Resueltos}}{\text{Total}} \times 100\right), & \text{si Total} > 0 \ 0, & \text{en caso contrario} \end{cases}$$
6. Cola de Prioridad Alta y Urgente: $$\text{Urgente/Alta} = \text{tickets.filter}(t \Rightarrow t.\text{priority} === 'Urgent' \lor t.\text{priority} === 'High').\text{length}$$
7. Distribuciones por Categoría y Prioridad:
   • Calcula los recuentos para todas las categorías y prioridades predefinidas incluso si el recuento es 0 para evitar parpadeos en la UI o divisiones por cero.
   • Asegúrate de que los porcentajes de ancho de las barras de progreso sumen siempre $\le 100%$.

Envuelve todos los cálculos estadísticos dentro del hook useMemo de React con [tickets] como dependencia para mantener el rendimiento.

---

6. Probar Cambios y Ejecutar la Compilación

Antes de enviar cualquier cambio de código o marcar una tarea como completa, verifica la aplicación mediante análisis estático y pasos de compilación de producción:

Protocolo de Verificación

1. Navega al Directorio del Proyecto:

   cd "campus-helpdesk"
   

2. Ejecuta el Análisis de Código Estático:

   npm run lint
   

   • Debe terminar con código de salida 0.
   • Asegúrate de que no haya imports no utilizados, variables o entidades JSX sin escapar.

3. Ejecuta la Compilación de Producción:

   npm run build
   

   • Verifica que Vite complete el empaquetado de activos de producción sin errores ni advertencias.
   • Verifica que dist/index.html, dist/assets/*.css y dist/assets/*.js se creen correctamente.

4. Verifica la Persistencia de localStorage:

   • Prueba que al enviar un ticket se actualice localStorage.getItem('campus_helpdesk_tickets_v1').
   • Prueba que la actualización del estado del ticket persista después de recargar la página.
   • Prueba la funcionalidad "Restablecer Datos de Muestra" y "Borrar Todo".

---

7. Reportar Errores con Honestidad

La integridad y la honestidad son esenciales al reportar el estado del sistema o errores:

• No Ocultes Fallos: Si ocurre un error de compilación, error de sintaxis o fallo de lint, reporta el mensaje de error exacto, el nombre del archivo y el número de línea.
• Explicación de la Causa Raíz: Explica por qué ocurrió el error (por ejemplo, import faltante, caso null no manejado en el analizador de almacenamiento, contrato de props roto).
• Solo Correcciones Verificadas: No digas que un problema está solucionado sin volver a ejecutar el comando de verificación (npm run lint / npm run build) y confirmar el código de salida 0.
• Transparencia con el Usuario: Si ocurre una limitación inesperada del navegador o un problema de cuota de localStorage, explica proactivamente la limitación al usuario y presenta opciones técnicas claras.