# Explainable Workforce KPI

Explainable Workforce KPI отвечает на вопрос: почему получился такой индекс
активности. Слой предназначен для руководителя, ИБ и администратора, но не
является HR-оценкой сотрудника и не использует ML/LLM.

## API

Endpoint:

```http
GET /api/workforce/kpi/explain
```

Поддерживаемые параметры:

- `date`;
- `department`;
- `owner`;
- `role`.

`employee_id` намеренно не добавлен: отдельная безопасная модель доступа к
персональному explainability-контракту в Pilot v1 не утверждена.

## Модель ответа

Ответ содержит:

- `kpi_score`: итоговый индекс 0-100;
- `confidence`: `high`, `medium` или `low`;
- `coverage`: покрытие агента, свежесть данных, отсутствующие источники;
- `factors`: детерминированные факторы с вкладом и объяснением;
- `top_applications`: агрегированные приложения, влияющие на индекс;
- `warnings`: предупреждения о качестве KPI;
- `recommendations`: действия для проверки или улучшения данных.

## Факторы

Минимальный набор факторов:

| Factor | Смысл |
| --- | --- |
| `productive_activity` | Доля активности относительно планового рабочего времени |
| `business_app_usage` | Наличие рабочих приложений и правил весов |
| `idle_time` | Простой в рабочее время |
| `afterhours_activity` | Активность вне рабочего окна |
| `remote_session_activity` | Подтверждение активности через удаленные сессии |
| `data_coverage` | Полнота агентских данных |
| `missing_data` | Пропущенные источники |
| `trend_change` | Наличие дневной/недельной/месячной истории |

Факторы rule-based, порядок стабильный, объяснения детерминированные.

## Confidence

`high`:

- хорошее покрытие;
- свежие данные;
- нет критичных пропусков.

`medium`:

- есть частичные пропуски;
- свежесть или покрытие требуют проверки.

`low`:

- нет worktime-данных;
- мало данных;
- слабое покрытие;
- источник отсутствует или недоступен.

## Роли

| Роль | Видимость |
| --- | --- |
| `executive` | Агрегированный KPI, без персональных деталей |
| `manager` | Workforce KPI по доступному управленческому срезу |
| `security` | Только факторы, релевантные ИБ и надежности данных |
| `forensics` | Контекст расследования: временные отклонения и пропуски данных |
| `admin` | Техническое покрытие и состояние источников |

Security и Forensics не получают Workforce Dashboard через `/api/reports` по
умолчанию. Для explainability используется отдельный endpoint с серверной
фильтрацией.

## UI и Markdown

Портал показывает блок:

```text
Почему такой индекс активности?
```

В Markdown-отчет добавлен раздел:

```markdown
## Объяснение индекса активности
```

Раздел содержит KPI score, confidence, coverage, факторы, warnings и
рекомендации.

## Ограничения Pilot v1

- Это не ML и не LLM.
- Это не predictive scoring.
- Это не дисциплинарная HR-оценка.
- Персональные выводы не формируются.
- Качество KPI зависит от свежести ActivityWatch/worktime/agent data.