feat(analytics): tab "Quản lý thời lượng" theo dõi người dùng cho quản trị

Ghi log thô raw_events rồi suy ra 9 chỉ số (A1-A5, B1-B4) bằng ETL, không lưu
sẵn chỉ số. Lưu Postgres nếu có DATABASE_URL, không thì SQLite trong STORAGE_DIR
(giữ 90 ngày, tự dọn).

- backend: services/analytics (storage + etl + track), api/analytics
(POST /api/events + các endpoint quản trị), middleware reqctx đọc header
X-TNT-* để dòng log máy chạy gắn đúng task; JobManager tự phát
job_queued/started/done kèm latency_ms (đã trừ thời gian chờ hàng đợi).
- frontend: lib/track.js (đồng hồ người), nút 👍/👎 (ThumbsFeedback) cho B3,
dashboard SVG thuần trong tab Quản lý thời lượng; gắn điểm đo vào 8 tool.

Kèm sửa lỗi phát hiện khi test:
- khôi phục core.files.rel_path() + gom mọi đường dẫn phiên ở cut/dub/shuffle/
download về "/" (trước nối "\" của Windows làm hỏng URL).
- get_file trả 404 khi trỏ vào thư mục (thay vì 500).
- run_tests.py cô lập STORAGE_DIR sang temp (trước dọn nhầm phiên thật).
- cập nhật test_cut/test_dub theo API hiện hành + thêm test_analytics (14 test).
Toàn bộ 66/66 PASS.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

backend/app/api/analytics.py

@@ -0,0 +1,198 @@
+"""API theo dõi người dùng.
+
+Hai nhóm endpoint:
+    - POST /api/events                  — app gửi log lên (không cần token).
+    - GET  /api/analytics/admin/*       — quản trị đọc báo cáo (cần
+      VIDEO_ADMIN_TOKEN, dùng chung mật khẩu với tab "Quản lý người dùng").
+
+Vì app đăng nhập bằng tên (không có token phiên), endpoint nhận log KHÔNG xác
+thực được người gửi — đây là tool nội bộ nên chấp nhận, nhưng có chặn kích
+thước lô để không ai bơm được cả biển dữ liệu trong một lần gọi.
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+import time
+from datetime import datetime, timedelta, timezone
+
+from fastapi import APIRouter, HTTPException, Request
+from fastapi.responses import StreamingResponse
+
+from ..config import settings
+from ..services.analytics import etl
+from ..services.analytics import storage as store
+
+router = APIRouter(tags=["analytics"])
+
+# Trần số event một lần POST (frontend gửi lô ~20).
+MAX_BATCH = 200
+
+# Dọn log quá hạn nhiều nhất 1 lần/giờ, đi ké request có sẵn (khỏi cần cron).
+_last_purge = 0.0
+_PURGE_EVERY = 3600.0
+
+
+def _maybe_purge():
+    global _last_purge
+    now = time.time()
+    if now - _last_purge < _PURGE_EVERY:
+        return
+    _last_purge = now
+    try:
+        store.purge_old()
+    except Exception as ex:  # dọn dẹp lỗi thì kệ, không được làm hỏng request
+        print(f"[analytics] purge error: {ex}")
+
+
+def _check(token: str):
+    if not settings.VIDEO_ADMIN_TOKEN or token != settings.VIDEO_ADMIN_TOKEN:
+        raise HTTPException(403, "Not authorized")
+
+
+def _tz():
+    return timezone(timedelta(hours=settings.ANALYTICS_TZ_OFFSET))
+
+
+def _range(days: int, date_from: str, date_to: str) -> tuple[float, float]:
+    """Đổi bộ lọc ngày (theo múi giờ báo cáo) thành khoảng epoch [from, to)."""
+    tz = _tz()
+    if date_from or date_to:
+        try:
+            start = (datetime.strptime(date_from, "%Y-%m-%d").replace(tzinfo=tz).timestamp()
+                     if date_from else 0.0)
+            end = ((datetime.strptime(date_to, "%Y-%m-%d").replace(tzinfo=tz) + timedelta(days=1)).timestamp()
+                   if date_to else time.time() + 60)
+            return start, end
+        except ValueError:
+            raise HTTPException(400, "Ngày phải theo dạng YYYY-MM-DD")
+    days = max(1, min(int(days or 30), 365))
+    now = datetime.now(tz)
+    start = (now - timedelta(days=days - 1)).replace(hour=0, minute=0, second=0, microsecond=0)
+    return start.timestamp(), time.time() + 60
+
+
+# ── Nhận log ─────────────────────────────────────────────────────
+
+@router.post("/api/events")
+async def ingest(request: Request):
+    """Nhận một lô event. Chấp cả `{"events":[...]}` lẫn mảng trần.
+
+    `sendBeacon` lúc đóng tab gửi Content-Type lạ nên đọc body thủ công.
+    """
+    try:
+        body = await request.json()
+    except Exception:
+        return {"ok": False, "error": "Body không phải JSON", "saved": 0}
+
+    items = body.get("events") if isinstance(body, dict) else body
+    if not isinstance(items, list):
+        return {"ok": False, "error": "Thiếu mảng events", "saved": 0}
+    if len(items) > MAX_BATCH:
+        items = items[:MAX_BATCH]
+
+    now = time.time()
+    rows = [store.normalize(it, now) for it in items if isinstance(it, dict)]
+
+    # CHỈNH LỆCH ĐỒNG HỒ: dời cả lô theo đúng một hằng số sao cho event MỚI NHẤT
+    # trùng giờ máy chủ. Hiệu số giữa các dòng (thời gian mỗi bước) giữ nguyên,
+    # nhưng mốc tuyệt đối khớp với dòng log do backend ghi -> ghép chung một
+    # dòng thời gian được. Lô nào cũng mới gửi nên sai số chỉ còn độ trễ mạng.
+    if rows:
+        skew = now - max(r["event_ts"] for r in rows)
+        if abs(skew) > 1.0:
+            for r in rows:
+                r["event_ts"] += skew
+
+    saved = store.insert(rows)
+    _maybe_purge()
+    return {"ok": True, "saved": saved, "received": len(rows)}
+
+
+# ── Báo cáo cho quản trị ─────────────────────────────────────────
+
+@router.get("/api/analytics/admin/summary")
+def admin_summary(token: str = "", days: int = 30, date_from: str = "",
+                  date_to: str = "", feature: str = "", user_id: str = ""):
+    """Toàn bộ số liệu cho tab "Quản lý thời lượng"."""
+    _check(token)
+    start, end = _range(days, date_from, date_to)
+    events = store.query(start, end, user_id=user_id, feature=feature)
+    data = etl.summarize(events)
+    data["range"] = {"from_ts": start, "to_ts": end, "days": days,
+                     "tz_offset": settings.ANALYTICS_TZ_OFFSET}
+    data["storage"] = store.stats()
+    return {"ok": True, **data}
+
+
+@router.get("/api/analytics/admin/user")
+def admin_user_detail(token: str = "", user_id: str = "", days: int = 30,
+                      date_from: str = "", date_to: str = ""):
+    """Chi tiết một người: từng phiên -> từng task -> từng bước."""
+    _check(token)
+    if not user_id.strip():
+        raise HTTPException(400, "Thiếu user_id")
+    start, end = _range(days, date_from, date_to)
+    events = store.query(start, end, user_id=user_id)
+    return {"ok": True, **etl.user_detail(events, user_id.strip().lower())}
+
+
+@router.get("/api/analytics/admin/events")
+def admin_raw_events(token: str = "", days: int = 7, date_from: str = "",
+                     date_to: str = "", user_id: str = "", feature: str = "",
+                     task_id: str = "", limit: int = 500):
+    """Log thô — để soi đúng dòng khi số liệu trông lạ."""
+    _check(token)
+    start, end = _range(days, date_from, date_to)
+    rows = store.query(start, end, user_id=user_id, feature=feature,
+                       task_id=task_id, limit=max(1, min(int(limit or 500), 5000)),
+                       newest_first=True)
+    return {"ok": True, "events": rows, "count": len(rows)}
+
+
+@router.get("/api/analytics/admin/export.csv")
+def admin_export_csv(token: str = "", days: int = 30, date_from: str = "",
+                     date_to: str = "", user_id: str = "", feature: str = ""):
+    """Xuất log thô đúng 11 cột của `raw_events_schema_v2.xlsx`."""
+    _check(token)
+    start, end = _range(days, date_from, date_to)
+    rows = store.query(start, end, user_id=user_id, feature=feature)
+
+    buf = io.StringIO()
+    cols = ["event_id", "event_time", "user_id", "session_id", "task_id", "feature",
+            "step", "event_name", "event_value", "latency_ms", "properties_json"]
+    w = csv.writer(buf)
+    w.writerow(cols)
+    import json as _json
+    for r in rows:
+        w.writerow([
+            r.get("event_id", ""), r.get("event_time", ""), r.get("user_id", ""),
+            r.get("session_id", ""), r.get("task_id", ""), r.get("feature", ""),
+            r.get("step", ""), r.get("event_name", ""), r.get("event_value", ""),
+            "" if r.get("latency_ms") is None else r["latency_ms"],
+            _json.dumps(r.get("properties") or {}, ensure_ascii=False),
+        ])
+    buf.seek(0)
+    fname = f"raw_events_{datetime.now(_tz()).strftime('%Y%m%d')}.csv"
+    return StreamingResponse(
+        # BOM để Excel mở tiếng Việt không lỗi phông
+        iter(["" + buf.getvalue()]),
+        media_type="text/csv; charset=utf-8",
+        headers={"Content-Disposition": f'attachment; filename="{fname}"'},
+    )
+
+
+@router.get("/api/analytics/admin/storage")
+def admin_storage(token: str = ""):
+    _check(token)
+    return {"ok": True, **store.stats()}
+
+
+@router.post("/api/analytics/admin/purge")
+def admin_purge(body: dict):
+    """Dọn tay log cũ hơn `days` ngày."""
+    _check(body.get("token") or "")
+    days = body.get("days")
+    deleted = store.purge_old(int(days) if days else None)
+    return {"ok": True, "deleted": deleted}

backend/app/api/common.py

@@ -62,8 +62,12 @@ def list_inputs(sid: str):
 @router.get("/files/{sid}/{path:path}")
 def get_file(sid: str, path: str):
     base = os.path.abspath(session_dir(sid))
-    full = os.path.abspath(os.path.join(base, path))
-    if not full.startswith(base) or not os.path.exists(full):
+    # Chấp cả "/" lẫn "\" trong path (Windows) -> chuẩn hoá trước khi nối.
+    rel = path.replace("\\", "/").strip("/")
+    full = os.path.abspath(os.path.join(base, *rel.split("/")))
+    # Phải nằm trong phiên VÀ là FILE thật: trỏ vào THƯ MỤC thì FileResponse
+    # ném lỗi 500, trong khi đúng nghĩa là 404.
+    if not full.startswith(base) or not os.path.isfile(full):
         raise HTTPException(404, "file không tồn tại")
     # inline (KHÔNG attachment) -> trình duyệt render video/ảnh trực tiếp trong <video>.
     # Nút tải vẫn hoạt động nhờ thuộc tính `download` phía frontend.

backend/app/api/cut.py

@@ -13,7 +13,7 @@ import os
 from fastapi import APIRouter, File, Form, UploadFile
 from pydantic import BaseModel
 
-from ..core.files import new_session, session_dir, sub_dir, save_upload_stream
+from ..core.files import new_session, rel_path, save_upload_stream, session_dir, sub_dir
 from ..core.jobs import jobs
 from ..config import settings
 from ..services.cutter import cut as cutter
@@ -32,7 +32,7 @@ def upload(file: UploadFile = File(...), session: str = Form(None)):
     info = probe(path)
     return {
         "session": sid,
-        "file": os.path.relpath(path, session_dir(sid)),
+        "file": rel_path(path, sid),
         "info": {"duration": info.duration, "fps": info.fps,
                  "nb_frames": info.nb_frames,
                  "width": info.width, "height": info.height},
@@ -63,8 +63,7 @@ def split_audio(req: SplitAudioReq):
             res = cutter.split_audio(src, out_dir)
 
             def url(p):
-                return f"/api/files/{req.session}/" + os.path.relpath(
-                    p, session_dir(req.session)).replace(os.sep, "/")
+                return f"/api/files/{req.session}/" + rel_path(p, req.session)
 
             result = {
                 "muted_video_url": url(res.muted_video),

backend/app/api/download.py

@@ -10,7 +10,7 @@ from fastapi import APIRouter
 from pydantic import BaseModel
 
 from ..config import settings
-from ..core.files import new_session, session_dir, sub_dir, zip_paths
+from ..core.files import new_session, rel_path, session_dir, sub_dir, zip_paths
 from ..core.jobs import DONE, ERROR, RUNNING, jobs
 from ..services.downloader.ydl import detect_source, download_one, parse_links
 from ..services.history.auto_save import auto_save_result
@@ -58,7 +58,7 @@ def start(req: StartReq):
             res = download_one(url, out_dir, req.cookies_file)
             if res.ok:
                 done_paths.append(res.path)
-                rel = os.path.relpath(res.path, session_dir(sid)).replace(os.sep, "/")
+                rel = rel_path(res.path, sid)
                 h.item_status(it, DONE, detail=res.title, result={
                     "path": rel,
                     # quote() để encode '#', khoảng trắng... trong tên file
@@ -128,5 +128,5 @@ def push_to_tool(req: PushReq):
         if os.path.exists(src):
             d = os.path.join(dst, os.path.basename(src))
             shutil.copy(src, d)
-            copied.append(os.path.relpath(d, session_dir(new_sid)))
+            copied.append(rel_path(d, new_sid))
     return {"session": new_sid, "target_tool": req.target_tool, "files": copied}

backend/app/api/dub.py

@@ -18,7 +18,7 @@ from fastapi import APIRouter, File, Form, HTTPException, UploadFile
 from fastapi.responses import FileResponse
 from pydantic import BaseModel
 
-from ..core.files import new_session, session_dir, sub_dir, save_upload, save_upload_stream
+from ..core.files import new_session, rel_path, save_upload, save_upload_stream, session_dir, sub_dir
 from ..core.jobs import jobs
 from ..config import settings
 from ..services.dubber import pipeline
@@ -127,7 +127,7 @@ def upload(file: UploadFile = File(...), session: str = Form(None)):
     # stream xuống đĩa (không nạp cả video vào RAM) + chặn file quá lớn
     path = save_upload_stream(sid, file.filename, file.file, folder="inputs",
                               max_mb=settings.MAX_UPLOAD_MB)
-    rel = os.path.relpath(path, session_dir(sid))
+    rel = rel_path(path, sid)
     return {"session": sid, "file": rel, "name": os.path.basename(path),
             "size": os.path.getsize(path)}
 
@@ -138,7 +138,7 @@ def voice_sample(file: UploadFile = File(...), session: str = Form(None)):
     sid = session or new_session("dub")
     path = save_upload_stream(sid, file.filename, file.file, folder="voice",
                               max_mb=settings.MAX_UPLOAD_MB)
-    rel = os.path.relpath(path, session_dir(sid))
+    rel = rel_path(path, sid)
     return {"session": sid, "file": rel, "name": os.path.basename(path)}
 
 
@@ -216,8 +216,7 @@ def start(req: DubReq):
                 res = pipeline.run_dub(src, out_dir, opt, prog)
 
                 def url(path):
-                    return f"/api/files/{req.session}/" + os.path.relpath(
-                        path, session_dir(req.session)).replace(os.sep, "/")
+                    return f"/api/files/{req.session}/" + rel_path(path, req.session)
 
                 result = {
                     "name": base,
@@ -329,7 +328,7 @@ def prepare(req: DubReq):
                 ar = pipeline.analyze(src, out_dir, opt, prog)
 
                 def rel_to(path):
-                    return os.path.relpath(path, session_dir(req.session)).replace(os.sep, "/")
+                    return rel_path(path, req.session)
 
                 def url(path):
                     return f"/api/files/{req.session}/" + rel_to(path)
@@ -421,8 +420,7 @@ def synthesize(req: SynthReq):
                 res = pipeline.synthesize(state_abs, lines, opt, prog)
 
                 def url(path):
-                    return f"/api/files/{req.session}/" + os.path.relpath(
-                        path, session_dir(req.session)).replace(os.sep, "/")
+                    return f"/api/files/{req.session}/" + rel_path(path, req.session)
 
                 result = {
                     "name": base, "language": res.language, "n_lines": res.n_lines,
@@ -526,7 +524,7 @@ def tts_from_text(req: TtsReq):
                 h.set_progress(p)
                 h.item_status(_it, "running", detail=m)
             wav = pipeline.run_tts(opt, out_dir, prog)
-            rel = os.path.relpath(wav, session_dir(sid)).replace(os.sep, "/")
+            rel = rel_path(wav, sid)
             result = {"name": "voice.wav", "audio_url": f"/api/files/{sid}/{rel}"}
             h.item_status(it, "done", detail="đã tạo voice", result=result)
             return {"session": sid, "output": result}

backend/app/api/flux2.py

@@ -14,6 +14,8 @@ from pydantic import BaseModel
 from gradio_client import Client, handle_file
 
 from ..core.bg import submit_bg
+from ..core.reqctx import get_ctx
+from ..services.analytics import track as tracking
 
 WANGP_URL = "https://00114dcf4c286c050a.gradio.live/"
 OUTPUT_DIR = Path(__file__).resolve().parent.parent / "flux2_outputs"
@@ -106,7 +108,10 @@ def _download_image(img_info: Any, dest: Path):
         dest.write_bytes(resp.content)
 
 
-def _generate(task_id: str, params: dict):
+def _generate(task_id: str, params: dict, ctx: dict | None = None):
+    ctx = ctx or {}
+    started = time.time()
+    tracking.emit("job_started", ctx, job_id=task_id, kind="flux2")
     try:
         with _tasks_lock:
             _tasks[task_id] = {"status": "processing"}
@@ -236,6 +241,8 @@ def _generate(task_id: str, params: dict):
 
         with _tasks_lock:
             _tasks[task_id] = {"status": "done", "images": saved}
+        tracking.emit("job_done", ctx, latency_ms=int((time.time() - started) * 1000),
+                      job_id=task_id, kind="flux2", phase="generate", items=len(saved))
 
     except Exception as e:
         import traceback
@@ -246,6 +253,8 @@ def _generate(task_id: str, params: dict):
                 "error": str(e),
                 "traceback": traceback.format_exc(),
             }
+        tracking.emit("job_failed", ctx, latency_ms=int((time.time() - started) * 1000),
+                      job_id=task_id, kind="flux2", phase="generate", error=str(e)[:200])
 
 
 @router.get("/health")
@@ -264,7 +273,11 @@ async def api_generate(req: GenRequest):
     with _tasks_lock:
         _tasks[task_id] = {"status": "queued"}
 
-    submit_bg(_generate, task_id, req.model_dump())
+    # Bắt ngữ cảnh theo dõi NGAY tại request: hàm chạy ở luồng nền, ContextVar
+    # của request không còn sống tới đó.
+    ctx = get_ctx()
+    tracking.emit("job_queued", ctx, job_id=task_id, kind="flux2")
+    submit_bg(_generate, task_id, req.model_dump(), ctx)
 
     return {"task_id": task_id, "status": "queued"}
 

backend/app/api/listing.py

@@ -18,6 +18,8 @@ from ..services.listing.textgen import generate_copy_pack, generate_shopee_text
 from ..services.auth.storage import is_authorized as _check_user_auth
 from ..services.history.auto_save import auto_save_result
 from ..core.bg import submit_bg
+from ..core.reqctx import get_ctx
+from ..services.analytics import track as tracking
 
 
 router = APIRouter(prefix="/api/listing", tags=["listing"])
@@ -222,12 +224,17 @@ async def generate(body: dict):
     s["model"] = model
     s["quality"] = quality
 
-    submit_bg(_run_generation, sid, image_prompts)
+    ctx = get_ctx()          # luồng nền không giữ được ContextVar -> bắt tại đây
+    tracking.emit("job_queued", ctx, job_id=sid, kind="listing")
+    submit_bg(_run_generation, sid, image_prompts, ctx)
 
     return {"ok": True, "session_id": sid, "status": "started", "total": len(image_prompts)}
 
 
-def _run_generation(sid, image_prompts):
+def _run_generation(sid, image_prompts, ctx=None):
+    ctx = ctx or {}
+    _t0 = time.time()
+    tracking.emit("job_started", ctx, job_id=sid, kind="listing")
     s = _sessions.get(sid)
     if not s:
         return
@@ -369,6 +376,9 @@ def _run_generation(sid, image_prompts):
             s["errors"].append({"type": p["type"], "error": str(last_error) if last_error else "Unknown error"})
 
     s["status"] = "completed"
+    tracking.emit("job_done", ctx, latency_ms=int((time.time() - _t0) * 1000),
+                  job_id=sid, kind="listing", phase="analyze_generate",
+                  items=len(s.get("results") or []))
     s["last_status"] = {"level": "success", "message": "✅ Hoàn thành tất cả! Đang sinh text Shopee...", "time": time.time()}
 
     if s.get("attributes"):

backend/app/api/shuffle.py

@@ -18,7 +18,7 @@ from dataclasses import replace
 from fastapi import APIRouter, File, Form, HTTPException, UploadFile
 from pydantic import BaseModel
 
-from ..core.files import new_session, session_dir, sub_dir, save_upload_stream
+from ..core.files import new_session, rel_path, save_upload_stream, session_dir, sub_dir
 from ..core.jobs import jobs
 from ..config import settings
 from ..services.shuffler import engine
@@ -41,7 +41,7 @@ def upload(
     folder = f"seg_{segment}"
     path = save_upload_stream(sid, file.filename, file.file, folder=folder,
                               max_mb=settings.MAX_UPLOAD_MB)
-    rel = os.path.relpath(path, session_dir(sid))
+    rel = rel_path(path, sid)
     return {
         "session": sid, "segment": segment, "file": rel,
         "name": os.path.basename(path), "size": os.path.getsize(path),
@@ -57,7 +57,7 @@ def upload_audio(
     """Tải 1 track âm thanh dùng để lồng vào các biến thể."""
     path = save_upload_stream(session, file.filename, file.file, folder="audio",
                               max_mb=settings.MAX_UPLOAD_MB)
-    rel = os.path.relpath(path, session_dir(session))
+    rel = rel_path(path, session)
     return {
         "session": session, "file": rel,
         "name": os.path.basename(path), "size": os.path.getsize(path),

backend/app/config.py

@@ -23,6 +23,20 @@ def _env(key: str, default: str = "") -> str:
     return os.environ.get(key, default)
 
 
+def _env_int(key: str, default: int) -> int:
+    try:
+        return int(os.environ.get(key, "") or default)
+    except (TypeError, ValueError):
+        return default
+
+
+def _env_float(key: str, default: float) -> float:
+    try:
+        return float(os.environ.get(key, "") or default)
+    except (TypeError, ValueError):
+        return default
+
+
 @dataclass
 class Settings:
     # Vùng LÀM VIỆC TẠM theo phiên (không phải kho lưu trữ): mặc định nằm trong
@@ -43,6 +57,18 @@ class Settings:
     # Database cho user auth (để trống thì dùng JSON file)
     DATABASE_URL: str = field(default_factory=lambda: _env("DATABASE_URL", ""))
 
+    # --- Theo dõi người dùng (tab "Quản lý thời lượng") ---
+    # Log thô lưu chung DATABASE_URL nếu có, không thì SQLite trong STORAGE_DIR.
+    # Giữ bao nhiêu ngày rồi tự dọn (0 = giữ mãi).
+    ANALYTICS_RETENTION_DAYS: int = field(
+        default_factory=lambda: _env_int("ANALYTICS_RETENTION_DAYS", 90))
+    # Múi giờ dùng để gộp "theo ngày" trong báo cáo (giờ so với UTC).
+    ANALYTICS_TZ_OFFSET: float = field(
+        default_factory=lambda: _env_float("ANALYTICS_TZ_OFFSET", 7.0))
+    # Im lặng quá ngần này phút -> coi như hết phiên (spec §6, mốc mềm).
+    SESSION_IDLE_MINUTES: int = field(
+        default_factory=lambda: _env_int("SESSION_IDLE_MINUTES", 30))
+
     # Danh sách user được dùng key chung (cách nhau bằng dấu phẩy)
     AUTHORIZED_USERS: list[str] = field(
         default_factory=lambda: [u.strip() for u in _env("AUTHORIZED_USERS", "admin").split(",") if u.strip()]

backend/app/core/files.py

@@ -45,6 +45,15 @@ def sub_dir(sid: str, *parts: str) -> str:
     return d
 
 
+def rel_path(full: str, sid: str) -> str:
+    """Đường dẫn tương đối trong phiên, LUÔN dùng "/".
+
+    An toàn cho URL/JSON: dấu "\\" của Windows lọt vào `<video src>` hay khoá
+    khớp đường dẫn là hỏng. Đừng gọi thẳng os.path.relpath ở endpoint.
+    """
+    return os.path.relpath(full, session_dir(sid)).replace(os.sep, "/")
+
+
 def save_upload(sid: str, filename: str, data: bytes, folder: str = "uploads") -> str:
     if not data or len(data) == 0:
         raise ValueError(f"Upload file '{filename}' is empty (0 bytes)")

backend/app/core/jobs.py

@@ -69,6 +69,13 @@ class Job:
     result: dict | None = None
     error: str = ""
     created_at: float = field(default_factory=time.time)
+    # Mốc RỜI HÀNG ĐỢI và mốc XONG -> tách "chờ tới lượt" khỏi "máy chạy thật".
+    # latency_ms của chỉ số B2/B4 = finished_at - started_at, KHÔNG tính chờ.
+    started_at: float | None = None
+    finished_at: float | None = None
+    # 4 tầng định danh do frontend gửi kèm (user/session/task/feature) để dòng
+    # log máy chạy gắn được vào đúng task của đúng người. Rỗng -> không ghi log.
+    ctx: dict = field(default_factory=dict)
     # Vị trí trong hàng đợi (0 = đang chạy/đến lượt). Manager cập nhật khi xem.
     queue_pos: int = 0
     queue_total: int = 0
@@ -86,6 +93,8 @@ class Job:
             "result": self.result,
             "error": self.error,
             "created_at": self.created_at,
+            "started_at": self.started_at,
+            "finished_at": self.finished_at,
             "failed_items": [
                 {"id": i.id, "label": i.label, "error": i.error}
                 for i in self.items if i.status == ERROR
@@ -129,6 +138,21 @@ class JobHandle:
         return self._m._cancel.get(self.job.id, False)
 
 
+def _emit(job: "Job", event_name: str, **props):
+    """Bắn một dòng log máy-chạy cho job (nuốt mọi lỗi).
+
+    Job không mang ctx (endpoint chưa gửi user/session/task) -> bỏ qua im lặng,
+    tracking không bao giờ được làm hỏng pipeline.
+    """
+    if not job.ctx or not job.ctx.get("user_id"):
+        return
+    try:
+        from ..services.analytics.track import emit
+        emit(event_name, job.ctx, step="run", job_id=job.id, kind=job.kind, **props)
+    except Exception:
+        pass
+
+
 class JobManager:
     def __init__(self):
         self._jobs: dict[str, Job] = {}
@@ -152,8 +176,15 @@ class JobManager:
     def _cat(kind: str) -> str:
         return "heavy" if kind in HEAVY_KINDS else "io"
 
-    def create(self, kind: str) -> Job:
-        job = Job(id=uuid.uuid4().hex[:12], kind=kind)
+    def create(self, kind: str, ctx: dict | None = None) -> Job:
+        if ctx is None:
+            # Không truyền tay -> lấy từ header X-TNT-* của request đang chạy.
+            try:
+                from .reqctx import get_ctx
+                ctx = get_ctx()
+            except Exception:
+                ctx = {}
+        job = Job(id=uuid.uuid4().hex[:12], kind=kind, ctx=dict(ctx or {}))
         with self._lock:
             self._jobs[job.id] = job
             self._order.append(job.id)
@@ -222,6 +253,7 @@ class JobManager:
         with self._lock:
             self._waiting[cat].append(job.id)
             job.status = QUEUED
+        _emit(job, "job_queued")
 
         def runner():
             with self._lock:
@@ -232,7 +264,9 @@ class JobManager:
                     return
                 self._running[cat].add(job.id)
                 job.status = RUNNING
+                job.started_at = time.time()
                 job.queue_pos = 0
+            _emit(job, "job_started")
             try:
                 result = fn(handle)
                 with self._lock:
@@ -248,7 +282,13 @@ class JobManager:
                 handle.log(traceback.format_exc(), level="error")
             finally:
                 with self._lock:
+                    job.finished_at = time.time()
                     self._running[cat].discard(job.id)
+                # latency_ms = CHẠY THẬT (started -> finished), không gồm chờ.
+                _emit(job, "job_done" if job.status == DONE else "job_failed",
+                      latency_ms=int(max(0.0, job.finished_at - (job.started_at or job.finished_at)) * 1000),
+                      status=job.status, items=len(job.items) or None,
+                      error=(job.error or None))
 
         self._pools[cat].submit(runner)
 

backend/app/core/reqctx.py

@@ -0,0 +1,66 @@
+"""Ngữ cảnh theo dõi đi kèm mỗi request (user / session / task / feature).
+
+VÌ SAO LÀ HEADER, KHÔNG PHẢI BODY:
+    Job được tạo ở ~15 endpoint với ~15 model Pydantic khác nhau, lại có cả
+    endpoint nhận multipart (upload). Thêm 6 trường vào từng model là sửa rải
+    rác và rất dễ sót. Frontend gắn header `X-TNT-*` một chỗ duy nhất (bản vá
+    `fetch` trong `lib/track.js`), backend đọc một chỗ duy nhất ở đây, và
+    `jobs.create()` tự nhặt — endpoint không phải biết gì về tracking.
+
+Dùng ContextVar nên an toàn với cả endpoint `async def` lẫn `def` (Starlette
+chạy endpoint đồng bộ trong threadpool có sao chép context).
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+
+_ctx: ContextVar[dict] = ContextVar("tnt_track_ctx", default={})
+
+HEADERS = {
+    "user_id": "x-tnt-user",
+    "session_id": "x-tnt-session",
+    "task_id": "x-tnt-task",
+    "feature": "x-tnt-feature",
+    "phase": "x-tnt-phase",
+    "attempt": "x-tnt-attempt",
+}
+
+
+def get_ctx() -> dict:
+    return _ctx.get() or {}
+
+
+class TrackContextMiddleware:
+    """ASGI middleware thuần — CỐ Ý không dùng BaseHTTPMiddleware.
+
+    BaseHTTPMiddleware bọc response vào một luồng trung gian; app này phục vụ
+    file video lớn bằng FileResponse nên không đáng đánh đổi. Ở đây chỉ đọc vài
+    header rồi đặt ContextVar, không đụng gì tới request/response.
+    """
+
+    def __init__(self, app):
+        self.app = app
+
+    async def __call__(self, scope, receive, send):
+        if scope.get("type") != "http":
+            return await self.app(scope, receive, send)
+
+        raw = {}
+        for k, v in scope.get("headers") or ():
+            key = k.decode("latin-1").lower()
+            if key.startswith("x-tnt-"):
+                raw[key] = v.decode("latin-1", "ignore")[:120]
+
+        ctx = {k: raw.get(v, "") for k, v in HEADERS.items()}
+        try:
+            ctx["attempt"] = int(ctx["attempt"]) if ctx["attempt"] else None
+        except (TypeError, ValueError):
+            ctx["attempt"] = None
+        ctx["user_id"] = ctx["user_id"].strip().lower()
+
+        token = _ctx.set(ctx if ctx["user_id"] else {})
+        try:
+            await self.app(scope, receive, send)
+        finally:
+            _ctx.reset(token)

backend/app/main.py

@@ -28,14 +28,18 @@ from starlette.exceptions import HTTPException as StarletteHTTPException
 
 from .config import settings
 from .core.files import cleanup_old
+from .core.reqctx import TrackContextMiddleware
 _here = os.path.dirname(os.path.abspath(__file__))
 _parent = os.path.dirname(_here)
 sys.path.insert(0, _parent)
 
-from .api import common, download, cut, shuffle, dub, listing, video, auth, drive, history_api, flux2, listing_free
+from .api import common, download, cut, shuffle, dub, listing, video, auth, drive, history_api, flux2, listing_free, analytics
 
 app = FastAPI(title="TNT Group - AI Content Create", version="1.0.0")
 
+# Nhặt ngữ cảnh theo dõi (X-TNT-*) trước khi vào endpoint.
+app.add_middleware(TrackContextMiddleware)
+
 app.add_middleware(
     CORSMiddleware,
     allow_origins=settings.CORS_ORIGINS or ["*"],
@@ -56,6 +60,7 @@ app.include_router(drive.router)
 app.include_router(history_api.router)
 app.include_router(flux2.router)
 app.include_router(listing_free.router)
+app.include_router(analytics.router)
 
 
 @app.get("/api/health")

backend/app/services/analytics/etl.py

@@ -0,0 +1,472 @@
+"""ETL: từ `raw_events` suy ra 9 chỉ số (A1-A5, B1-B4).
+
+Không bảng chỉ số dựng sẵn — mọi con số ở đây tính lại từ log thô mỗi lần gọi
+(spec §1 "một dòng log, suy ra mọi chỉ số"). Dữ liệu nội bộ vài chục nghìn dòng
+/tháng nên gộp bằng Python là đủ nhanh và tránh viết SQL hai lần cho PG/SQLite.
+
+HAI ĐỒNG HỒ — dùng đúng chỗ:
+    - `event_ts` (giờ máy người dùng) -> MỌI phép TRỪ thời gian. Lệch đồng hồ
+      là hằng số trong một phiên nên hiệu số vẫn đúng. Không dùng `server_ts`
+      cho việc này: frontend gom event thành lô rồi mới gửi, mọi dòng trong lô
+      có `server_ts` gần bằng nhau -> thời gian mỗi bước sẽ hoá 0.
+    - `server_ts` (giờ máy chủ) -> LỌC khoảng ngày & gộp "theo ngày", vì đây là
+      đồng hồ duy nhất tin được khi so giữa nhiều người dùng.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from datetime import datetime, timedelta, timezone
+
+from ...config import settings
+
+# Thứ tự bước theo spec §2.
+STEP_ORDER = ["open", "prepare", "run", "review", "output", "done"]
+
+# Nhãn tiếng Việt cho FE khỏi phải nhúng bảng dịch.
+FEATURE_LABELS = {
+    "down_list": "Down list",
+    "cut": "Cắt video",
+    "shuffle": "Xào video",
+    "dub": "Dịch / đổi giọng",
+    "text_video": "Chèn chữ vào video",
+    "listing_image": "Listing ảnh",
+    "listing_free": "Listing ảnh Free",
+    "flux2": "Flux2",
+    "create_video": "Tạo video AI",
+    "history": "Lịch sử cá nhân",
+    "guide": "Hướng dẫn",
+    "support": "Hỗ trợ",
+    "home": "Trang chủ",
+    "admin": "Quản trị",
+}
+
+# Event tính là "một lần bấm/hỏi" cho chỉ số A4.
+ATTEMPT_EVENTS = {"job_done", "regenerate", "edit_request"}
+
+
+# ── Tiện ích thống kê ────────────────────────────────────────────
+
+def _median(xs: list[float]) -> float | None:
+    if not xs:
+        return None
+    ys = sorted(xs)
+    n = len(ys)
+    mid = n // 2
+    return float(ys[mid]) if n % 2 else (ys[mid - 1] + ys[mid]) / 2.0
+
+
+def _pct(xs: list[float], p: float) -> float | None:
+    """Phân vị kiểu nearest-rank (đủ dùng, không cần numpy)."""
+    if not xs:
+        return None
+    ys = sorted(xs)
+    k = max(0, min(len(ys) - 1, int(round(p * (len(ys) - 1)))))
+    return float(ys[k])
+
+
+def _avg(xs: list[float]) -> float | None:
+    return (sum(xs) / len(xs)) if xs else None
+
+
+def _ratio(num: int, den: int) -> float | None:
+    return (num / den) if den else None
+
+
+def local_date(ts: float) -> str:
+    """Epoch -> 'YYYY-MM-DD' theo múi giờ báo cáo (mặc định +07:00)."""
+    tz = timezone(timedelta(hours=settings.ANALYTICS_TZ_OFFSET))
+    return datetime.fromtimestamp(ts, tz).strftime("%Y-%m-%d")
+
+
+# ── Dựng Task từ log ─────────────────────────────────────────────
+
+def build_tasks(events: list[dict]) -> list[dict]:
+    """Gom event theo `task_id` -> danh sách task đã tính sẵn mốc chính.
+
+    Dòng không có `task_id` (vd `session_start`) không thuộc task nào.
+    """
+    groups: dict[str, list[dict]] = defaultdict(list)
+    for e in events:
+        if e.get("task_id"):
+            groups[e["task_id"]].append(e)
+
+    tasks = []
+    for task_id, evs in groups.items():
+        evs.sort(key=lambda x: (x.get("event_ts") or 0.0))
+        first, last = evs[0], evs[-1]
+
+        # Mốc bắt đầu = feature_open nếu có (spec: A1 đo từ lúc mở tool).
+        open_ev = next((e for e in evs if e["event_name"] == "feature_open"), None)
+        start_ts = (open_ev or first).get("event_ts") or 0.0
+        end_ts = last.get("event_ts") or start_ts
+
+        outputs = [e for e in evs if e["event_name"].startswith("output_")]
+        abandon = next((e for e in evs if e["event_name"] == "feature_abandon"), None)
+        complete = next((e for e in evs if e["event_name"] == "feature_complete"), None)
+
+        first_output_ts = outputs[0]["event_ts"] if outputs else None
+        success_type = ""
+        if outputs:
+            success_type = (outputs[0].get("properties") or {}).get("success_type") or (
+                "forward" if outputs[0]["event_name"] == "output_forward" else "download")
+        elif complete:
+            success_type = (complete.get("properties") or {}).get("success_type") or "done"
+
+        # B2/B4: chỉ dòng máy chạy mới có latency_ms.
+        jobs = [e for e in evs if e.get("latency_ms") is not None]
+        machine_ms = sum(e["latency_ms"] for e in jobs)
+
+        # Thời gian CHỜ tới lượt (queued -> started) — không tính vào tốc độ máy.
+        wait_ms = 0.0
+        queued: dict[str, float] = {}
+        for e in evs:
+            jid = (e.get("properties") or {}).get("job_id") or ""
+            if e["event_name"] == "job_queued":
+                queued[jid] = e.get("event_ts") or 0.0
+            elif e["event_name"] == "job_started" and jid in queued:
+                wait_ms += max(0.0, ((e.get("event_ts") or 0.0) - queued.pop(jid)) * 1000.0)
+
+        attempts = sum(1 for e in evs if e["event_name"] in ATTEMPT_EVENTS)
+
+        # B1: số sản phẩm sinh ra (properties.count/items nếu có, không thì đếm dòng).
+        produced = 0
+        for e in outputs:
+            p = e.get("properties") or {}
+            try:
+                produced += int(p.get("count") or p.get("items") or 1)
+            except (TypeError, ValueError):
+                produced += 1
+
+        thumbs = [e for e in evs if e["event_name"] == "thumbs_feedback"]
+
+        tasks.append({
+            "task_id": task_id,
+            "user_id": first.get("user_id", ""),
+            "session_id": first.get("session_id", ""),
+            "feature": first.get("feature", "") or (open_ev or first).get("feature", ""),
+            "start_ts": start_ts,
+            "end_ts": end_ts,
+            "server_ts": first.get("server_ts") or 0.0,
+            "date": local_date(first.get("server_ts") or 0.0),
+            "events": evs,
+            "n_events": len(evs),
+            "has_output": bool(outputs),
+            "first_output_ts": first_output_ts,
+            # A1 — xong một tính năng mất bao lâu (chỉ task có đầu ra).
+            "duration_ms": ((first_output_ts - start_ts) * 1000.0) if first_output_ts else None,
+            "span_ms": (end_ts - start_ts) * 1000.0,
+            "success_type": success_type,
+            "abandoned": bool(abandon) and not outputs,
+            "last_step": ((abandon.get("properties") or {}).get("last_step")
+                          or abandon.get("step") or "") if abandon else "",
+            "abandon_reason": (abandon.get("properties") or {}).get("reason", "") if abandon else "",
+            "attempts": attempts,
+            "machine_ms": machine_ms,      # B4
+            "wait_ms": wait_ms,
+            "jobs": [{"name": e["event_name"], "latency_ms": e["latency_ms"],
+                      "step": e.get("step", ""),
+                      "attempt": (e.get("properties") or {}).get("attempt")} for e in jobs],
+            "produced": produced,          # B1
+            "thumbs_up": sum(1 for e in thumbs if e.get("event_value") == "up"),
+            "thumbs_down": sum(1 for e in thumbs if e.get("event_value") == "down"),
+        })
+
+    tasks.sort(key=lambda t: t["start_ts"])
+    return tasks
+
+
+def step_durations(task: dict) -> list[dict]:
+    """A2 — thời gian mỗi bước: hiệu hai mốc `step` kề nhau trong một task."""
+    marks = []
+    for e in task["events"]:
+        st = e.get("step") or ""
+        if st and (not marks or marks[-1]["step"] != st):
+            marks.append({"step": st, "ts": e.get("event_ts") or 0.0})
+            # `done` là mốc cuối. Việc bấm 👍 sau khi tải xong mang step=output
+            # nên nếu không dừng ở đây, dòng thời gian hiện "…done → output",
+            # đọc như thể còn một bước nữa sau khi đã xong.
+            if st == "done":
+                break
+    out = []
+    for i, m in enumerate(marks):
+        end = marks[i + 1]["ts"] if i + 1 < len(marks) else task["end_ts"]
+        out.append({"step": m["step"], "ms": max(0.0, (end - m["ts"]) * 1000.0)})
+    return out
+
+
+# ── Dựng Phiên (session) ─────────────────────────────────────────
+
+def build_sessions(events: list[dict]) -> list[dict]:
+    """Gom theo `session_id`, cắt tiếp khi im lặng quá ngưỡng (spec §6).
+
+    Trả cả hai con số vì chúng khác nhau và đều cần:
+        span_ms   = mốc cuối − mốc đầu (kể cả lúc bỏ máy đi pha cà phê).
+        active_ms = tổng khoảng cách giữa hai thao tác LIÊN TIẾP còn dưới ngưỡng
+                    im lặng -> "thời lượng dùng thật".
+    """
+    idle_s = max(1, settings.SESSION_IDLE_MINUTES) * 60
+    groups: dict[str, list[dict]] = defaultdict(list)
+    for e in events:
+        if e.get("session_id"):
+            groups[e["session_id"]].append(e)
+
+    sessions = []
+    for sid, evs in groups.items():
+        evs.sort(key=lambda x: (x.get("event_ts") or 0.0))
+        # Một session_id để lâu vẫn có thể chứa nhiều lần dùng cách nhau nửa ngày
+        # (tab mở suốt) -> cắt thành nhiều phiên con.
+        chunk: list[dict] = []
+        chunks: list[list[dict]] = []
+        for e in evs:
+            if chunk and ((e.get("event_ts") or 0.0) - (chunk[-1].get("event_ts") or 0.0)) > idle_s:
+                chunks.append(chunk)
+                chunk = []
+            chunk.append(e)
+        if chunk:
+            chunks.append(chunk)
+
+        for i, ch in enumerate(chunks):
+            active = 0.0
+            for a, b in zip(ch, ch[1:]):
+                gap = (b.get("event_ts") or 0.0) - (a.get("event_ts") or 0.0)
+                if 0 <= gap <= idle_s:
+                    active += gap
+            tids = {e["task_id"] for e in ch if e.get("task_id")}
+            feats = [e.get("feature", "") for e in ch if e.get("feature")]
+            sessions.append({
+                "session_id": sid if len(chunks) == 1 else f"{sid}#{i + 1}",
+                "user_id": ch[0].get("user_id", ""),
+                "start_ts": ch[0].get("event_ts") or 0.0,
+                "end_ts": ch[-1].get("event_ts") or 0.0,
+                "date": local_date(ch[0].get("server_ts") or 0.0),
+                "span_ms": ((ch[-1].get("event_ts") or 0.0) - (ch[0].get("event_ts") or 0.0)) * 1000.0,
+                "active_ms": active * 1000.0,
+                "n_events": len(ch),
+                "task_ids": sorted(tids),
+                "n_tasks": len(tids),
+                "features": sorted(set(feats)),
+            })
+
+    sessions.sort(key=lambda s: s["start_ts"])
+    return sessions
+
+
+# ── Tổng hợp cho tab quản trị ────────────────────────────────────
+
+def _bucket_metrics(tasks: list[dict]) -> dict:
+    """Cụm chỉ số dùng chung cho mọi cách gộp (toàn cục / theo tool / theo người)."""
+    done = [t for t in tasks if t["has_output"]]
+    durations = [t["duration_ms"] for t in done if t["duration_ms"] is not None]
+    machine = [t["machine_ms"] for t in tasks if t["machine_ms"]]
+    up = sum(t["thumbs_up"] for t in tasks)
+    down = sum(t["thumbs_down"] for t in tasks)
+    return {
+        "tasks": len(tasks),
+        "tasks_done": len(done),
+        "completion_rate": _ratio(len(done), len(tasks)),        # A3
+        "duration_median_ms": _median(durations),                # A1
+        "duration_p90_ms": _pct(durations, 0.9),
+        "attempts_avg": _avg([t["attempts"] for t in tasks]),    # A4
+        "produced_total": sum(t["produced"] for t in tasks),     # B1
+        "machine_median_ms": _median(machine),                   # B4
+        "machine_total_ms": sum(machine),
+        "wait_total_ms": sum(t["wait_ms"] for t in tasks),
+        "thumbs_up": up,
+        "thumbs_down": down,
+        "thumbs_rate": _ratio(up, up + down),                    # B3
+        "abandoned": sum(1 for t in tasks if t["abandoned"]),
+    }
+
+
+def summarize(events: list[dict]) -> dict:
+    """Toàn bộ số liệu cho tab "Quản lý thời lượng"."""
+    tasks = build_tasks(events)
+    sessions = build_sessions(events)
+
+    by_user_tasks: dict[str, list[dict]] = defaultdict(list)
+    for t in tasks:
+        by_user_tasks[t["user_id"]].append(t)
+    by_user_sessions: dict[str, list[dict]] = defaultdict(list)
+    for s in sessions:
+        by_user_sessions[s["user_id"]].append(s)
+
+    # A5 — quay lại dùng: xuất hiện ở >= 2 ngày khác nhau.
+    days_by_user: dict[str, set[str]] = defaultdict(set)
+    for e in events:
+        if e.get("user_id"):
+            days_by_user[e["user_id"]].add(local_date(e.get("server_ts") or 0.0))
+
+    users = []
+    for uid in sorted(set(list(by_user_tasks) + list(by_user_sessions) + list(days_by_user))):
+        if not uid:
+            continue
+        ut, us = by_user_tasks.get(uid, []), by_user_sessions.get(uid, [])
+        feat_count: dict[str, int] = defaultdict(int)
+        for t in ut:
+            feat_count[t["feature"]] += 1
+        m = _bucket_metrics(ut)
+        users.append({
+            "user_id": uid,
+            "days_active": len(days_by_user.get(uid, ())),
+            "returning": len(days_by_user.get(uid, ())) >= 2,     # A5
+            "sessions": len(us),
+            "active_ms": sum(s["active_ms"] for s in us),
+            "span_ms": sum(s["span_ms"] for s in us),
+            "first_seen": min((s["start_ts"] for s in us), default=None),
+            "last_seen": max((s["end_ts"] for s in us), default=None),
+            # Kèm nhãn tiếng Việt: bảng trên giao diện hiển thị tên tool ở mọi
+            # cột khác, riêng cột này mà hiện khoá thô (down_list) thì lệch.
+            "top_features": [
+                {"feature": f, "label": FEATURE_LABELS.get(f, f), "tasks": n}
+                for f, n in sorted(feat_count.items(), key=lambda kv: -kv[1])[:3]
+            ],
+            **m,
+        })
+    users.sort(key=lambda u: -(u["active_ms"] or 0))
+
+    # Theo tool
+    by_feat: dict[str, list[dict]] = defaultdict(list)
+    for t in tasks:
+        by_feat[t["feature"]].append(t)
+    features = []
+    for f, ft in sorted(by_feat.items()):
+        abandon_steps: dict[str, int] = defaultdict(int)
+        for t in ft:
+            if t["abandoned"]:
+                abandon_steps[t["last_step"] or "?"] += 1
+        step_ms: dict[str, list[float]] = defaultdict(list)
+        for t in ft:
+            for d in step_durations(t):
+                step_ms[d["step"]].append(d["ms"])
+        features.append({
+            "feature": f,
+            "label": FEATURE_LABELS.get(f, f),
+            "users": len({t["user_id"] for t in ft}),
+            "abandon_by_step": dict(abandon_steps),               # A2
+            "step_median_ms": {k: _median(v) for k, v in step_ms.items()
+                               if k in STEP_ORDER},
+            **_bucket_metrics(ft),
+        })
+    features.sort(key=lambda f: -f["tasks"])
+
+    # Tốc độ máy từng loại job (B2)
+    job_ms: dict[str, list[float]] = defaultdict(list)
+    for e in events:
+        if e.get("latency_ms") is not None:
+            job_ms[f"{e.get('feature', '')}|{(e.get('properties') or {}).get('phase') or e['event_name']}"].append(
+                float(e["latency_ms"]))
+    jobs = [{
+        "feature": k.split("|", 1)[0],
+        "label": FEATURE_LABELS.get(k.split("|", 1)[0], k.split("|", 1)[0]),
+        "phase": k.split("|", 1)[1],
+        "runs": len(v),
+        "median_ms": _median(v),
+        "p90_ms": _pct(v, 0.9),
+        "total_ms": sum(v),
+    } for k, v in job_ms.items()]
+    jobs.sort(key=lambda j: -j["runs"])
+
+    # Sản phẩm làm ra: gộp theo tool + loại file
+    products: dict[str, int] = defaultdict(int)
+    for e in events:
+        if e["event_name"].startswith("output_"):
+            # Chuyển tiếp sang tool khác cũng là một đầu ra, nhưng phải đọc ra
+            # được là "chuyển sang cut" chứ không lẫn với "file .cut".
+            if e["event_name"] == "output_forward":
+                kind = "→ " + (e.get("event_value") or "tool khác")
+            else:
+                kind = e.get("event_value") or "file"
+            n = (e.get("properties") or {}).get("count") or 1
+            try:
+                n = int(n)
+            except (TypeError, ValueError):
+                n = 1
+            products[f"{e.get('feature', '')}|{kind}"] += n
+    product_rows = [{
+        "feature": k.split("|", 1)[0],
+        "label": FEATURE_LABELS.get(k.split("|", 1)[0], k.split("|", 1)[0]),
+        "kind": k.split("|", 1)[1],
+        "count": v,
+    } for k, v in sorted(products.items(), key=lambda kv: -kv[1])]
+
+    # Chuỗi theo ngày
+    daily: dict[str, dict] = defaultdict(lambda: {
+        "date": "", "users": set(), "sessions": 0, "tasks": 0,
+        "tasks_done": 0, "active_ms": 0.0, "machine_ms": 0.0, "outputs": 0})
+    for s in sessions:
+        d = daily[s["date"]]
+        d["date"] = s["date"]
+        d["users"].add(s["user_id"])
+        d["sessions"] += 1
+        d["active_ms"] += s["active_ms"]
+    for t in tasks:
+        d = daily[t["date"]]
+        d["date"] = t["date"]
+        d["tasks"] += 1
+        d["tasks_done"] += 1 if t["has_output"] else 0
+        d["machine_ms"] += t["machine_ms"]
+        d["outputs"] += t["produced"]
+    timeseries = [{**v, "users": len(v["users"])} for v in
+                  sorted(daily.values(), key=lambda x: x["date"])]
+
+    overall = _bucket_metrics(tasks)
+    overall.update({
+        "users": len([u for u in users if u["tasks"] or u["sessions"]]),
+        "returning_users": sum(1 for u in users if u["returning"]),
+        "sessions": len(sessions),
+        "active_ms": sum(s["active_ms"] for s in sessions),
+        "session_median_ms": _median([s["active_ms"] for s in sessions]),
+        "events": len(events),
+    })
+
+    return {
+        "overall": overall,
+        "users": users,
+        "features": features,
+        "jobs": jobs,
+        "products": product_rows,
+        "timeseries": timeseries,
+    }
+
+
+def user_detail(events: list[dict], user_id: str) -> dict:
+    """Chi tiết một người: từng phiên, từng task trong phiên."""
+    evs = [e for e in events if e.get("user_id") == user_id]
+    tasks = {t["task_id"]: t for t in build_tasks(evs)}
+    sessions = build_sessions(evs)
+
+    out_sessions = []
+    for s in sessions:
+        rows = []
+        for tid in s["task_ids"]:
+            t = tasks.get(tid)
+            if not t:
+                continue
+            rows.append({
+                "task_id": t["task_id"],
+                "feature": t["feature"],
+                "label": FEATURE_LABELS.get(t["feature"], t["feature"]),
+                "start_ts": t["start_ts"],
+                "duration_ms": t["duration_ms"],
+                "span_ms": t["span_ms"],
+                "machine_ms": t["machine_ms"],
+                "wait_ms": t["wait_ms"],
+                "attempts": t["attempts"],
+                "produced": t["produced"],
+                "has_output": t["has_output"],
+                "success_type": t["success_type"],
+                "abandoned": t["abandoned"],
+                "last_step": t["last_step"],
+                "abandon_reason": t["abandon_reason"],
+                "thumbs_up": t["thumbs_up"],
+                "thumbs_down": t["thumbs_down"],
+                "steps": step_durations(t),
+                "jobs": t["jobs"],
+            })
+        rows.sort(key=lambda r: r["start_ts"])
+        out_sessions.append({**{k: v for k, v in s.items() if k != "task_ids"}, "tasks": rows})
+
+    out_sessions.sort(key=lambda s: -s["start_ts"])
+    return {"user_id": user_id, "sessions": out_sessions,
+            "totals": _bucket_metrics(list(tasks.values()))}

backend/app/services/analytics/storage.py

@@ -0,0 +1,382 @@
+"""Kho log sự kiện thô (`raw_events`) — nền cho tab "Quản lý thời lượng".
+
+NGUYÊN TẮC (theo User_Flow_and_Tracking_Spec §1):
+    Không lưu sẵn chỉ số. Chỉ ghi log thô, mọi chỉ số tính sau bằng ETL
+    (xem `etl.py`). Một thao tác = một dòng.
+
+BACKEND LƯU TRỮ — giống `services/auth/storage.py`:
+    - Có DATABASE_URL  -> PostgreSQL (bền, dùng trên HF Spaces).
+    - Không            -> SQLite trong STORAGE_DIR (đủ cho máy dev).
+      KHÔNG dùng JSON như bảng user: log nhiều gấp hàng trăm lần, cần append
+      rẻ + lọc theo khoảng thời gian.
+
+MỐC THỜI GIAN: mỗi dòng giữ HAI đồng hồ.
+    - event_ts  = giờ máy người dùng (dùng tính hiệu số trong cùng phiên).
+    - server_ts = giờ máy chủ lúc nhận (dùng xếp thứ tự & lọc theo ngày,
+      không lệch khi đồng hồ máy khách sai).
+Cả hai là epoch giây (float) nên hai backend query giống hệt nhau; chuỗi ISO
+gốc vẫn giữ ở cột `event_time` để đối chiếu khi cần.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+import threading
+import time
+import uuid
+from datetime import datetime, timezone
+
+from ...config import settings
+
+_lock = threading.Lock()
+
+# Trần số dòng trả về cho một lần query (chặn kéo cả bảng về RAM).
+MAX_ROWS = 300_000
+
+COLUMNS = (
+    "event_id", "event_time", "event_ts", "server_ts", "user_id", "session_id",
+    "task_id", "feature", "step", "event_name", "event_value", "latency_ms",
+    "properties_json",
+)
+
+
+# ── Chuẩn hoá một dòng event ─────────────────────────────────────
+
+def _parse_iso(s: str) -> float | None:
+    """ISO8601 (kèm ms + múi giờ) -> epoch giây. Sai định dạng -> None."""
+    if not s:
+        return None
+    try:
+        txt = s.strip().replace("Z", "+00:00")
+        dt = datetime.fromisoformat(txt)
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return dt.timestamp()
+    except (ValueError, TypeError):
+        return None
+
+
+def normalize(raw: dict, server_ts: float | None = None) -> dict:
+    """Ép một event từ client về đúng schema, cắt bớt chuỗi quá dài.
+
+    latency_ms: CHỈ giữ khi là dòng máy chạy. Client gửi 0/rỗng -> None
+    (spec §2 "quy tắc vàng": đừng nhét 0, làm hỏng trung bình).
+    """
+    srv = server_ts if server_ts is not None else time.time()
+
+    def s(key: str, limit: int = 200) -> str:
+        v = raw.get(key)
+        return "" if v is None else str(v)[:limit]
+
+    lat = raw.get("latency_ms")
+    try:
+        lat = int(lat) if lat not in (None, "", False) else None
+    except (TypeError, ValueError):
+        lat = None
+    if lat is not None and lat < 0:
+        lat = None
+
+    props = raw.get("properties")
+    if not isinstance(props, dict):
+        props = raw.get("properties_json")
+    if isinstance(props, str):
+        try:
+            props = json.loads(props)
+        except (json.JSONDecodeError, TypeError):
+            props = {"_raw": props[:500]}
+    if not isinstance(props, dict):
+        props = {}
+
+    event_time = s("event_time", 64)
+    ts = _parse_iso(event_time)
+    if ts is None:
+        ts = srv
+        event_time = datetime.fromtimestamp(srv, timezone.utc).isoformat(timespec="milliseconds")
+
+    return {
+        "event_id": s("event_id", 64) or uuid.uuid4().hex,
+        "event_time": event_time,
+        "event_ts": ts,
+        "server_ts": srv,
+        "user_id": s("user_id", 120).strip().lower(),
+        "session_id": s("session_id", 64),
+        "task_id": s("task_id", 64),
+        "feature": s("feature", 40),
+        "step": s("step", 20),
+        "event_name": s("event_name", 60),
+        "event_value": s("event_value", 200),
+        "latency_ms": lat,
+        "properties_json": json.dumps(props, ensure_ascii=False)[:4000],
+    }
+
+
+def _row_to_dict(row) -> dict:
+    d = dict(zip(COLUMNS, row))
+    try:
+        d["properties"] = json.loads(d.pop("properties_json") or "{}")
+    except (json.JSONDecodeError, TypeError):
+        d.pop("properties_json", None)
+        d["properties"] = {}
+    return d
+
+
+# ── SQLite backend ───────────────────────────────────────────────
+
+def _sqlite_path() -> str:
+    return os.path.join(settings.STORAGE_DIR, "analytics.db")
+
+
+def _sq_conn():
+    os.makedirs(settings.STORAGE_DIR, exist_ok=True)
+    conn = sqlite3.connect(_sqlite_path(), timeout=10)
+    conn.execute("PRAGMA journal_mode=WAL")
+    return conn
+
+
+def _sq_init():
+    conn = _sq_conn()
+    conn.execute("""
+        CREATE TABLE IF NOT EXISTS raw_events (
+            event_id TEXT PRIMARY KEY,
+            event_time TEXT NOT NULL,
+            event_ts REAL NOT NULL,
+            server_ts REAL NOT NULL,
+            user_id TEXT NOT NULL DEFAULT '',
+            session_id TEXT NOT NULL DEFAULT '',
+            task_id TEXT NOT NULL DEFAULT '',
+            feature TEXT NOT NULL DEFAULT '',
+            step TEXT NOT NULL DEFAULT '',
+            event_name TEXT NOT NULL DEFAULT '',
+            event_value TEXT NOT NULL DEFAULT '',
+            latency_ms INTEGER,
+            properties_json TEXT NOT NULL DEFAULT '{}'
+        )
+    """)
+    conn.execute("CREATE INDEX IF NOT EXISTS ix_ev_server_ts ON raw_events (server_ts)")
+    conn.execute("CREATE INDEX IF NOT EXISTS ix_ev_user ON raw_events (user_id, server_ts)")
+    conn.execute("CREATE INDEX IF NOT EXISTS ix_ev_task ON raw_events (task_id)")
+    conn.commit()
+    conn.close()
+
+
+def _sq_insert(rows: list[dict]) -> int:
+    conn = _sq_conn()
+    placeholders = ",".join(["?"] * len(COLUMNS))
+    cur = conn.executemany(
+        "INSERT OR IGNORE INTO raw_events (%s) VALUES (%s)" % (",".join(COLUMNS), placeholders),
+        [tuple(r[c] for c in COLUMNS) for r in rows],
+    )
+    n = cur.rowcount
+    conn.commit()
+    conn.close()
+    return max(0, n)
+
+
+def _sq_query(where: str, params: list, limit: int, desc: bool) -> list[dict]:
+    conn = _sq_conn()
+    cur = conn.execute(
+        "SELECT %s FROM raw_events %s ORDER BY server_ts %s LIMIT ?"
+        % (",".join(COLUMNS), where, "DESC" if desc else "ASC"),
+        (*params, limit),
+    )
+    rows = [_row_to_dict(r) for r in cur.fetchall()]
+    conn.close()
+    return rows
+
+
+def _sq_purge(before_ts: float) -> int:
+    conn = _sq_conn()
+    cur = conn.execute("DELETE FROM raw_events WHERE server_ts < ?", (before_ts,))
+    n = cur.rowcount
+    conn.commit()
+    conn.close()
+    return max(0, n)
+
+
+def _sq_stats() -> dict:
+    conn = _sq_conn()
+    row = conn.execute("SELECT COUNT(*), MIN(server_ts), MAX(server_ts) FROM raw_events").fetchone()
+    conn.close()
+    return {"rows": row[0] or 0, "first_ts": row[1], "last_ts": row[2]}
+
+
+# ── PostgreSQL backend ───────────────────────────────────────────
+
+try:
+    import psycopg2
+    import psycopg2.extras
+    _PG_AVAILABLE = True
+except ImportError:
+    _PG_AVAILABLE = False
+
+
+def _pg_conn():
+    conn = psycopg2.connect(settings.DATABASE_URL, connect_timeout=5)
+    conn.autocommit = True
+    return conn
+
+
+def _pg_init():
+    conn = _pg_conn()
+    cur = conn.cursor()
+    cur.execute("""
+        CREATE TABLE IF NOT EXISTS raw_events (
+            event_id TEXT PRIMARY KEY,
+            event_time TEXT NOT NULL,
+            event_ts DOUBLE PRECISION NOT NULL,
+            server_ts DOUBLE PRECISION NOT NULL,
+            user_id TEXT NOT NULL DEFAULT '',
+            session_id TEXT NOT NULL DEFAULT '',
+            task_id TEXT NOT NULL DEFAULT '',
+            feature TEXT NOT NULL DEFAULT '',
+            step TEXT NOT NULL DEFAULT '',
+            event_name TEXT NOT NULL DEFAULT '',
+            event_value TEXT NOT NULL DEFAULT '',
+            latency_ms BIGINT,
+            properties_json TEXT NOT NULL DEFAULT '{}'
+        )
+    """)
+    cur.execute("CREATE INDEX IF NOT EXISTS ix_ev_server_ts ON raw_events (server_ts)")
+    cur.execute("CREATE INDEX IF NOT EXISTS ix_ev_user ON raw_events (user_id, server_ts)")
+    cur.execute("CREATE INDEX IF NOT EXISTS ix_ev_task ON raw_events (task_id)")
+    cur.close()
+    conn.close()
+
+
+def _pg_insert(rows: list[dict]) -> int:
+    conn = _pg_conn()
+    cur = conn.cursor()
+    psycopg2.extras.execute_values(
+        cur,
+        "INSERT INTO raw_events (%s) VALUES %%s ON CONFLICT (event_id) DO NOTHING" % ",".join(COLUMNS),
+        [tuple(r[c] for c in COLUMNS) for r in rows],
+        page_size=200,
+    )
+    n = cur.rowcount
+    cur.close()
+    conn.close()
+    return max(0, n)
+
+
+def _pg_query(where: str, params: list, limit: int, desc: bool) -> list[dict]:
+    conn = _pg_conn()
+    cur = conn.cursor()
+    cur.execute(
+        "SELECT %s FROM raw_events %s ORDER BY server_ts %s LIMIT %%s"
+        % (",".join(COLUMNS), where.replace("?", "%s"), "DESC" if desc else "ASC"),
+        (*params, limit),
+    )
+    rows = [_row_to_dict(r) for r in cur.fetchall()]
+    cur.close()
+    conn.close()
+    return rows
+
+
+def _pg_purge(before_ts: float) -> int:
+    conn = _pg_conn()
+    cur = conn.cursor()
+    cur.execute("DELETE FROM raw_events WHERE server_ts < %s", (before_ts,))
+    n = cur.rowcount
+    cur.close()
+    conn.close()
+    return max(0, n)
+
+
+def _pg_stats() -> dict:
+    conn = _pg_conn()
+    cur = conn.cursor()
+    cur.execute("SELECT COUNT(*), MIN(server_ts), MAX(server_ts) FROM raw_events")
+    row = cur.fetchone()
+    cur.close()
+    conn.close()
+    return {"rows": row[0] or 0, "first_ts": row[1], "last_ts": row[2]}
+
+
+# ── Chọn backend (lười; thử PG trước, lỗi thì lùi SQLite) ────────
+
+_backend: str | None = None
+
+
+def _resolve() -> str:
+    global _backend
+    if _backend is not None:
+        return _backend
+    if _PG_AVAILABLE and settings.DATABASE_URL:
+        try:
+            _pg_init()
+            _backend = "pg"
+            print("[analytics] Using PostgreSQL backend")
+            return _backend
+        except Exception as ex:
+            print(f"[analytics] PostgreSQL unavailable ({ex}), fallback to SQLite")
+    _sq_init()
+    _backend = "sqlite"
+    print(f"[analytics] Using SQLite backend ({_sqlite_path()})")
+    return _backend
+
+
+def backend_name() -> str:
+    return _resolve()
+
+
+# ── API công khai ────────────────────────────────────────────────
+
+def insert(events: list[dict]) -> int:
+    """Ghi một lô event ĐÃ chuẩn hoá. Trả số dòng thực sự thêm mới."""
+    rows = [e for e in events if e.get("event_name") and e.get("user_id")]
+    if not rows:
+        return 0
+    with _lock:
+        return _pg_insert(rows) if _resolve() == "pg" else _sq_insert(rows)
+
+
+def query(from_ts: float | None = None, to_ts: float | None = None,
+          user_id: str = "", feature: str = "", task_id: str = "",
+          limit: int = MAX_ROWS, newest_first: bool = False) -> list[dict]:
+    """Lấy event thô trong khoảng (lọc theo server_ts — đồng hồ máy chủ).
+
+    `newest_first`: BẮT BUỘC bật khi có cắt `limit` mà muốn xem log mới nhất.
+    Sắp tăng dần rồi LIMIT sẽ lấy nhầm N dòng CŨ NHẤT — ETL cần thứ tự tăng dần
+    và lấy hết nên để mặc định, còn màn "log thô" thì phải đảo.
+    """
+    clauses: list[str] = []
+    params: list = []
+    if from_ts is not None:
+        clauses.append("server_ts >= ?")
+        params.append(from_ts)
+    if to_ts is not None:
+        clauses.append("server_ts < ?")
+        params.append(to_ts)
+    if user_id:
+        clauses.append("user_id = ?")
+        params.append(user_id.strip().lower())
+    if feature:
+        clauses.append("feature = ?")
+        params.append(feature)
+    if task_id:
+        clauses.append("task_id = ?")
+        params.append(task_id)
+    where = ("WHERE " + " AND ".join(clauses)) if clauses else ""
+    limit = max(1, min(int(limit or MAX_ROWS), MAX_ROWS))
+    if _resolve() == "pg":
+        return _pg_query(where, params, limit, newest_first)
+    return _sq_query(where, params, limit, newest_first)
+
+
+def purge_old(days: int | None = None) -> int:
+    """Xoá log cũ hơn `days` ngày (mặc định ANALYTICS_RETENTION_DAYS)."""
+    d = days if days is not None else settings.ANALYTICS_RETENTION_DAYS
+    if not d or d <= 0:
+        return 0
+    before = time.time() - d * 86400
+    with _lock:
+        return _pg_purge(before) if _resolve() == "pg" else _sq_purge(before)
+
+
+def stats() -> dict:
+    st = _pg_stats() if _resolve() == "pg" else _sq_stats()
+    st["backend"] = _backend
+    st["retention_days"] = settings.ANALYTICS_RETENTION_DAYS
+    return st

backend/app/services/analytics/track.py

@@ -0,0 +1,73 @@
+"""Ghi event TỪ PHÍA MÁY CHỦ (dòng máy chạy).
+
+Phân vai rõ ràng (spec §1 "hai chiếc đồng hồ"):
+    - Hành vi người  -> frontend ghi (thời gian tường, gồm cả lúc ngồi nghĩ).
+    - Máy chạy       -> BACKEND ghi ở đây, vì chỉ máy chủ biết job rời hàng đợi
+      lúc nào và chạy hết bao lâu. Frontend KHÔNG được bắn `job_done` nữa,
+      tránh đếm đôi.
+
+Ghi log không bao giờ được làm hỏng job: mọi lỗi ở đây đều nuốt.
+"""
+
+from __future__ import annotations
+
+import threading
+import uuid
+from datetime import datetime, timezone
+
+# Ghi vào DB ở luồng riêng: một cú INSERT chậm (Neon vừa thức dậy) không được
+# chặn worker đang chạy job.
+_pool_lock = threading.Lock()
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="milliseconds")
+
+
+def ctx_from(body: dict | None) -> dict:
+    """Bóc 4 tầng định danh mà frontend gửi kèm khi tạo job."""
+    b = body or {}
+    return {
+        "user_id": str(b.get("user_id") or b.get("username") or "")[:120],
+        "session_id": str(b.get("session_id") or "")[:64],
+        "task_id": str(b.get("task_id") or "")[:64],
+        "feature": str(b.get("feature") or "")[:40],
+        "phase": str(b.get("phase") or "")[:40],
+        "attempt": b.get("attempt"),
+    }
+
+
+def emit(event_name: str, ctx: dict, *, step: str = "run",
+         latency_ms: int | None = None, event_value: str = "",
+         **props) -> None:
+    """Ghi một dòng event. Thiếu user_id -> bỏ qua (không có gì để quy về ai)."""
+    ctx = ctx or {}
+    if not ctx.get("user_id"):
+        return
+
+    def _work():
+        try:
+            from . import storage as store
+            extra = {k: v for k, v in props.items() if v is not None}
+            if ctx.get("phase"):
+                extra.setdefault("phase", ctx["phase"])
+            if ctx.get("attempt") is not None:
+                extra.setdefault("attempt", ctx["attempt"])
+            extra.setdefault("src", "backend")
+            store.insert([store.normalize({
+                "event_id": uuid.uuid4().hex,
+                "event_time": now_iso(),
+                "user_id": ctx.get("user_id", ""),
+                "session_id": ctx.get("session_id", ""),
+                "task_id": ctx.get("task_id", ""),
+                "feature": ctx.get("feature", ""),
+                "step": step,
+                "event_name": event_name,
+                "event_value": event_value,
+                "latency_ms": latency_ms,
+                "properties": extra,
+            })])
+        except Exception as ex:  # pragma: no cover
+            print(f"[analytics] emit {event_name} error: {ex}")
+
+    threading.Thread(target=_work, daemon=True).start()

backend/tests/run_tests.py

@@ -22,6 +22,21 @@ BACKEND = os.path.dirname(HERE)
 if BACKEND not in sys.path:
     sys.path.insert(0, BACKEND)
 
+# VÙNG LÀM VIỆC RIÊNG CHO TEST — đặt TRƯỚC khi import bất kỳ module app nào.
+# Không ép thì test dùng STORAGE_DIR thật trong .env: mỗi lần chạy vừa đổ thư mục
+# rác vào đó, vừa kích hoạt cleanup_old xoá mất phiên làm việc thật của người dùng.
+# Chỉ set biến môi trường là chưa đủ vì config load .env với override=True.
+import tempfile  # noqa: E402
+
+_TEST_STORAGE = tempfile.mkdtemp(prefix="tnt_tests_")
+os.environ["STORAGE_DIR"] = _TEST_STORAGE
+try:
+    from app.config import settings as _settings
+
+    _settings.STORAGE_DIR = _TEST_STORAGE
+except Exception:  # pragma: no cover - thiếu deps thì để test tự báo lỗi
+    pass
+
 GREEN, RED, DIM, BOLD, RESET = "\033[32m", "\033[31m", "\033[2m", "\033[1m", "\033[0m"
 
 
@@ -44,6 +59,7 @@ def main() -> int:
     failures = []
 
     print(f"{BOLD}TNT Content AI — bộ test luồng backend{RESET}")
+    print(f"{DIM}vùng làm việc test: {_TEST_STORAGE}{RESET}")
     print(f"{DIM}python {sys.version.split()[0]} · {len(modules)} file test{RESET}\n")
 
     for modname in modules:

backend/tests/test_analytics.py

@@ -0,0 +1,237 @@
+"""Test theo dõi người dùng: ghi log thô -> suy ra 9 chỉ số (A1-A5, B1-B4).
+
+Cô lập bằng cách trỏ STORAGE_DIR vào thư mục tạm TRƯỚC khi import storage, và
+ép DATABASE_URL rỗng để luôn chạy nhánh SQLite (không đụng Postgres thật).
+"""
+from __future__ import annotations
+
+import os
+import tempfile
+import time
+import uuid
+from datetime import datetime, timedelta, timezone
+
+_TEST_STORAGE = tempfile.mkdtemp(prefix="tnt_an_")
+os.environ["STORAGE_DIR"] = _TEST_STORAGE
+
+from app.config import settings           # noqa: E402
+
+settings.STORAGE_DIR = _TEST_STORAGE      # .env của máy load override -> ép lại
+settings.DATABASE_URL = ""                # ép SQLite
+os.makedirs(_TEST_STORAGE, exist_ok=True)
+
+from app.services.analytics import etl, storage as store   # noqa: E402
+
+TZ = timezone(timedelta(hours=7))
+T0 = time.time() - 3600
+
+
+def _ev(off, name, step, *, feature="dub", task="task_1", sess="sess_1",
+        user="an", lat=None, value="", **props):
+    """Một dòng log đã chuẩn hoá, đặt tại mốc T0+off giây."""
+    ts = T0 + off
+    row = store.normalize({
+        "event_id": uuid.uuid4().hex,
+        "event_time": datetime.fromtimestamp(ts, TZ).isoformat(timespec="milliseconds"),
+        "user_id": user, "session_id": sess, "task_id": task, "feature": feature,
+        "step": step, "event_name": name, "event_value": value,
+        "latency_ms": lat, "properties": props,
+    }, ts)
+    row["event_ts"] = ts                  # giữ nguyên trục thời gian giả lập
+    # storage.normalize() trả dạng GHI (properties_json). Khi đọc lại từ DB,
+    # _row_to_dict() bung thành `properties` dict — ETL dùng dạng đó. Cho dòng
+    # mang cả hai để test được cả nhánh ghi lẫn nhánh tính chỉ số.
+    row["properties"] = dict(props)
+    return row
+
+
+def _one_full_task():
+    """Một task dub hoàn chỉnh: 2 lần máy, người sửa ở giữa, tải về, 👍."""
+    return [
+        _ev(0, "session_start", "open", feature="", task=""),
+        _ev(2, "feature_open", "open"),
+        _ev(6, "upload_done", "prepare"),
+        _ev(9, "job_queued", "run", job_id="j1"),
+        _ev(11, "job_started", "run", job_id="j1"),
+        _ev(41, "job_done", "run", lat=30000, job_id="j1", phase="asr_translate"),
+        _ev(120, "edit_translation", "review"),
+        _ev(200, "job_queued", "run", job_id="j2"),
+        _ev(202, "job_started", "run", job_id="j2"),
+        _ev(260, "job_done", "run", lat=59000, job_id="j2", phase="tts"),
+        _ev(275, "output_download", "output", value="mp4", count=2,
+            success_type="download"),
+        _ev(277, "thumbs_feedback", "output", value="up"),
+        _ev(280, "feature_complete", "done", success_type="download"),
+    ]
+
+
+# ── Chuẩn hoá dòng log ───────────────────────────────────────────
+
+def test_normalize_drops_zero_latency():
+    """latency_ms chỉ dành cho dòng MÁY chạy: 0/rỗng phải thành None.
+
+    Nhét 0 vào là kéo tụt trung bình tốc độ máy (spec §2 "quy tắc vàng").
+    """
+    assert store.normalize({"event_name": "x", "user_id": "a", "latency_ms": 0})["latency_ms"] is None
+    assert store.normalize({"event_name": "x", "user_id": "a", "latency_ms": ""})["latency_ms"] is None
+    assert store.normalize({"event_name": "x", "user_id": "a", "latency_ms": -5})["latency_ms"] is None
+    assert store.normalize({"event_name": "x", "user_id": "a", "latency_ms": 1200})["latency_ms"] == 1200
+
+
+def test_normalize_parses_time_and_props():
+    r = store.normalize({
+        "event_name": "feature_open", "user_id": "  AN  ",
+        "event_time": "2026-08-24T09:25:09.300+07:00",
+        "properties": {"entry": "sidebar"},
+    })
+    assert r["user_id"] == "an"                       # chuẩn hoá để gom đúng người
+    assert abs(r["event_ts"] - 1787538309.3) < 1.0     # 09:25:09.300 +07:00
+    assert '"entry"' in r["properties_json"]
+    # thời gian sai định dạng -> lùi về giờ máy chủ, không làm vỡ luồng
+    bad = store.normalize({"event_name": "x", "user_id": "a", "event_time": "hôm qua"})
+    assert bad["event_ts"] > 0
+
+
+# ── Kho lưu ──────────────────────────────────────────────────────
+
+def test_insert_query_and_dedup():
+    rows = _one_full_task()
+    n = store.insert(rows)
+    assert n == len(rows)
+    assert store.insert(rows) == 0                    # cùng event_id -> không nhân đôi
+    got = store.query(user_id="an")
+    assert len(got) >= len(rows)
+    assert all(g["user_id"] == "an" for g in got)
+    # dòng thiếu user_id thì bỏ, không rác vào bảng
+    assert store.insert([store.normalize({"event_name": "x"})]) == 0
+
+
+def test_query_newest_first_respects_limit():
+    """Cắt `limit` mà xếp tăng dần sẽ lấy nhầm N dòng CŨ NHẤT — màn log thô cần MỚI nhất."""
+    old = store.query(limit=3)
+    new = store.query(limit=3, newest_first=True)
+    assert len(old) == len(new) == 3
+    assert new[0]["server_ts"] >= old[-1]["server_ts"]
+    assert [r["server_ts"] for r in new] == sorted([r["server_ts"] for r in new], reverse=True)
+
+
+def test_purge_old_keeps_recent():
+    before = store.stats()["rows"]
+    assert store.purge_old(days=3650) == 0            # chưa có gì cũ tới vậy
+    assert store.stats()["rows"] == before
+
+
+# ── ETL: dựng task & chỉ số ──────────────────────────────────────
+
+def test_task_metrics_from_one_session():
+    evs = _one_full_task()
+    tasks = etl.build_tasks(evs)
+    assert len(tasks) == 1
+    t = tasks[0]
+
+    assert t["has_output"] and t["success_type"] == "download"
+    # A1 = từ lúc mở tool tới ĐẦU RA đầu tiên (275 - 2 giây)
+    assert abs(t["duration_ms"] - 273000) < 50
+    # B4 = tổng thời gian máy chạy thật, KHÔNG gồm chờ hàng đợi
+    assert t["machine_ms"] == 89000
+    assert abs(t["wait_ms"] - 4000) < 50               # (11-9) + (202-200)
+    assert t["attempts"] == 2                          # A4: hai lần job_done
+    assert t["produced"] == 2                          # B1: count=2
+    assert t["thumbs_up"] == 1 and t["thumbs_down"] == 0
+
+
+def test_step_durations_stop_at_done():
+    """Bấm 👍 sau khi xong mang step=output; dòng thời gian không được hiện thêm bước sau 'done'."""
+    steps = [d["step"] for d in etl.step_durations(etl.build_tasks(_one_full_task())[0])]
+    assert steps[-1] == "done"
+    assert steps.count("done") == 1
+
+
+def test_abandon_and_completion_rate():
+    """A3 = task có đầu ra / tổng task; bỏ dở ghi rõ bước cuối chạm tới."""
+    evs = _one_full_task() + [
+        _ev(300, "feature_open", "open", feature="shuffle", task="task_2"),
+        _ev(340, "upload_done", "prepare", feature="shuffle", task="task_2"),
+        _ev(900, "feature_abandon", "prepare", feature="shuffle", task="task_2",
+            last_step="prepare", reason="qua_nhieu_clip"),
+    ]
+    s = etl.summarize(evs)
+    assert s["overall"]["tasks"] == 2
+    assert s["overall"]["tasks_done"] == 1
+    assert abs(s["overall"]["completion_rate"] - 0.5) < 1e-9
+    sh = next(f for f in s["features"] if f["feature"] == "shuffle")
+    assert sh["abandon_by_step"] == {"prepare": 1}
+    assert sh["label"] == "Xào video"
+
+
+def test_forward_counts_as_success():
+    """Chuyển tiếp sang tool khác cũng là ĐẦU RA hợp lệ (spec §6.2)."""
+    evs = [
+        _ev(0, "feature_open", "open", feature="down_list", task="t_fw"),
+        _ev(5, "output_forward", "output", feature="down_list", task="t_fw",
+            value="cut", success_type="forward", to="cut", count=3),
+    ]
+    t = etl.build_tasks(evs)[0]
+    assert t["has_output"] and t["success_type"] == "forward"
+    prods = etl.summarize(evs)["products"]
+    assert prods[0]["kind"].startswith("→")            # đọc ra "chuyển sang", không lẫn đuôi file
+    assert prods[0]["count"] == 3
+
+
+def test_job_speed_split_by_phase():
+    """B2 phải tách tốc độ theo TỪNG BƯỚC máy, không gộp một cục."""
+    jobs = etl.summarize(_one_full_task())["jobs"]
+    phases = {j["phase"]: j["median_ms"] for j in jobs}
+    assert phases["asr_translate"] == 30000
+    assert phases["tts"] == 59000
+
+
+def test_passive_pages_are_not_tasks():
+    """page_view (trang chủ/hướng dẫn) không có task_id -> không tính vào A3."""
+    evs = _one_full_task() + [
+        _ev(400, "page_view", "open", feature="home", task=""),
+        _ev(410, "page_view", "open", feature="guide", task=""),
+    ]
+    s = etl.summarize(evs)
+    assert s["overall"]["tasks"] == 1
+    assert all(f["feature"] not in ("home", "guide") for f in s["features"])
+
+
+# ── ETL: phiên làm việc ──────────────────────────────────────────
+
+def test_session_splits_on_long_silence():
+    """Im lặng quá ngưỡng -> tách thành hai phiên (spec §6: session_end là mốc mềm)."""
+    gap = (settings.SESSION_IDLE_MINUTES + 10) * 60
+    evs = [
+        _ev(0, "session_start", "open", feature="", task="", sess="s"),
+        _ev(60, "feature_open", "open", task="t1", sess="s"),
+        _ev(60 + gap, "feature_open", "open", task="t2", sess="s"),
+        _ev(120 + gap, "upload_done", "prepare", task="t2", sess="s"),
+    ]
+    sessions = etl.build_sessions(evs)
+    assert len(sessions) == 2
+    # thời lượng DÙNG THẬT không được cộng cả quãng im lặng
+    assert sum(s["active_ms"] for s in sessions) < gap * 1000
+    assert abs(sessions[0]["active_ms"] - 60000) < 50
+
+
+def test_returning_user_needs_two_days():
+    """A5 = một user xuất hiện ở >= 2 ngày khác nhau."""
+    day = 86400
+    evs = [
+        _ev(0, "feature_open", "open", task="t1", user="an"),
+        _ev(-2 * day, "feature_open", "open", task="t0", user="an", sess="s0"),
+        _ev(0, "feature_open", "open", task="t2", user="binh", sess="sb"),
+    ]
+    users = {u["user_id"]: u for u in etl.summarize(evs)["users"]}
+    assert users["an"]["returning"] is True
+    assert users["binh"]["returning"] is False
+
+
+def test_user_detail_lists_sessions_and_tasks():
+    d = etl.user_detail(_one_full_task(), "an")
+    assert d["user_id"] == "an" and len(d["sessions"]) == 1
+    task = d["sessions"][0]["tasks"][0]
+    assert task["label"] == "Dịch / đổi giọng"
+    assert task["has_output"] and task["machine_ms"] == 89000
+    assert [j["latency_ms"] for j in task["jobs"]] == [30000, 59000]

backend/tests/test_cut.py

@@ -73,16 +73,17 @@ def _contiguous(segs, total):
         assert b.start_frame == a.end_frame
 
 
-def test_extract_features_no_cv2():
-    """Đọc frame qua pipe ffmpeg (không cần OpenCV) -> có motion + histogram."""
+def test_frame_signals_returns_motion_and_hist():
+    """Quét video 1 lần -> hai chuỗi tín hiệu (đổi màu, chuyển động) cùng độ dài.
+
+    Đây là nền của scene_cut/highlight_cut: sai độ dài là mọi mốc cắt lệch theo.
+    """
     d = tempfile.mkdtemp()
     v = _multi_scene_video(os.path.join(d, "in.mp4"))
-    info = probe(v)
-    feats = modes.extract_features(info, use_clip=False)
-    assert feats.times.size > 3
-    assert feats.motion.size == feats.times.size
-    assert feats.color_hist.shape[0] == feats.times.size
-
+    hist_diff, motion = modes._frame_signals(v)
+    assert hist_diff.size > 3
+    assert hist_diff.size == motion.size
+    assert float(hist_diff.max()) > 0.0        # video nhiều cảnh -> phải có đổi màu
 
 def test_smart_cut_runs_and_detects_scenes():
     """Smart chạy được KHÔNG có CLIP (fallback histogram) và bắt được ranh giới."""
@@ -113,22 +114,38 @@ def test_scene_and_highlight_no_crash():
         _contiguous(segs, info.nb_frames)
 
 
-def test_smart_uses_clip_when_available():
-    """Khi có open_clip+torch -> smart DÙNG CLIP (embedding 512 chiều), không phải histogram."""
-    if not modes._clip_available():
-        return                                    # môi trường không có CLIP -> bỏ qua
+def test_smart_cut_uses_clip_or_falls_back():
+    """smart dùng CLIP khi có torch+open_clip; thiếu thì LÙI scene_cut, không vỡ.
+
+    Dù đi nhánh nào, các khúc trả về vẫn phải liền mạch và phủ hết video.
+    """
+    try:
+        import torch  # noqa: F401
+        import open_clip  # noqa: F401
+        has_clip = True
+    except Exception:
+        has_clip = False
+
     d = tempfile.mkdtemp()
     v = _multi_scene_video(os.path.join(d, "in.mp4"))
     info = probe(v)
-    feats = modes.extract_features(info, use_clip=True)
-    assert feats.clip_emb is not None
-    assert feats.clip_emb.shape[0] == feats.times.size
-    assert feats.clip_emb.shape[1] == 512         # ViT-B-32
-    # và vẫn cắt ra khúc liền mạch
-    segs = modes.build_segments(info, "smart", n=3)
-    assert len(segs) == 3
-    _contiguous(segs, info.nb_frames)
 
+    called = {"clip": False}
+    orig = modes._smart_cut_clip
+
+    def spy(inf, n):
+        called["clip"] = True
+        return orig(inf, n)
+
+    modes._smart_cut_clip = spy
+    try:
+        segs = modes.smart_cut(info, n=3)
+    finally:
+        modes._smart_cut_clip = orig
+
+    assert called["clip"] is has_clip, "có CLIP thì phải dùng CLIP, không có thì lùi scene_cut"
+    assert len(segs) >= 1
+    _contiguous(segs, info.nb_frames)
 
 def test_smart_segments_are_cuttable():
     """Khúc smart cắt ra file được, không tiếng."""

backend/tests/test_dub.py

@@ -54,37 +54,48 @@ def test_run_dub_multi_speaker_flag_ok():
     assert has_video(res.video_out)            # bật nhiều người nói vẫn ra video
 
 
-def test_asr_routes_to_local_without_groq_key():
-    """Không có GROQ key -> transcribe gọi thẳng faster-whisper local (không gọi Groq)."""
+def test_asr_requires_groq_key():
+    """ASR chạy Groq Whisper; thiếu key -> báo lỗi RÕ RÀNG để pipeline lùi passthrough.
+
+    Bản dự phòng faster-whisper local đã được GỠ CÓ CHỦ Ý (xem requirements.txt:
+    "faster-whisper — GỠ: không dùng trong code"), nên hợp đồng hiện tại là
+    transcribe() phải NÉM LỖI thay vì im lặng trả rỗng.
+    """
     from app.config import settings
-    called = {"local": False}
-    orig_local, orig_key = asr._transcribe_local, settings.GROQ_API_KEY
-    asr._transcribe_local = lambda w: (called.__setitem__("local", True),
-                                       ([asr.Segment(0.0, 1.0, "hi")], "en"))[1]
+    orig_key = settings.GROQ_API_KEY
     settings.GROQ_API_KEY = ""
     try:
-        segs, lang = asr.transcribe("whatever.wav")
+        raised = False
+        try:
+            asr.transcribe("khong-ton-tai.wav")
+        except Exception:
+            raised = True
+        assert raised, "thiếu GROQ_API_KEY thì transcribe phải ném lỗi"
     finally:
-        asr._transcribe_local, settings.GROQ_API_KEY = orig_local, orig_key
-    assert called["local"] and lang == "en" and segs[0].text == "hi"
-
+        settings.GROQ_API_KEY = orig_key
 
 def test_translate_free_fallback_without_keys():
-    """Không có key Gemini/Groq -> dùng dịch miễn phí (deep-translator)."""
+    """Không có key Gemini/Groq -> dịch miễn phí bằng deep-translator (không cần key)."""
     from app.config import settings
     seg = translate.Segment(0.0, 1.5, "hello world")
-    orig_free = translate._free_translate
+    orig_deep = translate._deep_translate
+    orig_gem, orig_groq = translate._gemini, translate._groq_llm
     orig_g, orig_q = settings.GOOGLE_API_KEY, settings.GROQ_API_KEY
-    translate._free_translate = lambda text, lang: f"[{lang}]{text}"
+
+    def boom(*a, **k):
+        raise RuntimeError("no key")
+
+    translate._deep_translate = lambda text, lang: f"[{lang}]{text}"
+    translate._gemini = translate._groq_llm = boom
     settings.GOOGLE_API_KEY = settings.GROQ_API_KEY = ""
     try:
         out = translate.translate_line(seg, "vi")
     finally:
-        translate._free_translate = orig_free
+        translate._deep_translate = orig_deep
+        translate._gemini, translate._groq_llm = orig_gem, orig_groq
         settings.GOOGLE_API_KEY, settings.GROQ_API_KEY = orig_g, orig_q
     assert out == "[vi]hello world"
-    assert translate.GT_CODE["fil"] == "tl"
-
+    assert translate._DEEP_CODE["fil"] == "tl"        # Filipino -> mã "tl" của Google
 
 def test_run_tts_fallback_wav():
     d = tempfile.mkdtemp()
@@ -104,25 +115,34 @@ def test_atempo_chain_valid():
 
 
 def test_pick_engine_defaults_and_override():
-    """fil mặc định Edge; vi/en theo model local; engine chỉ định thì giữ nguyên."""
+    """vi -> VieNeu (local); en & fil -> Edge; engine chỉ định thì giữ nguyên.
+
+    en dùng Edge chứ không phải XTTS: XTTS/Coqui nặng RAM và đã được gỡ khỏi
+    requirements ("XTTS-v2 không dùng mặc định — en/fil chạy Edge").
+    """
     assert tts.pick_engine(tts.VoiceConfig(target_lang="fil", engine="auto")) == "edge"
     assert tts.pick_engine(tts.VoiceConfig(target_lang="vi", engine="auto")) == "vieneu"
-    assert tts.pick_engine(tts.VoiceConfig(target_lang="en", engine="auto")) == "xtts"
-    # chọn edge cho mọi ngôn ngữ
+    assert tts.pick_engine(tts.VoiceConfig(target_lang="en", engine="auto")) == "edge"
+    # chọn tay thì tôn trọng lựa chọn
     assert tts.pick_engine(tts.VoiceConfig(target_lang="vi", engine="edge")) == "edge"
-    assert tts.pick_engine(tts.VoiceConfig(target_lang="en", engine="edge")) == "edge"
+    assert tts.pick_engine(tts.VoiceConfig(target_lang="en", engine="xtts")) == "xtts"
 
+def test_edge_voice_defaults_and_voice_list():
+    """Giọng Edge: mặc định theo ngôn ngữ, người dùng chọn tay qua `preset`.
 
-def test_edge_voice_mapping():
-    """Edge chọn giọng theo (ngôn ngữ, giới tính); preset là id giọng Edge thì ưu tiên."""
-    assert tts.edge_voice(tts.VoiceConfig(target_lang="vi", gender="female")) == "vi-VN-HoaiMyNeural"
-    assert tts.edge_voice(tts.VoiceConfig(target_lang="vi", gender="male")) == "vi-VN-NamMinhNeural"
-    assert tts.edge_voice(tts.VoiceConfig(target_lang="fil", gender="male")) == "fil-PH-AngeloNeural"
-    # "nam" tiếng Việt cũng hiểu là male
-    assert tts.edge_voice(tts.VoiceConfig(target_lang="en", gender="Nam")) == "en-US-GuyNeural"
-    # preset là id giọng Edge -> dùng thẳng
-    assert tts.edge_voice(tts.VoiceConfig(target_lang="en", preset="en-GB-RyanNeural")) == "en-GB-RyanNeural"
+    Bản cũ suy giọng t��� giới tính (edge_voice(cfg)); nay giao diện hiện HẲN danh
+    sách giọng (list_voices) rồi gửi id xuống làm `preset`, nên hợp đồng cần giữ là
+    danh sách và giọng mặc định phải khớp nhau.
+    """
+    for lang, prefix in (("vi", "vi-VN-"), ("fil", "fil-PH-"), ("en", "en-")):
+        assert tts._EDGE_VOICES[lang].startswith(prefix)
 
+    for lang in ("en", "fil"):
+        ids = [vid for _label, vid in tts._EDGE_VOICE_LIST[lang]]
+        assert tts._EDGE_VOICES[lang] in ids, "giọng mặc định phải nằm trong danh sách"
+        voices = tts.list_voices(lang)
+        assert voices and all(v.get("id") and v.get("label") for v in voices)
+        assert tts._EDGE_VOICES[lang] in [v["id"] for v in voices]
 
 def test_synth_line_falls_back_when_engine_breaks():
     """Engine lỗi HOẶC không ra file -> synth_line vẫn để lại 1 wav (khoảng lặng)."""
@@ -143,40 +163,45 @@ def test_synth_line_falls_back_when_engine_breaks():
         assert os.path.exists(out) and duration(out) > 0.0
 
 
-def test_resilient_tts_falls_back_to_edge():
-    """Model chính (vieneu/xtts/voxcpm) hỏng -> ResilientTTS tự dùng Edge để VẪN ra giọng."""
-    cfg = tts.VoiceConfig(target_lang="vi", engine="vieneu")
+def test_load_engine_falls_back_to_edge_when_model_missing():
+    """Model nặng không nạp được -> load_engine tự lùi về Edge để VẪN ra giọng.
 
-    class BadPrimary(tts.TTSEngine):
-        def synth(self, text, out, c):
-            raise RuntimeError("model dead")
+    Trước đây việc này do lớp bọc ResilientTTS lo; nay nằm thẳng trong load_engine.
+    Nhánh "engine chạy nhưng ghi file rỗng" do synth_line lo (test riêng bên dưới).
+    """
+    class Boom(tts.TTSEngine):
+        def __init__(self):
+            raise RuntimeError("model chưa cài")
 
-    calls = {"edge": 0}
+    made = {"edge": 0}
 
     class FakeEdge(tts.TTSEngine):
         def __init__(self):
-            pass
+            made["edge"] += 1
 
         def synth(self, text, out, c):
-            calls["edge"] += 1
-            with open(out, "wb") as f:
-                f.write(b"RIFFfakecontent")     # file KHÔNG rỗng
             return out
 
-    orig_load, orig_edge = tts.load_engine, tts.EdgeTTSEngine
-    tts.load_engine = lambda c: BadPrimary()
+    orig_engines = dict(tts._ENGINES)
+    orig_inst = dict(tts._INSTANCES)
+    orig_edge = tts.EdgeTTSEngine
+    tts._ENGINES["vieneu"] = Boom
     tts.EdgeTTSEngine = FakeEdge
+    tts._INSTANCES.clear()
     try:
-        eng = tts.ResilientTTS(cfg)
-        out = os.path.join(tempfile.mkdtemp(), "v.wav")
-        eng.synth("xin chào", out, cfg)
+        eng = tts.load_engine(tts.VoiceConfig(target_lang="vi", engine="vieneu"))
     finally:
-        tts.load_engine, tts.EdgeTTSEngine = orig_load, orig_edge
-    assert calls["edge"] == 1 and os.path.exists(out) and os.path.getsize(out) > 0
+        tts._ENGINES.clear(); tts._ENGINES.update(orig_engines)
+        tts._INSTANCES.clear(); tts._INSTANCES.update(orig_inst)
+        tts.EdgeTTSEngine = orig_edge
+    assert isinstance(eng, FakeEdge) and made["edge"] == 1
 
+def test_translate_prompt_is_faithful_and_bounded():
+    """Prompt dịch phải GIỮ ĐÚNG NGHĨA (cấm thêm thắt) và chốt độ dài đọc vừa khung giờ.
 
-def test_translate_prompt_is_faithful_and_carries_style():
-    """Prompt dịch phải YÊU CẦU TRUNG THÀNH (không thêm thắt) + mang ngữ điệu đã chọn."""
+    Ngữ điệu (style) KHÔNG còn nằm trong prompt dịch — nó đã chuyển sang khâu TTS
+    (VoiceConfig.style), nên ở đây chỉ kiểm tính trung thành + ràng buộc thời lượng.
+    """
     from app.config import settings
     seg = translate.Segment(0.0, 2.0, "Hello everyone, welcome back to the channel.")
     captured = {}
@@ -189,23 +214,27 @@ def test_translate_prompt_is_faithful_and_carries_style():
     translate._gemini = fake_gemini
     settings.GOOGLE_API_KEY = "x"
     try:
-        out = translate.translate_line(seg, "vi", style="ads")
+        out = translate.translate_line(seg, "vi", source_lang="en")
     finally:
         translate._gemini, settings.GOOGLE_API_KEY = orig_g, orig_key
     assert "chào mừng" in out
     p = captured["p"].lower()
-    assert "be faithful" in p                         # ưu tiên trung thành
-    assert "do not add" in p and "embellish" in p     # cấm thêm thắt/phóng đại
-    assert "register" in p                            # ngữ điệu (nhẹ) có trong prompt
+    assert "keep all the real meaning" in p            # trung thành
+    assert "do not pad" in p and "never invent" in p   # cấm thêm thắt
     assert "hello everyone" in p                       # có câu gốc
-    assert "vietnamese" in p
-
-
-def test_style_guide_covers_all_styles():
-    for s in ("natural", "ads", "news", "story"):
-        assert s in translate.STYLE_GUIDE
-    assert translate.has_llm() in (True, False)
-
+    assert "vietnamese" in p                           # ngôn ngữ đích
+    assert "english" in p                              # ngôn ngữ nguồn
+
+def test_all_ui_styles_reach_voice_config():
+    """4 ngữ điệu trên giao diện phải đi lọt xuống VoiceConfig của khâu TTS.
+
+    Trước đây ngữ điệu nằm ở prompt dịch (translate.STYLE_GUIDE); nay nó thuộc
+    khâu đọc, nên hợp đồng cần giữ là pipeline chuyển đúng giá trị xuống TTS.
+    """
+    for st in ("natural", "ads", "news", "story"):
+        cfg = tts.VoiceConfig(target_lang="vi", style=st)
+        assert cfg.style == st
+        assert P.DubOptions(target_lang="vi", style=st).style == st
 
 def test_srt_time_and_write():
     d = tempfile.mkdtemp()

frontend/src/api.js

@@ -1,3 +1,4 @@
+import { currentCtx as trackCtx } from "./lib/track";
 // Client gọi backend FastAPI. Dev: Vite proxy /api -> :8000.
 
 const BASE = "";
@@ -30,6 +31,18 @@ export function uploadWithProgress(path, file, fields = {}, onProgress) {
     for (const [k, v] of Object.entries(fields)) if (v != null) fd.append(k, v);
     const xhr = new XMLHttpRequest();
     xhr.open("POST", BASE + path);
+    // Upload đi bằng XHR (để có % tiến độ) nên KHÔNG qua bản vá fetch trong
+    // lib/track.js -> gắn tay ngữ cảnh theo dõi để backend vẫn quy được về
+    // đúng task của đúng người.
+    try {
+      const c = trackCtx();
+      if (c.user_id) {
+        xhr.setRequestHeader("X-TNT-User", c.user_id);
+        xhr.setRequestHeader("X-TNT-Session", c.session_id);
+        if (c.task_id) xhr.setRequestHeader("X-TNT-Task", c.task_id);
+        if (c.feature) xhr.setRequestHeader("X-TNT-Feature", c.feature);
+      }
+    } catch { /* thiếu header theo dõi không được chặn upload */ }
     if (xhr.upload && onProgress) {
       xhr.upload.onprogress = (e) => {
         if (e.lengthComputable) onProgress(e.loaded, e.total);

frontend/src/components/Layout.jsx

@@ -4,6 +4,7 @@ import Sidebar from "./Sidebar";
 import { useVideoGen } from "../stores/videoGenStore";
 import { useDirty } from "../stores/dirtyStore";
 import { useAuth } from "../stores/authStore";
+import track, { ROUTE_FEATURE } from "../lib/track";
 
 // Fallback nhẹ khi chunk trang đang tải (code-splitting).
 function PageFallback() {
@@ -29,7 +30,21 @@ export default function Layout() {
     if (!authorized) navigate("/dang-nhap", { replace: true });
   }, [authorized]);
 
+  // Theo dõi người dùng: bật một lần, rồi mỗi lần đổi trang là mở "task" mới
+  // cho tool đó (task cũ chưa có đầu ra sẽ tự ghi là bỏ dở).
+  useEffect(() => {
+    if (authorized) track.initTracking();
+  }, [authorized]);
+
+  useEffect(() => {
+    if (!authorized) return;
+    const feature = ROUTE_FEATURE[location.pathname];
+    if (feature) track.featureOpen(feature, { entry: "router" });
+  }, [authorized, location.pathname]);
+
   const handleLogout = () => {
+    track.abandon("logout");
+    track.flush();
     logout();
     navigate("/dang-nhap");
   };

frontend/src/components/ThumbsFeedback.jsx

@@ -0,0 +1,64 @@
+// Nút 👍/👎 ở chỗ hiện kết quả — nguồn duy nhất cho chỉ số B3 (chất lượng đầu ra).
+// Trước đây app không có nút nào để người dùng chấm kết quả, nên B3 không có gì
+// để đếm (User_Flow_and_Tracking_Spec §1.5).
+//
+// Hỏi MỘT LẦN cho mỗi mẻ kết quả, không hỏi từng file: mỗi task chỉ cần một
+// phiếu, hỏi nhiều lần thì người dùng bỏ qua hết.
+
+import { useState } from "react";
+import track from "../lib/track";
+
+export default function ThumbsFeedback({ label = "Kết quả này ổn chứ?", target = "result_set" }) {
+  const [sent, setSent] = useState("");
+  const [note, setNote] = useState("");
+  const [noteSent, setNoteSent] = useState(false);
+
+  const vote = (v) => {
+    if (sent) return;
+    setSent(v);
+    track.thumbs(v, { target });
+  };
+
+  const sendNote = () => {
+    if (!note.trim() || noteSent) return;
+    setNoteSent(true);
+    track.step("feedback_note", "output", { target, chars: note.trim().length }, note.trim().slice(0, 200));
+  };
+
+  return (
+    <div style={{
+      display: "flex", alignItems: "center", gap: 10, flexWrap: "wrap",
+      padding: "8px 12px", background: "var(--orange-tint)",
+      border: "1px solid var(--line)", borderRadius: "var(--radius-sm)",
+      fontSize: 13,
+    }}>
+      {!sent ? (
+        <>
+          <span style={{ color: "var(--ink-2)" }}>{label}</span>
+          <button className="btn sm" onClick={() => vote("up")} title="Ổn">👍 Ổn</button>
+          <button className="btn sm" onClick={() => vote("down")} title="Chưa ổn">👎 Chưa ổn</button>
+        </>
+      ) : sent === "up" ? (
+        <span style={{ color: "var(--green)", fontWeight: 600 }}>👍 Cảm ơn bạn đã đánh giá!</span>
+      ) : (
+        <>
+          <span style={{ color: "var(--ink-2)", fontWeight: 600 }}>👎 Chưa ổn ở đâu?</span>
+          {noteSent ? (
+            <span style={{ color: "var(--green)", fontWeight: 600 }}>Đã ghi nhận, cảm ơn bạn!</span>
+          ) : (
+            <>
+              <input value={note} onChange={(e) => setNote(e.target.value)}
+                onKeyDown={(e) => e.key === "Enter" && sendNote()}
+                placeholder="Không bắt buộc — vd: chữ bị lệch, dịch sai câu cuối…"
+                style={{
+                  flex: "1 1 240px", minWidth: 180, padding: "6px 10px", fontSize: 13,
+                  border: "1px solid var(--line)", borderRadius: "var(--radius-sm)",
+                }} />
+              <button className="btn sm" onClick={sendNote} disabled={!note.trim()}>Gửi</button>
+            </>
+          )}
+        </>
+      )}
+    </div>
+  );
+}

frontend/src/components/admin/UsageCharts.jsx

@@ -0,0 +1,168 @@
+// Biểu đồ SVG thuần cho tab "Quản lý thời lượng".
+// Không thêm thư viện biểu đồ: cả frontend hiện chỉ có react + react-router,
+// mà mấy dạng ở đây (cột ngang, đường theo ngày) vẽ tay còn nhẹ và gọn hơn.
+// Mọi con số đều IN THẲNG lên biểu đồ, không bắt người xem ước lượng theo trục.
+
+// ── Định dạng ───────────────────────────────────────────────────
+
+export function fmtDur(ms) {
+  if (ms == null || Number.isNaN(ms)) return "—";
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s} giây`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return s % 60 ? `${m} phút ${s % 60} giây` : `${m} phút`;
+  const h = Math.floor(m / 60);
+  return m % 60 ? `${h} giờ ${m % 60} phút` : `${h} giờ`;
+}
+
+export function fmtShort(ms) {
+  if (ms == null || Number.isNaN(ms)) return "—";
+  const s = ms / 1000;
+  if (s < 60) return `${s < 10 ? s.toFixed(1) : Math.round(s)}s`;
+  const m = s / 60;
+  if (m < 60) return `${m < 10 ? m.toFixed(1) : Math.round(m)}p`;
+  return `${(m / 60).toFixed(1)}h`;
+}
+
+export const fmtPct = (v) => (v == null ? "—" : `${Math.round(v * 100)}%`);
+export const fmtNum = (v) => (v == null ? "—" : Number(v).toLocaleString("vi-VN"));
+
+export const fmtTime = (ts) =>
+  ts ? new Date(ts * 1000).toLocaleString("vi-VN", { day: "2-digit", month: "2-digit", hour: "2-digit", minute: "2-digit" }) : "—";
+
+// ── Ô chỉ số ────────────────────────────────────────────────────
+
+export function Kpi({ label, value, hint, tone = "" }) {
+  const color = tone === "good" ? "var(--green)" : tone === "warn" ? "var(--orange)" : "var(--ink)";
+  return (
+    <div style={{
+      background: "var(--white)", border: "1px solid var(--line)",
+      borderRadius: "var(--radius-sm)", padding: "12px 14px", minWidth: 0,
+    }}>
+      <div style={{ fontSize: 11.5, color: "var(--muted)", fontWeight: 600, marginBottom: 4 }}>{label}</div>
+      <div style={{ fontSize: 20, fontWeight: 800, color, letterSpacing: "-0.5px", lineHeight: 1.2 }}>{value}</div>
+      {hint && <div style={{ fontSize: 11.5, color: "var(--muted)", marginTop: 3 }}>{hint}</div>}
+    </div>
+  );
+}
+
+// ── Cột ngang ───────────────────────────────────────────────────
+// data: [{ label, value, text?, sub? }]
+
+export function BarChart({ data, color = "var(--orange)", empty = "Chưa có dữ liệu" }) {
+  const rows = (data || []).filter((d) => d && d.value != null);
+  if (!rows.length) return <p className="small muted" style={{ fontStyle: "italic", margin: 0 }}>{empty}</p>;
+  const max = Math.max(...rows.map((r) => Math.abs(r.value)), 1);
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: 9 }}>
+      {rows.map((r, i) => (
+        <div key={r.label + i}>
+          <div style={{ display: "flex", justifyContent: "space-between", gap: 10, fontSize: 12.5, marginBottom: 3 }}>
+            <span style={{ fontWeight: 600, whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" }}>
+              {r.label}
+            </span>
+            <span style={{ color: "var(--ink-2)", whiteSpace: "nowrap", fontWeight: 700 }}>
+              {r.text != null ? r.text : fmtNum(r.value)}
+              {r.sub && <span style={{ color: "var(--muted)", fontWeight: 500 }}> · {r.sub}</span>}
+            </span>
+          </div>
+          <div style={{ height: 8, background: "var(--line-2)", borderRadius: 99, overflow: "hidden" }}>
+            <div style={{
+              width: `${Math.max(2, (Math.abs(r.value) / max) * 100)}%`,
+              height: "100%", background: color, borderRadius: 99,
+            }} />
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+// ── Đường theo ngày ─────────────────────────────────────────────
+// series: [{ key, label, color, values: number[] }] · labels: string[]
+
+export function LineChart({ labels, series, height = 170, unit = "" }) {
+  const pts = labels || [];
+  if (pts.length < 2) {
+    return <p className="small muted" style={{ fontStyle: "italic", margin: 0 }}>Cần ít nhất 2 ngày dữ liệu để vẽ.</p>;
+  }
+  const W = 720, H = height, PADL = 38, PADR = 10, PADT = 12, PADB = 24;
+  const max = Math.max(1, ...series.flatMap((s) => s.values.map((v) => v || 0)));
+  const x = (i) => PADL + (i * (W - PADL - PADR)) / (pts.length - 1);
+  const y = (v) => H - PADB - ((v || 0) / max) * (H - PADT - PADB);
+
+  // Nhãn trục X: thưa ra để không chồng chữ.
+  const stepX = Math.max(1, Math.ceil(pts.length / 8));
+
+  return (
+    <div style={{ width: "100%", overflowX: "auto" }}>
+      <svg viewBox={`0 0 ${W} ${H}`} style={{ width: "100%", minWidth: 420, display: "block" }}
+           role="img" aria-label="Hoạt động theo ngày">
+        {[0, 0.5, 1].map((f) => (
+          <g key={f}>
+            <line x1={PADL} x2={W - PADR} y1={y(max * f)} y2={y(max * f)}
+                  stroke="var(--line)" strokeWidth="1" />
+            <text x={PADL - 6} y={y(max * f) + 4} textAnchor="end"
+                  fontSize="10" fill="var(--muted)">
+              {max * f >= 1000 ? `${Math.round((max * f) / 1000)}k` : Math.round(max * f)}
+            </text>
+          </g>
+        ))}
+        {series.map((s) => (
+          <g key={s.key}>
+            <polyline
+              points={s.values.map((v, i) => `${x(i)},${y(v)}`).join(" ")}
+              fill="none" stroke={s.color} strokeWidth="2"
+              strokeLinejoin="round" strokeLinecap="round" />
+            {s.values.map((v, i) => (
+              <circle key={i} cx={x(i)} cy={y(v)} r="2.5" fill={s.color}>
+                <title>{`${pts[i]} · ${s.label}: ${fmtNum(v)}${unit}`}</title>
+              </circle>
+            ))}
+          </g>
+        ))}
+        {pts.map((p, i) => (i % stepX === 0 ? (
+          <text key={p} x={x(i)} y={H - 7} textAnchor="middle" fontSize="10" fill="var(--muted)">
+            {p.slice(5)}
+          </text>
+        ) : null))}
+      </svg>
+      <div style={{ display: "flex", gap: 14, flexWrap: "wrap", marginTop: 4 }}>
+        {series.map((s) => (
+          <span key={s.key} style={{ fontSize: 12, color: "var(--ink-2)", display: "flex", alignItems: "center", gap: 6 }}>
+            <i style={{ width: 10, height: 3, background: s.color, borderRadius: 2, display: "inline-block" }} />
+            {s.label}
+          </span>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+// ── Thanh chia phần (dùng cho "bỏ dở ở bước nào") ──────────────
+
+const STEP_COLORS = {
+  open: "#c9c2ba", prepare: "var(--orange)", run: "#f2b21c",
+  review: "#3b82f6", output: "var(--green)", done: "#16a34a",
+};
+
+export function StepBar({ counts }) {
+  const entries = Object.entries(counts || {}).filter(([, v]) => v > 0);
+  const total = entries.reduce((a, [, v]) => a + v, 0);
+  if (!total) return <span className="small muted">—</span>;
+  return (
+    <div>
+      <div style={{ display: "flex", height: 8, borderRadius: 99, overflow: "hidden", background: "var(--line-2)" }}>
+        {entries.map(([k, v]) => (
+          <div key={k} title={`${k}: ${v}`} style={{
+            width: `${(v / total) * 100}%`, background: STEP_COLORS[k] || "var(--muted)",
+          }} />
+        ))}
+      </div>
+      <div style={{ fontSize: 11.5, color: "var(--muted)", marginTop: 3 }}>
+        {entries.map(([k, v]) => `${k} ${v}`).join(" · ")}
+      </div>
+    </div>
+  );
+}

frontend/src/components/admin/UsageDashboard.jsx

@@ -0,0 +1,393 @@
+// Tab "Quản lý thời lượng" — người dùng nào, dùng tool gì, mất bao lâu,
+// làm ra sản phẩm gì. Mọi con số tính từ bảng log thô `raw_events` ở backend.
+//
+// Mã chỉ số ghi kèm nhãn (A1..B4) để đối chiếu với User_Flow_and_Tracking_Spec.
+
+import { useCallback, useEffect, useState } from "react";
+import {
+  BarChart, Kpi, LineChart, StepBar,
+  fmtDur, fmtNum, fmtPct, fmtShort, fmtTime,
+} from "./UsageCharts";
+
+const RANGES = [
+  { days: 7, label: "7 ngày" },
+  { days: 30, label: "30 ngày" },
+  { days: 90, label: "90 ngày" },
+];
+
+export default function UsageDashboard({ token }) {
+  const [days, setDays] = useState(30);
+  const [feature, setFeature] = useState("");
+  const [data, setData] = useState(null);
+  const [busy, setBusy] = useState(false);
+  const [err, setErr] = useState("");
+  const [openUser, setOpenUser] = useState("");
+  const [detail, setDetail] = useState(null);
+  const [rawOpen, setRawOpen] = useState(false);
+  const [raw, setRaw] = useState([]);
+
+  const qs = useCallback((extra = {}) => {
+    const p = new URLSearchParams({ token, days: String(days), ...extra });
+    if (feature) p.set("feature", feature);
+    return p.toString();
+  }, [token, days, feature]);
+
+  const load = useCallback(async () => {
+    setBusy(true); setErr("");
+    try {
+      const r = await fetch(`/api/analytics/admin/summary?${qs()}`);
+      const d = await r.json();
+      if (!d.ok) throw new Error(d.detail || "Không đọc được số liệu");
+      setData(d);
+    } catch (e) { setErr(e.message); }
+    finally { setBusy(false); }
+  }, [qs]);
+
+  useEffect(() => { load(); }, [load]);
+
+  const openDetail = async (uid) => {
+    if (openUser === uid) { setOpenUser(""); setDetail(null); return; }
+    setOpenUser(uid); setDetail(null);
+    try {
+      const r = await fetch(`/api/analytics/admin/user?${qs({ user_id: uid })}`);
+      const d = await r.json();
+      if (d.ok) setDetail(d);
+    } catch { /* im lặng, panel sẽ hiện "đang tải" */ }
+  };
+
+  const loadRaw = async () => {
+    setRawOpen((v) => !v);
+    if (raw.length) return;
+    try {
+      const r = await fetch(`/api/analytics/admin/events?${qs({ limit: "300" })}`);
+      const d = await r.json();
+      if (d.ok) setRaw(d.events);
+    } catch { /* bỏ qua */ }
+  };
+
+  const o = data?.overall;
+  const ts = data?.timeseries || [];
+
+  return (
+    <div className="stack" style={{ gap: 18 }}>
+      {/* Thanh lọc */}
+      <div className="card" style={{ display: "flex", gap: 10, alignItems: "center", flexWrap: "wrap" }}>
+        <span style={{ fontSize: 13, fontWeight: 700 }}>Khoảng thời gian</span>
+        {RANGES.map((r) => (
+          <button key={r.days} className={"btn sm" + (days === r.days ? " primary" : "")}
+                  onClick={() => setDays(r.days)}>{r.label}</button>
+        ))}
+        <select value={feature} onChange={(e) => setFeature(e.target.value)}
+                style={{ padding: "7px 10px", fontSize: 13, border: "1px solid var(--line)", borderRadius: "var(--radius-sm)" }}>
+          <option value="">Tất cả tool</option>
+          {(data?.features || []).map((f) => (
+            <option key={f.feature} value={f.feature}>{f.label}</option>
+          ))}
+        </select>
+        <div style={{ flex: 1 }} />
+        <button className="btn sm" onClick={load} disabled={busy}>{busy ? "⏳ Đang tải…" : "↻ Tải lại"}</button>
+        <a className="btn sm" href={`/api/analytics/admin/export.csv?${qs()}`}>⬇ Tải CSV log thô</a>
+      </div>
+
+      {err && (
+        <div style={{ padding: "10px 14px", background: "var(--red-soft)", borderRadius: "var(--radius-sm)", fontSize: 13, fontWeight: 600 }}>
+          Lỗi: {err}
+        </div>
+      )}
+
+      {!data ? (
+        <p className="small muted">Đang tải số liệu…</p>
+      ) : o.events === 0 ? (
+        <div className="card">
+          <div className="panel-title">Chưa có dữ liệu</div>
+          <p className="small muted" style={{ margin: 0 }}>
+            Chưa ghi được thao tác nào trong {days} ngày qua. Số liệu sẽ hiện dần khi người dùng
+            mở tool và làm việc — không cần thao tác gì thêm.
+          </p>
+        </div>
+      ) : (
+        <>
+          {/* Ô chỉ số */}
+          <div style={{ display: "grid", gap: 10, gridTemplateColumns: "repeat(auto-fill, minmax(168px, 1fr))" }}>
+            <Kpi label="Người dùng hoạt động" value={fmtNum(o.users)}
+                 hint={`${o.returning_users} người quay lại (A5)`} />
+            <Kpi label="Phiên làm việc" value={fmtNum(o.sessions)}
+                 hint={`trung vị ${fmtShort(o.session_median_ms)}/phiên`} />
+            <Kpi label="Tổng thời lượng dùng" value={fmtDur(o.active_ms)}
+                 hint="đã trừ lúc bỏ máy > 30′" />
+            <Kpi label="Số việc (task)" value={fmtNum(o.tasks)}
+                 hint={`${o.tasks_done} có sản phẩm`} />
+            <Kpi label="Tỷ lệ làm xong (A3)" value={fmtPct(o.completion_rate)}
+                 tone={o.completion_rate >= 0.7 ? "good" : "warn"}
+                 hint={`${o.abandoned} task bỏ dở`} />
+            <Kpi label="Xong 1 việc mất (A1)" value={fmtDur(o.duration_median_ms)}
+                 hint={`chậm nhất 10%: ${fmtShort(o.duration_p90_ms)}`} />
+            <Kpi label="Số lần bấm/việc (A4)" value={o.attempts_avg == null ? "—" : o.attempts_avg.toFixed(1)}
+                 hint="chạy lại nhiều = khó ưng" />
+            <Kpi label="Máy chạy tổng (B4)" value={fmtDur(o.machine_total_ms)}
+                 hint={`chờ hàng đợi ${fmtShort(o.wait_total_ms)}`} />
+            <Kpi label="Sản phẩm làm ra (B1)" value={fmtNum(o.produced_total)} />
+            <Kpi label="Hài lòng (B3)"
+                 value={o.thumbs_up + o.thumbs_down ? fmtPct(o.thumbs_rate) : "—"}
+                 tone={o.thumbs_rate >= 0.7 ? "good" : o.thumbs_rate == null ? "" : "warn"}
+                 hint={`${o.thumbs_up}👍 / ${o.thumbs_down}👎`} />
+          </div>
+
+          {/* Hoạt động theo ngày */}
+          <div className="card">
+            <div className="panel-title">📈 Hoạt động theo ngày</div>
+            <LineChart
+              labels={ts.map((d) => d.date)}
+              series={[
+                { key: "users", label: "Người dùng", color: "var(--orange)", values: ts.map((d) => d.users) },
+                { key: "tasks", label: "Số việc", color: "#3b82f6", values: ts.map((d) => d.tasks) },
+                { key: "done", label: "Việc có sản phẩm", color: "var(--green)", values: ts.map((d) => d.tasks_done) },
+              ]}
+            />
+            <div style={{ marginTop: 16 }}>
+              <div className="small muted" style={{ marginBottom: 8, fontWeight: 600 }}>Thời lượng dùng mỗi ngày</div>
+              <BarChart data={ts.slice(-14).map((d) => ({
+                label: d.date.slice(5), value: d.active_ms, text: fmtDur(d.active_ms),
+                sub: `${d.users} người`,
+              }))} />
+            </div>
+          </div>
+
+          {/* Tool & sản phẩm */}
+          <div style={{ display: "grid", gap: 18, gridTemplateColumns: "repeat(auto-fit, minmax(320px, 1fr))" }}>
+            <div className="card">
+              <div className="panel-title">🧰 Tool dùng nhiều nhất</div>
+              <BarChart data={(data.features || []).map((f) => ({
+                label: f.label, value: f.tasks, text: `${f.tasks} việc`,
+                sub: `${f.users} người`,
+              }))} />
+            </div>
+            <div className="card">
+              <div className="panel-title">📦 Sản phẩm làm ra</div>
+              <BarChart color="var(--green)" data={(data.products || []).slice(0, 10).map((p) => ({
+                label: `${p.label} · ${p.kind}`, value: p.count, text: fmtNum(p.count),
+              }))} empty="Chưa có sản phẩm nào được tải về." />
+            </div>
+          </div>
+
+          {/* Bảng theo tool */}
+          <div className="card">
+            <div className="panel-title">🧪 Chi tiết theo tool</div>
+            <div className="tablewrap">
+              <table className="list">
+                <thead>
+                  <tr>
+                    <th>Tool</th><th>Người</th><th>Việc</th><th>Xong (A3)</th>
+                    <th>Xong mất (A1)</th><th>Bấm/việc (A4)</th><th>Máy (B4)</th>
+                    <th>Bỏ dở ở bước nào (A2)</th><th>👍 (B3)</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {(data.features || []).map((f) => (
+                    <tr key={f.feature}>
+                      <td style={{ fontWeight: 700 }}>{f.label}</td>
+                      <td>{f.users}</td>
+                      <td>{f.tasks}</td>
+                      <td style={{ color: f.completion_rate >= 0.7 ? "var(--green)" : "var(--orange)", fontWeight: 700 }}>
+                        {fmtPct(f.completion_rate)}
+                      </td>
+                      <td>{fmtShort(f.duration_median_ms)}</td>
+                      <td>{f.attempts_avg == null ? "—" : f.attempts_avg.toFixed(1)}</td>
+                      <td>{fmtShort(f.machine_median_ms)}</td>
+                      <td style={{ minWidth: 150 }}><StepBar counts={f.abandon_by_step} /></td>
+                      <td>{f.thumbs_up + f.thumbs_down ? fmtPct(f.thumbs_rate) : "—"}</td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            </div>
+            <p className="small muted" style={{ margin: "10px 0 0" }}>
+              “Xong mất (A1)” là trung vị từ lúc mở tool tới lúc có sản phẩm đầu tiên — gồm cả thời gian
+              người ngồi chỉnh. “Máy (B4)” chỉ tính lúc máy chạy thật, đã trừ thời gian chờ hàng đợi.
+            </p>
+          </div>
+
+          {/* Bảng theo người */}
+          <div className="card">
+            <div className="panel-title">👥 Theo từng người ({(data.users || []).length})</div>
+            <div className="tablewrap">
+              <table className="list">
+                <thead>
+                  <tr>
+                    <th>Người dùng</th><th>Lần cuối</th><th>Ngày</th><th>Phiên</th>
+                    <th>Thời lượng dùng</th><th>Việc</th><th>Xong</th>
+                    <th>Sản phẩm</th><th>Máy chạy</th><th>Hay dùng</th><th></th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {(data.users || []).map((u) => (
+                    <tr key={u.user_id}>
+                      <td style={{ fontWeight: 700 }}>
+                        {u.user_id}
+                        {u.returning && <span title="Có quay lại dùng (A5)" style={{ marginLeft: 6 }}>🔁</span>}
+                      </td>
+                      <td className="small muted">{fmtTime(u.last_seen)}</td>
+                      <td>{u.days_active}</td>
+                      <td>{u.sessions}</td>
+                      <td style={{ fontWeight: 700 }}>{fmtDur(u.active_ms)}</td>
+                      <td>{u.tasks}</td>
+                      <td style={{ color: u.completion_rate >= 0.7 ? "var(--green)" : "var(--orange)", fontWeight: 700 }}>
+                        {u.tasks ? `${u.tasks_done} · ${fmtPct(u.completion_rate)}` : "—"}
+                      </td>
+                      <td>{fmtNum(u.produced_total)}</td>
+                      <td>{fmtShort(u.machine_total_ms)}</td>
+                      <td className="small">
+                        {(u.top_features || []).map((f) => `${f.label} (${f.tasks})`).join(", ") || "—"}
+                      </td>
+                      <td>
+                        <button className="btn sm" onClick={() => openDetail(u.user_id)}>
+                          {openUser === u.user_id ? "Đóng" : "Xem phiên"}
+                        </button>
+                      </td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            </div>
+
+            {openUser && (
+              <div style={{ marginTop: 16, borderTop: "1px solid var(--line)", paddingTop: 14 }}>
+                <div style={{ fontWeight: 800, marginBottom: 10 }}>
+                  Nhật ký làm việc của <span style={{ color: "var(--orange)" }}>{openUser}</span>
+                </div>
+                {!detail ? <p className="small muted">Đang tải…</p> : <UserSessions detail={detail} />}
+              </div>
+            )}
+          </div>
+
+          {/* Tốc độ máy */}
+          <div className="card">
+            <div className="panel-title">⚙️ Tốc độ máy mỗi bước (B2)</div>
+            <div className="tablewrap">
+              <table className="list">
+                <thead>
+                  <tr><th>Tool</th><th>Bước máy</th><th>Số lần chạy</th><th>Trung vị</th><th>Chậm nhất 10%</th><th>Tổng</th></tr>
+                </thead>
+                <tbody>
+                  {(data.jobs || []).map((j, i) => (
+                    <tr key={j.feature + j.phase + i}>
+                      <td style={{ fontWeight: 600 }}>{j.label || "—"}</td>
+                      <td>{j.phase}</td>
+                      <td>{j.runs}</td>
+                      <td style={{ fontWeight: 700 }}>{fmtShort(j.median_ms)}</td>
+                      <td>{fmtShort(j.p90_ms)}</td>
+                      <td className="small muted">{fmtDur(j.total_ms)}</td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            </div>
+          </div>
+
+          {/* Log thô */}
+          <div className="card">
+            <div style={{ display: "flex", justifyContent: "space-between", alignItems: "center" }}>
+              <div className="panel-title" style={{ margin: 0 }}>🧾 Log thô</div>
+              <button className="btn sm" onClick={loadRaw}>{rawOpen ? "Ẩn" : "Xem 300 dòng gần nhất"}</button>
+            </div>
+            {rawOpen && (
+              <div className="tablewrap" style={{ marginTop: 12, maxHeight: 420, overflowY: "auto" }}>
+                <table className="list">
+                  <thead>
+                    <tr><th>Thời gian</th><th>Người</th><th>Tool</th><th>Bước</th><th>Sự kiện</th><th>Giá trị</th><th>Máy (ms)</th><th>Chi tiết</th></tr>
+                  </thead>
+                  <tbody>
+                    {raw.map((e) => (
+                      <tr key={e.event_id}>
+                        <td className="small muted" style={{ whiteSpace: "nowrap" }}>{fmtTime(e.event_ts)}</td>
+                        <td className="small">{e.user_id}</td>
+                        <td className="small">{e.feature || "—"}</td>
+                        <td className="small">{e.step || "—"}</td>
+                        <td className="small" style={{ fontWeight: 600 }}>{e.event_name}</td>
+                        <td className="small">{e.event_value || "—"}</td>
+                        <td className="small">{e.latency_ms == null ? "" : fmtNum(e.latency_ms)}</td>
+                        <td className="small muted" style={{ maxWidth: 260, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>
+                          {JSON.stringify(e.properties || {})}
+                        </td>
+                      </tr>
+                    ))}
+                  </tbody>
+                </table>
+              </div>
+            )}
+            <p className="small muted" style={{ margin: "10px 0 0" }}>
+              Lưu tại <b>{data.storage?.backend === "pg" ? "PostgreSQL" : "SQLite (máy chủ)"}</b> ·
+              {" "}{fmtNum(data.storage?.rows)} dòng · giữ {data.storage?.retention_days} ngày rồi tự dọn.
+            </p>
+          </div>
+        </>
+      )}
+    </div>
+  );
+}
+
+// ── Nhật ký từng phiên của một người ───────────────────────────
+
+function UserSessions({ detail }) {
+  const sessions = detail.sessions || [];
+  if (!sessions.length) return <p className="small muted">Không có phiên nào trong khoảng đã chọn.</p>;
+
+  return (
+    <div className="stack" style={{ gap: 12 }}>
+      {sessions.map((s) => (
+        <div key={s.session_id} style={{
+          border: "1px solid var(--line)", borderRadius: "var(--radius-sm)",
+          padding: "10px 12px", background: "var(--cream)",
+        }}>
+          <div style={{ display: "flex", gap: 12, flexWrap: "wrap", alignItems: "baseline", marginBottom: 8 }}>
+            <b style={{ fontSize: 13 }}>{fmtTime(s.start_ts)}</b>
+            <span className="small muted">
+              dùng {fmtDur(s.active_ms)} · {s.n_tasks} việc · {s.n_events} thao tác
+            </span>
+            <span className="small muted" style={{ marginLeft: "auto" }}>{s.session_id}</span>
+          </div>
+
+          {(s.tasks || []).map((t) => (
+            <div key={t.task_id} style={{
+              borderTop: "1px dashed var(--line)", paddingTop: 8, marginTop: 8,
+            }}>
+              <div style={{ display: "flex", gap: 10, flexWrap: "wrap", alignItems: "center" }}>
+                <span style={{ fontWeight: 700, fontSize: 13 }}>{t.label}</span>
+                {t.has_output ? (
+                  <span style={{ fontSize: 11.5, fontWeight: 700, color: "var(--green)", background: "var(--green-soft)", padding: "2px 8px", borderRadius: 99 }}>
+                    ✓ {t.success_type === "forward" ? "chuyển tiếp" : "tải về"} · {t.produced} sản phẩm
+                  </span>
+                ) : t.abandoned ? (
+                  <span style={{ fontSize: 11.5, fontWeight: 700, color: "var(--red)", background: "var(--red-soft)", padding: "2px 8px", borderRadius: 99 }}>
+                    ✕ bỏ dở ở “{t.last_step || "?"}”{t.abandon_reason ? ` · ${t.abandon_reason}` : ""}
+                  </span>
+                ) : (
+                  <span className="small muted">đang làm dở</span>
+                )}
+                <span className="small muted">
+                  {t.has_output ? `xong sau ${fmtDur(t.duration_ms)}` : `kéo dài ${fmtDur(t.span_ms)}`}
+                  {" · "}máy {fmtShort(t.machine_ms)}
+                  {t.wait_ms ? ` (chờ ${fmtShort(t.wait_ms)})` : ""}
+                  {t.attempts ? ` · bấm chạy ${t.attempts} lần` : ""}
+                  {t.thumbs_up ? " · 👍" : ""}{t.thumbs_down ? " · 👎" : ""}
+                </span>
+              </div>
+              {!!(t.steps || []).length && (
+                <div style={{ display: "flex", gap: 6, flexWrap: "wrap", marginTop: 6 }}>
+                  {t.steps.map((st, i) => (
+                    <span key={i} style={{
+                      fontSize: 11, color: "var(--ink-2)", background: "var(--white)",
+                      border: "1px solid var(--line)", borderRadius: 99, padding: "2px 8px",
+                    }}>
+                      {st.step} {fmtShort(st.ms)}
+                    </span>
+                  ))}
+                </div>
+              )}
+            </div>
+          ))}
+        </div>
+      ))}
+    </div>
+  );
+}

frontend/src/lib/track.js

@@ -0,0 +1,330 @@
+// Ghi log hành vi người dùng (phần "đồng hồ người" — thời gian tường).
+//
+// Phân vai với backend: ở đây CHỈ ghi thao tác của người. Thời gian máy chạy do
+// backend tự ghi trong JobManager (job_queued/job_started/job_done) vì chỉ máy
+// chủ biết job rời hàng đợi lúc nào — frontend không bắn job_done, tránh đếm đôi.
+//
+// Bốn tầng định danh: user_id > session_id > task_id > step.
+//   session_id: một lần dùng app; im lặng quá 30' thì mở phiên mới.
+//   task_id   : một lần làm ra một sản phẩm. Mở khi mở tool, đóng khi có đầu ra
+//               hoặc bỏ dở. Chạy lại/regenerate KHÔNG mở task mới, chỉ attempt+1.
+//
+// Log gom thành lô, gửi mỗi 5 giây; lúc đóng tab dùng sendBeacon để không mất
+// dòng feature_abandon.
+
+const ENDPOINT = "/api/events";
+const FLUSH_MS = 5000;
+const MAX_BATCH = 20;
+const IDLE_MS = 30 * 60 * 1000; // ngưỡng im lặng -> hết phiên (spec §6)
+
+const STEPS = ["open", "prepare", "run", "review", "output", "done"];
+
+// Đường dẫn -> khoá tính năng (feature) dùng trong log.
+export const ROUTE_FEATURE = {
+  "/": "home",
+  "/down-list": "down_list",
+  "/cut": "cut",
+  "/xao": "shuffle",
+  "/dub": "dub",
+  "/chen-chu": "text_video",
+  "/listing-anh": "listing_image",
+  "/listing-free": "listing_free",
+  "/flux2": "flux2",
+  "/tao-video": "create_video",
+  "/huong-dan": "guide",
+  "/ho-tro": "support",
+  "/quan-tri": "admin",
+  "/lich-su": "history",
+};
+
+// Trang chỉ để XEM, không làm ra sản phẩm. Ghi `page_view` KHÔNG kèm task_id:
+// mở trang chủ/hướng dẫn mà tính là một "task 0% hoàn thành" thì bảng theo tool
+// và tỷ lệ A3 bị pha loãng bằng thứ không phải công việc.
+const PASSIVE = new Set(["home", "guide", "support", "admin", "history"]);
+
+const rid = () => Math.random().toString(36).slice(2, 10) + Date.now().toString(36).slice(-4);
+
+const nowIso = () => {
+  const d = new Date();
+  const off = -d.getTimezoneOffset();
+  const sign = off >= 0 ? "+" : "-";
+  const p = (n, w = 2) => String(Math.abs(n)).padStart(w, "0");
+  return (
+    `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}` +
+    `T${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}.${p(d.getMilliseconds(), 3)}` +
+    `${sign}${p(off / 60 | 0)}:${p(off % 60)}`
+  );
+};
+
+const ls = {
+  get(k) { try { return localStorage.getItem(k); } catch { return null; } },
+  set(k, v) { try { localStorage.setItem(k, v); } catch { /* chế độ riêng tư */ } },
+};
+
+// ── Trạng thái phiên / task ─────────────────────────────────────
+
+let queue = [];
+let timer = null;
+let session = "";
+let task = null;      // { id, feature, startedAt, lastStep, closed, attempt, phase }
+let started = false;
+let lastOpen = { feature: "", ts: 0 };   // chặn mở trùng (xem featureOpen)
+
+function touch() {
+  ls.set("tnt_track_last", String(Date.now()));
+}
+
+function sessionId() {
+  if (session) return session;
+  const last = Number(ls.get("tnt_track_last") || 0);
+  const prev = ls.get("tnt_track_sess") || "";
+  if (prev && last && Date.now() - last < IDLE_MS) {
+    session = prev;                 // quay lại trong 30' -> vẫn phiên cũ
+  } else {
+    session = "sess_" + rid();
+    ls.set("tnt_track_sess", session);
+    started = false;
+  }
+  return session;
+}
+
+function userId() {
+  return (ls.get("tnt_user") || "").trim().toLowerCase();
+}
+
+// ── Hàng đợi gửi ────────────────────────────────────────────────
+
+function push(row) {
+  const user = userId();
+  if (!user) return;              // chưa đăng nhập -> không có gì để quy về ai
+  queue.push({ event_id: "evt_" + rid(), event_time: nowIso(), user_id: user, ...row });
+  touch();
+  if (queue.length >= MAX_BATCH) flush();
+  else if (!timer) timer = setTimeout(flush, FLUSH_MS);
+}
+
+export function flush(useBeacon = false) {
+  if (timer) { clearTimeout(timer); timer = null; }
+  if (!queue.length) return;
+  const body = JSON.stringify({ events: queue });
+  queue = [];
+  try {
+    if (useBeacon && navigator.sendBeacon) {
+      navigator.sendBeacon(ENDPOINT, new Blob([body], { type: "application/json" }));
+      return;
+    }
+    fetch(ENDPOINT, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body,
+      keepalive: true,
+    }).catch(() => {});
+  } catch { /* mất log còn hơn vỡ app */ }
+}
+
+// ── Ghi event ───────────────────────────────────────────────────
+
+function emit(event_name, step, props = {}, event_value = "") {
+  push({
+    session_id: sessionId(),
+    task_id: task ? task.id : "",
+    feature: task ? task.feature : "",
+    step: STEPS.includes(step) ? step : "prepare",
+    event_name,
+    event_value: event_value == null ? "" : String(event_value),
+    properties: props,
+  });
+  if (task && STEPS.includes(step) && step !== "done") task.lastStep = step;
+}
+
+/** Mở app / đăng nhập xong. Gọi một lần khi vào Layout. */
+export function sessionStart(props = {}) {
+  sessionId();
+  if (started) return;
+  started = true;
+  // Cờ `started` nằm trong bộ nhớ nên F5 là mất, trong khi session_id vẫn giữ
+  // trong localStorage -> không chốt lại thì mỗi lần tải lại trang đẻ thêm một
+  // dòng session_start cho cùng một phiên.
+  if (ls.get("tnt_track_started") === session) return;
+  ls.set("tnt_track_started", session);
+  push({
+    session_id: session, task_id: "", feature: "", step: "open",
+    event_name: "session_start", event_value: "",
+    properties: { client: "web", ...props },
+  });
+}
+
+/** Mở một tool -> đóng task cũ (nếu dở) và mở task mới. */
+export function featureOpen(feature, props = {}) {
+  if (!feature) return;
+
+  // Chống mở TRÙNG: React.StrictMode (dev) chạy effect hai lần, và một lần
+  // re-render lạc cũng gọi lại. Không chặn thì mỗi lần mở tool đẻ thêm một task
+  // rỗng kèm feature_abandon dài 1ms -> tỷ lệ "làm xong" tụt oan.
+  if (Date.now() - lastOpen.ts < 2000 && lastOpen.feature === feature) return;
+  lastOpen = { feature, ts: Date.now() };
+
+  abandonIfOpen();
+
+  if (PASSIVE.has(feature)) {
+    task = null;                       // trang xem: không mở task
+    push({
+      session_id: sessionId(), task_id: "", feature, step: "open",
+      event_name: "page_view", event_value: "", properties: props,
+    });
+    return;
+  }
+
+  task = {
+    id: "task_" + rid(), feature, startedAt: Date.now(),
+    lastStep: "open", closed: false, attempt: 0, phase: "",
+  };
+  emit("feature_open", "open", props);
+}
+
+/** Một thao tác thường của người (dán link, tải file lên, sửa lời...). */
+export function step(event_name, stepName = "prepare", props = {}, value = "") {
+  if (!task) return;
+  // Task đã có đầu ra mà người dùng làm tiếp -> đó là sản phẩm mới -> task mới.
+  if (task.closed) featureOpen(task.feature, { from: "continue" });
+  emit(event_name, stepName, props, value);
+}
+
+/** Người bấm nút chạy máy. Tăng attempt (A4) — backend đọc qua header. */
+export function runClick(props = {}) {
+  if (!task) return;
+  if (task.closed) featureOpen(task.feature, { from: "continue" });
+  task.attempt += 1;
+  // Nhớ tên pha máy sắp chạy (asr_translate / tts / burn / cut…) và gửi kèm
+  // header, để dòng job_done do backend ghi biết mình là bước nào -> chỉ số B2
+  // tách được tốc độ từng bước thay vì gộp một cục.
+  if (props.phase) task.phase = props.phase;
+  emit("run_click", "run", { attempt: task.attempt, ...props });
+  return task.attempt;
+}
+
+/** Làm lại (Tạo lại / Yêu cầu sửa) — cùng task, attempt+1. */
+export function retry(event_name = "regenerate", props = {}) {
+  if (!task) return;
+  task.attempt += 1;
+  emit(event_name, "run", { attempt: task.attempt, ...props });
+}
+
+/** Có sản phẩm: tải về hoặc chuyển tiếp sang tool khác. Cả hai đều là XONG. */
+export function output(kind = "file", props = {}, forwardTo = "") {
+  if (!task) return;
+  const isForward = !!forwardTo;
+  emit(
+    isForward ? "output_forward" : "output_download",
+    "output",
+    { success_type: isForward ? "forward" : "download", ...(isForward ? { to: forwardTo } : {}), ...props },
+    isForward ? forwardTo : kind,
+  );
+  if (!task.closed) {
+    emit("feature_complete", "done", {
+      success_type: isForward ? "forward" : "download",
+      dur_ms: Date.now() - task.startedAt,
+      attempts: task.attempt,
+    });
+    task.closed = true;
+  }
+}
+
+/** Nút 👍/👎 ở chỗ hiện kết quả (chỉ số B3). */
+export function thumbs(value, props = {}) {
+  if (!task) return;
+  emit("thumbs_feedback", task.closed ? "output" : "review", props, value === "up" ? "up" : "down");
+}
+
+/** Nút "Làm mới / Bắt đầu lại" -> đóng task hiện tại, mở task mới. */
+export function restart(props = {}) {
+  if (!task) return;
+  const f = task.feature;
+  featureOpen(f, { from: "restart", ...props });
+}
+
+function abandonIfOpen(extra = {}) {
+  if (!task || task.closed) return;
+  emit("feature_abandon", task.lastStep || "open", {
+    last_step: task.lastStep || "open",
+    dur_ms: Date.now() - task.startedAt,
+    attempts: task.attempt,
+    ...extra,
+  });
+  task.closed = true;
+}
+
+/** Bỏ dở có lý do rõ (vd thiếu API key). */
+export function abandon(reason = "", lastStep = "") {
+  if (!task || task.closed) return;
+  if (lastStep) task.lastStep = lastStep;
+  abandonIfOpen(reason ? { reason } : {});
+}
+
+/** Ngữ cảnh hiện tại — dùng để gắn header X-TNT-* vào request API. */
+export function currentCtx() {
+  return {
+    user_id: userId(),
+    session_id: session || sessionId(),
+    task_id: task ? task.id : "",
+    feature: task ? task.feature : "",
+    phase: task ? task.phase || "" : "",
+    attempt: task ? task.attempt : 0,
+  };
+}
+
+// ── Gắn ngữ cảnh vào MỌI request /api/ ──────────────────────────
+//
+// Vá `fetch` một lần ở đây thay vì sửa ~15 chỗ gọi API: backend đọc header
+// X-TNT-* trong middleware rồi tự gắn vào job, nên dòng log "máy chạy" biết
+// thuộc task nào của ai mà không phải đổi model request nào cả.
+
+let patched = false;
+
+function patchFetch() {
+  if (patched || typeof window === "undefined") return;
+  patched = true;
+  const orig = window.fetch.bind(window);
+  window.fetch = (input, init = {}) => {
+    try {
+      const url = typeof input === "string" ? input : (input && input.url) || "";
+      const isApi = url.startsWith("/api/") || url.includes("/api/");
+      if (isApi && !url.includes("/api/events")) {
+        const c = currentCtx();
+        if (c.user_id) {
+          const h = new Headers((init && init.headers) || (input instanceof Request ? input.headers : undefined));
+          h.set("X-TNT-User", c.user_id);
+          h.set("X-TNT-Session", c.session_id);
+          if (c.task_id) h.set("X-TNT-Task", c.task_id);
+          if (c.feature) h.set("X-TNT-Feature", c.feature);
+          if (c.phase) h.set("X-TNT-Phase", c.phase);
+          if (c.attempt) h.set("X-TNT-Attempt", String(c.attempt));
+          return orig(input, { ...init, headers: h });
+        }
+      }
+    } catch { /* vá lỗi thì gọi như cũ */ }
+    return orig(input, init);
+  };
+}
+
+let inited = false;
+
+/** Gọi một lần lúc app khởi động (trong Layout). */
+export function initTracking() {
+  if (inited || typeof window === "undefined") return;
+  inited = true;
+  patchFetch();
+  sessionStart();
+
+  const bye = () => { abandonIfOpen({ reason: "close_tab" }); flush(true); };
+  window.addEventListener("pagehide", bye);
+  window.addEventListener("visibilitychange", () => {
+    if (document.visibilityState === "hidden") flush(true);
+  });
+  setInterval(() => flush(), FLUSH_MS * 3);
+}
+
+export default {
+  initTracking, sessionStart, featureOpen, step, runClick, retry,
+  output, thumbs, restart, abandon, flush, currentCtx, ROUTE_FEATURE,
+};

frontend/src/pages/AdminUsers.jsx

@@ -1,6 +1,7 @@
 import { useState } from "react";
 import { useNavigate } from "react-router-dom";
 import { useAuth } from "../stores/authStore";
+import UsageDashboard from "../components/admin/UsageDashboard";
 
 export default function AdminUsers() {
   const { user, logout } = useAuth();
@@ -13,6 +14,8 @@ export default function AdminUsers() {
   const [note, setNote] = useState("");
   const [busy, setBusy] = useState(false);
   const [msg, setMsg] = useState("");
+  // Sau khi nhập mật khẩu quản trị: 2 tab — quản lý người dùng / theo dõi thời lượng.
+  const [tab, setTab] = useState("users");
 
   const load = async (t) => {
     const tk = t || token;
@@ -92,13 +95,17 @@ export default function AdminUsers() {
   return (
     <div>
       <div style={{ display: "flex", alignItems: "center", justifyContent: "space-between", marginBottom: 8 }}>
-        <div className="h1" style={{ margin: 0 }}>Quản lý <span className="accent">người dùng</span></div>
+        <div className="h1" style={{ margin: 0 }}>Quản trị <span className="accent">{tab === "users" ? "người dùng" : "thời lượng"}</span></div>
         <div style={{ display: "flex", alignItems: "center", gap: 10 }}>
           <span style={{ fontSize: 13, color: "var(--ink-2)" }}>👤 {user}</span>
           <button className="btn sm" onClick={() => { logout(); navigate("/dang-nhap"); }}>Đăng xuất</button>
         </div>
       </div>
-      <p className="subtitle">Duyệt và quản lý những tài khoản được phép đăng nhập, sử dụng app.</p>
+      <p className="subtitle">
+        {tab === "users"
+          ? "Duyệt và quản lý những tài khoản được phép đăng nhập, sử dụng app."
+          : "Ai dùng tool gì, mất bao lâu, làm ra sản phẩm gì — tính từ log thao tác thật."}
+      </p>
 
       <div className="card" style={{ maxWidth: 600, marginBottom: 20 }}>
         <div className="panel-title">🔑 Đăng nhập quản trị</div>
@@ -113,6 +120,17 @@ export default function AdminUsers() {
       {msg && <div style={{ padding: "10px 14px", background: msg.startsWith("✅") ? "var(--green-soft)" : "var(--red-soft)", borderRadius: "var(--radius-sm)", marginBottom: 16, fontSize: 13, fontWeight: 600 }}>{msg}</div>}
 
       {authenticated && (
+        <div style={{ display: "flex", gap: 8, marginBottom: 18 }}>
+          <button className={"btn" + (tab === "users" ? " primary" : "")}
+            onClick={() => setTab("users")}>👥 Quản lý người dùng</button>
+          <button className={"btn" + (tab === "usage" ? " primary" : "")}
+            onClick={() => setTab("usage")}>📊 Quản lý thời lượng</button>
+        </div>
+      )}
+
+      {authenticated && tab === "usage" && <UsageDashboard token={token} />}
+
+      {authenticated && tab === "users" && (
         <>
           {pending.length > 0 && (
             <div className="card" style={{ maxWidth: 600, marginBottom: 20, border: "2px solid var(--orange)" }}>

frontend/src/pages/CreateVideo.jsx

@@ -1,5 +1,6 @@
 import { useState, useEffect } from "react";
 import { useVideoGen } from "../stores/videoGenStore";
+import track from "../lib/track";
 import { useDirty } from "../stores/dirtyStore";
 import { IcVideo } from "../components/Icons";
 
@@ -25,6 +26,10 @@ export default function CreateVideo() {
     makeDirty("Bạn đang kết nối tạo video. Mất tiến trình nếu rời đi.");
     if (!connectUrl.trim()) return;
     setBusy(true);
+    // Tool này chỉ bàn giao sang app ngoài: đo được tới đây là hết, KHÔNG có
+    // output nội bộ để đo (spec §4.8).
+    const t0 = Date.now();
+    track.runClick({ phase: "connect" });
     try {
       const r = await fetch("/api/video/connect", {
         method: "POST",
@@ -34,7 +39,9 @@ export default function CreateVideo() {
       const data = await r.json();
       if (!r.ok) throw new Error(data.detail || data.error || "Lỗi kết nối");
       connect(connectUrl, data);
+      track.step("connect_success", "output", { latency_ms_client: Date.now() - t0 });
     } catch (e) {
+      track.abandon("connect_failed", "run");
       alert("Lỗi kết nối: " + e.message);
     } finally {
       setBusy(false);

frontend/src/pages/CutVideo.jsx

@@ -7,6 +7,8 @@ import { ProcessRail, FileDrop, ProcessingOverlay, CacheNote } from "../componen
 import {
   IcStar, IcPlay, IcArrow, IcDownload, IcPlus, IcTrash, IcShuffle,
 } from "../components/Icons";
+import track from "../lib/track";
+import ThumbsFeedback from "../components/ThumbsFeedback";
 
 // Luồng: tải video -> "Tách khúc tự động" (máy tự tìm điểm cắt theo nội dung) ->
 // XEM/chỉnh điểm cắt trên timeline (thêm/xoá/kéo) -> "Cắt & xuất khúc".
@@ -217,6 +219,7 @@ export default function CutVideo() {
           info: r.info, thumbs: [], cuts: [],
         };
         set((s) => ({ videos: [...(s.videos || []), v] }));
+        track.step("upload_done", "prepare", { name: file.name, idx: i + 1, total: arr.length });
       } catch (e) { alert("Lỗi tải video: " + e.message); }
     }
     setUploading(null);
@@ -247,6 +250,7 @@ export default function CutVideo() {
   const previewAll = async () => {
     if (!videos.length) return;
     setPrevBusy(true);
+    track.runClick({ phase: "auto_segment", videos: videos.length });
     try {
       for (let i = 0; i < videos.length; i++) await doPreview(i);
     } catch (e) { alert("Lỗi tách khúc: " + e.message); }
@@ -266,6 +270,9 @@ export default function CutVideo() {
   const executeAll = async () => {
     if (!videos.length) return;
     setBusy(true); set({ results: [] });
+    // Người đã xem & chỉnh điểm cắt xong mới bấm -> đây là mốc "duyệt xong".
+    track.step("review_cuts_done", "review", { videos: videos.length });
+    track.runClick({ phase: "cut", videos: videos.length });
     try {
       const sid = videos[0].session;
       const payload = {
@@ -306,6 +313,7 @@ export default function CutVideo() {
     }
     try {
       const r = await api.cutPushShuffle(st.resultSession, groups);
+      track.output("", { count: groups.length }, "shuffle");
       nav(`/xao?session=${r.session}`);
     } catch (e) { alert("Lỗi: " + e.message); }
   };
@@ -321,11 +329,13 @@ export default function CutVideo() {
         (done.items || []).find((i) => i.status === "done")?.result;
       if (!out) throw new Error(done.error || "Không tách được (xem log).");
       set({ splitResult: out });
+      track.step("split_audio_done", "output", { subflow: "split_audio" });
     } catch (e) { alert("Lỗi tách âm thanh: " + e.message); }
     finally { set({ splitBusy: false }); }
   };
 
   const downloadAll = () => {
+    track.output("mp4", { count: allClips().length });
     allClips().forEach((r, i) => setTimeout(() => {
       const a = document.createElement("a");
       a.href = fileUrl(r.url); a.download = r.name;
@@ -442,6 +452,7 @@ export default function CutVideo() {
                   <button className="btn sm primary" onClick={pushToShuffle}><IcShuffle size={15} /> Chuyển sang Xào</button>
                 </div>
               </div>
+              <div className="mt12"><ThumbsFeedback label="Các khúc cắt có đúng ý không?" /></div>
               {st.results.map((v, vi) => (
                 <div key={vi} className="mt16">
                   <div className="flex between center">

frontend/src/pages/DownList.jsx

@@ -5,6 +5,8 @@ import { useToolState } from "../store";
 import { useAuth } from "../stores/authStore";
 import { ProcessRail, Toggle, ProcessingOverlay, CacheNote } from "../components/ui";
 import { IcTrash, IcDownload, IcArrow, IcScissors, IcMic, IcCheck } from "../components/Icons";
+import track from "../lib/track";
+import ThumbsFeedback from "../components/ThumbsFeedback";
 
 const STEPS = [
   { t: "Dán danh sách link", d: "Dán hoặc nhập danh sách các link video cần tải." },
@@ -41,6 +43,7 @@ export default function DownList() {
   const [analyzing, setAnalyzing] = useState(false);
   const parseTimer = useRef(null);
   const forwardingRef = useRef(false);
+  const pastedRef = useRef(false);   // đã ghi mốc 'dán link' cho task này chưa
   // Huỷ vòng poll job khi rời trang.
   const pollAbort = useRef(new AbortController());
   useEffect(() => () => pollAbort.current.abort(), []);
@@ -52,6 +55,11 @@ export default function DownList() {
     try {
       const r = await api.parseLinks(text);
       set({ items: r.items });
+      // Ghi một lần cho mỗi task: mốc "bắt đầu chuẩn bị" của luồng Down list.
+      if (r.items.length && !pastedRef.current) {
+        pastedRef.current = true;
+        track.step("paste_links", "prepare", { count: r.items.length, chars: text.length });
+      }
     } catch (e) { /* im lặng khi đang gõ dở */ }
     finally { setAnalyzing(false); }
   };
@@ -67,6 +75,7 @@ export default function DownList() {
     const urls = st.items.map((i) => i.url);
     if (!urls.length) return;
     setBusy(true);
+    track.runClick({ phase: "analyze_download", count: urls.length, zip: st.zip });
     set({ results: [], failed: [] });
     try {
       const { job_id } = await api.startDownload(urls, st.zip, user);
@@ -99,12 +108,16 @@ export default function DownList() {
         if (r.error) { alert(r.error); return; }
         if (!firstRoute) firstRoute = `/${t.route}?session=${r.session}`;
       }
+      track.output("", { count: tools.length }, tools.map((t) => t.id).join("+"));
+      pastedRef.current = false;
       if (firstRoute) nav(firstRoute);
     } catch (e) { alert("Lỗi: " + e.message); }
     finally { forwardingRef.current = false; }
   };
 
   const downloadAll = () => {
+    track.output("video", { count: st.results.length });
+    pastedRef.current = false;
     st.results.forEach((r, i) => setTimeout(() => {
       const a = document.createElement("a");
       a.href = fileUrl(r.url); a.download = `${r.title}.${r.ext}`;
@@ -193,6 +206,7 @@ export default function DownList() {
                   )}
                 </div>
               </div>
+              <div className="mt12"><ThumbsFeedback label="Bộ video tải về có ổn không?" /></div>
               <div className="tablewrap mt12">
                 <table className="list">
                   <thead><tr><th>#</th><th>Tên file</th><th>Nguồn</th><th>Dung lượng</th><th>Tải</th><th>Chuyển tiếp (chọn tool)</th></tr></thead>
@@ -205,7 +219,8 @@ export default function DownList() {
                           <td className="url-cell" title={`${r.title}.${r.ext}`}>{r.title}.{r.ext}</td>
                           <td>{SOURCE_LABEL[r.source] || r.source}</td>
                           <td className="muted">{(r.size / 1048576).toFixed(1)} MB</td>
-                          <td><a className="btn sm" href={fileUrl(r.url)} download={`${r.title}.${r.ext}`}>Về máy</a></td>
+                          <td><a className="btn sm" href={fileUrl(r.url)} download={`${r.title}.${r.ext}`}
+                            onClick={() => track.output(r.ext || "video", { count: 1 })}>Về máy</a></td>
                           <td>
                             <div className="flex gap8 center" style={{ flexWrap: "nowrap", whiteSpace: "nowrap" }}>
                               <div className="toolchips" style={{ flexWrap: "nowrap" }}>

frontend/src/pages/DubVideo.jsx

@@ -5,6 +5,8 @@ import { useToolState } from "../store";
 import { useAuth } from "../stores/authStore";
 import { ProcessRail, FileDrop, Toggle, ProcessingOverlay, CacheNote } from "../components/ui";
 import { IcMic, IcDownload, IcPlay, IcDoc, IcText } from "../components/Icons";
+import track from "../lib/track";
+import ThumbsFeedback from "../components/ThumbsFeedback";
 import SubtitleEditor from "../components/SubtitleEditor";
 
 const STEPS = [
@@ -179,6 +181,7 @@ export default function DubVideo() {
     }
     setUploading(null);
     set((cur) => ({ session: sid, videos: [...cur.videos, ...added] }));
+    if (added.length) track.step("upload_done", "prepare", { count: added.length });
   };
   const removeVideo = (i) => set((cur) => ({ videos: cur.videos.filter((_, j) => j !== i) }));
 
@@ -197,6 +200,7 @@ export default function DubVideo() {
   const doPrepare = async () => {
     if (!st.videos.length) return;
     setBusy(true); set({ prepared: [], outputs: [] });
+    track.runClick({ phase: "asr_translate", videos: st.videos.length, target: st.target });
     try {
       const { job_id } = await api.dubPrepare({
         session: st.session, files: st.videos.map((v) => v.file),
@@ -208,6 +212,7 @@ export default function DubVideo() {
         (done.items || []).filter((i) => i.status === "done").map((i) => i.result);
       // cùng ngôn ngữ -> mặc định GIỮ NGUYÊN (không đọc lại), user bỏ tick nếu muốn đọc lại
       set({ prepared: (outs || []).map((p) => ({ ...p, keep: !!p.same_language })) });
+      track.step("translation_shown", "review", { videos: (outs || []).length });
     } catch (e) { alert("Lỗi: " + e.message); }
     finally { setBusy(false); }
   };
@@ -281,6 +286,7 @@ export default function DubVideo() {
     }));
     if (!editable.length && !kept.length) return;
     setBusy(true);
+    track.runClick({ phase: "tts", videos: editable.length, kept: kept.length });
     try {
       let synthOuts = [];
       if (editable.length) {
@@ -322,6 +328,7 @@ export default function DubVideo() {
     if (busy || ttsBusy) return;
     if (!st.videos.length && !st.prepared.length && !st.outputs.length) return;
     if (!window.confirm("Xoá video & kết quả hiện tại để làm video khác?")) return;
+    track.restart({ reason: "start_new" });
     set({ videos: [], prepared: [], outputs: [], job: null, outStamp: 0 });
   };
 
@@ -627,6 +634,9 @@ export default function DubVideo() {
                   ＋ Làm video mới
                 </button>
               </div>
+              <div style={{ marginBottom: 12 }}>
+                <ThumbsFeedback label="Bản lồng tiếng nghe có ổn không?" />
+              </div>
               <div className="stack">
                 {st.outputs.map((o) => {
                   const isSameLang = o.note && o.note.includes("giữ nguyên");
@@ -662,9 +672,12 @@ export default function DubVideo() {
                         </div>
                       </div>
                       <div className="flex gap8 mt12" style={{ flexWrap: "wrap" }}>
-                        <a className="btn sm" href={fileUrl(o.video_url)} download><IcDownload size={14} /> Video MP4</a>
-                        <a className="btn sm" href={fileUrl(o.audio_url)} download><IcDownload size={14} /> Audio</a>
-                        <a className="btn sm" href={fileUrl(o.srt_url)} download><IcDoc size={14} /> Subtitle SRT</a>
+                        <a className="btn sm" href={fileUrl(o.video_url)} download
+                          onClick={() => track.output("mp4", { count: 1 })}><IcDownload size={14} /> Video MP4</a>
+                        <a className="btn sm" href={fileUrl(o.audio_url)} download
+                          onClick={() => track.output("audio", { count: 1 })}><IcDownload size={14} /> Audio</a>
+                        <a className="btn sm" href={fileUrl(o.srt_url)} download
+                          onClick={() => track.output("srt", { count: 1 })}><IcDoc size={14} /> Subtitle SRT</a>
                         {!isSameLang && (
                           <button className="btn sm primary" onClick={() => {
                             const rel = (u) => (u || "").replace(`/api/files/${st.session}/`, "");

frontend/src/pages/Flux2Gen.jsx

@@ -1,5 +1,7 @@
 import { useState, useCallback, useRef } from "react";
 import { IcBolt, IcDownload as IcDl, IcImage, IcSliders } from "../components/Icons";
+import track from "../lib/track";
+import ThumbsFeedback from "../components/ThumbsFeedback";
 
 const RESOLUTIONS = [
   { label: "1024×1024 (Square)", value: "1024x1024" },
@@ -250,6 +252,10 @@ export default function Flux2Gen() {
     setImages([]);
     setError(null);
     startTimeRef.current = Date.now();
+    // Mỗi lần bấm Generate = một lần "hỏi máy" (A4). Thời gian máy chạy do
+    // backend tự ghi, ở đây chỉ ghi thao tác của người.
+    track.step("edit_prompt", "prepare", { chars: prompt.trim().length });
+    track.runClick({ phase: "generate", batch, resolution, steps });
 
     try {
       const res = await fetch("/api/flux2/generate", {
@@ -280,6 +286,7 @@ export default function Flux2Gen() {
   }, [prompt, negativePrompt, resolution, steps, guidance, seed, batch, pollStatus]);
 
   const downloadAll = useCallback(() => {
+    track.output("png", { count: images.filter((im) => im.url).length });
     images.forEach((img, i) => {
       if (img.url) {
         const a = document.createElement("a");
@@ -490,6 +497,10 @@ export default function Flux2Gen() {
             </button>
           </div>
 
+          <div style={{ marginBottom: 14 }}>
+            <ThumbsFeedback label="Ảnh sinh ra có đúng ý không?" />
+          </div>
+
           <div style={styles.gallery}>
             {images.map((img, i) =>
               img.error ? (
@@ -516,6 +527,7 @@ export default function Flux2Gen() {
                   <button
                     style={styles.downloadBtn}
                     onClick={() => {
+                      track.output("png", { count: 1 });
                       const a = document.createElement("a");
                       a.href = img.url;
                       a.download = `flux2_${i + 1}.png`;

frontend/src/pages/ListingImage.jsx

@@ -3,6 +3,8 @@ import { ProcessRail, CacheNote } from "../components/ui";
 import { useDirty } from "../stores/dirtyStore";
 import { useAuth } from "../stores/authStore";
 import { IcImage, IcUpload, IcDownload, IcRefresh } from "../components/Icons";
+import track from "../lib/track";
+import ThumbsFeedback from "../components/ThumbsFeedback";
 
 const STEPS = [
   { t: "Tải ảnh", d: "Ảnh sản phẩm là bắt buộc — chụp chính diện, đủ sáng, rõ nhãn. Thêm ảnh người mẫu / bối cảnh nếu muốn AI dùng đúng gương mặt và khung cảnh." },
@@ -122,6 +124,7 @@ export default function ListingImage() {
 
   const handleFile = (slot, f) => {
     if (!f || !f.type.startsWith("image/")) return;
+    track.step("upload_done", "prepare", { slot });
     if (previews[slot]) URL.revokeObjectURL(previews[slot]);
     setFiles(prev => ({ ...prev, [slot]: f }));
     setPreviews(prev => ({ ...prev, [slot]: URL.createObjectURL(f) }));
@@ -151,6 +154,11 @@ export default function ListingImage() {
     addLog("info", "🔍 Đang phân tích ảnh với GPT-4o...");
 
     const ak = _apiKey();
+    // Bước nhập API key là chỗ tắc riêng của tool này (spec §4.6). Ghi cờ
+    // has_key để đếm được "bao nhiêu task chạy khi chưa có key riêng" — KHÔNG
+    // ghi bỏ dở ở đây vì thiếu key vẫn chạy được bằng key chung của máy chủ.
+    track.step("api_key_set", "prepare", { has_key: !!ak });
+    track.runClick({ phase: "analyze_generate", quantity, types: selectedTypes.length });
     const fd = new FormData();
     fd.append("file", files.product);
     if (files.person) fd.append("person_image", files.person);
@@ -251,6 +259,7 @@ export default function ListingImage() {
   const startEdit = async (type) => {
     if (!sessionId || editBusy) return;
     setEditBusy(true);
+    track.retry("edit_request", { type, chars: editRequest.length });
     addLog("info", `✏️ Đang edit ảnh "${type}" (giữ nguyên mẫu mã)...`);
     try {
       const fd = new FormData();
@@ -285,6 +294,7 @@ export default function ListingImage() {
     if (!sessionId || regeneratingSingle) return;
     const savedResults = [...results];
     setRegeneratingSingle(true);
+    track.retry("regenerate", { type: viewingPromptType });
     addLog("info", `🔄 Đang tạo lại ảnh "${viewingPromptType}"...`);
     const promptObj = prompts.find(p => p.type === viewingPromptType);
     const customPrompt = { ...promptObj, prompt: editedPromptText };
@@ -327,11 +337,13 @@ export default function ListingImage() {
       const a = document.createElement("a");
       a.href = url; a.download = `listing_images_${sessionId.slice(0, 8)}.zip`;
       a.click(); URL.revokeObjectURL(url);
+      track.output("zip", { count: results.length });
     } catch (e) { addLog("error", "❌ " + e.message); }
   };
 
   const resetAll = () => {
     makeClean();
+    track.restart({ reason: "reset" });
     if (pollRef.current) clearTimeout(pollRef.current);
     if (sessionId) fetch(`/api/listing/session/${sessionId}`, { method: "DELETE" }).catch(() => {});
     setSessionId(null); setPrompts([]); setResults([]); setLogs([]);
@@ -562,6 +574,11 @@ export default function ListingImage() {
                   </div>
                 </div>
               )}
+              {!generating && !regeneratingSingle && (
+                <div style={{ marginTop: 14 }}>
+                  <ThumbsFeedback label="Bộ ảnh listing này có dùng được không?" />
+                </div>
+              )}
               {!generating && !regeneratingSingle && (
                 <div style={{ display: "flex", gap: 8, marginTop: 14 }}>
                   <button className="btn primary" onClick={downloadAll}><IcDownload size={16} /> Tải tất cả về</button>

frontend/src/pages/ShuffleVideo.jsx

@@ -6,6 +6,8 @@ import { useAuth } from "../stores/authStore";
 import { ProcessRail, FileDrop, ProcessingOverlay, CacheNote } from "../components/ui";
 import { IcShuffle, IcDownload, IcCheck, IcMusic } from "../components/Icons";
 import ComboTable from "../components/ComboTable";
+import track from "../lib/track";
+import ThumbsFeedback from "../components/ThumbsFeedback";
 
 const STEPS = [
   { t: "Nhập số khúc", d: "Khai báo video gồm bao nhiêu khúc theo kịch bản." },
@@ -167,6 +169,8 @@ export default function ShuffleVideo() {
       n[idx].files.push(...ok);
       return { session: sid, segs: n };
     });
+    // Thả clip vào từng khúc = chỗ nghẽn của Xào (spec §4.3) -> ghi từng lần.
+    track.step("upload_done", "prepare", { seg: idx, count: ok.length });
   };
 
   const addAudio = async (files) => {
@@ -178,6 +182,7 @@ export default function ShuffleVideo() {
     const { ok } = await uploadMany(
       arr, (file, sid, onP) => api.shuffleUploadAudioP(file, sid, onP), "audio");
     set((cur) => ({ audio: [...cur.audio, ...ok] }));
+    track.step("upload_done", "prepare", { seg: "audio", count: ok.length });
   };
 
   const removeClip = (si, fi) => set((cur) => {
@@ -216,6 +221,7 @@ export default function ShuffleVideo() {
     try {
       const r = await api.shufflePlan(payload());
       set({ plan: r, maxRender: r.max_render || 10000 });
+      track.step("plan_shown", "review", { count: r.count, raw_total: r.raw_total });
       if (r.capped) alert(
         `Tổng ${Number(r.raw_total).toLocaleString()} tổ hợp — hiển thị MẪU ĐA DẠNG `
         + `${Number(r.count).toLocaleString()} tổ hợp (trần ${Number(r.plan_cap).toLocaleString()}).`);
@@ -235,6 +241,7 @@ export default function ShuffleVideo() {
       sequences = sequences.slice(0, MAX_RENDER);
     }
     setBusy(true); set({ results: [] });
+    track.runClick({ phase: "render", variants: sequences ? sequences.length : null, segs: segs.length });
     try {
       const { job_id } = await api.shuffleGenerate({ ...payload(), sequences });
       const done = await pollJob(job_id, setJob, 1000, pollAbort.current.signal);
@@ -248,6 +255,7 @@ export default function ShuffleVideo() {
   };
 
   const downloadAll = () => {
+    track.output("mp4", { count: st.results.length });
     st.results.forEach((r, i) => setTimeout(() => {
       const a = document.createElement("a");
       a.href = fileUrl(r.url); a.download = r.name;
@@ -412,9 +420,11 @@ export default function ShuffleVideo() {
                 <div className="panel-title" style={{ margin: 0 }}>Xem trước kết quả ({st.results.length} biến thể)</div>
                 <div className="flex gap8">
                   <button className="btn sm" onClick={downloadAll}><IcDownload size={15} /> Tải tất cả theo thứ tự</button>
-                  <a className="btn sm" href={fileUrl(`/api/files/${st.session}/variations.zip`)} download><IcDownload size={15} /> Tải ZIP</a>
+                  <a className="btn sm" href={fileUrl(`/api/files/${st.session}/variations.zip`)} download
+                onClick={() => track.output("zip", { count: st.results.length })}><IcDownload size={15} /> Tải ZIP</a>
                 </div>
               </div>
+              <div className="mt12"><ThumbsFeedback label="Các biến thể xào ra có dùng được không?" /></div>
               <div className="results mt12">
                 {st.results.map((r) => {
                   const bust = st.resStamp ? `?v=${st.resStamp}` : "";

frontend/src/pages/TextVideo.jsx

@@ -5,6 +5,8 @@ import { useAuth } from "../stores/authStore";
 import { ProcessRail, FileDrop, ProcessingOverlay, CacheNote } from "../components/ui";
 import { IcText, IcDownload, IcVideo } from "../components/Icons";
 import SubtitleEditor from "../components/SubtitleEditor";
+import track from "../lib/track";
+import ThumbsFeedback from "../components/ThumbsFeedback";
 
 const STEPS = [
   { t: "Tải video", d: "Tải 1 hoặc nhiều video cần chèn chữ." },
@@ -61,6 +63,7 @@ export default function TextVideo() {
       // nếu chưa mở video nào -> mở video đầu tiên vừa thêm
       selIdx: cur.selIdx < 0 || !cur.videos.length ? cur.videos.length : cur.selIdx,
     }));
+    if (added.length) track.step("upload_done", "prepare", { count: added.length });
   };
 
   const removeVideo = (i) => set((cur) => {
@@ -125,12 +128,14 @@ export default function TextVideo() {
     setMsg(count > 0
       ? `✅ Đã áp KIỂU chữ cho ${count} video (giữ lời riêng từng video).`
       : "Không có video nào khác đang có chữ để áp kiểu.");
+    if (count > 0) track.step("apply_form_all", "prepare", { count });
   };
 
   // Nhận dạng lời gốc trong video đang mở (ASR) -> trả lines cho editor đổ vào.
   const fetchLines = async () => {
     if (!selV) return [];
     setBusy(true);
+    track.runClick({ phase: "asr" });
     try {
       const { job_id } = await api.dubTranscribe({ session: st.session, video: selV.file });
       const done = await pollJob(job_id, setJob, 1000, pollAbort.current.signal);
@@ -150,6 +155,7 @@ export default function TextVideo() {
       return;
     }
     setBusy(true); set({ outputs: [] });
+    track.runClick({ phase: "burn", videos: targets.length });
     const outs = [];
     try {
       for (const v of targets) {
@@ -164,6 +170,7 @@ export default function TextVideo() {
         if (out) outs.push({ ...out, srcName: v.name, srcUrl: v.url });
       }
       set({ outputs: outs, outStamp: Date.now() });
+      track.step("burn_batch_done", "review", { videos_in: targets.length, videos_out: outs.length });
       if (!outs.length) alert("Không tạo được video nào (xem log).");
     } catch (e) { alert("Lỗi: " + e.message); }
     finally { setBusy(false); }
@@ -173,6 +180,7 @@ export default function TextVideo() {
     if (busy) return;
     if (!st.videos.length && !st.outputs.length) return;
     if (!window.confirm("Xoá video & kết quả hiện tại để làm mẻ khác?")) return;
+    track.restart({ reason: "start_new" });
     set({ videos: [], forms: {}, outputs: [], selIdx: -1, job: null, outStamp: 0 });
   };
 
@@ -292,6 +300,9 @@ export default function TextVideo() {
                   ＋ Làm mẻ mới
                 </button>
               </div>
+              <div style={{ marginBottom: 10 }}>
+                <ThumbsFeedback label="Chữ chèn vào video có đúng ý không?" />
+              </div>
               <div className="stack">
                 {st.outputs.map((o) => {
                   const bust = st.outStamp ? `?v=${st.outStamp}` : "";
@@ -314,7 +325,8 @@ export default function TextVideo() {
                         </div>
                       </div>
                       <div className="flex gap8 mt12" style={{ flexWrap: "wrap" }}>
-                        <a className="btn sm" href={fileUrl(o.video_url)} download><IcDownload size={14} /> Tải video MP4</a>
+                        <a className="btn sm" href={fileUrl(o.video_url)} download
+                          onClick={() => track.output("mp4", { count: 1 })}><IcDownload size={14} /> Tải video MP4</a>
                       </div>
                     </div>
                   );