Feat: 后端新增基础资料与业务管理只读汇总接口

为 Web 端改版提供名称、统计和看板数据。只新增只读查询、扩展列表与详情
返回字段；写接口、托盘状态机和幂等键规则均未改动，未新增权限标识。

- 基础资料：列表补充名称与汇总，客户详情返回现场树，托盘详情返回最近流转，
  托盘列表支持按流转阶段筛选和二维码精确匹配；新增现场、产线、隧道的上级
  资料选项接口；Excel 导入支持 preview 只校验不写入
- 发货出库：列表支持 keyword、receiptState 筛选并补充名称、托盘数、包数和
  菌种构成；详情明细补充托盘号、菌种、批次
- 首次入库：列表与详情补充名称、托盘数、托盘当前状态；新增 /summary
- 托盘退回：列表支持 keyword 并补充名称与托盘汇总，详情补充托盘号和隧道；
  新增 /summary、/site-options
- 工厂装填：列表支持 keyword 并补充托盘号、仓库、操作人；新增 /summary、
  /batches、/batches/detail
- 客户现场使用：列表支持 keyword、fifoSkipped 并补充名称和被跳过的先到托盘号；
  新增 /site-options、/site-board 以及 usage-fifo 的 /queue
- 先到先用 DAO 抽出公共候选条件与排序，建议查询生成的 SQL 与改动前一致
- 新增各汇总 DAO 的单元测试，同步更新路由权限与模型字段契约测试

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

shierfeng-fastapi-backend/module_business/controller/customer_controller.py

@@ -14,8 +14,10 @@ from common.vo import DataResponseModel, PageResponseModel, ResponseBaseModel
 from module_admin.entity.vo.user_vo import CurrentUserModel
 from module_business.dependency.test_batch_dependency import TestBatchScopeDependency
 from module_business.domain.test_batch_scope import TestBatchScope
+from module_business.entity.vo.master_summary_vo import CustomerDetailModel, CustomerListItemModel
 from module_business.entity.vo.master_vo import CustomerModel, CustomerPageQueryModel, DeleteCustomerModel
 from module_business.service.master_service import MasterService
