workbuddy-portal/workbuddy_portal/web/api.py

# -*- coding: utf-8 -*-
# SPDX-License-Identifier: MIT
# Copyright (c) 2026 Wang Chuanli

"""JSON API —— ECharts 大屏与后台页面的数据入口。

约定：
  * 全部需要登录；POST 另需 CSRF（security.check_csrf 统一拦截）
  * 参数 from/to 为 'YYYY-MM-DD'；缺省则不限（即全量）
  * 列表类接口默认不返回 prompt 全文（占传输量约 80%），只有 /api/top 与
    /api/records/<request_id> 会带

**多用户约定**
每个接口都只操作 `current_user()["id"]` 那份数据。查询函数要求显式传 uid，
所以这里漏传会直接 TypeError（而不是静默返回全量）。

写权限只有两条规则（`config.writable_by`，前后端与测试共用同一判断）：

  * 普通用户**只能**写 `config.USER_EDITABLE_KEYS`（本人的 cookie / user_agent）；
  * 其余键（接口地址、注册策略、采集参数、调度时刻）只有管理员能写，
    任何越权写入都会被 `/api/settings` 拒绝并在审计里记一笔 `settings_rejected`。
"""
import os
from datetime import datetime

from flask import Blueprint, jsonify, request

from .. import collect, config, db, query, scheduler, security
from ..security import admin_required, current_user, is_admin, login_required

bp = Blueprint("api", __name__, url_prefix="/api")


def _uid():
    u = current_user()
    return u["id"] if u else 0


def _arg(name, default=None):
    v = request.args.get(name)
    return v if v not in (None, "") else default


def _json_body():
    body = request.get_json(silent=True)
    return body if isinstance(body, dict) else {}


class BadParam(ValueError):
    """查询参数不合法 -> 由 __init__ 的 ValueError 处理器统一转成 400。"""


def _win(required=False):
    """解析 from/to，返回归一化后的 (from, to)。

    归一化放在这里，视图与聚合层就不必再各自防御：
    无法识别的写法（'abc'、'2026-09-08 12:00:00' 里的空格等）此前会一路冒到
    `datetime.strptime` 变成 HTTP 500，现在统一 400 并带上人话说明。
    """
    raw_f, raw_t = _arg("from"), _arg("to")
    f, t = query.norm_day(raw_f), query.norm_day(raw_t)
    if raw_f and not f:
        raise BadParam("参数 from 不是合法日期：%s（正确写法 2026-09-08）" % raw_f)
    if raw_t and not t:
        raise BadParam("参数 to 不是合法日期：%s（正确写法 2026-09-08）" % raw_t)
    if f and t and f > t:
        f, t = t, f
    if required and (not f or not t):
        raise BadParam("需要同时提供 from 与 to（YYYY-MM-DD）")
    return f, t


def _int(name, default, lo=1, hi=2000):
    try:
        return max(lo, min(hi, int(request.args.get(name, default))))
    except (TypeError, ValueError):
        return default


@bp.get("/manifest")
@login_required
def api_manifest():
    u = current_user()
    m = query.manifest(db.get_db(), u["id"])
    # 角色标记只在这里补：大屏是**静态页**，拿不到 Jinja 上下文，
    # 只能靠数据接口知道自己该不该渲染「日志管理」这类管理员入口。
    # 前端隐藏只是不给死链，真正的闸门始终是服务端的 @admin_required。
    m["role"] = "admin" if u["is_admin"] else "user"
    return jsonify(m)


@bp.get("/bundle")
@login_required
def api_bundle():
    """大屏页一次拿齐：全量 daily + 窗口 dims/top/records。"""
    frm, to = _win()
    return jsonify(query.bundle(db.get_db(), _uid(), frm, to,
                                top_n=_int("topN", query.DEFAULT_TOP_N, 1, 1000)))


@bp.get("/summary")
@login_required
def api_summary():
    conn = db.get_db()
    uid = _uid()
    frm, to = _win()
    if not frm or not to:
        t = query.totals(conn, uid)
        frm, to = t["firstDay"], t["lastDay"]
    return jsonify(query.summary(conn, uid, frm, to))


