Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/GianlucaBessone/HDB-Service/llms.txt

Use this file to discover all available pages before exploring further.

The HDB Service dashboard gives operators an at-a-glance view of the entire water dispenser fleet. It aggregates live data from tickets, dispensers, stock entries, and maintenance schedules into a set of purpose-built endpoints. All metrics are automatically scoped to the authenticated user’s accessible plants and clients, so field technicians, client contacts, and company administrators each see a tailored picture without any manual filtering. The dashboard is accessible to every role in the system via the dashboard:read permission.

​
Summary stats

GET /api/dashboard
Returns the core operational summary for the authenticated user’s data scope. All data is fetched in parallel for low latency.
Use the plantId query parameter on /api/dashboard to filter all metrics to a specific plant — for example, GET /api/dashboard?plantId=plnt_xyz789.

​
Response shape

​
user
object
Basic info about the authenticated user.
​
tickets
object
Ticket volume and SLA health.
​
dispensers
object
Real-time fleet status breakdown.
​
stock
object
Low-stock alert count.
​
maintenance
object
Maintenance schedule health.
Example response: 
{
  "user": { "nombre": "Ana García", "role": "SUPERVISOR" },
  "tickets": { "open": 4, "total": 31, "slaCompliance": 87.5 },
  "dispensers": { "total": 48, "inService": 43, "repair": 3, "blocked": 2 },
  "stock": { "lowAlerts": 6 },
  "maintenance": { "pending": 12, "overdue": 3 }
}

​
Analytics

GET /api/dashboard/analytics
Provides deep operational analytics combining tickets, repair history, maintenance checklists, and dispenser data. Accepts clientId, plantId, sectorId, and dispenserId as optional query filters to progressively narrow the scope. The response includes three top-level objects:
​
kpis
object
Aggregated time-based KPIs.
​
failures
object
Failure pattern analysis derived from maintenance checklist fallas arrays.
​
health
object
Dispenser health scoring.
All data in this endpoint is scoped to the user’s accessible plants via getDataFilter, and CLIENT_RESPONSIBLE users are further restricted to their own client’s data.

​
Performance metrics

GET /api/dashboard/performance
Delivers time-series KPI data across a rolling 6-month window, broken down by month. Accepts clientId, plantId, and an optional failureName filter to isolate trends caused by a specific failure type.
​
kpis
object
Same sla, mttr, and mtbf aggregates as the analytics endpoint, but computed exclusively over the filtered data set.
​
failures
array
Top 10 failure types sorted by count, each with name, count, avgRepairTime, and severity.
​
timeline
array
Six monthly data points (oldest to newest). Each entry has a month label (e.g., "Jan 2025"), an average sla in hours, and an average mttr in hours for that calendar month.
Example timeline entry: 
{ "month": "Apr 2025", "sla": 3.2, "mttr": 18.7 }

​
Fleet health

GET /api/dashboard/salud
Returns a per-dispenser health ranking and distribution for the entire accessible fleet. Filters by clientId or plantId are supported. The health score (0–100) is computed by calculateDispenserHealth using a weighted algorithm:
FactorWeightTarget
MTBF (months between failures)30%≥ 6 months
MTTR (hours to repair)20%≤ 48 hours (score reaches 0 at 48 h)
Maintenance condition rating20%GOOD
Failure recurrence (last 6 months)15%0 recurrences (−20 pts each; zero at 5+)
Lifecycle progress consumed15%Near 0%
Dispensers are classified as:

ÓPTIMO

Score > 80 — healthy, low failure rate, within expected lifecycle.

ESTABLE

Score 50–80 — acceptable condition, monitor for deterioration.

CRÍTICO

Score < 50 — high failure rate, poor condition, or near end of lifecycle.
The response includes:
​
ranking
array
All dispensers in scope, sorted ascending by score (most critical first). Each entry includes id, marca, modelo, serial, planta, score, status, and a details block with raw mtbfDays, mtbfMonths, mttrHours, recurrences, condition, progress, ownerPlantId, and currentPlantId values.
​
distribution
object
Aggregate counts: optimo, estable, and critico.
​
timeline
array
6-month score trend for the fleet’s global average health score.

​
PDF reports

POST /api/dashboard/pdf
Generates a downloadable PDF report of either operational performance or fleet health data, rendered server-side using @react-pdf/renderer. The response is a binary PDF stream with Content-Type: application/pdf. Request body: 
{
  "type": "performance",
  "filters": {
    "clientId": "clnt_abc",
    "plantId": null,
    "failureName": null
  },
  "data": { ... }
}
type valueReport content
performanceSLA, MTTR, MTBF KPIs with metric definitions
saludDispenser health distribution and top-10 ranking
The PDF includes:
  • A header with the report title and generation date, plus the active filters.
  • A metrics section showing the current KPI values.
  • For salud reports: a ranking table of the worst-scoring dispensers with MTBF detail.
  • A metric definitions section explaining SLA, MTTR, MTBF, and (for health reports) the scoring algorithm.
The PDF endpoint is a POST request — it expects the already-fetched analytics data in the request body so it can render the report without making additional database queries.

​
Role-based data scoping

Every dashboard endpoint applies automatic data filters based on the authenticated user’s role using the getDataFilter utility:
RoleData scope
ADMINAll clients and plants in the system.
SUPERVISORAll clients and plants in the system.
TECHNICIANOnly tickets assigned to them (assignedToId).
CLIENT_RESPONSIBLEAll plants and dispensers belonging to their clientId.
CLIENT_REQUESTEROnly tickets they reported, scoped to their UserPlantAccess plant list.
Attempting to pass a plantId that falls outside the user’s access scope returns 403 — Acceso denegado a esta planta.

Build docs developers (and LLMs) love

Get started for freeTalk to us