623 lines
21 KiB
Python
623 lines
21 KiB
Python
"""Admin analytics: aggregate trainee results (supports date-range filter)."""
|
|
from __future__ import annotations
|
|
|
|
import datetime
|
|
import io
|
|
import math
|
|
from typing import Callable, Iterator, cast
|
|
from flask import Blueprint, g, jsonify, request
|
|
|
|
from ..auth.users import AuthError, normalize_identifier
|
|
from ..config import Config
|
|
from ..storage.store import StoreError
|
|
from .helpers import ApiError, current_user, is_valid_tenant_id, require_auth, require_roles
|
|
|
|
analytics_bp = Blueprint("analytics", __name__)
|
|
|
|
|
|
def _stores():
|
|
from flask import current_app
|
|
|
|
return {
|
|
"sessions": current_app.extensions["session_store"],
|
|
"groups": current_app.extensions["group_store"],
|
|
"users": current_app.extensions["user_store"],
|
|
}
|
|
|
|
|
|
def _log_audit(action: str, subject: str, *, detail: dict | None = None) -> None:
|
|
import json
|
|
import time
|
|
|
|
from ..config import Config
|
|
from .helpers import current_user as _cu
|
|
|
|
actor = _cu()
|
|
entry = {
|
|
"ts": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
|
|
"actor": (actor or {}).get("username") or (actor or {}).get("id"),
|
|
"action": action,
|
|
"subject": subject,
|
|
"detail": detail or {},
|
|
}
|
|
try:
|
|
log_dir = Config.DATA_DIR / "audit"
|
|
log_dir.mkdir(parents=True, exist_ok=True)
|
|
with open(log_dir / "audit.jsonl", "a", encoding="utf-8") as fh:
|
|
fh.write(json.dumps(entry, ensure_ascii=False) + "\n")
|
|
except Exception:
|
|
pass
|
|
|
|
|
|
def _csv_cell(value: object, *, max_chars: int | None = None) -> str:
|
|
"""Keep exported cells from being interpreted as spreadsheet formulas."""
|
|
text = "" if value is None else str(value)
|
|
if max_chars is not None:
|
|
text = text[:max_chars]
|
|
probe = text
|
|
while probe and (probe[0].isspace() or ord(probe[0]) < 32 or probe[0] == "\ufeff"):
|
|
probe = probe[1:]
|
|
if probe.startswith(("=", "+", "-", "@")):
|
|
return "'" + text
|
|
return text
|
|
|
|
|
|
def _debrief_score(session: dict, default: int | float = 0) -> int | float:
|
|
raw_debrief = session.get("debrief")
|
|
if not isinstance(raw_debrief, dict):
|
|
return default
|
|
score = raw_debrief.get("score", default)
|
|
if isinstance(score, bool) or not isinstance(score, (int, float)):
|
|
return default
|
|
try:
|
|
if not math.isfinite(score):
|
|
return default
|
|
return max(0, min(100, score))
|
|
except (OverflowError, TypeError, ValueError):
|
|
return default
|
|
|
|
|
|
def _is_finished_outcome(session: dict) -> bool:
|
|
return (
|
|
isinstance(session, dict)
|
|
and session.get("status") == "finished"
|
|
and session.get("outcome") in {"won", "lost"}
|
|
)
|
|
|
|
|
|
def _is_safe_export_identity(value: object) -> bool:
|
|
if not isinstance(value, str):
|
|
return False
|
|
try:
|
|
return normalize_identifier(value) == value
|
|
except AuthError:
|
|
return False
|
|
|
|
|
|
def _is_safe_export_token_id(value: object) -> bool:
|
|
if not isinstance(value, str):
|
|
return False
|
|
try:
|
|
normalize_identifier(value)
|
|
return True
|
|
except AuthError:
|
|
return False
|
|
|
|
|
|
# Short-lived signed link for CSV export (HMAC-SHA256, expiring). Not the long-lived JWT.
|
|
import hmac
|
|
import hashlib
|
|
import secrets
|
|
import time as _t
|
|
|
|
_EXPORT_TTL = 300 # 5 minutes
|
|
|
|
|
|
def _sign_export_token(actor: dict) -> str:
|
|
from ..config import Config
|
|
|
|
user_id = actor.get("id") or actor.get("username") or ""
|
|
org_id = actor.get("org_id") or ""
|
|
role = actor.get("role") or ""
|
|
if (
|
|
not _is_safe_export_identity(user_id)
|
|
or role not in Config.ROLES
|
|
or (role != "super_admin" and not is_valid_tenant_id(org_id))
|
|
or (role == "super_admin" and org_id and not is_valid_tenant_id(org_id))
|
|
):
|
|
raise ApiError("invalid export authorization", 403)
|
|
expires_at = int(_t.time()) + _EXPORT_TTL
|
|
jti = secrets.token_urlsafe(18)
|
|
payload = f"{user_id}:{org_id}:{role}:{expires_at}:{jti}"
|
|
_export_token_store().create(
|
|
{
|
|
"id": jti,
|
|
"user_id": user_id,
|
|
"org_id": org_id,
|
|
"role": role,
|
|
"expires_at": expires_at,
|
|
"used": False,
|
|
},
|
|
key=jti,
|
|
)
|
|
sig = hmac.new(Config.SECRET_KEY.encode(), payload.encode(), hashlib.sha256).hexdigest()
|
|
return "{}.{}".format(sig, payload)
|
|
|
|
|
|
def _export_token_store():
|
|
from ..config import Config
|
|
from ..storage.store import JsonStore
|
|
|
|
return JsonStore(Config.DATA_DIR / "export_tokens")
|
|
|
|
|
|
def _verify_export_token(token: str) -> dict | None:
|
|
from ..config import Config
|
|
|
|
try:
|
|
sig, payload = token.split(".", 1)
|
|
except (ValueError, AttributeError):
|
|
return None
|
|
expected = hmac.new(Config.SECRET_KEY.encode(), payload.encode(), hashlib.sha256).hexdigest()
|
|
if not hmac.compare_digest(sig, expected):
|
|
return None
|
|
parts = payload.split(":")
|
|
if len(parts) != 5:
|
|
return None
|
|
user_id, org_id, role, exp_s, jti = parts
|
|
if (
|
|
not _is_safe_export_identity(user_id)
|
|
or not _is_safe_export_token_id(jti)
|
|
or role not in Config.ROLES
|
|
or (role != "super_admin" and not is_valid_tenant_id(org_id))
|
|
or (role == "super_admin" and org_id and not is_valid_tenant_id(org_id))
|
|
):
|
|
return None
|
|
try:
|
|
expires_at = int(exp_s)
|
|
if expires_at < _t.time():
|
|
return None # expired
|
|
except ValueError:
|
|
return None
|
|
from ..storage.store import StoreError
|
|
|
|
try:
|
|
record = _export_token_store().get_or_none(jti)
|
|
except (OSError, StoreError, TypeError, UnicodeError, ValueError):
|
|
return None
|
|
if (
|
|
record is None
|
|
or not isinstance(record, dict)
|
|
or record.get("used") is not False
|
|
or record.get("user_id") != user_id
|
|
or record.get("org_id") != org_id
|
|
or record.get("role") != role
|
|
or record.get("expires_at") != expires_at
|
|
):
|
|
return None
|
|
return {
|
|
"org_id": org_id or None,
|
|
"user_id": user_id or None,
|
|
"role": role,
|
|
"active": True,
|
|
"jti": jti,
|
|
"expires_at": expires_at,
|
|
}
|
|
|
|
|
|
def _consume_export_token(token_actor: dict) -> bool:
|
|
"""Atomically consume a previously authorized signed export token."""
|
|
if not isinstance(token_actor, dict):
|
|
return False
|
|
jti = token_actor.get("jti")
|
|
expires_at = token_actor.get("expires_at")
|
|
if not isinstance(jti, str) or not isinstance(expires_at, int):
|
|
return False
|
|
try:
|
|
consumed = _export_token_store().update_if(
|
|
jti,
|
|
lambda row: (
|
|
row.get("used") is False
|
|
and row.get("user_id") == token_actor.get("user_id")
|
|
and row.get("org_id") == (token_actor.get("org_id") or "")
|
|
and row.get("role") == token_actor.get("role")
|
|
and row.get("expires_at") == expires_at
|
|
and expires_at >= int(_t.time())
|
|
),
|
|
used=True,
|
|
used_at=int(_t.time()),
|
|
)
|
|
except (OSError, StoreError, TypeError, UnicodeError, ValueError, AttributeError):
|
|
return False
|
|
return consumed is not None
|
|
|
|
|
|
def _authenticated_export_actor():
|
|
"""Reuse the normal Bearer auth/role guards for the non-signed path."""
|
|
return current_user()
|
|
|
|
|
|
_authenticated_export_actor = require_auth(
|
|
require_roles("admin")(_authenticated_export_actor)
|
|
)
|
|
|
|
|
|
def _signed_export_actor(token: str) -> tuple[dict, dict]:
|
|
token_actor = _verify_export_token(token)
|
|
if token_actor is None:
|
|
raise ApiError("invalid or expired export link", 403)
|
|
|
|
from ..storage.store import StoreError
|
|
|
|
stores = _stores()
|
|
token_user_id = token_actor.get("user_id")
|
|
token_org_id = token_actor.get("org_id")
|
|
global_super_admin = token_actor.get("role") == "super_admin" and token_org_id is None
|
|
if not _is_safe_export_identity(token_user_id) or (
|
|
not global_super_admin and not is_valid_tenant_id(token_org_id)
|
|
):
|
|
raise ApiError("export link authorization is stale", 403)
|
|
try:
|
|
actor = stores["users"].get_user_or_none(token_user_id)
|
|
org = None if global_super_admin else stores["users"].get_org_or_none(token_org_id)
|
|
except (AuthError, OSError, StoreError, TypeError, UnicodeError, ValueError):
|
|
raise ApiError("export link authorization is stale", 403)
|
|
if actor is not None and not isinstance(actor, dict):
|
|
raise ApiError("export link authorization is stale", 403)
|
|
if org is not None and not isinstance(org, dict):
|
|
raise ApiError("export link authorization is stale", 403)
|
|
actor_id = actor.get("id") if isinstance(actor, dict) else None
|
|
if (
|
|
not actor
|
|
or actor.get("active") is not True
|
|
or (
|
|
not global_super_admin
|
|
and not is_valid_tenant_id(actor.get("org_id"))
|
|
)
|
|
or (
|
|
global_super_admin
|
|
and actor.get("org_id") not in (None, "")
|
|
and not is_valid_tenant_id(actor.get("org_id"))
|
|
)
|
|
or token_actor.get("user_id") != actor_id
|
|
or token_actor.get("role") != actor.get("role")
|
|
):
|
|
raise ApiError("export link authorization is stale", 403)
|
|
if global_super_admin:
|
|
if actor.get("role") != "super_admin":
|
|
raise ApiError("export link authorization is stale", 403)
|
|
elif (
|
|
not org
|
|
or org.get("active") is not True
|
|
or token_actor.get("org_id") != actor.get("org_id")
|
|
):
|
|
raise ApiError("export link authorization is stale", 403)
|
|
if actor.get("role") not in {"admin", "super_admin"}:
|
|
raise ApiError("permission denied", 403)
|
|
|
|
if request.headers.get("Authorization"):
|
|
bearer_actor = _authenticated_export_actor()
|
|
if any(
|
|
bearer_actor.get(key) != actor.get(key)
|
|
for key in ("id", "org_id", "role")
|
|
):
|
|
raise ApiError("export link authorization is stale", 403)
|
|
g.user = actor
|
|
g.org_id = actor.get("org_id")
|
|
return actor, token_actor
|
|
|
|
|
|
@analytics_bp.get("/export/token")
|
|
@require_auth
|
|
@require_roles("admin")
|
|
def export_token():
|
|
"""Issue a short-lived signed download link for the CSV export."""
|
|
actor = current_user()
|
|
token = _sign_export_token(actor)
|
|
return jsonify({"token": token, "expires_in": _EXPORT_TTL, "url": f"/api/analytics/export?token={token}"})
|
|
|
|
|
|
def _parse_date_iso(value: str | None, *, end: bool = False) -> str | None:
|
|
"""Parse a YYYY-MM-DD into an ISO datetime bound for created_at filtering."""
|
|
if not value:
|
|
return None
|
|
try:
|
|
d = datetime.date.fromisoformat(value.strip())
|
|
except ValueError:
|
|
return None
|
|
if end:
|
|
# end-of-day bound (inclusive)
|
|
return datetime.datetime.combine(d, datetime.time(23, 59, 59, 999999), tzinfo=datetime.timezone.utc).isoformat()
|
|
return datetime.datetime.combine(d, datetime.time(0, 0, 0), tzinfo=datetime.timezone.utc).isoformat()
|
|
|
|
|
|
@analytics_bp.get("")
|
|
@require_auth
|
|
@require_roles("admin")
|
|
def analytics():
|
|
s = _stores()
|
|
actor = current_user()
|
|
|
|
# Date filter (optional) from ?from=YYYY-MM-DD&to=YYYY-MM-DD on created_at
|
|
date_from = _parse_date_iso(request.args.get("from"))
|
|
date_to = _parse_date_iso(request.args.get("to"), end=True)
|
|
|
|
def _in_window(sess) -> bool:
|
|
created = (sess.get("created_at") or "")[:19]
|
|
if not created:
|
|
return True
|
|
if date_from and created < date_from[:19]:
|
|
return False
|
|
if date_to and created > date_to[:19]:
|
|
return False
|
|
return True
|
|
|
|
if actor.get("role") == "super_admin":
|
|
users = [
|
|
user
|
|
for user in s["users"].list_users()
|
|
if isinstance(user, dict)
|
|
]
|
|
trainee_users = [user for user in users if user.get("role") == "user"]
|
|
trainee_count = len(trainee_users)
|
|
user_ids = {
|
|
user["id"] for user in trainee_users if isinstance(user.get("id"), str)
|
|
}
|
|
sessions = [
|
|
x for x in s["sessions"].sessions.all()
|
|
if isinstance(x, dict)
|
|
and x.get("user_id") in user_ids
|
|
and (x.get("mode") or "trainee") == "trainee"
|
|
and _is_finished_outcome(x)
|
|
and _in_window(x)
|
|
]
|
|
else:
|
|
org_id = actor.get("org_id")
|
|
if not is_valid_tenant_id(org_id):
|
|
raise ApiError("permission denied", 403)
|
|
users = [
|
|
user
|
|
for user in s["users"].list_users(org_id=org_id)
|
|
if isinstance(user, dict)
|
|
]
|
|
trainee_users = [user for user in users if user.get("role") == "user"]
|
|
trainee_count = len(trainee_users)
|
|
user_ids = {
|
|
user["id"] for user in trainee_users if isinstance(user.get("id"), str)
|
|
}
|
|
group_ids = {
|
|
group.get("id")
|
|
for group in s["groups"].groups.all()
|
|
if isinstance(group, dict)
|
|
and isinstance(group.get("id"), str)
|
|
and group.get("org_id") == org_id
|
|
and "owner_user_id" not in group
|
|
}
|
|
sessions = [
|
|
x for x in s["sessions"].sessions.all()
|
|
if isinstance(x, dict)
|
|
and x.get("user_id") in user_ids
|
|
and x.get("org_id") == org_id
|
|
and x.get("group_id") in group_ids
|
|
and (x.get("mode") or "trainee") == "trainee"
|
|
and _is_finished_outcome(x)
|
|
and _in_window(x)
|
|
]
|
|
|
|
overall = {
|
|
"total_sessions": len(sessions),
|
|
"wins": sum(1 for x in sessions if x.get("outcome") == "won"),
|
|
"losses": sum(1 for x in sessions if x.get("outcome") == "lost"),
|
|
}
|
|
overall["close_rate"] = round(
|
|
overall["wins"] / overall["total_sessions"] * 100, 1
|
|
) if overall["total_sessions"] else 0
|
|
|
|
# average score
|
|
scores = [_debrief_score(x) for x in sessions]
|
|
overall["avg_score"] = round(sum(scores) / len(scores), 1) if scores else 0
|
|
|
|
# hardest personas = personas with most losses (lowest avg score)
|
|
by_persona: dict = {}
|
|
for x in sessions:
|
|
key = (x.get("group_id"), x.get("persona_id"), x.get("persona_name", "?"))
|
|
if key not in by_persona:
|
|
by_persona[key] = {"plays": 0, "losses": 0, "wins": 0, "scores": []}
|
|
rec = by_persona[key]
|
|
rec["plays"] += 1
|
|
rec["scores"].append(_debrief_score(x))
|
|
if x.get("outcome") == "won":
|
|
rec["wins"] += 1
|
|
elif x.get("outcome") == "lost":
|
|
rec["losses"] += 1
|
|
hardest = sorted(
|
|
(
|
|
{
|
|
"persona_name": k[2],
|
|
"plays": v["plays"],
|
|
"wins": v["wins"],
|
|
"losses": v["losses"],
|
|
"avg_score": round(sum(v["scores"]) / len(v["scores"]), 1) if v["scores"] else 0,
|
|
}
|
|
for k, v in by_persona.items()
|
|
),
|
|
key=lambda r: (-r["losses"], r["avg_score"]),
|
|
)[:10]
|
|
|
|
return jsonify({
|
|
"overall": overall,
|
|
"trainee_count": trainee_count,
|
|
"hardest_personas": hardest,
|
|
})
|
|
|
|
|
|
@require_auth
|
|
@require_roles("admin")
|
|
def _export_with_bearer():
|
|
return _export_csv_for_actor(current_user())
|
|
|
|
|
|
@analytics_bp.get("/export")
|
|
def export_csv():
|
|
"""Export via a one-time signed link or the normal Bearer JWT."""
|
|
token = request.args.get("token")
|
|
if token:
|
|
actor, token_actor = _signed_export_actor(token)
|
|
response = _export_csv_for_actor(actor, audit=False)
|
|
if not _consume_export_token(token_actor):
|
|
raise ApiError("invalid or expired export link", 403)
|
|
_log_audit(
|
|
"analytics.export",
|
|
actor.get("org_id") or "?",
|
|
detail={"signed": True},
|
|
)
|
|
return response
|
|
return _export_with_bearer()
|
|
|
|
|
|
def _export_csv_for_actor(actor: dict, *, audit: bool = True):
|
|
"""Export per-trainee finished session results as CSV (for HR/offline review)."""
|
|
import csv
|
|
from flask import Response, current_app
|
|
|
|
# Tenant: an admin exports only their own org's sessions; super_admin sees all.
|
|
is_super_admin = actor.get("role") == "super_admin"
|
|
export_org = None if is_super_admin else actor.get("org_id")
|
|
if not is_super_admin and not is_valid_tenant_id(export_org):
|
|
raise ApiError("permission denied", 403)
|
|
s = _stores()
|
|
users = {}
|
|
try:
|
|
user_store = current_app.extensions.get("user_store")
|
|
if user_store and hasattr(user_store, "list_users"):
|
|
for rec in user_store.list_users(org_id=export_org):
|
|
if not isinstance(rec, dict):
|
|
continue
|
|
if rec.get("role") != "user":
|
|
continue
|
|
user_id = rec.get("id") or rec.get("username")
|
|
if isinstance(user_id, str):
|
|
users[user_id] = rec.get("username") or rec.get("id")
|
|
except (OSError, StoreError, TypeError, ValueError) as exc:
|
|
raise ApiError("analytics unavailable", 503) from exc
|
|
|
|
max_rows = Config.ANALYTICS_EXPORT_MAX_ROWS
|
|
max_bytes = Config.ANALYTICS_EXPORT_MAX_BYTES
|
|
max_scan_records = Config.ANALYTICS_EXPORT_MAX_SCAN_RECORDS
|
|
if (
|
|
isinstance(max_rows, bool)
|
|
or not isinstance(max_rows, int)
|
|
or max_rows <= 0
|
|
or isinstance(max_bytes, bool)
|
|
or not isinstance(max_bytes, int)
|
|
or max_bytes <= 0
|
|
or isinstance(max_scan_records, bool)
|
|
or not isinstance(max_scan_records, int)
|
|
or max_scan_records <= 0
|
|
):
|
|
raise ApiError("analytics export is unavailable", 503)
|
|
sessions = []
|
|
try:
|
|
grp_store = s["groups"]
|
|
sess_store = s["sessions"]
|
|
group_collection = getattr(grp_store, "groups", grp_store)
|
|
session_collection = getattr(sess_store, "sessions", sess_store)
|
|
raw_group_iter = getattr(group_collection, "iter_all", None)
|
|
raw_session_iter = getattr(session_collection, "iter_all", None)
|
|
if not callable(raw_group_iter) or not callable(raw_session_iter):
|
|
raise StoreError("analytics stores lack bounded iteration")
|
|
group_iter = cast(Callable[[], Iterator[dict]], raw_group_iter)
|
|
session_iter = cast(Callable[[], Iterator[dict]], raw_session_iter)
|
|
|
|
scanned_records = 0
|
|
group_ids: set[str] = set()
|
|
for group in group_iter():
|
|
scanned_records += 1
|
|
if scanned_records > max_scan_records:
|
|
raise ApiError("analytics export scan limit exceeded", 413)
|
|
if (
|
|
isinstance(group, dict)
|
|
and isinstance(group.get("id"), str)
|
|
and (export_org is None or group.get("org_id") == export_org)
|
|
and (export_org is None or "owner_user_id" not in group)
|
|
):
|
|
group_ids.add(group["id"])
|
|
|
|
for row in session_iter():
|
|
scanned_records += 1
|
|
if scanned_records > max_scan_records:
|
|
raise ApiError("analytics export scan limit exceeded", 413)
|
|
if not (
|
|
isinstance(row, dict)
|
|
and row.get("group_id") in group_ids
|
|
and (row.get("mode") or "trainee") == "trainee"
|
|
and row.get("status") == "finished"
|
|
and row.get("outcome") in {"won", "lost"}
|
|
and row.get("user_id") in users
|
|
and (
|
|
export_org is None
|
|
or row.get("org_id") == export_org
|
|
)
|
|
):
|
|
continue
|
|
sessions.append(row)
|
|
if len(sessions) > max_rows:
|
|
raise ApiError("analytics export has too many rows", 413)
|
|
except (OSError, StoreError, TypeError, ValueError) as exc:
|
|
raise ApiError("analytics unavailable", 503) from exc
|
|
|
|
if audit:
|
|
_log_audit("analytics.export", actor.get("org_id") or "?", detail={"rows": len(sessions)})
|
|
|
|
class _BoundedStringIO(io.StringIO):
|
|
def __init__(self, byte_limit: int):
|
|
super().__init__()
|
|
self._byte_limit = byte_limit
|
|
self._bytes_written = 0
|
|
|
|
def write(self, value: str) -> int:
|
|
try:
|
|
byte_count = len(value.encode("utf-8"))
|
|
except UnicodeError as exc:
|
|
raise ApiError("analytics export contains invalid text", 400) from exc
|
|
if self._bytes_written + byte_count > self._byte_limit:
|
|
raise ApiError("analytics export is too large", 413)
|
|
self._bytes_written += byte_count
|
|
return super().write(value)
|
|
|
|
buf = _BoundedStringIO(max_bytes)
|
|
w = csv.writer(buf)
|
|
w.writerow(["username", "persona", "scenario", "outcome", "score", "created_at"])
|
|
for sess in sessions:
|
|
w.writerow([
|
|
_csv_cell(
|
|
users.get(sess.get("user_id"), sess.get("user_id", "")),
|
|
max_chars=Config.ANALYTICS_EXPORT_MAX_CELL_CHARS,
|
|
),
|
|
_csv_cell(
|
|
sess.get("persona_name", ""),
|
|
max_chars=Config.ANALYTICS_EXPORT_MAX_CELL_CHARS,
|
|
),
|
|
_csv_cell(
|
|
sess.get("scenario", ""),
|
|
max_chars=Config.ANALYTICS_EXPORT_MAX_CELL_CHARS,
|
|
),
|
|
_csv_cell(
|
|
sess.get("outcome", ""),
|
|
max_chars=Config.ANALYTICS_EXPORT_MAX_CELL_CHARS,
|
|
),
|
|
_csv_cell(
|
|
_debrief_score(sess),
|
|
max_chars=Config.ANALYTICS_EXPORT_MAX_CELL_CHARS,
|
|
),
|
|
_csv_cell(
|
|
sess.get("created_at", ""),
|
|
max_chars=Config.ANALYTICS_EXPORT_MAX_CELL_CHARS,
|
|
),
|
|
])
|
|
return Response(
|
|
buf.getvalue(),
|
|
mimetype="text/csv",
|
|
headers={"Content-Disposition": "attachment; filename=sales-trainer-results.csv"},
|
|
)
|