@bp.get("/daily")
@login_required
def api_daily():
    return jsonify({"days": query.daily(db.get_db(), _uid(), *_win())})


@bp.get("/dims")
@login_required
def api_dims():
    conn = db.get_db()
    d = query.dims(conn, _uid(), *_win())
    dim = _arg("dim")
    if dim in d:
        return jsonify({dim: d[dim]})
    return jsonify(d)


@bp.get("/top")
@login_required
def api_top():
    conn = db.get_db()
    return jsonify(query.top(conn, _uid(), *_win(), n=_int("n", 50, 1, 1000)))


@bp.get("/records")
@login_required
def api_records():
    conn = db.get_db()
    uid = _uid()
    frm, to = _win()
    page = _int("page", 1, 1, 100000)
    size = _int("size", 50, 1, 500)
    r = query.records_page(conn, uid, frm, to, model=_arg("model"), client=_arg("client"),
                           q=_arg("q"), page=page, size=size, order=_arg("order", "ts_desc"),
                           with_prompt=False if _arg("lean") == "1" else True)
    return jsonify(r)


@bp.get("/records/<request_id>")
@login_required
def api_record(request_id):
    # user_id 必须进 WHERE：否则改一个 URL 就能读到别人的 Prompt 全文
    row = db.get_db().execute("SELECT * FROM usage_records WHERE user_id=? AND request_id=?",
                              (_uid(), request_id)).fetchone()
    if row is None:
        return jsonify({"ok": False, "message": "记录不存在"}), 404
    return jsonify(dict(row))


@bp.get("/runs")
@login_required
def api_runs():
    conn = db.get_db()
    rows = conn.execute("SELECT id,trigger,status,started_at,finished_at,duration_ms,win_from,"
                        "win_to,fetched,added,dup,total,conflicts,exit_code,message"
                        " FROM collect_runs WHERE user_id=? ORDER BY id DESC LIMIT ?",
                        (_uid(), _int("limit", 50, 1, 500)))
    return jsonify({"items": [dict(r) for r in rows]})


@bp.get("/runs/<int:run_id>")
@login_required
def api_run(run_id):
    row = db.get_db().execute("SELECT * FROM collect_runs WHERE id=? AND user_id=?",
                              (run_id, _uid())).fetchone()
    if row is None:
        return jsonify({"ok": False, "message": "运行记录不存在"}), 404
    return jsonify(dict(row))


@bp.get("/status")
@login_required
def api_status():
    conn = db.get_db()
    u = current_user()
    uid = u["id"]
    sch = scheduler.get_scheduler()
    nxt = scheduler.next_run_at(conn, uid)
    last = conn.execute("SELECT * FROM collect_runs WHERE user_id=? ORDER BY id DESC LIMIT 1",
                        (uid,)).fetchone()
    running = conn.execute("SELECT COUNT(*) FROM collect_runs WHERE user_id=? AND status='running'",
                           (uid,)).fetchone()[0]
    cred = db.secret_state(conn, "cookie", uid)
    return jsonify({
        "server_time": db.now_str(),
        # 角色能力：大屏等**静态页**拿不到 Jinja 上下文，只能靠这个字段
        # 决定要不要渲染管理员专属入口（如「日志管理」）。服务端仍会
        # 对这些入口再做一次鉴权，前端隐藏只是为了不给出误导性的按钮。
        "is_admin": bool(u["is_admin"]),
        "can_edit_schedule": bool(u["is_admin"]),
        "can_view_logs": bool(u["is_admin"]),
        "scheduler": {
            "running": sch.running,
            "enabled": db.get_bool(conn, "schedule_enabled", True, uid),
            "times": scheduler.slots(conn, uid),
            "next_run": nxt.strftime("%Y-%m-%d %H:%M:%S") if nxt else None,
            "catch_up": db.get_bool(conn, "catch_up", True, uid),
            "lockfile": os.path.exists(collect.LOCK_PATH),
        },
        "running_runs": running,
        "last_run": dict(last) if last else None,
        # 只回「有没有配」与字符数，绝不回凭证内容
        "cookie_set": bool(cred["set"] and not cred["broken"]),
        "cookie_chars": cred["chars"],
        "cookie_broken": cred["broken"],
    })