+from module_business.service.master_summary_service import MasterSummaryService
 from utils.response_util import ResponseUtil
 
 customer_controller = APIRouterPro(
@@ -27,7 +29,7 @@ customer_controller = APIRouterPro(
     '/list',
     summary='获取客户分页列表接口',
     description='用于获取客户分页列表',
-    response_model=PageResponseModel[CustomerModel],
+    response_model=PageResponseModel[CustomerListItemModel],
     dependencies=[UserInterfaceAuthDependency('master:customer:list')],
 )
 async def get_master_customer_list(
@@ -37,6 +39,9 @@ async def get_master_customer_list(
     scope: Annotated[TestBatchScope, TestBatchScopeDependency()],
 ) -> Response:
     customer_page_query_result = await MasterService.list_customer(query_db, customer_page_query, scope, is_page=True)
+    customer_page_query_result = await MasterSummaryService.enrich_page(
+        query_db, 'customer', customer_page_query_result, scope
+    )
 
     return ResponseUtil.success(model_content=customer_page_query_result)
 
@@ -45,7 +50,7 @@ async def get_master_customer_list(
     '/{customer_id}',
     summary='获取客户详情接口',
     description='用于获取指定客户的详细信息',
-    response_model=DataResponseModel[CustomerModel],
+    response_model=DataResponseModel[CustomerDetailModel],
     dependencies=[UserInterfaceAuthDependency('master:customer:query')],
 )
 async def query_detail_master_customer(
@@ -55,6 +60,7 @@ async def query_detail_master_customer(
     scope: Annotated[TestBatchScope, TestBatchScopeDependency()],
 ) -> Response:
     customer_detail_result = await MasterService.detail_customer(query_db, customer_id, scope)
+    customer_detail_result = await MasterSummaryService.customer_detail(query_db, customer_detail_result, scope)
 
     return ResponseUtil.success(data=customer_detail_result)
 

shierfeng-fastapi-backend/module_business/controller/filling_controller.py

@@ -15,8 +15,14 @@ from module_business.dependency.test_batch_dependency import TestBatchScopeDepen
 from module_business.domain.test_batch_scope import TestBatchScope
 from module_business.entity.vo.operation_vo import (
     BusinessOptionModel,
+    FillingBatchDetailModel,
+    FillingBatchDetailQueryModel,
+    FillingBatchModel,
+    FillingBatchPageQueryModel,
     FillingCreateModel,
+    FillingListItemModel,
     FillingModel,
+    FillingOverviewModel,
     FillingPageQueryModel,
     PalletScanResponseModel,
 )
@@ -34,7 +40,7 @@ filling_controller = APIRouterPro(
     '/list',
     summary='获取托盘装填记录分页列表接口',
     description='按当前用户仓库数据范围获取托盘装填记录分页列表',
-    response_model=PageResponseModel[FillingModel],
+    response_model=PageResponseModel[FillingListItemModel],
     dependencies=[UserInterfaceAuthDependency('business:filling:list')],
 )
 async def get_business_filling_list(
@@ -54,6 +60,64 @@ async def get_business_filling_list(
     return ResponseUtil.success(model_content=result)
 
 
+@filling_controller.get(
+    '/summary',
+    summary='获取工厂装填概况接口',
+    description='按当前用户仓库数据范围统计今日与本月装填、可装填空托盘和临期仍在仓的托盘',
+    response_model=DataResponseModel[FillingOverviewModel],
+    dependencies=[UserInterfaceAuthDependency('business:filling:list')],
+)
+async def get_business_filling_summary(
+    request: Request,
+    query_db: Annotated[AsyncSession, DBSessionDependency()],
+    current_user: Annotated[CurrentUserModel, CurrentUserDependency()],
+    test_scope: Annotated[TestBatchScope, TestBatchScopeDependency()],
+) -> Response:
+    result = await FillingService.get_filling_overview_services(query_db, current_user, test_scope)
+    return ResponseUtil.success(data=result)
+
+
+@filling_controller.get(
+    '/batches',
+    summary='获取生产批次装填汇总分页列表接口',
+    description='按当前用户仓库数据范围，将装填记录按菌种与生产批次聚合，最近装填的批次在前',
+    response_model=PageResponseModel[FillingBatchModel],
+    dependencies=[UserInterfaceAuthDependency('business:filling:list')],
+)
+async def get_business_filling_batches(
+    request: Request,
+    batch_page_query: Annotated[FillingBatchPageQueryModel, Query()],
+    query_db: Annotated[AsyncSession, DBSessionDependency()],
+    current_user: Annotated[CurrentUserModel, CurrentUserDependency()],
+    test_scope: Annotated[TestBatchScope, TestBatchScopeDependency()],
+) -> Response:
+    result = await FillingService.get_filling_batches_services(query_db, batch_page_query, current_user, test_scope)
+    return ResponseUtil.success(model_content=result)
+
+
+@filling_controller.get(
+    '/batches/detail',
+    summary='获取生产批次详情接口',
+    description='按当前用户仓库数据范围返回批次汇总、托盘当前去向与最近装填记录',
+    response_model=DataResponseModel[FillingBatchDetailModel],
+    dependencies=[UserInterfaceAuthDependency('business:filling:query')],
+)
+async def get_business_filling_batch_detail(
+    request: Request,
+    batch_detail_query: Annotated[FillingBatchDetailQueryModel, Query()],
+    query_db: Annotated[AsyncSession, DBSessionDependency()],
+    current_user: Annotated[CurrentUserModel, CurrentUserDependency()],
+    test_scope: Annotated[TestBatchScope, TestBatchScopeDependency()],
+) -> Response:
+    result = await FillingService.get_filling_batch_detail_services(
+        query_db,
+        batch_detail_query,
+        current_user,
+        test_scope,
+    )
+    return ResponseUtil.success(data=result)
+
+
 @filling_controller.get(
     '/strain-options',
     summary='获取装填菌种选项接口',

shierfeng-fastapi-backend/module_business/controller/inbound_controller.py

@@ -17,7 +17,9 @@ from module_business.entity.vo.operation_vo import (
     BusinessOptionModel,
     ConfirmCommandModel,
     InboundCreateModel,
+    InboundListItemModel,
     InboundModel,
+    InboundOverviewModel,
     InboundPageQueryModel,
     InboundScanQueryModel,
     InboundUpdateModel,
@@ -37,7 +39,7 @@ inbound_controller = APIRouterPro(
     '/list',
     summary='获取首次入库单分页列表接口',
     description='按当前用户仓库数据范围获取首次入库单分页列表',
-    response_model=PageResponseModel[InboundModel],
+    response_model=PageResponseModel[InboundListItemModel],
     dependencies=[UserInterfaceAuthDependency('business:inbound:list')],
 )
 async def get_business_inbound_list(
@@ -57,6 +59,23 @@ async def get_business_inbound_list(
     return ResponseUtil.success(model_content=result)
 
 
+@inbound_controller.get(
+    '/summary',
+    summary='获取首次入库概况接口',
+    description='按当前用户仓库数据范围统计待确认草稿、本月入库、待首次入库托盘与仓库空托盘',
+    response_model=DataResponseModel[InboundOverviewModel],
+    dependencies=[UserInterfaceAuthDependency('business:inbound:list')],
+)
+async def get_business_inbound_summary(
+    request: Request,
+    query_db: Annotated[AsyncSession, DBSessionDependency()],
+    current_user: Annotated[CurrentUserModel, CurrentUserDependency()],
+    test_scope: Annotated[TestBatchScope, TestBatchScopeDependency()],
+) -> Response:
+    result = await InboundService.get_inbound_overview_services(query_db, current_user, test_scope)
+    return ResponseUtil.success(data=result)
+
+
 @inbound_controller.get(
     '/warehouse-options',
     summary='获取首次入库仓库选项接口',

shierfeng-fastapi-backend/module_business/controller/line_controller.py

@@ -14,18 +14,40 @@ from common.vo import DataResponseModel, PageResponseModel, ResponseBaseModel
 from module_admin.entity.vo.user_vo import CurrentUserModel
 from module_business.dependency.test_batch_dependency import TestBatchScopeDependency
 from module_business.domain.test_batch_scope import TestBatchScope
+from module_business.entity.vo.master_summary_vo import LineListItemModel, MasterParentOptionModel
 from module_business.entity.vo.master_vo import DeleteLineModel, LineModel, LinePageQueryModel
 from module_business.service.master_service import MasterService
+from module_business.service.master_summary_service import MasterSummaryService
 from utils.response_util import ResponseUtil
 
 line_controller = APIRouterPro(prefix='/master/line', tags=['基础资料-生产线管理'], dependencies=[PreAuthDependency()])
+# 上级资料选项单独注册且排在详情路由之前，避免被 /{line_id} 捕获
+line_option_controller = APIRouterPro(
+    prefix='/master/line', order_num=99, tags=['基础资料-生产线管理'], dependencies=[PreAuthDependency()]
+)
+
+
+@line_option_controller.get(
+    '/site-options',
+    summary='获取产线可选现场接口',
+    description='新增或修改产线时选择所属现场，只返回状态正常的现场',
+    response_model=DataResponseModel[list[MasterParentOptionModel]],
+    dependencies=[UserInterfaceAuthDependency('master:line:list')],
+)
+async def get_master_line_site_options(
+    request: Request,
+    query_db: Annotated[AsyncSession, DBSessionDependency()],
+    scope: Annotated[TestBatchScope, TestBatchScopeDependency()],
+) -> Response:
+    options = await MasterSummaryService.site_options(query_db, scope)
+    return ResponseUtil.success(data=options)
 
 
 @line_controller.get(
     '/list',
     summary='获取生产线分页列表接口',
     description='用于获取生产线分页列表',
-    response_model=PageResponseModel[LineModel],
+    response_model=PageResponseModel[LineListItemModel],
     dependencies=[UserInterfaceAuthDependency('master:line:list')],
 )
 async def get_master_line_list(
@@ -35,6 +57,7 @@ async def get_master_line_list(
     scope: Annotated[TestBatchScope, TestBatchScopeDependency()],
 ) -> Response:
     line_page_query_result = await MasterService.list_line(query_db, line_page_query, scope, is_page=True)
+    line_page_query_result = await MasterSummaryService.enrich_page(query_db, 'line', line_page_query_result, scope)
 
     return ResponseUtil.success(model_content=line_page_query_result)
 

shierfeng-fastapi-backend/module_business/controller/master_excel_controller.py

@@ -88,7 +88,14 @@ async def _import_excel(
     db: AsyncSession,
     current_user: CurrentUserModel,
     scope: TestBatchScope,
+    preview: bool = False,
 ) -> Response:
+    if preview:
+        preview_result = await MasterExcelService.preview_import(
+            db, resource, file, update_support, current_user, scope
+        )
+        logger.info('导入校验完成')
+        return ResponseUtil.success(msg='校验完成，尚未写入', data=preview_result)
     result = await MasterExcelService.import_resource(
         db, resource, file, update_support, current_user, scope
     )
@@ -127,8 +134,9 @@ async def import_master_strain_excel(
     query_db: Annotated[AsyncSession, DBSessionDependency()],
     current_user: Annotated[CurrentUserModel, CurrentUserDependency()],
     scope: Annotated[TestBatchScope, TestBatchScopeDependency(write=True)],
+    preview: Annotated[bool, Query(description='只校验不写入')] = False,
 ) -> Response:
-    return await _import_excel('strain', file, update_support, query_db, current_user, scope)
+    return await _import_excel('strain', file, update_support, query_db, current_user, scope, preview)
 
 
 @strain_excel_controller.post(
@@ -176,8 +184,9 @@ async def import_master_customer_excel(
     query_db: Annotated[AsyncSession, DBSessionDependency()],
     current_user: Annotated[CurrentUserModel, CurrentUserDependency()],
     scope: Annotated[TestBatchScope, TestBatchScopeDependency(write=True)],
+    preview: Annotated[bool, Query(description='只校验不写入')] = False,
 ) -> Response:
-    return await _import_excel('customer', file, update_support, query_db, current_user, scope)
+    return await _import_excel('customer', file, update_support, query_db, current_user, scope, preview)
 
 
 @customer_excel_controller.post(
@@ -225,8 +234,9 @@ async def import_master_site_excel(
     query_db: Annotated[AsyncSession, DBSessionDependency()],
     current_user: Annotated[CurrentUserModel, CurrentUserDependency()],
     scope: Annotated[TestBatchScope, TestBatchScopeDependency(write=True)],
+    preview: Annotated[bool, Query(description='只校验不写入')] = False,
 ) -> Response:
-    return await _import_excel('site', file, update_support, query_db, current_user, scope)
+    return await _import_excel('site', file, update_support, query_db, current_user, scope, preview)
 
 
 @site_excel_controller.post(
@@ -274,8 +284,9 @@ async def import_master_line_excel(
     query_db: Annotated[AsyncSession, DBSessionDependency()],
     current_user: Annotated[CurrentUserModel, CurrentUserDependency()],
     scope: Annotated[TestBatchScope, TestBatchScopeDependency(write=True)],
+    preview: Annotated[bool, Query(description='只校验不写入')] = False,
 ) -> Response:
-    return await _import_excel('line', file, update_support, query_db, current_user, scope)
+    return await _import_excel('line', file, update_support, query_db, current_user, scope, preview)
 
 
 @line_excel_controller.post(
@@ -323,8 +334,9 @@ async def import_master_warehouse_excel(
     query_db: Annotated[AsyncSession, DBSessionDependency()],
     current_user: Annotated[CurrentUserModel, CurrentUserDependency()],
     scope: Annotated[TestBatchScope, TestBatchScopeDependency(write=True)],
+    preview: Annotated[bool, Query(description='只校验不写入')] = False,
 ) -> Response:
-    return await _import_excel('warehouse', file, update_support, query_db, current_user, scope)
+    return await _import_excel('warehouse', file, update_support, query_db, current_user, scope, preview)
 
 
 @warehouse_excel_controller.post(
@@ -372,8 +384,9 @@ async def import_master_pallet_excel(
     query_db: Annotated[AsyncSession, DBSessionDependency()],
     current_user: Annotated[CurrentUserModel, CurrentUserDependency()],
     scope: Annotated[TestBatchScope, TestBatchScopeDependency(write=True)],
+    preview: Annotated[bool, Query(description='只校验不写入')] = False,
 ) -> Response:
-    return await _import_excel('pallet', file, update_support, query_db, current_user, scope)
+    return await _import_excel('pallet', file, update_support, query_db, current_user, scope, preview)
 
 
 @pallet_excel_controller.post(
@@ -421,8 +434,9 @@ async def import_master_tunnel_excel(
     query_db: Annotated[AsyncSession, DBSessionDependency()],
     current_user: Annotated[CurrentUserModel, CurrentUserDependency()],
     scope: Annotated[TestBatchScope, TestBatchScopeDependency(write=True)],
+    preview: Annotated[bool, Query(description='只校验不写入')] = False,
 ) -> Response:
-    return await _import_excel('tunnel', file, update_support, query_db, current_user, scope)
+    return await _import_excel('tunnel', file, update_support, query_db, current_user, scope, preview)
 
 
 @tunnel_excel_controller.post(

shierfeng-fastapi-backend/module_business/controller/pallet_controller.py

@@ -13,13 +13,14 @@ from common.vo import DataResponseModel, PageResponseModel, ResponseBaseModel
 from module_admin.entity.vo.user_vo import CurrentUserModel
 from module_business.dependency.test_batch_dependency import TestBatchScopeDependency
 from module_business.domain.test_batch_scope import TestBatchScope
+from module_business.entity.vo.master_summary_vo import PalletDetailModel, PalletListItemModel
 from module_business.entity.vo.master_vo import (
     DeletePalletModel,
     PalletCreateModel,
     PalletEditModel,
-    PalletModel,
     PalletPageQueryModel,
 )
+from module_business.service.master_summary_service import MasterSummaryService
 from module_business.service.pallet_service import PalletService
 from utils.response_util import ResponseUtil
 
@@ -32,7 +33,7 @@ pallet_controller = APIRouterPro(
     '/list',
     summary='获取托盘分页列表接口',
     description='用于获取托盘分页列表',
-    response_model=PageResponseModel[PalletModel],
+    response_model=PageResponseModel[PalletListItemModel],
     dependencies=[UserInterfaceAuthDependency('master:pallet:list')],
 )
 async def get_master_pallet_list(
@@ -42,6 +43,7 @@ async def get_master_pallet_list(
     scope: Annotated[TestBatchScope, TestBatchScopeDependency()],
 ) -> Response:
     result = await PalletService.list_pallet(query_db, pallet_page_query, scope, is_page=True)
+    result = await MasterSummaryService.enrich_page(query_db, 'pallet', result, scope)
     return ResponseUtil.success(model_content=result)
 
 
@@ -67,7 +69,7 @@ async def query_master_pallet_qrcode(
     '/{pallet_id}',
     summary='获取托盘详情接口',
     description='用于获取指定托盘的详细信息',
-    response_model=DataResponseModel[PalletModel],
+    response_model=DataResponseModel[PalletDetailModel],
     dependencies=[UserInterfaceAuthDependency('master:pallet:query')],
 )
 async def query_detail_master_pallet(
@@ -77,6 +79,7 @@ async def query_detail_master_pallet(
     scope: Annotated[TestBatchScope, TestBatchScopeDependency()],
 ) -> Response:
     result = await PalletService.detail_pallet(query_db, pallet_id, scope)
+    result = await MasterSummaryService.pallet_detail(query_db, result, scope)
     return ResponseUtil.success(data=result)
 
 

shierfeng-fastapi-backend/module_business/controller/return_controller.py

@@ -19,10 +19,13 @@ from module_business.entity.vo.operation_vo import (
     BusinessOptionModel,
     PalletScanResponseModel,
     ReturnConfirmModel,
+    ReturnListItemModel,
     ReturnModel,
+    ReturnOverviewModel,
     ReturnPageQueryModel,
     ReturnRequestModel,
     ReturnScanQueryModel,
+    ReturnSiteOptionModel,
 )
 from module_business.service.return_service import ReturnService
 from utils.response_util import ResponseUtil
@@ -38,7 +41,7 @@ return_controller = APIRouterPro(
     '/list',
     summary='获取托盘退回单分页列表接口',
     description='按当前用户来源现场或目标仓库数据范围获取退回单',
-    response_model=PageResponseModel[ReturnModel],
+    response_model=PageResponseModel[ReturnListItemModel],
     dependencies=[UserInterfaceAuthDependency('business:return:list')],
 )
 async def get_business_return_list(
@@ -58,6 +61,40 @@ async def get_business_return_list(
     return ResponseUtil.success(model_content=result)
 
 
+@return_controller.get(
+    '/summary',
+    summary='获取托盘退回概况接口',
+    description='按当前用户来源现场或目标仓库数据范围统计待核对退回、退回中托盘与本月回仓去向',
+    response_model=DataResponseModel[ReturnOverviewModel],
+    dependencies=[UserInterfaceAuthDependency('business:return:list')],
+)
+async def get_business_return_summary(
+    request: Request,
+    query_db: Annotated[AsyncSession, DBSessionDependency()],
+    current_user: Annotated[CurrentUserModel, CurrentUserDependency()],
+    test_scope: Annotated[TestBatchScope, TestBatchScopeDependency()],
+) -> Response:
+    result = await ReturnService.get_return_overview_services(query_db, current_user, test_scope)
+    return ResponseUtil.success(data=result)
+
+
+@return_controller.get(
+    '/site-options',
+    summary='获取退回来源现场选项接口',
+    description='返回当前用户授权的现场及其可见退回单涉及的来源现场，用于筛选与显示名称',
+    response_model=DataResponseModel[list[ReturnSiteOptionModel]],
+    dependencies=[UserInterfaceAuthDependency('business:return:list')],
+)
+async def get_business_return_site_options(
+    request: Request,
+    query_db: Annotated[AsyncSession, DBSessionDependency()],
+    current_user: Annotated[CurrentUserModel, CurrentUserDependency()],
+    test_scope: Annotated[TestBatchScope, TestBatchScopeDependency()],
+) -> Response:
+    result = await ReturnService.get_site_options_services(query_db, current_user, test_scope)
+    return ResponseUtil.success(data=result)
+
+
 @return_controller.get(
     '/warehouse-options',
     summary='获取退回目标仓库选项接口',

shierfeng-fastapi-backend/module_business/controller/shipment_controller.py

@@ -18,6 +18,7 @@ from module_business.entity.vo.operation_vo import (
     ConfirmCommandModel,
     PalletScanResponseModel,
     ShipmentCreateModel,
+    ShipmentListItemModel,
     ShipmentModel,
     ShipmentPageQueryModel,
     ShipmentScanQueryModel,
@@ -39,7 +40,7 @@ shipment_controller = APIRouterPro(
     '/list',
     summary='获取整托发货单分页列表接口',
     description='按当前用户仓库与现场双数据范围获取整托发货单',
-    response_model=PageResponseModel[ShipmentModel],
+    response_model=PageResponseModel[ShipmentListItemModel],
     dependencies=[UserInterfaceAuthDependency('business:shipment:list')],
 )
 async def get_business_shipment_list(

shierfeng-fastapi-backend/module_business/controller/site_controller.py

@@ -14,6 +14,7 @@ from common.vo import DataResponseModel, PageResponseModel, ResponseBaseModel
 from module_admin.entity.vo.user_vo import CurrentUserModel
 from module_business.dependency.test_batch_dependency import TestBatchScopeDependency
 from module_business.domain.test_batch_scope import TestBatchScope
+from module_business.entity.vo.master_summary_vo import MasterParentOptionModel, SiteListItemModel
 from module_business.entity.vo.master_vo import (
     BusinessUserOptionModel,
     DeleteSiteModel,
@@ -22,6 +23,7 @@ from module_business.entity.vo.master_vo import (
     UserAssignModel,
 )
 from module_business.service.master_service import MasterService
+from module_business.service.master_summary_service import MasterSummaryService
 from module_business.service.pallet_service import PalletService
 from utils.response_util import ResponseUtil
 
@@ -31,6 +33,26 @@ ASSIGN_CURRENT_USER = CurrentUserDependency
 site_controller = APIRouterPro(
     prefix='/master/site', tags=['基础资料-客户现场管理'], dependencies=[PreAuthDependency()]
 )
+# 上级资料选项单独注册且排在详情路由之前，避免被 /{site_id} 捕获
+site_option_controller = APIRouterPro(
+    prefix='/master/site', order_num=99, tags=['基础资料-客户现场管理'], dependencies=[PreAuthDependency()]
+)
+
+
+@site_option_controller.get(
+    '/customer-options',
+    summary='获取客户现场可选客户接口',
+    description='新增或修改客户现场时选择所属客户，只返回状态正常的客户',
+    response_model=DataResponseModel[list[MasterParentOptionModel]],
+    dependencies=[UserInterfaceAuthDependency('master:site:list')],
+)
+async def get_master_site_customer_options(
+    request: Request,
+    query_db: Annotated[AsyncSession, DBSessionDependency()],
+    scope: Annotated[TestBatchScope, TestBatchScopeDependency()],
+) -> Response:
+    options = await MasterSummaryService.customer_options(query_db, scope)
+    return ResponseUtil.success(data=options)
 site_user_controller = APIRouterPro(
     prefix='/master/site', tags=['基础资料-客户现场用户分配'], dependencies=[PreAuthDependency()]
 )
@@ -77,7 +99,7 @@ async def assign_master_site_users(
     '/list',
     summary='获取客户现场分页列表接口',
     description='用于获取客户现场分页列表',
-    response_model=PageResponseModel[SiteModel],
+    response_model=PageResponseModel[SiteListItemModel],
     dependencies=[UserInterfaceAuthDependency('master:site:list')],
 )
 async def get_master_site_list(
@@ -87,6 +109,7 @@ async def get_master_site_list(
     scope: Annotated[TestBatchScope, TestBatchScopeDependency()],
 ) -> Response:
     site_page_query_result = await MasterService.list_site(query_db, site_page_query, scope, is_page=True)
+    site_page_query_result = await MasterSummaryService.enrich_page(query_db, 'site', site_page_query_result, scope)
 
     return ResponseUtil.success(model_content=site_page_query_result)
 

shierfeng-fastapi-backend/module_business/controller/strain_controller.py

@@ -14,8 +14,10 @@ from common.vo import DataResponseModel, PageResponseModel, ResponseBaseModel
 from module_admin.entity.vo.user_vo import CurrentUserModel
 from module_business.dependency.test_batch_dependency import TestBatchScopeDependency
 from module_business.domain.test_batch_scope import TestBatchScope
+from module_business.entity.vo.master_summary_vo import StrainListItemModel
 from module_business.entity.vo.master_vo import DeleteStrainModel, StrainModel, StrainPageQueryModel
 from module_business.service.master_service import MasterService
+from module_business.service.master_summary_service import MasterSummaryService
 from utils.response_util import ResponseUtil
 
 strain_controller = APIRouterPro(
@@ -27,7 +29,7 @@ strain_controller = APIRouterPro(
     '/list',
     summary='获取菌种分页列表接口',
     description='用于获取菌种分页列表',
-    response_model=PageResponseModel[StrainModel],
+    response_model=PageResponseModel[StrainListItemModel],
     dependencies=[UserInterfaceAuthDependency('master:strain:list')],
 )
 async def get_master_strain_list(
@@ -37,6 +39,9 @@ async def get_master_strain_list(
     scope: Annotated[TestBatchScope, TestBatchScopeDependency()],
 ) -> Response:
     strain_page_query_result = await MasterService.list_strain(query_db, strain_page_query, scope, is_page=True)
+    strain_page_query_result = await MasterSummaryService.enrich_page(
+        query_db, 'strain', strain_page_query_result, scope
+    )
 
     return ResponseUtil.success(model_content=strain_page_query_result)
 

shierfeng-fastapi-backend/module_business/controller/tunnel_controller.py

@@ -14,8 +14,10 @@ from common.vo import DataResponseModel, PageResponseModel, ResponseBaseModel
 from module_admin.entity.vo.user_vo import CurrentUserModel
 from module_business.dependency.test_batch_dependency import TestBatchScopeDependency
 from module_business.domain.test_batch_scope import TestBatchScope
+from module_business.entity.vo.master_summary_vo import MasterParentOptionModel, TunnelListItemModel
 from module_business.entity.vo.master_vo import DeleteTunnelModel, TunnelModel, TunnelPageQueryModel
 from module_business.service.master_service import MasterService
+from module_business.service.master_summary_service import MasterSummaryService
 from utils.response_util import ResponseUtil
 
 tunnel_controller = APIRouterPro(
@@ -23,13 +25,33 @@ tunnel_controller = APIRouterPro(
     tags=['基础资料-隧道管理'],
     dependencies=[PreAuthDependency()],
 )
+# 上级资料选项单独注册且排在详情路由之前，避免被 /{tunnel_id} 捕获
+tunnel_option_controller = APIRouterPro(
+    prefix='/master/tunnel', order_num=99, tags=['基础资料-隧道管理'], dependencies=[PreAuthDependency()]
+)
+
+
+@tunnel_option_controller.get(
+    '/site-options',
+    summary='获取隧道可选现场接口',
+    description='新增或修改隧道时选择所属现场，只返回状态正常的现场',
+    response_model=DataResponseModel[list[MasterParentOptionModel]],
+    dependencies=[UserInterfaceAuthDependency('master:tunnel:list')],
+)
+async def get_master_tunnel_site_options(
+    request: Request,
+    query_db: Annotated[AsyncSession, DBSessionDependency()],
+    scope: Annotated[TestBatchScope, TestBatchScopeDependency()],
+) -> Response:
+    options = await MasterSummaryService.site_options(query_db, scope)
+    return ResponseUtil.success(data=options)
 
 
 @tunnel_controller.get(
     '/list',
     summary='获取隧道分页列表接口',
     description='用于获取客户现场隧道分页列表',
-    response_model=PageResponseModel[TunnelModel],
+    response_model=PageResponseModel[TunnelListItemModel],
     dependencies=[UserInterfaceAuthDependency('master:tunnel:list')],
 )
 async def get_master_tunnel_list(
@@ -39,6 +61,7 @@ async def get_master_tunnel_list(
     scope: Annotated[TestBatchScope, TestBatchScopeDependency()],
 ) -> Response:
     result = await MasterService.list_tunnel(query_db, tunnel_page_query, scope, is_page=True)
+    result = await MasterSummaryService.enrich_page(query_db, 'tunnel', result, scope)
     return ResponseUtil.success(model_content=result)
 
 

shierfeng-fastapi-backend/module_business/controller/usage_controller.py

@@ -21,8 +21,11 @@ from module_business.entity.vo.operation_vo import (
     TunnelEntryCreateModel,
     TunnelEntrySuccessResponseModel,
     UsageCreateModel,
+    UsageListItemModel,
     UsageModel,
     UsagePageQueryModel,
+    UsageSiteBoardModel,
+    UsageSiteOptionModel,
     UsageSuccessResponseModel,
 )
 from module_business.service.usage_service import UsageService
@@ -39,7 +42,7 @@ usage_controller = APIRouterPro(
     '/list',
     summary='获取客户现场使用记录分页列表接口',
     description='按当前用户客户现场数据范围获取使用记录',
-    response_model=PageResponseModel[UsageModel],
+    response_model=PageResponseModel[UsageListItemModel],
     dependencies=[UserInterfaceAuthDependency('business:usage:list')],
 )
 async def get_business_usage_list(
@@ -95,6 +98,41 @@ async def get_business_usage_tunnel_options(
     return ResponseUtil.success(data=result)
 
 
+@usage_controller.get(
+    '/site-options',
+    summary='获取客户现场使用的现场选项接口',
+    description='返回当前用户有权访问且已启用的客户现场，附带启用隧道与产线数',
+    response_model=DataResponseModel[list[UsageSiteOptionModel]],
+    dependencies=[UserInterfaceAuthDependency('business:usage:list')],
+)
+async def get_business_usage_site_options(
+    request: Request,
+    query_db: Annotated[AsyncSession, DBSessionDependency()],
+    current_user: Annotated[CurrentUserModel, CurrentUserDependency()],
+    test_scope: Annotated[TestBatchScope, TestBatchScopeDependency()],
+) -> Response:
+    result = await UsageService.get_site_options_services(query_db, current_user, test_scope)
+    return ResponseUtil.success(data=result)
+
+
+@usage_controller.get(
+    '/site-board',
+    summary='获取客户现场看板接口',
+    description='统计指定现场的托盘库存、今日用量、隧道使用与跳过先到托盘次数；不返回内部溯源号',
+    response_model=DataResponseModel[UsageSiteBoardModel],
+    dependencies=[UserInterfaceAuthDependency('business:usage:query')],
+)
+async def get_business_usage_site_board(
+    request: Request,
+    site_id: Annotated[int, Query(alias='siteId', gt=0, description='客户现场ID')],
+    query_db: Annotated[AsyncSession, DBSessionDependency()],
+    current_user: Annotated[CurrentUserModel, CurrentUserDependency()],
+    test_scope: Annotated[TestBatchScope, TestBatchScopeDependency()],
+) -> Response:
+    result = await UsageService.get_site_board_services(query_db, site_id, current_user, test_scope)
+    return ResponseUtil.success(data=result)
+
+
 @usage_controller.post(
     '/enter-tunnel',
     summary='扫码入隧接口',

shierfeng-fastapi-backend/module_business/controller/usage_fifo_controller.py

@@ -13,18 +13,22 @@ from common.vo import DataResponseModel
 from module_admin.entity.vo.user_vo import CurrentUserModel
 from module_business.dependency.test_batch_dependency import TestBatchScopeDependency
 from module_business.domain.test_batch_scope import TestBatchScope
-from module_business.entity.vo.usage_fifo_vo import UsageFifoRecommendationModel
+from module_business.entity.vo.usage_fifo_vo import UsageFifoQueueModel, UsageFifoRecommendationModel
 from module_business.service.usage_fifo_service import UsageFifoService
 from utils.response_util import ResponseUtil
 
 usage_fifo_controller = APIRouterPro(
     prefix='/business/usage-fifo',
     tags=['业务管理-客户现场使用'],
-    dependencies=[PreAuthDependency(), UserInterfaceAuthDependency('business:usage:query')],
+    dependencies=[PreAuthDependency()],
 )
 
 
-@usage_fifo_controller.get('/recommendation', response_model=DataResponseModel[UsageFifoRecommendationModel])
+@usage_fifo_controller.get(
+    '/recommendation',
+    response_model=DataResponseModel[UsageFifoRecommendationModel],
+    dependencies=[UserInterfaceAuthDependency('business:usage:query')],
+)
 async def get_usage_fifo_recommendation(
     request: Request,
     qr_token: Annotated[str, Query(alias='qrToken', min_length=1, max_length=128, pattern=r'\S')],
@@ -37,3 +41,19 @@ async def get_usage_fifo_recommendation(
         query_db, qr_token, current_user, test_scope, tunnel_id=tunnel_id,
     )
     return ResponseUtil.success(data=result)
+
+
+@usage_fifo_controller.get(
+    '/queue',
+    response_model=DataResponseModel[UsageFifoQueueModel],
+    dependencies=[UserInterfaceAuthDependency('business:usage:query')],
+)
+async def get_usage_fifo_queue(
+    request: Request,
+    site_id: Annotated[int, Query(alias='siteId', gt=0, description='客户现场ID')],
+    query_db: Annotated[AsyncSession, DBSessionDependency()],
+    current_user: Annotated[CurrentUserModel, CurrentUserDependency()],
+    test_scope: Annotated[TestBatchScope, TestBatchScopeDependency()],
+) -> Response:
+    result = await UsageFifoService.queue(query_db, site_id, current_user, test_scope)
+    return ResponseUtil.success(data=result)

shierfeng-fastapi-backend/module_business/controller/warehouse_controller.py

@@ -14,6 +14,7 @@ from common.vo import DataResponseModel, PageResponseModel, ResponseBaseModel
 from module_admin.entity.vo.user_vo import CurrentUserModel
 from module_business.dependency.test_batch_dependency import TestBatchScopeDependency
 from module_business.domain.test_batch_scope import TestBatchScope
+from module_business.entity.vo.master_summary_vo import WarehouseListItemModel
 from module_business.entity.vo.master_vo import (
     BusinessUserOptionModel,
     DeleteWarehouseModel,
@@ -22,6 +23,7 @@ from module_business.entity.vo.master_vo import (
     WarehousePageQueryModel,
 )
 from module_business.service.master_service import MasterService
+from module_business.service.master_summary_service import MasterSummaryService
 from module_business.service.pallet_service import PalletService
 from utils.response_util import ResponseUtil
 
@@ -77,7 +79,7 @@ async def assign_master_warehouse_users(
     '/list',
     summary='获取仓库分页列表接口',
     description='用于获取仓库分页列表',
-    response_model=PageResponseModel[WarehouseModel],
+    response_model=PageResponseModel[WarehouseListItemModel],
     dependencies=[UserInterfaceAuthDependency('master:warehouse:list')],
 )
 async def get_master_warehouse_list(
@@ -92,6 +94,9 @@ async def get_master_warehouse_list(
         scope,
         is_page=True,
     )
+    warehouse_page_query_result = await MasterSummaryService.enrich_page(
+        query_db, 'warehouse', warehouse_page_query_result, scope
+    )
 
     return ResponseUtil.success(model_content=warehouse_page_query_result)