wecom_it_smart_desk/backend/app/api/otp.py

# =============================================================================
# 企微IT智能服务台 — 统一 OTP 二次认证 API（三端认证重构 AUTH-03）
# =============================================================================
# 说明：三端（H5 员工端 / 坐席端 / 管理端）统一的 OTP(TOTP) 二次认证路由。
#
# 端点列表（前缀 /auth，nginx 会剥离 /api 前缀，对外即 /api/auth/otp-*）：
#   1. GET  /auth/otp-status            — 查询绑定状态（路由守卫用）
#   2. POST /auth/otp-bind              — 生成 secret + 二维码（尚未启用）
#   3. POST /auth/otp-verify            — 输入 OTP 通过验证（写 Redis 30 分钟）
#   4. POST /auth/otp-unbind            — 用户主动关闭 MFA
#   5. POST /auth/otp-admin-reset/{id}  — 管理员重置（员工丢手机兜底）
#   6. GET  /auth/otp-admin-users       — 管理员查看全部坐席 MFA 绑定状态
#
# 设计要点（与 system_design.md 对齐）：
#   - 复用 MFAService（pyotp + qrcode）与 agents 表的 mfa_* 字段
#   - 验证通过后在 Redis 写 mfa:verified:{employee_id}，TTL=1800s
#   - 与 dependencies.require_high_risk_otp 共用同一 Redis key（契约不变）
#   - 取代原 /mfa/* 与 /admin/mfa/* 以及 agents 内联 /agents/otp-* 端点
#
# 鉴权：
#   - 1-4 用 get_current_user（任意已登录用户）
#   - 5-6 用 require_role("admin")（管理员）
# =============================================================================

import logging
from datetime import datetime
from typing import Optional

import redis.asyncio as aioredis
from fastapi import APIRouter, Depends
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession

from app.config import settings
from app.database import get_db
from app.dependencies import UserInfo, get_current_user, require_role
from app.models.agent import Agent
from app.schemas.mfa import (
    MFABindConfirmRequest,
    MFABindStartResponse,
    MFADisableRequest,
    MFADisableResponse,
    MFAStatusResponse,
    MFAVerifyRequest,
    MFAVerifyResponse,
)
from app.services.mfa_service import MFA_VERIFIED_TTL_SECONDS, MFAService
from app.utils.error_codes import ErrorCode
from app.utils.response import AppException, success_response

logger = logging.getLogger(__name__)


# -----------------------------------------------------------------------------
# 路由配置：统一前缀 /auth
# -----------------------------------------------------------------------------
router = APIRouter(prefix="/auth", tags=["OTP二次认证"])


def _get_redis() -> aioredis.Redis:
    """获取 Redis 客户端（模块级 helper，便于测试 patch）。

    Returns:
        aioredis.Redis: Redis 异步客户端
    """
    return settings.create_redis_client()


# -----------------------------------------------------------------------------
# 通用工具：根据 user_id(employee_id) 查 Agent 记录
# -----------------------------------------------------------------------------
async def _get_agent_by_employee_id(
    db: AsyncSession, employee_id: str
) -> Optional[Agent]:
    """按 user_id（employee_id）查询 Agent 行。

    Args:
        db: 数据库会话
        employee_id: 用户标识（企微 userid）

    Returns:
        Optional[Agent]: 找不到返回 None
    """
    stmt = select(Agent).where(Agent.user_id == employee_id)
    result = await db.execute(stmt)
    return result.scalars().first()


# -----------------------------------------------------------------------------
# 通用工具：验证当前用户是否已登录 + 取得 Agent 行
# -----------------------------------------------------------------------------
async def _require_agent(
    db: AsyncSession, current_user: UserInfo
) -> Agent:
    """根据当前 token 取出对应的 Agent 行，不存在则 404。

    MFA 状态 / secret 都存放在 agents 表，不是 employees 表。

    Raises:
        AppException: 坐席不存在（E4001）
    """
    agent = await _get_agent_by_employee_id(db, current_user.employee_id)
    if not agent:
        raise AppException(ErrorCode.AGENT_NOT_FOUND, "坐席不存在，无法进行 OTP 操作")
    return agent


