docs(KB-035): modelo de dados dos KPIs de Service Desk no GLPI 11

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 <noreply@anthropic.com>

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"
     }
   ]
 }

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)

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();`.