docs/roadmap/TASK_003_EXPLAINABLE_KPI.md

Рекомендуемые параметры

Mode: xhigh
Reasoning: maximum
Task type: product feature / explainability / executive UX
Quality bar: production-ready
Breaking changes: forbidden
Architecture changes: minimal
Simplifications: forbidden
Security posture: no sensitive data exposure

Required checks:

cargo fmt --all --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all
cargo build --release

Если есть smoke scripts — выполнить их.

---

Задача

Добавить explainability-слой для Workforce KPI:

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

---

Цель

Сделать индекс активности понятным для руководителя, безопасника и администратора без ML/LLM.

Система должна показывать не только итоговый KPI, но и объяснение:

- из чего он сложился;
- какие приложения внесли вклад;
- какие факторы снизили индекс;
- какие данные отсутствуют;
- насколько KPI надежен.

---

Контекст

AWatch-rus уже имеет Workforce-first направление:

- Executive Dashboard
- Workforce Portal
- Security Portal
- Forensics Portal
- Role-based доступ
- UEBA Score v1
- department comparison
- owner comparison
- trend status

Нужно усилить доверие к KPI, не добавляя ML.

---

Что реализовать

1. API explain endpoint

Добавить endpoint:

GET /api/workforce/kpi/explain

Поддержать параметры, если они уже соответствуют текущей архитектуре:

- date
- department
- owner
- employee_id, только если в проекте уже есть безопасная модель доступа
- role

Если конкретный employee-level доступ не готов — не добавлять его насильно.

---

2. Explainability model

Добавить структуру ответа:

{
  "kpi_score": 82,
  "confidence": "high",
  "coverage": {
    "agent_coverage_percent": 95,
    "data_freshness": "fresh",
    "missing_sources": []
  },
  "factors": [
    {
      "name": "productive_activity",
      "label": "Полезная активность",
      "impact": "+32",
      "explanation": "Высокая доля активности в рабочих приложениях"
    },
    {
      "name": "idle_time",
      "label": "Простой",
      "impact": "-8",
      "explanation": "Есть периоды неактивности в рабочее время"
    }
  ],
  "top_applications": [
    {
      "name": "1C",
      "category": "business",
      "active_minutes": 180,
      "contribution": "positive"
    }
  ],
  "warnings": [],
  "recommendations": [
    "Проверить сотрудников с низким покрытием данных"
  ]
}

---

3. Factors

Минимальные факторы:

- productive_activity
- business_app_usage
- idle_time
- afterhours_activity
- remote_session_activity
- data_coverage
- missing_data
- trend_change

Важно:

- факторы должны быть rule-based;
- не использовать ML;
- не использовать LLM;
- объяснение должно быть детерминированным;
- при нехватке данных возвращать "confidence: low".

---

4. Confidence

Добавить уровень доверия к KPI:

high
medium
low

Пример логики:

- high: хорошее покрытие, свежие данные, нет критичных пропусков;
- medium: есть частичные пропуски;
- low: мало данных или слабое покрытие.

---

5. UI в портале

Добавить секцию в Workforce/Executive portal:

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

Показать:

- итоговый KPI;
- confidence;
- coverage;
- положительные факторы;
- отрицательные факторы;
- top applications;
- warnings;
- recommendations.

Не перегружать интерфейс.
Стиль должен соответствовать существующему HTML/HTMX portal.

---

6. Role-based visibility

Соблюдать текущую ролевую модель:

Executive:

- агрегированный KPI;
- подразделения;
- тренды;
- без лишних персональных деталей.

Manager:

- свое подразделение;
- объяснение KPI по подразделению.

Security:

- только security-relevant факторы;
- не смешивать с HR-оценкой.

Forensics:

- детализация только для расследовательского контекста.

Admin:

- техническое покрытие и состояние источников.

---

7. Markdown report

Обновить markdown report.

Добавить раздел:

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

Включить:

- KPI score;
- confidence;
- coverage;
- основные положительные факторы;
- основные отрицательные факторы;
- warnings;
- рекомендации.

---

8. Tests

Добавить тесты:

- explain endpoint returns valid JSON;
- confidence high при хорошем покрытии;
- confidence low при нехватке данных;
- factors deterministic;
- role filtering не раскрывает лишнее;
- markdown report содержит explain section;
- existing reports не сломаны.

---

9. Документация

Добавить или обновить:

docs/EXPLAINABLE_KPI_RU.md

Описать:

- что такое explainable KPI;
- какие факторы используются;
- как считается confidence;
- что не является HR-оценкой;
- что не является ML/LLM;
- ограничения Pilot v1.

---

Запрещено

Не делать:

- ML
- LLM
- predictive scoring
- HR disciplinary scoring
- скрытые формулы без объяснения
- персональные выводы без role gate
- React
- Tauri
- Dioxus
- новую БД
- переписывание portal

---

Критерии приемки

Задача выполнена, если:

- добавлен explain API;
- добавлена explain model;
- portal показывает объяснение KPI;
- markdown report обновлен;
- role visibility соблюдена;
- документация добавлена;
- тесты проходят;
- существующий Pilot v1 не сломан.

---

Финальный отчет должен содержать

1. Краткое описание изменений.
2. Список измененных файлов.
3. API endpoint.
4. Описание модели explainability.
5. Добавленные UI-блоки.
6. Добавленные тесты.
7. Результаты проверок.
8. Известные ограничения.