# =============================================================================
# 1. GET /auth/otp-status — 查询绑定状态
# =============================================================================
@router.get("/otp-status", response_model=None)
async def get_otp_status(
    current_user: UserInfo = Depends(get_current_user),
    db: AsyncSession = Depends(get_db),
    redis: aioredis.Redis = Depends(_get_redis),
):
    """查询当前用户的 OTP 绑定状态。

    前端路由守卫使用：
      - bound=false → 强制走绑定流程
      - bound=true  → 跳到"输入 OTP 验证"或继续业务

    Returns:
        success_response({bound, enabled, last_verified_at, verified})
    """
    agent = await _require_agent(db, current_user)

    # 是否处于 30 分钟验证窗口内（与 require_high_risk_otp 共用 key）
    verified = await MFAService.is_verified(redis, agent.user_id)

    return success_response(data=MFAStatusResponse(
        bound=bool(agent.mfa_enabled and agent.mfa_secret),
        enabled=bool(agent.mfa_enabled),
        last_verified_at=agent.mfa_last_verified_at,
    ).model_dump(mode="json") | {"verified": verified})


# =============================================================================
# 2. POST /auth/otp-bind — 生成 secret + 二维码
# =============================================================================
@router.post("/otp-bind", response_model=None)
async def bind_otp(
    current_user: UserInfo = Depends(get_current_user),
    db: AsyncSession = Depends(get_db),
):
    """生成 TOTP 密钥和二维码。

    行为：
      - 生成 32 位 base32 secret
      - 把 secret 写入 agents.mfa_secret（mfa_enabled=False, mfa_bound_at=None）
      - 返回 otpauth URI + base64 二维码 PNG（给前端展示）

    重复调用策略：
      - 已 enabled=True → 拒绝，要求先 unbind 再重新绑定
      - 仅 secret 存在但 enabled=False → 复用旧 secret（支持"刷新二维码"）

    Returns:
        success_response({secret, otpauth_url, qr_code_base64})
    """
    agent = await _require_agent(db, current_user)

    # 已启用则拒绝重新绑定（必须先 unbind）
    if agent.mfa_enabled:
        raise AppException(
            ErrorCode.INVALID_PARAMETER,
            "已绑定 OTP，如需重新绑定请先关闭",
        )

    # 复用旧 secret 还是新生成？
    if agent.mfa_secret:
        secret = agent.mfa_secret
    else:
        secret = MFAService.generate_secret()
        agent.mfa_secret = secret
        # mfa_enabled 保持 False，mfa_bound_at 等首次验证通过再写
        db.add(agent)
        await db.flush()

    otpauth_url = MFAService.build_provisioning_uri(secret, agent.user_id)
    qr_base64 = MFAService.render_qrcode_base64(otpauth_url)

    logger.info(f"OTP bind: agent={agent.user_id}, secret_prefix={secret[:4]}...")

    return success_response(data=MFABindStartResponse(
        secret=secret,
        otpauth_url=otpauth_url,
        qr_code_base64=qr_base64,
    ).model_dump())


# =============================================================================
# 3. POST /auth/otp-verify — 输入 OTP 通过验证（写 Redis 30 分钟）
# =============================================================================
@router.post("/otp-verify", response_model=None)
async def verify_otp(
    body: MFAVerifyRequest,
    current_user: UserInfo = Depends(get_current_user),
    db: AsyncSession = Depends(get_db),
    redis: aioredis.Redis = Depends(_get_redis),
):
    """校验 6 位码，在 Redis 写 30 分钟复用标记。

    行为：
      - 校验通过 → mfa:verified:{employee_id}=1 TTL 1800s
                  + 更新 mfa_last_verified_at
      - 校验失败 → verified=false（不抛异常，前端可重试）

    Returns:
        success_response({verified, expires_in})
    """
    agent = await _require_agent(db, current_user)

    if not agent.mfa_enabled or not agent.mfa_secret:
        # 用户还没绑定 OTP，直接返回 verified=false（前端可据此跳转绑定流程）
        return success_response(data=MFAVerifyResponse(
            verified=False,
            expires_in=0,
        ).model_dump())

    # 校验
    if not MFAService.verify_code(agent.mfa_secret, body.otp_code):
        logger.warning(f"OTP verify 验证码错误: agent={agent.user_id}")
        return success_response(data=MFAVerifyResponse(
            verified=False,
            expires_in=0,
        ).model_dump())

    # 写 Redis 复用标记（与 require_high_risk_otp 共用 key）
    await MFAService.mark_verified(redis, agent.user_id, MFA_VERIFIED_TTL_SECONDS)

    # 更新最后验证时间
    now = datetime.now()
    agent.mfa_last_verified_at = now
    db.add(agent)
    await db.flush()

    logger.info(f"OTP verify 通过: agent={agent.user_id}")

    return success_response(data=MFAVerifyResponse(
        verified=True,
        expires_in=MFA_VERIFIED_TTL_SECONDS,
    ).model_dump())


