feat(firstleg): count actionable customer customs cabinets

firstleg/src/main/java/com/baiyue/firstleg/customs/container/controller/MerchantContainerCustomsController.java

@@ -26,6 +26,12 @@ import java.util.List;
 public class MerchantContainerCustomsController {
     @Resource private ContainerCustomsService service;
 
+    @GetMapping("/pending-summary")
+    @PreAuthorize("hasAuthority('merchant:order:view')")
+    public ApiResponse<PendingSummary> pendingSummary(@AuthenticationPrincipal AuthenticatedUser user) {
+        return ApiResponse.success(service.merchantPendingSummary(FirstlegScopeGuard.merchant(user)));
+    }
+
     @GetMapping("/orders/{orderId}")
     @PreAuthorize("hasAuthority('merchant:order:view')")
     public ApiResponse<ContainerView> order(@AuthenticationPrincipal AuthenticatedUser user,

firstleg/src/main/java/com/baiyue/firstleg/customs/container/dto/ContainerCustomsDtos.java

@@ -74,4 +74,5 @@ public final class ContainerCustomsDtos {
                                           @Size(max = 1000) String resolution) {}
 
     public record Download(String fileName, String contentType, byte[] content) {}
+    public record PendingSummary(long pendingCount) {}
 }

firstleg/src/main/java/com/baiyue/firstleg/customs/container/mapper/ContainerCustomsMapper.java

@@ -87,6 +87,42 @@ public interface ContainerCustomsMapper {
         """)
     Long completedPlanForOrder(@Param("tenantId") long tenantId, @Param("orderId") long orderId);
 
+    /** One customer action badge per actual loaded cabinet, including receipt confirmation. */
+    @Select("""
+        SELECT COUNT(DISTINCT p.container_booking_id)
+        FROM fl_loading_plan p
+        JOIN fl_container_booking b ON b.id=p.container_booking_id AND b.record_status='ACTIVE'
+        JOIN fl_loading_plan_item item ON item.loading_plan_id=p.id AND item.deleted=0
+        JOIN fl_inbound_order i ON i.id=item.inbound_id AND i.tenant_id=item.account_id AND i.deleted=0
+        LEFT JOIN fl_customs_container c ON c.loading_plan_id=p.id
+        WHERE p.plan_status='COMPLETED' AND i.tenant_id=#{tenantId} AND i.tax_mode='TAX_REFUND'
+          AND
+        """ + ACTUAL_ITEM_SCOPE + """
+          AND p.id=(
+            SELECT latest.id FROM fl_loading_plan latest
+            JOIN fl_loading_plan_item item ON item.loading_plan_id=latest.id AND item.deleted=0
+            JOIN fl_inbound_order own ON own.id=item.inbound_id AND own.tenant_id=item.account_id AND own.deleted=0
+            WHERE latest.plan_status='COMPLETED' AND own.tenant_id=i.tenant_id AND own.order_id=i.order_id
+              AND own.tax_mode='TAX_REFUND' AND
+        """ + ACTUAL_ITEM_SCOPE + """
+            ORDER BY COALESCE(latest.confirmed_at,latest.updated_at) DESC,latest.id DESC LIMIT 1
+          )
+          AND (
+            ((c.id IS NULL OR c.status IN ('WAITING_CUSTOMER_DOCUMENTS','READY_TO_START')) AND NOT EXISTS (
+              SELECT 1 FROM fl_customs_customer_document_inbound scope
+              JOIN fl_customs_customer_document d ON d.id=scope.document_id AND d.status='ACTIVE'
+              WHERE d.customs_container_id=c.id AND d.tenant_id=i.tenant_id
+                AND scope.tenant_id=i.tenant_id AND scope.inbound_id=i.id))
+            OR (c.status='DECLARING' AND EXISTS (
+              SELECT 1 FROM fl_customs_customer_document d
+              JOIN fl_customs_customer_document_inbound scope ON scope.document_id=d.id AND scope.tenant_id=d.tenant_id
+              JOIN fl_customs_completion_document receipt ON receipt.source_document_id=d.id
+              WHERE d.customs_container_id=c.id AND d.tenant_id=i.tenant_id AND d.status='ACTIVE'
+                AND d.frozen_at IS NOT NULL AND scope.inbound_id=i.id AND receipt.customer_confirm_status='PENDING'))
+          )
+        """)
+    long merchantPendingCount(@Param("tenantId") long tenantId);
+
     @Insert("""
         INSERT INTO fl_customs_container
           (id,loading_plan_id,container_booking_id,status,created_at,updated_at,version)

firstleg/src/main/java/com/baiyue/firstleg/customs/container/service/ContainerCustomsService.java

@@ -44,6 +44,11 @@ public class ContainerCustomsService {
     @Resource private ApplicationEventPublisher events;
     @Value("${baiyue.security.internal-service-token}") private String internalToken;
 
+    @Transactional(readOnly = true)
+    public PendingSummary merchantPendingSummary(long tenantId) {
+        return new PendingSummary(mapper.merchantPendingCount(tenantId));
+    }
+
     @Transactional
     public ContainerView platformView(long planId) {
         List<InboundRow> rows = actualPlanRows(planId);

firstleg/src/main/resources/openapi/customs-v1.yaml

@@ -1,6 +1,28 @@
 openapi: 3.0.3
 info: {title: Firstleg Container Customs API, version: 2.0.0}
 paths:
+  /api/merchant/v1/customs/pending-summary:
+    get:
+      summary: 当前客户报关资料待处理柜次数量
+      description: >-
+        权限merchant:order:view，客户范围仅来自认证上下文。只读COUNT，不创建报关记录。
+        最新实际已装柜的退税货物尚未被本客户有效资料覆盖，或DECLARING阶段本客户冻结资料的当前回执为PENDING，均计入。
+        同柜多票、多份资料只计一次；已打回等待平台重做、已确认、已完成及其他客户的待办不计入。
+      x-permission: merchant:order:view
+      responses:
+        '200':
+          description: ApiResponse，code为200时才成功；失败不能解释为零待办
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: {type: string}
+                  data:
+                    type: object
+                    required: [pendingCount]
+                    properties:
+                      pendingCount: {type: string, pattern: '^[0-9]+$'}
   /api/platform/v1/customs/loading-plans/{planId}:
     get:
       summary: 查询整柜报关状态、缺资料票及文件映射