Harden DetMir runtime hot paths

2026-07-01 06:06:01 +03:00
parent fe87c85a31
commit c017cb08a9
15 changed files with 1923 additions and 86 deletions
@@ -0,0 +1,239 @@
+# Workforce Operations Model
+
+Статус: implemented in Worktime API and DetMir portal.
+
+Модель отвечает на главный управленческий вопрос AWatch-rus Workforce:
+рабочая активность сотрудников, загрузка, простои, перегруз и дисциплина
+рабочего процесса. Это rule-based слой операционного контроля. Он не является
+HR-оценкой, не использует ML/LLM и не выполняет автоматических санкций.
+
+## Где смотреть
+
+Основные точки:
+
+- Worktime API:
+  `GET /reports/worktime/management?format=json`;
+- Worktime HTML:
+  `GET /reports/worktime/management?format=html`;
+- DetMir portal:
+  `/api/reports`, блок `workforce_operations`;
+- UI портала:
+  роли `Руководитель` и вкладка `Отчеты`, блок `Операционная загрузка`.
+
+## Источники
+
+Модель использует только подтвержденные рабочие источники:
+
+- ActivityWatch worktime rows;
+- bucket рабочих сессий RDP;
+- интервалы активности в рабочем окне;
+- configured owner/department aliases;
+- freshness/coverage metadata, которые уже возвращает Worktime API.
+
+Отсутствие данных не считается простоем. При пропусках источников строка
+получает `data_confidence=low` и guardrail
+`low_confidence_not_for_discipline`.
+
+## Runtime-настройки
+
+Основной файл политики:
+
+- пример: `configs/worktime-interpretation-policy.example.json`;
+- runtime: `/etc/activitywatch/worktime-interpretation-policy.json`;
+- env path: `AW_WORKTIME_MANAGER_INTERPRETATION_POLICY`.
+
+Поля policy:
+
+| Поле | Смысл | Рекомендуемое значение |
+| --- | --- | --- |
+| `underload_threshold` | порог недогруза от рабочего окна | `0.35..0.45` |
+| `overload_threshold` | порог перегруза от рабочего окна | `1.10..1.25` |
+| `drop_threshold_pct` | порог просадки тренда | `10..25` |
+| `night_work_after` | начало вечернего/ночного отклонения | `20:00` |
+| `weekend_work` | учитывать выходные отклонения | `true` |
+| `min_trend_points` | минимум daily points для тренда | `3..7` |
+| `off_hours_threshold_seconds` | минимум внерабочей активности для флага | `1800` |
+
+`underload_threshold` и `overload_threshold` можно задавать дробью или
+процентом: `0.45` равно `45`, `1.15` равно `115`.
+Для перегруза effective threshold fail-closed зажат в диапазон `100..300`, чтобы
+значение ниже 100% не создавало ложный статус перегруза.
+
+Env fallback:
+
+- `AW_WORKTIME_MANAGER_TARGET_COVERAGE_PCT`;
+- `AW_WORKTIME_MANAGER_LOW_COVERAGE_PCT`;
+- `AW_WORKTIME_MANAGER_OVERLOAD_COVERAGE_PCT`;
+- `AW_WORKTIME_MANAGER_TREND_MIN_POINTS`;
+- `AW_WORKTIME_MANAGER_TREND_DELTA_PCT`;
+- `AW_WORKTIME_MANAGER_OFF_HOURS_THRESHOLD_SECONDS`;
+- `AW_WORKTIME_MANAGER_NIGHT_WORK_AFTER`;
+- `AW_WORKTIME_MANAGER_WEEKEND_WORK_ENABLED`.
+
+Веса приложений остаются отдельной политикой:
+
+- пример: `configs/detmir-workforce-policy.example.json`;
+- runtime: `/etc/detmir-portal-workforce-policy.json`.
+
+Она влияет на explainable KPI и weighted activity, но не подменяет
+операционные статусы загрузки/простоя.
+
+## API contract
+
+`/reports/worktime/management?format=json` содержит:
+
+```json
+{
+  "workday": {
+    "target_coverage_pct": 75,
+    "low_coverage_pct": 35,
+    "overload_coverage_pct": 115
+  },
+  "workforce_operations": {
+    "status": "ATTENTION",
+    "summary": {},
+    "rows": [],
+    "model": {
+      "type": "rule_based",
+      "ml": false,
+      "llm": false,
+      "version": "workforce-operations-v1"
+    }
+  }
+}
+```
+
+Каждая строка сотрудника содержит:
+
+- `workday_active_seconds`, `workday_active_hhmm`;
+- `workday_idle_seconds`, `workday_idle_hhmm`;
+- `coverage_pct`;
+- `load_status`;
+- `idle_status`;
+- `discipline_status`;
+- `data_confidence`;
+- `recommended_action`.
+
+Полный roster в `rows[]` дополнительно содержит `operations`,
+`operations.evidence`, `operations.guardrail` и
+`operations_recommended_action`.
+
+## Статусы загрузки
+
+| Status | Значение | Действие |
+| --- | --- | --- |
+| `insufficient_data` | рабочее окно еще не началось или равно нулю | не делать вывод |
+| `no_data` | нет сессий или worktime samples | проверить источники |
+| `no_activity` | сессия/данные есть, активности в окне нет | проверить присутствие и задачи |
+| `underloaded` | ниже low threshold | проверить загрузку и доступ к процессам |
+| `below_target` | ниже target threshold | уточнить причину отклонения |
+| `normal` | в рабочем диапазоне | наблюдать |
+| `overloaded` | выше overload threshold | проверить переработку и риск аврала |
+
+## Статусы простоя
+
+| Status | Значение |
+| --- | --- |
+| `not_applicable` | нет рабочего окна |
+| `unknown` | нет достаточных источников |
+| `full_workday_idle_or_absent` | активность в рабочем окне отсутствует |
+| `idle_detected` | простой выше порога |
+| `no_significant_idle` | существенный простой не найден |
+
+## Дисциплина процесса
+
+`discipline_status` показывает отклонение от рабочего процесса, а не
+автоматическое нарушение:
+
+- `ok`;
+- `off_hours`;
+- `late_start`;
+- `early_finish`;
+- `multiple_flags`.
+
+Для текущего дня `early_finish` не выставляется до завершения рабочего окна.
+
+## Достоверность
+
+`data_confidence`:
+
+- `high`: есть session samples, worktime samples и active samples;
+- `medium`: данных мало или нет active samples;
+- `low`: нет сессий/worktime samples или рабочее окно невалидно.
+
+Правило: low confidence строки сначала проверяются как проблема источников.
+Их нельзя использовать как персональный дисциплинарный вывод.
+
+## Summary
+
+`workforce_operations.summary` содержит:
+
+- `users_count`;
+- `action_required_users`;
+- `load.unknown_or_no_data_users`;
+- `load.underloaded_users`;
+- `load.normal_users`;
+- `load.overloaded_users`;
+- `idle.idle_users`;
+- `discipline.review_users`;
+- `confidence.low_users`;
+- `confidence.medium_users`;
+- `confidence.high_users`;
+- `guardrail`.
+
+Summary status:
+
+- `LOW_CONFIDENCE`: нет строк или все строки low confidence;
+- `ATTENTION`: есть перегруз, простой или дисциплинарные флаги;
+- `WATCH`: есть недогруз, нет данных или low confidence;
+- `OK`: отклонений нет.
+
+## UI contract
+
+Портал показывает отдельный блок `Операционная загрузка`:
+
+- сводка: требуют разбора, недогруз, перегруз, простой, дисциплина, low
+  confidence;
+- таблица сотрудников: active/idle/coverage/load/idle/discipline/confidence;
+- рекомендуемое действие;
+- guardrail и версию rule-based модели.
+
+Это отдельный блок от `Почему такой индекс активности?`: explainable KPI
+отвечает на вопрос "почему такой процент", а Workforce Operations отвечает
+"кого и почему нужно разобрать".
+
+## Ограничения
+
+- Не утверждать автоматическую оценку эффективности сотрудника.
+- Не считать missing data простоем.
+- Не смешивать Security/Forensics claims с Workforce Operations.
+- Не заявлять ML/LLM detection.
+- Не выполнять автоматическое remediation/action.
+- Не использовать GitHub Actions или демо-данные как registry release evidence.
+
+## Проверка после изменения
+
+Минимальный локальный контур:
+
+```bash
+cd /mnt/usb_hdd2/Projects/ActivityWatch-Russian/adk-rust
+export CARGO_TARGET_DIR=/home/igor/.cache/detmir-adk-rust-target
+cargo fmt --all --check
+cargo test -p worktime-api -p detmir-portal --locked
+cargo clippy -p worktime-api -p detmir-portal --all-targets --locked -- -D warnings
+```
+
+Минимальный live smoke:
+
+```bash
+curl -fsS 'http://10.10.10.13:5610/reports/worktime/management?format=json' \
+  | jq '.workforce_operations.summary'
+
+curl -fsS 'http://10.10.10.2:8720/api/reports?role=manager' \
+  | jq '{status: .workforce_operations.summary.status, rows: (.workforce_operations.rows | length)}'
+```
+
+Браузерный smoke: открыть `http://10.10.10.2:8720/`, выбрать представление
+менеджера и проверить блок `Операционная загрузка`. В рабочем состоянии должны
+быть видны summary-карточки, таблица сотрудников, `workforce-operations-v1` и
+guardrail про `low confidence`.