# =============================================================================
# 4. POST /auth/otp-unbind — 用户主动关闭 OTP
# =============================================================================
@router.post("/otp-unbind", response_model=None)
async def unbind_otp(
    body: MFADisableRequest,
    current_user: UserInfo = Depends(get_current_user),
    db: AsyncSession = Depends(get_db),
    redis: aioredis.Redis = Depends(_get_redis),
):
    """关闭 OTP（清空 secret + disabled 标记）。

    安全要求：必须先校验当前 OTP，防止误操作或被劫持后恶意关闭。

    Returns:
        success_response({success: true})
    """
    agent = await _require_agent(db, current_user)

    if not agent.mfa_enabled or not agent.mfa_secret:
        # 没绑定过，直接幂等成功
        return success_response(data=MFADisableResponse(success=True).model_dump())

    # 必须先验证 OTP
    if not MFAService.verify_code(agent.mfa_secret, body.otp_code):
        raise AppException(ErrorCode.INVALID_PARAMETER, "OTP 验证码错误，无法关闭 OTP")

    # 清空字段
    agent.mfa_secret = None
    agent.mfa_enabled = False
    agent.mfa_bound_at = None
    # mfa_last_verified_at 保留，作为历史记录
    db.add(agent)
    await db.flush()

    # 顺手清掉 Redis 验证标记（避免遗留）
    await MFAService.clear_verified(redis, agent.user_id)

    logger.info(f"OTP unbind: agent={agent.user_id}")

    return success_response(data=MFADisableResponse(success=True).model_dump())


# =============================================================================
# 5. POST /auth/otp-admin-reset/{employee_id} — 管理员重置（丢手机兜底）
# =============================================================================
# 注意：此端点不要求 otp_code（员工已无法提供），只校验 admin 角色
# 鉴权：@require_role("admin") 装饰器强制
# =============================================================================
@router.post("/otp-admin-reset/{employee_id}", response_model=None)
@require_role("admin")
async def admin_reset_otp(
    employee_id: str,
    current_user: UserInfo = Depends(get_current_user),
    db: AsyncSession = Depends(get_db),
    redis: aioredis.Redis = Depends(_get_redis),
):
    """管理员重置指定员工的 OTP 绑定（无 OTP 验证）。

    使用场景：
      - 员工丢手机 / 换手机 → 管理员后台"重置 OTP"按钮

    Returns:
        success_response({success: true})
    """
    stmt = select(Agent).where(Agent.user_id == employee_id)
    result = await db.execute(stmt)
    agent = result.scalars().first()

    if not agent:
        raise AppException(ErrorCode.AGENT_NOT_FOUND, f"坐席 {employee_id} 不存在")

    agent.mfa_secret = None
    agent.mfa_enabled = False
    agent.mfa_bound_at = None
    # mfa_last_verified_at 保留，作为审计
    db.add(agent)
    await db.flush()

    # 顺手清 Redis 标记
    await MFAService.clear_verified(redis, employee_id)

    logger.info(f"OTP admin reset: employee_id={employee_id} by={current_user.employee_id}")

    return success_response(data={"success": True})


# =============================================================================
# 6. GET /auth/otp-admin-users — 管理员查看全部坐席 OTP 绑定状态
# =============================================================================
@router.get("/otp-admin-users", response_model=None)
@require_role("admin")
async def admin_list_otp_users(
    current_user: UserInfo = Depends(get_current_user),
    db: AsyncSession = Depends(get_db),
):
    """管理员查看全部坐席的 OTP 绑定状态。

    Returns:
        success_response([{employee_id, name, mfa_enabled, mfa_bound_at,
                           mfa_last_verified_at}, ...])
    """
    stmt = select(Agent).order_by(Agent.user_id)
    result = await db.execute(stmt)
    agents = result.scalars().all()

    users = [
        {
            "employee_id": a.user_id,
            "name": getattr(a, "name", "") or "",
            "mfa_enabled": bool(a.mfa_enabled),
            "mfa_bound_at": a.mfa_bound_at.isoformat() if a.mfa_bound_at else None,
            "mfa_last_verified_at": (
                a.mfa_last_verified_at.isoformat() if a.mfa_last_verified_at else None
            ),
        }
        for a in agents
    ]

    return success_response(data=users)