feat(portal): harden readiness and explain workforce KPI

2026-06-07 14:12:32 +03:00
parent 7df665a457
commit 07dfb95b6b
9 changed files with 2458 additions and 47 deletions
@@ -0,0 +1,111 @@
+# 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.