dingdanquanliucheng/backend/app/api/ai.py

"""
AI 智能识别路由模块

提供 AI 图像识别和订单智能解析接口，包括：
- 图像识别（识别订单图片内容）
- 识别结果纠错（修正AI识别错误）
- 订单智能解析（从文本/图片中提取订单信息）

URL 前缀：/api/ai
权限要求：manager/admin 角色，需对应细粒度权限
"""

from fastapi import APIRouter, Depends
from sqlalchemy.orm import Session

from backend.app.api.deps import require_permissions, require_roles
from backend.app.db import get_db_session
from backend.app.schemas.ai import CorrectRecognizeResultRequest, ParseCustomerRequest, ParseOrderRequest, RecognizeImageRequest
from backend.app.schemas.common import success_payload
from backend.app.services.ai_service import ai_service

router = APIRouter(prefix="/api/ai", tags=["ai"])


@router.post("/recognize")
def recognize_image(
    payload: RecognizeImageRequest,  # 图像识别请求体，包含图片URL或Base64数据
    session: Session = Depends(get_db_session),  # 数据库会话
    current_user: dict = Depends(require_roles("manager", "admin")),  # 当前登录用户，仅manager和admin
    _permission_user: dict = Depends(require_permissions("ai:recognize")),  # 权限校验：AI识别权限
) -> dict:
    """
    AI 图像识别

    上传订单相关图片，由AI进行OCR识别并提取结构化信息。

    请求参数：
        payload: RecognizeImageRequest 请求体，包含图片数据

    返回值：
        AI识别结果，包含提取的订单信息

    权限要求：manager、admin 角色，需 ai:recognize 权限
    """
    return success_payload(ai_service.recognize_image(payload.model_dump(), session))


@router.post("/recognize/{log_id}/correct")
def correct_recognize_result(
    log_id: int,  # AI识别日志ID
    payload: CorrectRecognizeResultRequest,  # 纠错请求体，包含修正后的识别结果
    session: Session = Depends(get_db_session),  # 数据库会话
    current_user: dict = Depends(require_roles("manager", "admin")),  # 当前登录用户
    _permission_user: dict = Depends(require_permissions("ai:correct")),  # 权限校验：AI纠错权限
) -> dict:
    """
    纠正AI识别结果

    对之前的AI识别结果进行人工修正，用于提升后续AI模型的准确率。

    请求参数：
        log_id: 路径参数，AI识别日志ID
        payload: CorrectRecognizeResultRequest 请求体，包含修正后的数据

    返回值：
        纠正后的识别结果

    权限要求：manager、admin 角色，需 ai:correct 权限
    """
    return success_payload(ai_service.correct_result(log_id, payload.model_dump(), session))


@router.post("/parse-order")
def parse_order(
    payload: ParseOrderRequest,  # 订单解析请求体，包含待解析的文本或图片数据
    session: Session = Depends(get_db_session),  # 数据库会话
    current_user: dict = Depends(require_roles("salesman", "admin")),  # 当前登录用户，仅salesman和admin
    _permission_user: dict = Depends(require_permissions("ai:parse-order")),  # 权限校验：AI订单解析权限
) -> dict:
    """
    AI 订单智能解析

    利用AI从文本或图片中提取订单关键信息（客户名、产品、数量、价格等），
    返回结构化的订单数据供前端填充表单。

    请求参数：
        payload: ParseOrderRequest 请求体，包含待解析内容

    返回值：
        解析后的结构化订单数据

    权限要求：salesman、admin 角色，需 ai:parse-order 权限
    """
    return success_payload(ai_service.parse_order(payload.model_dump(), session))


@router.post("/parse-customer")
def parse_customer(
    payload: ParseCustomerRequest,  # 客户信息解析请求体，包含待解析的文本
    session: Session = Depends(get_db_session),  # 数据库会话
    current_user: dict = Depends(require_roles("salesman", "admin")),  # 当前登录用户，仅salesman和admin
    _permission_user: dict = Depends(require_permissions("ai:parse-order")),  # 权限校验：复用订单解析权限
) -> dict:
    """
    AI 客户信息智能解析

    利用AI从文本中提取客户关键信息（姓名、手机号、地址等），
    返回结构化的客户数据供前端填充表单。

    请求参数：
        payload: ParseCustomerRequest 请求体，包含待解析内容

    返回值：
        解析后的结构化客户数据

    权限要求：salesman、admin 角色，需 ai:parse-order 权限
    """
    return success_payload(ai_service.parse_customer(payload.model_dump(), session))