helpdesk/README.md

HelpDesk ICHN (Frontend)

Frontend Next.js del sistema de HelpDesk (estilo Freshdesk/Zammad).

El backend vive en el proyecto principal: ICHN/sam — backend/SAM.API/Controllers/HelpdeskController.cs (ruta /api/helpdesk/*, datos en schema helpdesk.* de la DB compartida). Este repo es solo frontend.

Estructura

helpdesk/
├── frontend/                   # Next.js 16 + Bootstrap 5
│   └── src/
│       ├── app/               # App Router pages
│       │   ├── (auth)/        # Login
│       │   └── (app)/         # Dashboard, Tickets, KB, Settings
│       ├── components/        # UI reutilizable
│       └── lib/               # API client, auth context
├── gateway/                    # (legado, no se usa en deploy)
├── scripts/                    # (legado, no se usa en deploy)
├── docker-compose.yml          # Solo frontend (red sam-net)
└── README.md

Stack

Componente	Tecnología
Frontend	Next.js 16 (App Router)
UI	Bootstrap 5 + React-Bootstrap
Auth	Bearer token propio del backend
Icons / Font	Bootstrap Icons / Fira Sans

Desarrollo Local

cd frontend
pnpm install
pnpm dev
# Frontend en http://localhost:3000

Variables de entorno (frontend/.env.local, no versionado):

NEXT_PUBLIC_API_URL=https://api.ichn.local   # dev (.254), cliente (bundle)
# NEXT_PUBLIC_API_URL=https://api.devops.norteamericano.cl  # prod (.4)

# Solo servidor (route /api/correos → POST /api/email/send, jamás NEXT_PUBLIC_):
# MAIL_API_KEY=clave del módulo helpdesk (POST /api/email/modules, se muestra una vez)
# SAM_API_URL=https://api.ichn.local         # default: NEXT_PUBLIC_API_URL, luego prod
# MAIL_MODULE=helpdesk                       # default helpdesk

Auth: login con idUsuario + password (valida contra sige_sam_v3.usuario en el backend). El primer integrante del equipo queda admin (bootstrap).

Roles del equipo (helpdesk.team_members):

Rol	Alcance
admin	Todo + Configuración (departamentos, equipo, SLA, correo)
agent	Todos los tickets
supervisor	Solo su departamento (+ sus propios tickets); requiere departamento asignado; no puede mover tickets de departamento ni gestionar configuración

Deploy

Lo publica el deployer de SAM desde este repo (módulo helpdesk): push a main → webhook Gitea → build + up en .4 (https://helpdesk.devops.norteamericano.cl).

Endpoints que consume (backend SAM)

Base: NEXT_PUBLIC_API_URL/api/helpdesk

• POST /login {idUsuario, password} · GET /me
• GET /tickets?... (con archived=false solo activos [default UI], true solo archivados, ausente todos) · GET /ticket/{id} · POST /tickets · PUT /ticket/{id} (+ /status, /assign, /archive) · POST /ticket/{id}/merge {sourceId} (mueve historial y cierra origen) · DELETE /ticket/{id}
• GET|POST /comments/{ticketId} (POST acepta cc y attachmentIds, solo públicas) · POST /ticket/{id}/attachments (multipart, máx 5 × 10 MB) · GET /ticket/{id}/attachments · GET /attachments/{fileId} (descarga)
• GET /kb/published · GET /kb/search?q= · GET /kb/categories
• GET /stats
• GET|POST /groups · PUT|DELETE /groups/{id} (admin)
• GET|POST /users · PUT /users/{id} (admin)
• GET|POST /sla · PUT /sla/{id} (admin)
• GET /notifications?module=&limit=&unreadOnly= · GET /notifications/unread-count?module= · PUT /notifications/{id}/read · PUT /notifications/read-all?module= (propias, estándar multi-módulo mail.notifications, campana con polling 60s + color por módulo) · POST /notifications/send (módulos con X-Module + X-Api-Key)
• GET /email/templates · POST /email/templates · PUT /email/templates/{key} · GET /email/log?module=helpdesk&limit= (admin, banco único mail.*; las claves de módulos se gestionan en el portal IT)
• POST /api/correos (route propio server-side → POST /api/email/send con X-Module: helpdesk + X-Api-Key) · POST /helpdesk/email/inbound/sync (admin, inbound Gmail sin cambios)