DDRISS Panel Administrativo

Panel de administración web para la Dirección Departamental de Redes Integradas de Servicios de Salud (DDRISS) de Jutiapa. Este proyecto está diseñado para ser escalable, modular y fácil de mantener, utilizando las últimas tecnologías del ecosistema React.

Admin Module Expansion (Latest)

Recent updates focused on advanced management tools and data transparency:

• Advanced Filtering: Categorical search by Role and Operative Unit in the Users table.
• Data Export: CSV generation for Users and Audit Logs using a custom JSON-to-CSV utility.
• Detailed Audit: "Ver Detalle" modal for audit logs with object-level diffing (Before/After states).
• Catalog CRUD: Direct management of operational units from the admin dashboard.
• Premium UX: High-fidelity animated skeletons for all data-heavy components.

Important

Los módulos de Autenticación, Usuarios y Roles ya están integrados con el backend real a través de VITE_API_URL.

Tecnologías Principales

El proyecto está construido sobre un stack moderno y opiniónado enfocado en rendimiento y productividad.

• Librería: React 19
• Lenguaje: TypeScript 5 (Modo estricto)
• Estilos: Tailwind CSS 4
• Gestión de Estado (Cliente): Zustand 5
• Gestión de Estado (Servidor/Async): TanStack Query v5
• Formularios: React Hook Form + Zod
• Iconos: Lucide React
• Gráficos: Recharts 3
• Utilidades UI: clsx, tailwind-merge, date-fns

Arquitectura del Proyecto

El proyecto sigue una arquitectura basada en Features, lo que permite encapsular la lógica de negocio y UI relacionada en módulos independientes.

Organización de Carpetas

La estructura principal se encuentra dentro de src/ y se organiza de la siguiente manera:

• pages/: Rutas y páginas de la aplicación (Vite).
  • dashboard/: Grupo de rutas protegidas que comparten el layout principal.
  • login/: Ruta pública de autenticación.
  • App.tsx: App componente base y configuración de providers (React Router).
• components/: Componentes reutilizables.
  • ui/: Componentes primitivos de interfaz (Botones, Tablas, Cards).
  • layout/: Componentes estructurales (Sidebar, Navbar).
  • common/: Componentes genéricos de la aplicación.
• config/: Configuraciones globales (navegación, permisos).
• features/: Módulos de negocio. Cada funcionalidad tiene su propia carpeta:
  • auth/: Autenticación, guardias, store.
  • admin-users/: Gestión de usuarios del sistema.
  • hr-management/: Recursos humanos (empleados, vacaciones).
  • content-cms/: Gestión de contenido (noticias).
  • health-stats/: Estadísticas de salud.
• lib/: Utilidades y helpers globales (utils.ts, delay.ts).

Patrones de Diseño

1. Screaming Architecture: La estructura de carpetas "grita" el dominio del negocio (Usuarios, Auditoría, Recursos Humanos, Nómina, etc.) en lugar de agrupar por conceptos técnicos (todos los componentes juntos, todos los hooks juntos). Cada módulo dentro de features/ es altamente cohesivo y contiene sus propios:

   • components/: Componentes específicos de la funcionalidad, subdivididos en carpetas por subdominio (ej. dashboard/, employees/, audit-logs/).
   • services/: Lógica de comunicación con API (Integrados con backend real para Auth, Usuarios y Roles).
   • types/: Definiciones de TypeScript e interfaces.
   • stores/: Estado global específico del módulo (si aplica).
   • data.ts: Datos mock para desarrollo.

2. Service Layer Pattern: La lógica de negocio y llamadas a API están abstraídas en clases de servicio (ej. UsersService, AuthService). Los componentes de UI solo consumen estos servicios a través de React Query, nunca llaman a la API directamente.

3. Strict Typing: Se utiliza TypeScript de manera estricta. No se permite el uso de any o unknown sin justificación crítica. Todas las props, respuestas de API y estados están tipados.

4. Componentes UI Primitivos: Se utilizan componentes base en components/ui construidos con class-variance-authority para manejar variantes de estilo de manera consistente.

Configuración y Ejecución

Prerrequisitos

• Node.js 18+
• pnpm 8+

Instalación

# Clonar el repositorio
git clone <url-del-repo>

# Instalar dependencias
pnpm install

Desarrollo

Para iniciar el servidor de desarrollo en la URL predeterminada de Vite (usualmente http://localhost:5173):

pnpm dev

Producción

Para construir y ejecutar la versión optimizada:

pnpm build
pnpm preview

Convenciones de Código

• Nombres de Archivos: CamelCase para componentes (LoginForm.tsx), kebab-case para utilidades y servicios (auth.service.ts).
• Commits: Seguir la convención Conventional Commits (feat, fix, chore, refactor, docs).
• Estilos: Utilizar clases utilitarias de Tailwind. Evitar estilos en línea o archivos CSS separados a menos que sea estrictamente necesario.
• Imports: Utilizar alias de ruta @/ para importaciones limpias.

Autenticación y Seguridad

• AuthGuard: Componente de orden superior que protege las rutas privadas verificando el estado en useAuthStore.
• RBAC (Role-Based Access Control):
  • Los roles están definidos en UserRole (ADMIN, RRHH, HEALTH_OFFICER).
  • La navegación se genera dinámicamente según el rol del usuario (sidebar-config.ts).
  • Las vistas y componentes se renderizan condicionalmente según los permisos.

---

DDRISS Jutiapa - Desarrollo de Software Gubernamental