shaguabijia-app-server/app/admin/routers/users.py

"""admin 用户管理:列表 + 360 详情(读)+ 封禁/解封 + 手动调金币(写,带审计)。"""
from __future__ import annotations

from typing import Annotated

from fastapi import APIRouter, Depends, HTTPException, Query, Request

from app.admin.audit import write_audit
from app.admin.deps import AdminDb, get_client_ip, get_current_admin, require_role
from app.admin.repositories import mutations, queries
from app.admin.schemas.common import CursorPage, OkResponse
from app.admin.schemas.user import (
    AdminUserListItem,
    AdminUserOverview,
    GrantCoinsRequest,
    SetDebugTraceRequest,
    SetUserStatusRequest,
)
from app.models.admin import AdminUser
from app.repositories import user as user_repo
from app.repositories import wallet as wallet_repo

router = APIRouter(
    prefix="/admin/api/users",
    tags=["admin-users"],
    dependencies=[Depends(get_current_admin)],
)


@router.get("", response_model=CursorPage[AdminUserListItem], summary="用户列表(筛选+分页)")
def list_users(
    db: AdminDb,
    phone: Annotated[str | None, Query()] = None,
    register_channel: Annotated[str | None, Query()] = None,
    status: Annotated[str | None, Query()] = None,
    limit: Annotated[int, Query(ge=1, le=100)] = 20,
    cursor: Annotated[int | None, Query()] = None,
) -> CursorPage[AdminUserListItem]:
    items, next_cursor = queries.list_users(
        db, phone=phone, register_channel=register_channel, status=status,
        limit=limit, cursor=cursor,
    )
    return CursorPage(
        items=[AdminUserListItem.model_validate(u) for u in items],
        next_cursor=next_cursor,
    )


@router.get("/{user_id}", response_model=AdminUserOverview, summary="用户 360 详情")
def get_user(user_id: int, db: AdminDb) -> AdminUserOverview:
    overview = queries.get_user_overview(db, user_id)
    if overview is None:
        raise HTTPException(status_code=404, detail="用户不存在")
    return AdminUserOverview.model_validate(overview)


@router.post("/{user_id}/status", response_model=OkResponse, summary="封禁/解封用户")
def set_user_status(
    user_id: int,
    body: SetUserStatusRequest,
    request: Request,
    admin: Annotated[AdminUser, Depends(require_role("operator"))],
    db: AdminDb,
) -> OkResponse:
    user = user_repo.get_user_by_id(db, user_id)
    if user is None:
        raise HTTPException(status_code=404, detail="用户不存在")
    if user.status == "deleted":
        raise HTTPException(status_code=400, detail="已注销账号不可改状态")
    before = user.status
    # 业务写 + 审计写同一事务(commit=False),最后一起 commit:改了就有痕、有痕就真改了
    mutations.set_user_status(db, user, status=body.status, commit=False)
    write_audit(
        db, admin, action="user.status.set", target_type="user", target_id=user_id,
        detail={"before": before, "after": body.status}, ip=get_client_ip(request), commit=False,
    )
    db.commit()
    return OkResponse()


@router.post("/{user_id}/debug-trace", response_model=OkResponse, summary="开关调试链接权限")
def set_user_debug_trace(
    user_id: int,
    body: SetDebugTraceRequest,
    request: Request,
    admin: Annotated[AdminUser, Depends(require_role("operator"))],
    db: AdminDb,
) -> OkResponse:
    user = user_repo.get_user_by_id(db, user_id)
    if user is None:
        raise HTTPException(status_code=404, detail="用户不存在")
    before = user.debug_trace_enabled
    # 业务写 + 审计写同一事务(commit=False),最后一起 commit(同 set_user_status)
    mutations.set_user_debug_trace(db, user, enabled=body.enabled, commit=False)
    write_audit(
        db, admin, action="user.debug_trace.set", target_type="user", target_id=user_id,
        detail={"before": before, "after": body.enabled}, ip=get_client_ip(request), commit=False,
    )
    db.commit()
    return OkResponse()


@router.post("/{user_id}/coins", response_model=OkResponse, summary="手动增减金币(带审计)")
def grant_user_coins(
    user_id: int,
    body: GrantCoinsRequest,
    request: Request,
    admin: Annotated[AdminUser, Depends(require_role("finance"))],
    db: AdminDb,
) -> OkResponse:
    if body.amount == 0:
        raise HTTPException(status_code=400, detail="amount 不能为 0")
    user = user_repo.get_user_by_id(db, user_id)
    if user is None:
        raise HTTPException(status_code=404, detail="用户不存在")
    # 负数扣减时不允许扣成负余额(运营误操作保护)
    if body.amount < 0:
        acc_now = wallet_repo.get_or_create_account(db, user_id, commit=False)
        if acc_now.coin_balance + body.amount < 0:
            raise HTTPException(
                status_code=400, detail=f"扣减后金币为负(当前余额 {acc_now.coin_balance})"
            )
    biz_type = "admin_grant" if body.amount > 0 else "admin_deduct"
    # grant_coins 只 flush 不 commit;审计同 commit=False;最后一起 commit → 原子(改钱+留痕)
    acc, _ = wallet_repo.grant_coins(
        db, user_id, body.amount, biz_type=biz_type, remark=f"admin:{body.reason}"[:128],
    )
    write_audit(
        db, admin, action="user.coins.grant", target_type="user", target_id=user_id,
        detail={"amount": body.amount, "balance_after": acc.coin_balance, "reason": body.reason},
        ip=get_client_ip(request), commit=False,
    )
    db.commit()
    return OkResponse()