From 0c88e71f92328be70712f1140250f38ad02576ce Mon Sep 17 00:00:00 2001 From: Rodolpho Lopes Date: Mon, 22 Jun 2026 22:52:14 +0000 Subject: [PATCH] docs(KB-035): modelo de dados dos KPIs de Service Desk no GLPI 11 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documenta as colunas/tabelas reais usadas pelas 7 tools de KPI (MTTR via solve_delay_stat, FCR via solução recusada, SLA TTR/TTO, workload, backlog, CSAT, volume). Atualiza snapshot KB-026 para 26 tools. Co-Authored-By: Claude Opus 4.8 --- index.json | 19 ++++ ...IN-026-mcprotocol-roadmap-snapshot-v1.2.md | 7 +- ...-035-glpi11-service-desk-kpi-data-model.md | 94 +++++++++++++++++++ 3 files changed, 117 insertions(+), 3 deletions(-) create mode 100644 records/plugin-dev/KB-PLUGIN-035-glpi11-service-desk-kpi-data-model.md diff --git a/index.json b/index.json index b258f2e..be5c7f4 100755 --- a/index.json +++ b/index.json @@ -627,6 +627,25 @@ "severity": "high", "path": "records/plugin-dev/KB-PLUGIN-034-glpi11-encrypt-external-credentials-itemtype.md", "summary": "id: KB-PLUGIN-034" + }, + { + "id": "KB-PLUGIN-035", + "title": "Modelo de dados dos KPIs de Service Desk no GLPI 11 (tools de BI do mcprotocol)", + "domain": "plugin-dev", + "tags": [ + "glpi", + "glpi11", + "mcp", + "kpi", + "bi", + "tickets", + "sla", + "csat" + ], + "status": "active", + "severity": "medium", + "path": "records/plugin-dev/KB-PLUGIN-035-glpi11-service-desk-kpi-data-model.md", + "summary": "id: KB-PLUGIN-035" } ] } diff --git a/records/plugin-dev/KB-PLUGIN-026-mcprotocol-roadmap-snapshot-v1.2.md b/records/plugin-dev/KB-PLUGIN-026-mcprotocol-roadmap-snapshot-v1.2.md index fa17518..a30a675 100644 --- a/records/plugin-dev/KB-PLUGIN-026-mcprotocol-roadmap-snapshot-v1.2.md +++ b/records/plugin-dev/KB-PLUGIN-026-mcprotocol-roadmap-snapshot-v1.2.md @@ -134,14 +134,15 @@ Ambos comprovam o padrão de tools nativo funcionando em fluxo real de comercial 9. **SSE / Streamable HTTP completo** — notificações push (novo ticket, SLA estourando) 10. **OAuth2 com escopos finos** — separar permissões por escopo de tool -## Métricas atuais (v1.2.0 — 2026-06-22) +## Métricas atuais (v1.2.0 + KPIs — 2026-06-22) -- **Tools registradas:** 19 (13 domínio + 6 genéricas) +- **Tools registradas:** 26 (20 domínio + 6 genéricas) - Domínio Ticket (6): `get`, `bi_stats`, `create`, `update`, `add_followup`, `add_solution` - Domínio Project (3): `get`, `create`, `update` - Domínio ProjectTask (4): `get`, `create`, `update`, `delete` + - **Domínio KPI (7): `mttr_stats`, `fcr_stats`, `sla_compliance`, `team_productivity`, `backlog_stats`, `satisfaction_stats`, `volume_stats`** (ver KB-PLUGIN-035) - Genéricas (6): `get_items`, `get_item`, `add_item`, `update_item`, `delete_item`, `ticket_search_by_status` -- **Arquivos em `src/`:** `Boot`, `Server`, `ToolRegistry`, `InputValidation`, `TicketTools`, `ProjectTools`, `ProjectTaskTools` (7) +- **Arquivos em `src/`:** `Boot`, `Server`, `ToolRegistry`, `InputValidation`, `TicketTools`, `ProjectTools`, `ProjectTaskTools`, `TicketKpiTools` (8) - **Casos reais validados:** 2 projetos, 34 tarefas (VALGROUP, TCERJ) - **Bugs ativos:** 1 (baixa — TZ de datas, KB-PLUGIN-025). KB-024 resolvido. - **Versão atual do plugin:** 1.2.0 (em dev `origin`, aguardando homologação) diff --git a/records/plugin-dev/KB-PLUGIN-035-glpi11-service-desk-kpi-data-model.md b/records/plugin-dev/KB-PLUGIN-035-glpi11-service-desk-kpi-data-model.md new file mode 100644 index 0000000..7f120ca --- /dev/null +++ b/records/plugin-dev/KB-PLUGIN-035-glpi11-service-desk-kpi-data-model.md @@ -0,0 +1,94 @@ +--- +id: KB-PLUGIN-035 +title: Modelo de dados dos KPIs de Service Desk no GLPI 11 (tools de BI do mcprotocol) +domain: plugin-dev +tags: + - glpi + - glpi11 + - mcp + - kpi + - bi + - tickets + - sla + - csat +status: active +severity: medium +created_at: 2026-06-22 +updated_at: 2026-06-22 +applies_to: + - glpi-11 + - mcprotocol-plugin +related_records: + - KB-PLUGIN-019 + - KB-PLUGIN-022 + - KB-PLUGIN-026 +--- + +# Modelo de dados dos KPIs de Service Desk no GLPI 11 + +Referência canônica das colunas/tabelas reais do GLPI 11 usadas pelas tools de KPI +(`src/TicketKpiTools.php`, plugin v1.2.0+). Mapeamento levantado direto no schema +do core (a KB não tinha isso antes). Princípio BFF: o LLM pede o KPI, o PHP conhece +as colunas (KB-PLUGIN-019). + +## Colunas-chave de `glpi_tickets` + +| Coluna | Tipo | Uso | +|---|---|---| +| `date` / `date_creation` | timestamp | Abertura do chamado | +| `takeintoaccountdate` | timestamp | Data do primeiro atendimento (resposta) | +| `solvedate` | timestamp | Data de solução | +| `closedate` | timestamp | Data de fechamento | +| `status` | int | 1=Novo 2=Processando/Atribuído 3=Planejado 4=Pendente 5=Solucionado 6=Fechado | +| `solve_delay_stat` | int (s) | **Tempo real de solução em segundos**, já calculado pelo GLPI (calendário de trabalho, descontando espera) | +| `takeintoaccount_delay_stat` | int (s) | Tempo até o primeiro atendimento (resposta) | +| `close_delay_stat` | int (s) | Tempo até o fechamento | +| `waiting_duration` / `sla_waiting_duration` | int (s) | Tempo total em espera/pendente | +| `time_to_resolve` | timestamp | **Prazo** do SLA de solução (TTR) | +| `time_to_own` | timestamp | **Prazo** do SLA de resposta (TTO) | +| `slas_id_ttr` / `slas_id_tto` | int FK | SLA atribuído (solução / resposta) | + +> ⚠️ Para MTTR, **prefira `solve_delay_stat`** ao invés de `solvedate - date`: o GLPI já +> desconta horário não-útil e tempo de espera. A tool expõe os dois (`_wall` = corrido). + +## Mapeamento KPI → fonte + +| KPI | Tool | Fonte / regra | +|---|---|---| +| MTTR | `glpi_ticket_mttr_stats` | `AVG(solve_delay_stat)` de tickets status∈(5,6), `solvedate` no período | +| FCR ("sem reabertura") | `glpi_ticket_fcr_stats` | resolvidos − (resolvidos com solução recusada). Reabertura = `glpi_itilsolutions.status = 4` (`CommonITILValidation::REFUSED`) | +| SLA solução (TTR) | `glpi_ticket_sla_compliance` | `solvedate <= time_to_resolve` (entre os que têm `time_to_resolve` e `solvedate`) | +| SLA resposta (TTO) | `glpi_ticket_sla_compliance` | `takeintoaccountdate <= time_to_own` | +| Workload | `glpi_team_productivity` | JOIN `glpi_tickets_users` (type=2 técnico) ou `glpi_groups_tickets` (type=2). Resolvidos no período + backlog (status∉(5,6)) | +| Backlog growth | `glpi_ticket_backlog_stats` | abertos(`date`) vs resolvidos(`solvedate`) no período; `net = abertos − resolvidos` | +| CSAT | `glpi_satisfaction_stats` | `AVG(glpi_ticketsatisfactions.satisfaction_scaled_to_5)` (float 0-5), `date_answered` p/ taxa de resposta | +| Volume | `glpi_ticket_volume_stats` | `COUNT` agrupado por `itilcategories_id` / `priority` / `urgency` / `status` | + +## Constantes de actor (type) — `glpi_tickets_users` e `glpi_groups_tickets` + +`1` = requerente · `2` = atribuído (técnico/grupo) · `3` = observador. + +## Tabelas auxiliares + +- `glpi_itilsolutions` — `status` usa `CommonITILValidation`: 2=Waiting, 3=Accepted, **4=Refused**. + Múltiplas soluções / uma recusada ⇒ houve reabertura. +- `glpi_ticketsatisfactions` — `satisfaction` (bruto), `satisfaction_scaled_to_5` (float 0-5, + **usar este**), `date_begin` (enviada), `date_answered` (respondida). +- `glpi_itilcategories` — tem `name` e `completename` (caminho completo). + +## Labels (resolver IDs para humanos) + +- `\Ticket::getStatus($int)` · `\Ticket::getPriorityName($int)` · `\Ticket::getUrgencyName($int)`. + +## RBAC + +As tools de KPI agregam via `$DB` direto (como `glpi_ticket_bi_stats`), com filtros +opcionais (`entities_id`, `itilcategories_id`). NÃO aplicam `getEntitiesRestrictCriteria` +automaticamente — escopo fica a cargo dos filtros. Para BI gerencial é aceitável; se +precisar de isolamento estrito por entidade, evoluir para restrição de sessão. Ver KB-019. + +## Notas de validação (2026-06-22) + +Os 7 handlers foram testados contra o banco de dev via bootstrap CLI. Atenção: `$DB` +não é auto-inicializado pelo `inc/includes.php` no CLI do GLPI 11 — instanciar manual +após `include config/config_db.php`: `$DB = new DB();`.