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,
    GrantCashRequest,
    GrantCoinsRequest,
    SetDebugTraceRequest,
    SetForceOnboardingRequest,
    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}/force-onboarding", response_model=OkResponse, summary="一键开启/取消新手引导")
def set_user_force_onboarding(
    user_id: int,
    body: SetForceOnboardingRequest,
    request: Request,
    admin: Annotated[AdminUser, Depends(require_role("operator"))],
    db: AdminDb,
) -> OkResponse:
    """运营「一键开启新手引导」:置 user.force_onboarding。开启后该用户下次启动 App(/me 带出此字段)
    会被强制重走引导教程——即便此前已看完;走完引导后端自动清回 false,不无限循环。
    仅对支持 force_onboarding 的 App 版本生效(老版本忽略该字段)。"""
    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.force_onboarding
    # 业务写 + 审计写同一事务(commit=False),最后一起 commit(同 set_user_status / debug-trace)
    mutations.set_user_force_onboarding(db, user, enabled=body.enabled, commit=False)
    write_audit(
        db, admin, action="user.force_onboarding.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()


@router.post("/{user_id}/cash", response_model=OkResponse, summary="手动增减现金(带审计)")
def grant_user_cash(
    user_id: int,
    body: GrantCashRequest,
    request: Request,
    admin: Annotated[AdminUser, Depends(require_role("finance"))],
    db: AdminDb,
) -> OkResponse:
    """给指定用户增/减现金(分)。正=发放、负=扣减;主要用于让无现金用户直接测试提现。"""
    if body.amount_cents == 0:
        raise HTTPException(status_code=400, detail="amount_cents 不能为 0")
    user = user_repo.get_user_by_id(db, user_id)
    if user is None:
        raise HTTPException(status_code=404, detail="用户不存在")
    # 负数扣减时不允许扣成负余额(运营误操作保护)
    if body.amount_cents < 0:
        acc_now = wallet_repo.get_or_create_account(db, user_id, commit=False)
        if acc_now.cash_balance_cents + body.amount_cents < 0:
            raise HTTPException(
                status_code=400, detail=f"扣减后现金为负(当前余额 {acc_now.cash_balance_cents} 分)"
            )
    biz_type = "admin_grant" if body.amount_cents > 0 else "admin_deduct"
    # grant_cash 只 flush 不 commit;审计同 commit=False;最后一起 commit → 原子(改钱+留痕)
    acc, _ = wallet_repo.grant_cash(
        db, user_id, body.amount_cents, biz_type=biz_type, remark=f"admin:{body.reason}"[:128],
    )
    write_audit(
        db, admin, action="user.cash.grant", target_type="user", target_id=user_id,
        detail={
            "amount_cents": body.amount_cents,
            "balance_after_cents": acc.cash_balance_cents,
            "reason": body.reason,
        },
        ip=get_client_ip(request), commit=False,
    )
    db.commit()
    return OkResponse()