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/tests/module_business/test_usage_fifo.py

@@ -12,6 +12,7 @@ from module_business.dao.usage_fifo_dao import UsageFifoDao
 from module_business.domain.test_batch_scope import TestBatchScope
 from module_business.entity.do.master_do import BizPallet
 from module_business.entity.do.operation_do import BizFillingRecord, BizPalletInventory
+from module_business.service.access_service import AccessService
 from module_business.service.usage_fifo_service import UsageFifoService
 from module_business.service.usage_service import UsageService
 from module_business.dao.master_dao import MasterDao
@@ -188,3 +189,53 @@ class TestUsageFifo(unittest.IsolatedAsyncioTestCase):
                 self.db, 'qr-2', MagicMock(), TestBatchScope.formal(), tunnel_id=13)
         self.assertEqual(result.recommended.pallet_id, 1)
         self.assertTrue(result.requires_skip_reason)
+
+    async def test_queue_groups_by_strain_in_recommendation_order(self) -> None:
+        # 同菌种按实际收货时间排序；已入隧和不可用的托盘不进入待使用队列
+        self.add(1, datetime(2026, 10, 8))
+        self.add(2, datetime(2026, 10, 6), remaining=80, state='AT_SITE_PARTIAL')
+        self.add(3, datetime(2026, 10, 1), tunnel=13)
+        self.add(4, None)
+        self.add(5, datetime(2026, 10, 2), strain=8)
+        self.add(6, datetime(2026, 10, 1), state='RETURNING')
+        self.add(7, datetime(2026, 10, 1), site=10)
+
+        groups = await UsageFifoDao.queue(self.db, site_id=9, scope=TestBatchScope.formal())
+
+        self.assertEqual([4, 8], [group['strain_id'] for group in groups])
+        main = groups[0]
+        self.assertEqual([2, 1], [pallet['pallet_id'] for pallet in main['pallets']])
+        self.assertEqual((2, 1), (main['pallet_count'], main['unknown_arrival_count']))
+        self.assertEqual(80, main['pallets'][0]['remaining_packages'])
+        self.assertEqual([5], [pallet['pallet_id'] for pallet in groups[1]['pallets']])
+        candidate, unknown = await self.query()
+        self.assertEqual((main['pallets'][0]['pallet_id'], main['unknown_arrival_count']), (candidate['pallet_id'], unknown))
+
+    async def test_queue_limits_listed_pallets_but_counts_all_and_respects_test_scope(self) -> None:
+        for pallet_id in range(1, 6):
+            self.add(pallet_id, datetime(2026, 10, pallet_id))
+        self.add(9, datetime(2026, 9, 1), batch=7)
+
+        groups = await UsageFifoDao.queue(self.db, site_id=9, scope=TestBatchScope.formal(), limit_per_strain=2)
+        self.assertEqual(5, groups[0]['pallet_count'])
+        self.assertEqual([1, 2], [pallet['pallet_id'] for pallet in groups[0]['pallets']])
+        test_groups = await UsageFifoDao.queue(self.db, site_id=9, scope=make_test_scope(7))
+        self.assertEqual([9], [pallet['pallet_id'] for pallet in test_groups[0]['pallets']])
+
+    async def test_queue_service_checks_site_access_before_query(self) -> None:
+        with (
+            patch.object(AccessService, 'assert_site_access', new=AsyncMock(side_effect=PermissionException(data='', message='无权访问该客户现场'))),
+            self.assertRaises(PermissionException),
+        ):
+            await UsageFifoService.queue(self.db, 9, MagicMock(), TestBatchScope.formal())
+        self.db.execute.assert_not_awaited()
+
+        self.add(1, datetime(2026, 10, 1))
+        with (
+            patch.object(AccessService, 'assert_site_access', new=AsyncMock()),
+            patch.object(MasterDao, 'get_site', new=AsyncMock(return_value=SimpleNamespace(site_id=9, test_batch_id=None))),
+        ):
+            result = await UsageFifoService.queue(self.db, 9, MagicMock(), TestBatchScope.formal())
+        dumped = result.model_dump(by_alias=True)
+        self.assertEqual(9, dumped['siteId'])
+        self.assertEqual('P-1', dumped['strains'][0]['pallets'][0]['palletCode'])