@bp.post("/collect")
@login_required
def api_collect():
    """手动触发一次采集（后台线程之外同步执行，页面等待结果）。"""
    u = current_user()
    body = _json_body()
    frm, to = body.get("from"), body.get("to")
    try:
        kw = {}
        if frm:
            d = query.norm_day(frm)
            if not d:
                raise BadParam("起始日期不合法：%s（正确写法 2026-09-08）" % frm)
            kw["from_dt"] = datetime.strptime(d, "%Y-%m-%d")
        if to:
            d = query.norm_day(to)
            if not d:
                raise BadParam("结束日期不合法：%s（正确写法 2026-09-08）" % to)
            kw["to_dt"] = datetime.strptime(d, "%Y-%m-%d").replace(hour=23, minute=59, second=59)
        if kw.get("from_dt") and kw.get("to_dt") and kw["from_dt"] > kw["to_dt"]:
            raise BadParam("起始日期不能晚于结束日期")
        r = collect.run_sync(trigger="manual", uid=u["id"], **kw)
    except BadParam as e:
        return jsonify({"ok": False, "error": "bad_request", "message": str(e)}), 400
    except collect.Busy as e:
        return jsonify({"ok": False, "error": "busy", "message": str(e)}), 409
    except collect.NotReady as e:
        return jsonify({"ok": False, "error": "no_cookie", "message": str(e)}), 409
    except db.SecretUnreadable as e:
        return jsonify({"ok": False, "error": "cookie_broken",
                        "message": "已保存的 Cookie 无法解密（实例密钥被更换过）：%s。"
                                   "请到「配置管理」重新粘贴。" % e}), 409
    except collect.ApiError as e:
        code = 401 if e.cookie_expired else 502
        return jsonify({"ok": False, "error": "cookie_expired" if e.cookie_expired else "api",
                        "message": str(e)}), code
    except Exception as e:                      # noqa: BLE001
        return jsonify({"ok": False, "error": "internal", "message": str(e)}), 500
    db.audit(db.get_db(), "collect", u["username"], r["message"], request.remote_addr, u["id"])
    return jsonify({"ok": True, "result": r})


