功能：实现托盘两阶段退回

2026-07-26 23:33:01 +08:00
parent cda87a4d65
commit e58e110dd1
5 changed files with 2361 additions and 15 deletions
@@ -0,0 +1,155 @@
+"""托盘两阶段退回接口。"""
+
+from typing import Annotated
+
+from fastapi import Path, Query, Request, Response
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from common.annotation.log_annotation import Log
+from common.aspect.db_seesion import DBSessionDependency
+from common.aspect.interface_auth import UserInterfaceAuthDependency
+from common.aspect.pre_auth import CurrentUserDependency, PreAuthDependency
+from common.enums import BusinessType
+from common.router import APIRouterPro
+from common.vo import DataResponseModel, PageResponseModel, ResponseBaseModel
+from module_admin.entity.vo.user_vo import CurrentUserModel
+from module_business.entity.vo.operation_vo import (
+    BusinessOptionModel,
+    PalletScanResponseModel,
+    ReturnConfirmModel,
+    ReturnModel,
+    ReturnPageQueryModel,
+    ReturnRequestModel,
+    ReturnScanQueryModel,
+)
+from module_business.service.return_service import ReturnService
+from utils.response_util import ResponseUtil
+
+return_controller = APIRouterPro(
+    prefix='/business/return',
+    tags=['业务管理-托盘退回'],
+    dependencies=[PreAuthDependency()],
+)
+
+
+@return_controller.get(
+    '/list',
+    summary='获取托盘退回单分页列表接口',
+    description='按当前用户来源现场或目标仓库数据范围获取退回单',
+    response_model=PageResponseModel[ReturnModel],
+    dependencies=[UserInterfaceAuthDependency('business:return:list')],
+)
+async def get_business_return_list(
+    request: Request,
+    return_page_query: Annotated[ReturnPageQueryModel, Query()],
+    query_db: Annotated[AsyncSession, DBSessionDependency()],
+    current_user: Annotated[CurrentUserModel, CurrentUserDependency()],
+) -> Response:
+    result = await ReturnService.get_return_list_services(
+        query_db,
+        return_page_query,
+        current_user,
+        is_page=True,
+    )
+    return ResponseUtil.success(model_content=result)
+
+
+@return_controller.get(
+    '/warehouse-options',
+    summary='获取退回目标仓库选项接口',
+    description='返回全部启用仓库作为客户发起退回的目标字典',
+    response_model=DataResponseModel[list[BusinessOptionModel]],
+    dependencies=[UserInterfaceAuthDependency('business:return:query')],
+)
+async def get_business_return_warehouse_options(
+    request: Request,
+    query_db: Annotated[AsyncSession, DBSessionDependency()],
+    current_user: Annotated[CurrentUserModel, CurrentUserDependency()],
+) -> Response:
+    result = await ReturnService.get_warehouse_options_services(query_db, current_user)
+    return ResponseUtil.success(data=result)
+
+
+@return_controller.get(
+    '/scan/{qr_token}',
+    summary='扫描退回托盘接口',
+    description='按申请现场或确认仓库数据范围重新查询托盘退回状态',
+    response_model=DataResponseModel[PalletScanResponseModel],
+    dependencies=[UserInterfaceAuthDependency('business:return:query')],
+)
+async def scan_business_return_pallet(
+    request: Request,
+    qr_token: Annotated[
+        str,
+        Path(min_length=1, max_length=128, pattern=r'\S', description='二维码固定标识'),
+    ],
+    return_scan_query: Annotated[ReturnScanQueryModel, Query()],
+    query_db: Annotated[AsyncSession, DBSessionDependency()],
+    current_user: Annotated[CurrentUserModel, CurrentUserDependency()],
+) -> Response:
+    result = await ReturnService.scan_return_pallet_services(
+        query_db,
+        qr_token,
+        return_scan_query,
+        current_user,
+    )
+    return ResponseUtil.success(data=result)
+
+
+@return_controller.post(
+    '/request',
+    summary='发起托盘退回申请接口',
+    description='原子冻结同一客户现场的全部退回托盘并保存库存快照',
+    response_model=ResponseBaseModel,
+    dependencies=[UserInterfaceAuthDependency('business:return:request')],
+)
+@Log(title='托盘退回', business_type=BusinessType.INSERT)
+async def request_business_return(
+    request: Request,
+    request_command: ReturnRequestModel,
+    query_db: Annotated[AsyncSession, DBSessionDependency()],
+    current_user: Annotated[CurrentUserModel, CurrentUserDependency()],
+) -> Response:
+    result = await ReturnService.request_return_services(query_db, request_command, current_user)
+    return ResponseUtil.success(msg=result.message)
+
+
+@return_controller.get(
+    '/{return_id}',
+    summary='获取托盘退回单详情接口',
+    description='按来源现场或目标仓库数据范围获取指定退回单',
+    response_model=DataResponseModel[ReturnModel],
+    dependencies=[UserInterfaceAuthDependency('business:return:query')],
+)
+async def query_detail_business_return(
+    request: Request,
+    return_id: Annotated[int, Path(gt=0, description='退回单ID')],
+    query_db: Annotated[AsyncSession, DBSessionDependency()],
+    current_user: Annotated[CurrentUserModel, CurrentUserDependency()],
+) -> Response:
+    result = await ReturnService.return_detail_services(query_db, return_id, current_user)
+    return ResponseUtil.success(data=result)
+
+
+@return_controller.put(
+    '/{return_id}/confirm',
+    summary='确认托盘退回接口',
+    description='核对整单扫码集合和申请快照后原子移入目标仓库',
+    response_model=ResponseBaseModel,
+    dependencies=[UserInterfaceAuthDependency('business:return:confirm')],
+)
+@Log(title='托盘退回', business_type=BusinessType.UPDATE)
+async def confirm_business_return(
+    request: Request,
+    return_id: Annotated[int, Path(gt=0, description='退回单ID')],
+    confirm_command: ReturnConfirmModel,
+    query_db: Annotated[AsyncSession, DBSessionDependency()],
+    current_user: Annotated[CurrentUserModel, CurrentUserDependency()],
+) -> Response:
+    result = await ReturnService.confirm_return_services(
+        query_db,
+        return_id,
+        confirm_command,
+        current_user,
+    )
+    return ResponseUtil.success(msg=result.message)