Files
sales-trainer/backend/app/api/analytics_routes.py
T

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"},
)