helpdesk/README.md

# HelpDesk ICHN

Sistema de HelpDesk inspirado en Freshdesk/Zammad, construido con .NET 10 + Next.js 16 + PostgreSQL.

## Arquitectura

```
helpdesk/
├── backend/                    # .NET 10 API
│   ├── HelpDesk.API/          # Web API (controllers, services, middleware)
│   ├── HelpDesk.Data/         # EF Core DbContext + Repositories
│   ├── HelpDesk.Models/       # Entities, Enums, DTOs
│   └── HelpDesk.sln
├── frontend/                   # Next.js 16 + Bootstrap 5
│   └── src/
│       ├── app/               # App Router pages
│       │   ├── (auth)/        # Login, Register
│       │   └── (app)/         # Dashboard, Tickets, KB, Users
│       ├── components/        # Reusable UI components
│       └── lib/               # API client, auth context
├── gateway/                    # Caddy reverse proxy
├── scripts/                    # DB init scripts
├── docker-compose.yml          # Full stack orchestration
└── README.md
```

## Stack

| Componente         | Tecnología               |
|--------------------|--------------------------|
| Backend API        | .NET 10, C# 14           |
| ORM                | Entity Framework Core 10 |
| Database           | PostgreSQL 16            |
| Cache              | Redis 7                  |
| Frontend           | Next.js 16 (App Router)  |
| UI Framework       | Bootstrap 5 + React-Bootstrap |
| Authentication     | JWT Bearer               |
| Reverse Proxy      | Caddy 2                  |
| Icons              | Bootstrap Icons          |
| Font               | Fira Sans (matching SAM)  |

## Paleta de Colores (SAM)

| Variable       | Valor     | Uso                          |
|----------------|-----------|------------------------------|
| Primary        | #00285d   | Navbar, sidebar, headings    |
| Primary Light  | #1a3f7a   | Hover states, gradients      |
| Gradient       | #00285d → #1a4a8a | Sidebar, buttons, headers |
| Background     | #f0f2f5   | Page background              |
| Card Shadow    | rgba(0,0,0,0.08) | Card elevation           |

## Desarrollo Local

### Prerequisitos
- .NET 10 SDK
- Node.js 24+
- PostgreSQL 16 (o usar Docker)
- Redis (o usar Docker)

### Backend
```bash
cd backend
dotnet restore
dotnet run --project HelpDesk.API
# API en http://localhost:5000
# Swagger en http://localhost:5000/swagger
```

### Frontend
```bash
cd frontend
npm install
npm run dev
# Frontend en http://localhost:3000
```

### Docker (todo junto)
```bash
docker compose up -d
# Caddy: http://localhost:8080
# API: http://localhost:5000
# Frontend: http://localhost:3000
# PostgreSQL: localhost:5433
# Redis: localhost:6381
```

## Datos por Defecto

### Usuario Admin
- Email: admin@helpdesk.local
- Password: Admin123!
- Rol: SuperAdmin

### Grupos
- Soporte General
- Ventas
- Desarrollo

### Políticas SLA
- Estándar: Primera respuesta 4h, Resolución 24h
- Premium: Primera respuesta 1h, Resolución 8h

## Endpoints API Principales

### Auth
- `POST /api/auth/login` - Iniciar sesión
- `POST /api/auth/register` - Registrar usuario
- `GET /api/auth/me` - Usuario actual

### Tickets
- `GET /api/tickets` - Listar tickets (filtros: status, priority, assigneeId, search)
- `GET /api/tickets/{id}` - Detalle de ticket
- `POST /api/tickets` - Crear ticket
- `PUT /api/tickets/{id}` - Actualizar ticket
- `DELETE /api/tickets/{id}` - Eliminar ticket
- `PUT /api/tickets/{id}/status` - Cambiar estado
- `PUT /api/tickets/{id}/assign` - Asignar agente
- `POST /api/tickets/{id}/comments` - Agregar comentario
- `GET /api/tickets/stats` - Estadísticas

### Knowledge Base
- `GET /api/kb/articles/published` - Artículos publicados
- `GET /api/kb/search?q=termo` - Buscar artículos

### Dashboard
- `GET /api/dashboard/stats` - Estadísticas del dashboard

### Users
- `GET /api/users` - Listar usuarios
- `GET /api/users/agents` - Listar agentes

### Groups
- `GET /api/groups` - Listar grupos

### SLA
- `GET /api/sla` - Listar políticas SLA

## Funcionalidades

### Gestión de Tickets
- Crear, editar, eliminar tickets
- Estados: Abierto → En Progreso → Pendiente (Cliente/Agente) → Resuelto → Cerrado
- Prioridades: Baja, Media, Alta, Urgente
- Asignación a agentes y grupos
- Comentarios públicos e internos
- Historial de actividad
- Número de ticket automático (#XXXX)

### Dashboard
- Resumen de tickets por estado
- Distribución por prioridad
- Tiempo promedio de respuesta
- Carga de trabajo por agente
- Tickets recientes

### Knowledge Base
- Artículos organizados por categorías
- Búsqueda de artículos
- Contador de vistas
- Publicar/ocultar artículos

### Autenticación
- JWT Bearer tokens
- Roles: SuperAdmin, Admin, Agente, Cliente
- Registro de nuevos usuarios
- Políticas de autorización por rol

## Diseño

Inspirado en la interfaz de SAM (sam.norteamericano.cl):
- Sidebar azul oscuro con gradiente
- Tarjetas blancas con sombras suaves
- Fondo gris claro
- Tipografía Fira Sans
- Badges de color para estados y prioridades
- Layout responsive (mobile-first)