@bp.get("/audit")
@login_required
def api_audit():
    """操作审计分页。管理员看全部（便于追责），普通用户只看自己触发的。"""
    conn = db.get_db()
    u = current_user()
    action = _arg("action")
    page = _int("page", 1, 1, 100000)
    size = _int("size", 50, 1, 500)
    w, p = [], []
    if not u["is_admin"]:
        w.append("user_id = ?")
        p.append(u["id"])
    if action:
        w.append("action = ?")
        p.append(action)
    ws = ("WHERE " + " AND ".join(w)) if w else ""
    total = conn.execute("SELECT COUNT(*) FROM audit_log %s" % ws, p).fetchone()[0]
    rows = conn.execute("SELECT * FROM audit_log %s ORDER BY id DESC LIMIT ? OFFSET ?" % ws,
                        p + [size, (page - 1) * size])
    # 动作清单不带 action 条件，否则只剩下当前那一个动作可选
    base_p = [u["id"]] if not u["is_admin"] else []
    base = "WHERE user_id = ?" if not u["is_admin"] else ""
    actions = [r[0] for r in conn.execute(
        "SELECT DISTINCT action FROM audit_log %s ORDER BY action" % base, base_p)]
    return jsonify({"total": total, "page": page, "size": size,
                    "pages": max(1, (total + size - 1) // size),
                    "scope": "all" if u["is_admin"] else "self",
                    "actions": actions,
                    "items": [dict(r) for r in rows]})


# ---------------- 维护动作（原来只有 CLI 能做） ----------------
@bp.post("/maintenance/<action>")
@login_required
def api_maintenance(action):
    """把 CLI 里的维护动作搬到页面上。

    只有 `vacuum` 是**实例级**动作（整个库一起整理），所以它仅管理员可用；
    其余三个都只作用于当前账号自己的数据。
    """
    conn = db.get_db()
    u = current_user()
    uid = u["id"]
    if action == "vacuum" and not u["is_admin"]:
        return jsonify({"ok": False, "error": "forbidden",
                        "message": "数据库整理是整库操作，仅管理员可执行"}), 403
    try:
        if action == "fill-prompt":
            try:
                n = collect.fill_prompt(conn, uid, log=lambda m: None)
            except collect.NotReady as e:
                return jsonify({"ok": False, "error": "no_cookie", "message": str(e)}), 409
            except db.SecretUnreadable as e:
                return jsonify({"ok": False, "error": "cookie_broken",
                                "message": "已保存的 Cookie 无法解密，请重新粘贴：%s" % e}), 409
            except collect.ApiError as e:
                return jsonify({"ok": False, "error": "api", "message": str(e)}), 502
            msg = "补全 %d 条 User Prompt" % n
        elif action == "vacuum":
            before = os.path.getsize(config.SQLITE_PATH) if os.path.exists(config.SQLITE_PATH) else 0
            conn.execute("PRAGMA wal_checkpoint(TRUNCATE)")
            conn.execute("VACUUM")
            conn.execute("PRAGMA optimize")
            after = os.path.getsize(config.SQLITE_PATH) if os.path.exists(config.SQLITE_PATH) else 0
            msg = "数据库整理完成：%s → %s" % (_human(before), _human(after))
        elif action == "export-csv":
            path, n = collect.export_csv(conn, uid, username=u["username"])
            msg = "已导出 %d 条到 %s" % (n, os.path.relpath(path, config.BASE_DIR))
        elif action == "recount":
            n = collect.record_count(conn, uid)
            msg = "存档当前 %d 条记录" % n
        else:
            return jsonify({"ok": False, "error": "unknown", "message": "未知维护动作"}), 404
    except Exception as e:                      # noqa: BLE001
        return jsonify({"ok": False, "error": "internal", "message": str(e)}), 500
    db.audit(conn, "maintenance:" + action, u["username"], msg, request.remote_addr, uid)
    return jsonify({"ok": True, "message": msg})


def _human(n):
    for unit in ("B", "KB", "MB", "GB"):
        if n < 1024 or unit == "GB":
            return "%.1f %s" % (n, unit) if unit != "B" else "%d B" % n
        n /= 1024.0


@bp.get("/settings")
@login_required
def api_settings_get():
    """当前账号的**有效配置**（不含任何凭证明文）。"""
    conn = db.get_db()
    u = current_user()
    s = db.get_settings(conn, uid=u["id"])
    st = db.secret_state(conn, "cookie", u["id"])
    s["cookie_hint"] = ("%d 字符，…%s" % (st["chars"], st["tail"])) if st["set"] else ""
    s["cookie_broken"] = st["broken"]
    # 内部簿记键（slot:09:00 这类调度槽位标记）不属于配置项，绝不外泄
    for k in [k for k in list(s) if config.is_internal_key(k)]:
        s.pop(k, None)
    s["_globalKeys"] = sorted(config.GLOBAL_KEYS)
    s["_userKeys"] = sorted(config.USER_EDITABLE_KEYS)
    s["_canEditGlobal"] = bool(u["is_admin"])
    s["_role"] = "admin" if u["is_admin"] else "user"
    return jsonify(s)


@bp.post("/settings")
@login_required
def api_settings_post():
    conn = db.get_db()
    u = current_user()
    uid = u["id"]
    body = _json_body()
    changed, errors, ignored, denied = [], [], [], []
    for k, v in body.items():
        if config.is_internal_key(k):
            ignored.append(k)
            continue                        # slot:* 是调度簿记，不允许前台写
        if k not in config.DEFAULTS:
            errors.append("未知配置项：%s" % k)
            continue
        if not config.writable_by(k, u["is_admin"]):
            # 普通用户只能写**本人凭证**（cookie / user_agent）。其余键 ——
            # 接口基址、注册策略、采集参数、调度时刻 —— 一律归管理员：
            # 否则任意注册用户就能把大家的数据采集指向别的服务器，
            # 或者把 page_size 调到 1000 去 hammer 云端接口。
            denied.append(k)
            continue
        if k == "cookie":
            raw = str(v).strip()
            if not raw:
                continue                    # 空值不动，避免误清
            if raw.lower() in ("__clear__", "-"):
                db.set_secret(conn, "cookie", "", uid)
                changed.append(k)
                continue
        val, err = config.normalize_setting(k, v)
        if err:
            errors.append(err)
            continue
        if k in config.ENCRYPTED_KEYS:
            db.set_secret(conn, k, val, uid)
        else:
            db.set_setting(conn, k, val, uid)
        changed.append(k)
    if denied:
        errors.append("以下配置仅管理员可修改，本账号无法保存：%s。"
                      "普通账号可以维护的是本人凭证（Cookie / User-Agent）。"
                      % "、".join(sorted(denied)))
    if errors:
        db.audit(conn, "settings_rejected", u["username"], "；".join(errors)[:500],
                 request.remote_addr, uid)
        return jsonify({"ok": False, "error": "invalid", "message": "；".join(errors),
                        "errors": errors, "changed": sorted(changed)}), 400
    # 改了每日时刻：清掉**不再存在的**槽位标记（所有账号一起清）。
    # 这里刻意不做「全清」——时刻是实例级的，全清会让全部账号在宽限期内
    # 一起重采一遍；只清失效槽位，既让新时刻立即生效，又不会造成批量重采。
    if "schedule_times" in changed:
        keep = set(scheduler.slots(conn, 0))
        stale = [(r["user_id"], r["key"]) for r in conn.execute(
            "SELECT user_id,key FROM settings WHERE key LIKE ?", (scheduler.SLOT_PREFIX + "%",))
            if r["key"][len(scheduler.SLOT_PREFIX):] not in keep]
        for row_uid, skey in stale:
            conn.execute("DELETE FROM settings WHERE user_id=? AND key=?", (row_uid, skey))
    db.audit(conn, "settings", u["username"],
             "修改：" + (",".join(sorted(changed)) or "（无变化）"), request.remote_addr, uid)
    return jsonify({"ok": True, "changed": sorted(changed), "ignored": sorted(ignored)})


@bp.post("/password")
@login_required
def api_password():
    conn = db.get_db()
    u = current_user()
    body = _json_body()
    row = conn.execute("SELECT * FROM users WHERE id=?", (u["id"],)).fetchone()
    if row is None or not security.verify_password(row["password_hash"], body.get("old") or ""):
        return jsonify({"ok": False, "message": "原密码不正确"}), 400
    new = (body.get("new") or "").strip()
    err = security.password_problem(new, body.get("new2"), u["username"])
    if err:
        return jsonify({"ok": False, "message": err}), 400
    conn.execute("UPDATE users SET password_hash=? WHERE id=?",
                 (security.hash_password(new), u["id"]))
    db.audit(conn, "password", u["username"], "修改登录密码", request.remote_addr, u["id"])
    return jsonify({"ok": True, "message": "密码已更新"})


@bp.post("/profile")
@login_required
def api_profile():
    """自助修改个人资料（显示名 / 邮箱）。用户名不可改 —— 它是审计里的主键。"""
    conn = db.get_db()
    u = current_user()
    body = _json_body()
    changed = []
    if "display_name" in body:
        name = (body.get("display_name") or "").strip()[:64] or u["username"]
        conn.execute("UPDATE users SET display_name=? WHERE id=?", (name, u["id"]))
        changed.append("显示名")
    if "email" in body:
        email = (body.get("email") or "").strip()[:config.PROFILE_EMAIL_MAX]
        if email and ("@" not in email or " " in email):
            return jsonify({"ok": False, "message": "邮箱格式不正确"}), 400
        conn.execute("UPDATE users SET email=? WHERE id=?", (email or None, u["id"]))
        changed.append("邮箱")
    if not changed:
        return jsonify({"ok": False, "message": "没有要修改的内容"}), 400
    db.audit(conn, "profile", u["username"], "修改：" + "、".join(changed),
             request.remote_addr, u["id"])
    return jsonify({"ok": True, "message": "已更新：" + "、".join(changed)})


# ---------------- 用户管理（管理员） ----------------
def _user_public(r):
    """用户行 -> 可下发结构。**绝不包含口令散列，也不包含任何凭证。**"""
    return {"id": r["id"], "username": r["username"], "display_name": r["display_name"],
            "email": r["email"], "is_admin": bool(r["is_admin"]),
            "status": r["status"] or "active", "created_at": r["created_at"],
            "register_ip": r["register_ip"], "last_login_at": r["last_login_at"],
            "last_login_ip": r["last_login_ip"], "login_count": r["login_count"]}


@bp.get("/users")
@admin_required
def api_users():
    rows = db.get_db().execute("SELECT * FROM users ORDER BY id").fetchall()
    return jsonify({"items": [_user_public(r) for r in rows]})


@bp.post("/users")
@admin_required
def api_user_create():
    conn = db.get_db()
    me = current_user()
    body = _json_body()
    name = (body.get("username") or "").strip()
    pwd = (body.get("password") or "").strip()
    err = security.username_problem(name) or security.password_problem(
        pwd, body.get("password2"), name)
    if err:
        return jsonify({"ok": False, "message": err}), 400
    if db.user_by_name(conn, name):
        return jsonify({"ok": False, "message": "用户名已存在"}), 400
    # 默认建**普通账号**：多用户系统里「默认给管理员」是最常见的越权起点
    adm = 1 if str(body.get("is_admin", "0")) in ("1", "true", "on") else 0
    cur = conn.execute(
        "INSERT INTO users(username,password_hash,display_name,email,is_admin,status,created_at)"
        " VALUES(?,?,?,?,?, 'active', ?)",
        (name, security.hash_password(pwd),
         (body.get("display_name") or name).strip()[:64],
         (body.get("email") or "").strip()[:128] or None, adm, db.now_str()))
    db.audit(conn, "user_create", me["username"],
             "新建用户 %s（%s）" % (name, "管理员" if adm else "普通"), request.remote_addr, me["id"])
    return jsonify({"ok": True, "message": "已创建用户 %s" % name, "id": cur.lastrowid})


@bp.post("/users/<int:uid>")
@admin_required
def api_user_update(uid):
    conn = db.get_db()
    me = current_user()
    row = db.user_by_id(conn, uid)
    if row is None:
        return jsonify({"ok": False, "message": "用户不存在"}), 404
    body = _json_body()
    changed = []
    if "display_name" in body:
        conn.execute("UPDATE users SET display_name=? WHERE id=?",
                     ((body.get("display_name") or "").strip()[:64], uid))
        changed.append("显示名")
    if "email" in body:
        email = (body.get("email") or "").strip()[:config.PROFILE_EMAIL_MAX]
        if email and ("@" not in email or " " in email):
            return jsonify({"ok": False, "message": "邮箱格式不正确"}), 400
        conn.execute("UPDATE users SET email=? WHERE id=?", (email or None, uid))
        changed.append("邮箱")
    if "is_admin" in body:
        v = 1 if str(body.get("is_admin")) in ("1", "true", "on") else 0
        if uid == me["id"] and not v:
            return jsonify({"ok": False, "message": "不能取消自己的管理员身份"}), 400
        if not v and row["is_admin"]:
            left = conn.execute("SELECT COUNT(*) FROM users WHERE is_admin=1 AND status='active'"
                                " AND id<>?", (uid,)).fetchone()[0]
            if left == 0:
                return jsonify({"ok": False,
                                "message": "至少要保留一个启用状态的管理员"}), 400
        conn.execute("UPDATE users SET is_admin=? WHERE id=?", (v, uid))
        changed.append("管理员")
    if "status" in body:
        v = "active" if str(body.get("status")) in ("active", "1", "true", "on") else "disabled"
        if uid == me["id"] and v != "active":
            return jsonify({"ok": False, "message": "不能停用自己的账号"}), 400
        if v != "active":
            left = conn.execute("SELECT COUNT(*) FROM users WHERE is_admin=1 AND status='active'"
                                " AND id<>?", (uid,)).fetchone()[0]
            if row["is_admin"] and left == 0:
                return jsonify({"ok": False,
                                "message": "至少要保留一个启用状态的管理员"}), 400
        conn.execute("UPDATE users SET status=? WHERE id=?", (v, uid))
        changed.append("状态→" + ("启用" if v == "active" else "停用"))
    pwd = (body.get("password") or "").strip()
    if pwd:
        err = security.password_problem(pwd, body.get("password2"), row["username"])
        if err:
            return jsonify({"ok": False, "message": err}), 400
        conn.execute("UPDATE users SET password_hash=? WHERE id=?",
                     (security.hash_password(pwd), uid))
        changed.append("密码")
    if not changed:
        return jsonify({"ok": False, "message": "没有要修改的内容"}), 400
    db.audit(conn, "user_update", me["username"],
             "修改用户 %s：%s" % (row["username"], "、".join(changed)),
             request.remote_addr, me["id"])
    return jsonify({"ok": True, "message": "已更新：" + "、".join(changed)})


@bp.post("/users/<int:uid>/delete")
@admin_required
def api_user_delete(uid):
    conn = db.get_db()
    me = current_user()
    row = db.user_by_id(conn, uid)
    if row is None:
        return jsonify({"ok": False, "message": "用户不存在"}), 404
    if uid == me["id"]:
        return jsonify({"ok": False, "message": "不能删除当前登录的自己"}), 400
    if conn.execute("SELECT COUNT(*) FROM users").fetchone()[0] <= 1:
        return jsonify({"ok": False, "message": "至少要保留一个账号"}), 400
    if row["is_admin"]:
        left = conn.execute("SELECT COUNT(*) FROM users WHERE is_admin=1 AND status='active'"
                            " AND id<>?", (uid,)).fetchone()[0]
        if left == 0:
            return jsonify({"ok": False, "message": "至少要保留一个启用状态的管理员"}), 400
    keep = str(_json_body().get("keep_data", "")).strip() in ("1", "true", "on", "yes")
    if not keep:
        # 默认连同数据一起删 —— 留下孤儿数据既占空间，也会在重新注册
        # 同名用户时被新用户看到（历史遗留 user_id 复用风险）
        conn.execute("DELETE FROM usage_records WHERE user_id=?", (uid,))
        conn.execute("DELETE FROM settings WHERE user_id=?", (uid,))
        conn.execute("DELETE FROM collect_runs WHERE user_id=?", (uid,))
    conn.execute("DELETE FROM users WHERE id=?", (uid,))
    db.audit(conn, "user_delete", me["username"],
             "删除用户 %s（%s）" % (row["username"], "保留其数据" if keep else "连同数据一并删除"),
             request.remote_addr, me["id"])
    return jsonify({"ok": True, "message": "已删除 " + row["username"]})


@bp.post("/captcha")
@login_required
def api_captcha_note():
    """给前端一个「验证码怎么工作」的自述，便于排障时自检。"""
    conn = db.get_db()
    return jsonify({
        "policy": db.get_setting(conn, "captcha_policy", "always"),
        "length": db.get_int(conn, "captcha_length", 4),
        "ttl_seconds": 300,
        "image_url": "/captcha.png",
        "note": "答案只存在服务端 captchas 表；一次性使用，校验后立即删除。",
    })