优化

firstleg/AGENTS.md

@@ -2,6 +2,7 @@
 
 ## 职责与边界
 
+- Mapper 统一显式使用 `@Mapper`，仅由 `BaiyueFirstlegApplication.java` 对 `com.baiyue.firstleg` 根包按 `annotationClass = Mapper.class` 扫描；禁止恢复业务子域 Mapper 包白名单。静态门禁见根 `scripts/mapper-scan-contract.mjs`，模块内编译门禁见 `MapperRegistrationArchitectureTest.java`、`BaiyueFirstlegApplicationContractTest.java`。
 - 负责履约任务/分配、入库单、测量/OCR、审核后初始计价、FBA 计费、客户在途柜量统计、国内出仓履约链路，以及四期国内出仓后的船节点查询任务和节点事实。
 - 订单主数据归 `order/`，托盘/库位归 `warehouse/`，文件对象归 `file/`，OCR 供应商归 `integration-service/`；通过客户端 DTO 和内部令牌协作。
 - 入库、分柜、装柜、PDA 和出仓能力均在本模块按对应服务端契约协作；`WAIT_SPLIT + APPROVED + CONFIRMED` 是入库链路状态节点，不是全量验收的范围终点。财务状态仍归 `finance`，本模块只生产不可变费用来源和柜次成本快照。

firstleg/src/main/java/com/baiyue/firstleg/BaiyueFirstlegApplication.java

@@ -1,5 +1,6 @@
 package com.baiyue.firstleg;
 
+import org.apache.ibatis.annotations.Mapper;
 import org.mybatis.spring.annotation.MapperScan;
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
@@ -9,18 +10,7 @@ import org.springframework.scheduling.annotation.EnableScheduling;
 /**
  * 头程履约微服务启动入口，负责装配履约任务组件并扫描 MyBatis-Plus Mapper。
  */
-@MapperScan(basePackages = {
-        "com.baiyue.firstleg.mapper",
-        "com.baiyue.firstleg.split.mapper",
-        "com.baiyue.firstleg.loading.mapper",
-        "com.baiyue.firstleg.loading.bridge.mapper",
-        "com.baiyue.firstleg.oceanbooking.mapper",
-        "com.baiyue.firstleg.outbound.dispatch.mapper",
-        "com.baiyue.firstleg.portschedule.mapper",
-        "com.baiyue.firstleg.customs.container.mapper",
-        "com.baiyue.firstleg.customerstatistics.adapter.out.persistence",
-        "com.baiyue.firstleg.pricebookquery.adapter.out.persistence"
-})
+@MapperScan(basePackages = "com.baiyue.firstleg", annotationClass = Mapper.class)
 @EnableFeignClients(basePackages = "com.baiyue.firstleg")
 @EnableScheduling
 @SpringBootApplication(scanBasePackages = "com.baiyue")

firstleg/src/main/java/com/baiyue/firstleg/mapper/AssignmentHistoryMapper.java

@@ -1,4 +1,10 @@
-package com.baiyue.firstleg.mapper; import com.baiyue.firstleg.entity.AssignmentHistoryEntity; import com.baomidou.mybatisplus.core.mapper.BaseMapper; /**
+package com.baiyue.firstleg.mapper;
+import org.apache.ibatis.annotations.Mapper;
+import com.baiyue.firstleg.entity.AssignmentHistoryEntity;
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+
+/**
  * 头程任务指派历史 Mapper，提供 {@code fl_assignment_history} 的 MyBatis-Plus 基础数据访问能力。
  */
+@Mapper
 public interface AssignmentHistoryMapper extends BaseMapper<AssignmentHistoryEntity>{}

firstleg/src/main/java/com/baiyue/firstleg/mapper/CarrierFbaRateMapper.java

@@ -1,9 +1,12 @@
 package com.baiyue.firstleg.mapper;
+
+import org.apache.ibatis.annotations.Mapper;
 import com.baomidou.mybatisplus.core.mapper.BaseMapper;
 import com.baiyue.firstleg.entity.CarrierFbaRateEntity;
 import org.apache.ibatis.annotations.Delete;
 import org.apache.ibatis.annotations.Param;
 
+@Mapper
 public interface CarrierFbaRateMapper extends BaseMapper<CarrierFbaRateEntity> {
     @Delete("DELETE FROM fl_carrier_fba_rate WHERE price_book_version_id = #{versionId} AND status = 'PENDING_CONFIRMATION'")
     int physicallyDeletePendingByPriceBookVersionId(@Param("versionId") long versionId);

firstleg/src/main/java/com/baiyue/firstleg/mapper/CustomerChargeRuleMapper.java

@@ -1,4 +1,7 @@
 package com.baiyue.firstleg.mapper;
+
+import org.apache.ibatis.annotations.Mapper;
 import com.baomidou.mybatisplus.core.mapper.BaseMapper;
 import com.baiyue.firstleg.entity.CustomerChargeRuleEntity;
+@Mapper
 public interface CustomerChargeRuleMapper extends BaseMapper<CustomerChargeRuleEntity> {}

firstleg/src/main/java/com/baiyue/firstleg/mapper/CustomerDimensionConfigMapper.java

@@ -1,5 +1,7 @@
 package com.baiyue.firstleg.mapper;
 
+import org.apache.ibatis.annotations.Mapper;
+
 import com.baomidou.mybatisplus.core.mapper.BaseMapper;
 import com.baiyue.firstleg.entity.CustomerDimensionConfigEntity;
 import org.apache.ibatis.annotations.Delete;
@@ -9,6 +11,7 @@ import org.apache.ibatis.annotations.Select;
 
 import java.util.List;
 
+@Mapper
 public interface CustomerDimensionConfigMapper extends BaseMapper<CustomerDimensionConfigEntity> {
     @Insert("""
         <script>

firstleg/src/main/java/com/baiyue/firstleg/mapper/FulfillmentTaskMapper.java

@@ -1,4 +1,10 @@
-package com.baiyue.firstleg.mapper; import com.baiyue.firstleg.entity.FulfillmentTaskEntity; import com.baomidou.mybatisplus.core.mapper.BaseMapper; /**
+package com.baiyue.firstleg.mapper;
+import org.apache.ibatis.annotations.Mapper;
+import com.baiyue.firstleg.entity.FulfillmentTaskEntity;
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+
+/**
  * 头程履约任务 Mapper，提供 {@code fl_fulfillment_task} 的 MyBatis-Plus 基础数据访问能力。
  */
+@Mapper
 public interface FulfillmentTaskMapper extends BaseMapper<FulfillmentTaskEntity>{}

firstleg/src/main/java/com/baiyue/firstleg/mapper/InboundFeeItemMapper.java

@@ -1,4 +1,7 @@
 package com.baiyue.firstleg.mapper;
+
+import org.apache.ibatis.annotations.Mapper;
 import com.baomidou.mybatisplus.core.mapper.BaseMapper;
 import com.baiyue.firstleg.entity.InboundFeeItemEntity;
+@Mapper
 public interface InboundFeeItemMapper extends BaseMapper<InboundFeeItemEntity> {}

firstleg/src/main/java/com/baiyue/firstleg/mapper/InboundOrderLookupMapper.java

@@ -1,8 +1,11 @@
 package com.baiyue.firstleg.mapper;
 
+import org.apache.ibatis.annotations.Mapper;
+
 import com.baomidou.mybatisplus.core.mapper.BaseMapper;
 import com.baiyue.firstleg.entity.InboundOrderLookupEntity;
 
 /** 入库单只读 Mapper，开放接口不得在此增加 update 方法。 */
+@Mapper
 public interface InboundOrderLookupMapper extends BaseMapper<InboundOrderLookupEntity> {
 }

firstleg/src/main/java/com/baiyue/firstleg/mapper/InboundPickupSnapshotMapper.java

@@ -1,7 +1,10 @@
 package com.baiyue.firstleg.mapper;
 
+import org.apache.ibatis.annotations.Mapper;
+
 import com.baiyue.firstleg.entity.InboundPickupSnapshotEntity;
 import com.baomidou.mybatisplus.core.mapper.BaseMapper;
 
+@Mapper
 public interface InboundPickupSnapshotMapper extends BaseMapper<InboundPickupSnapshotEntity> {
 }

firstleg/src/main/java/com/baiyue/firstleg/mapper/InboundPricingIdempotencyMapper.java

@@ -1,4 +1,7 @@
 package com.baiyue.firstleg.mapper;
+
+import org.apache.ibatis.annotations.Mapper;
 import com.baomidou.mybatisplus.core.mapper.BaseMapper;
 import com.baiyue.firstleg.entity.InboundPricingIdempotencyEntity;
+@Mapper
 public interface InboundPricingIdempotencyMapper extends BaseMapper<InboundPricingIdempotencyEntity> {}

firstleg/src/main/java/com/baiyue/firstleg/mapper/InboundPricingMapper.java

@@ -1,4 +1,7 @@
 package com.baiyue.firstleg.mapper;
+
+import org.apache.ibatis.annotations.Mapper;
 import com.baomidou.mybatisplus.core.mapper.BaseMapper;
 import com.baiyue.firstleg.entity.InboundPricingEntity;
+@Mapper
 public interface InboundPricingMapper extends BaseMapper<InboundPricingEntity> {}

firstleg/src/main/java/com/baiyue/firstleg/mapper/PriceBookChannelMapper.java

@@ -1,9 +1,12 @@
 package com.baiyue.firstleg.mapper;
+
+import org.apache.ibatis.annotations.Mapper;
 import com.baomidou.mybatisplus.core.mapper.BaseMapper;
 import com.baiyue.firstleg.entity.PriceBookChannelEntity;
 import org.apache.ibatis.annotations.Delete;
 import org.apache.ibatis.annotations.Param;
 
+@Mapper
 public interface PriceBookChannelMapper extends BaseMapper<PriceBookChannelEntity> {
     @Delete("DELETE FROM fl_price_book_channel WHERE price_book_version_id = #{versionId}")
     int physicallyDeleteByPriceBookVersionId(@Param("versionId") long versionId);

firstleg/src/main/java/com/baiyue/firstleg/mapper/PriceBookVersionMapper.java

@@ -1,4 +1,7 @@
 package com.baiyue.firstleg.mapper;
+
+import org.apache.ibatis.annotations.Mapper;
 import com.baomidou.mybatisplus.core.mapper.BaseMapper;
 import com.baiyue.firstleg.entity.PriceBookVersionEntity;
+@Mapper
 public interface PriceBookVersionMapper extends BaseMapper<PriceBookVersionEntity> {}

firstleg/src/main/java/com/baiyue/firstleg/mapper/PriceChannelCatalogMapper.java

@@ -1,4 +1,7 @@
 package com.baiyue.firstleg.mapper;
+
+import org.apache.ibatis.annotations.Mapper;
 import com.baomidou.mybatisplus.core.mapper.BaseMapper;
 import com.baiyue.firstleg.entity.PriceChannelCatalogEntity;
+@Mapper
 public interface PriceChannelCatalogMapper extends BaseMapper<PriceChannelCatalogEntity> {}

firstleg/src/main/java/com/baiyue/firstleg/mapper/PriceOriginAliasMapper.java

@@ -1,4 +1,7 @@
 package com.baiyue.firstleg.mapper;
+
+import org.apache.ibatis.annotations.Mapper;
 import com.baomidou.mybatisplus.core.mapper.BaseMapper;
 import com.baiyue.firstleg.entity.PriceOriginAliasEntity;
+@Mapper
 public interface PriceOriginAliasMapper extends BaseMapper<PriceOriginAliasEntity> {}

firstleg/src/main/java/com/baiyue/firstleg/mapper/PriceWarehouseMappingMapper.java

@@ -1,6 +1,9 @@
 package com.baiyue.firstleg.mapper;
 
+import org.apache.ibatis.annotations.Mapper;
+
 import com.baomidou.mybatisplus.core.mapper.BaseMapper;
 import com.baiyue.firstleg.entity.PriceWarehouseMappingEntity;
 
+@Mapper
 public interface PriceWarehouseMappingMapper extends BaseMapper<PriceWarehouseMappingEntity> {}

firstleg/src/main/java/com/baiyue/firstleg/mapper/ThirdPartyCallLogMapper.java

@@ -1,7 +1,10 @@
 package com.baiyue.firstleg.mapper;
 
+import org.apache.ibatis.annotations.Mapper;
+
 import com.baomidou.mybatisplus.core.mapper.BaseMapper;
 import com.baiyue.firstleg.entity.ThirdPartyCallLogEntity;
 
+@Mapper
 public interface ThirdPartyCallLogMapper extends BaseMapper<ThirdPartyCallLogEntity> {
 }

firstleg/src/test/java/com/baiyue/firstleg/BaiyueFirstlegApplicationContractTest.java

@@ -1,5 +1,6 @@
 package com.baiyue.firstleg;
 
+import org.apache.ibatis.annotations.Mapper;
 import org.junit.jupiter.api.Test;
 import org.mybatis.spring.annotation.MapperScan;
 import org.springframework.cloud.openfeign.EnableFeignClients;
@@ -8,22 +9,11 @@ import static org.assertj.core.api.Assertions.assertThat;
 
 class BaiyueFirstlegApplicationContractTest {
     @Test
-    void scansAllFirstlegMapperPackagesIncludingCustoms() {
+    void scansAnnotatedMappersFromTheStableServiceRoot() {
         MapperScan scan = BaiyueFirstlegApplication.class.getAnnotation(MapperScan.class);
 
-        assertThat(scan.basePackages())
-            .contains("com.baiyue.firstleg.mapper")
-            .contains("com.baiyue.firstleg.split.mapper")
-            .contains("com.baiyue.firstleg.loading.mapper")
-            .contains("com.baiyue.firstleg.loading.bridge.mapper")
-            .contains("com.baiyue.firstleg.oceanbooking.mapper")
-            .contains("com.baiyue.firstleg.outbound.dispatch.mapper")
-            .contains("com.baiyue.firstleg.portschedule.mapper")
-            .contains("com.baiyue.firstleg.customs.container.mapper")
-            .contains("com.baiyue.firstleg.customerstatistics.adapter.out.persistence")
-            .contains("com.baiyue.firstleg.pricebookquery.adapter.out.persistence")
-            .doesNotContain("com.baiyue.firstleg.customerstatistics.mapper")
-            .doesNotContain("com.baiyue.firstleg.customs.mapper");
+        assertThat(scan.basePackages()).containsExactly("com.baiyue.firstleg");
+        assertThat(scan.annotationClass()).isEqualTo(Mapper.class);
     }
 
     @Test

firstleg/src/test/java/com/baiyue/firstleg/MapperRegistrationArchitectureTest.java

@@ -0,0 +1,21 @@
+package com.baiyue.firstleg;
+
+import com.tngtech.archunit.core.domain.JavaClasses;
+import com.tngtech.archunit.core.importer.ClassFileImporter;
+import org.apache.ibatis.annotations.Mapper;
+import org.junit.jupiter.api.Test;
+
+import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.classes;
+
+class MapperRegistrationArchitectureTest {
+    private static final JavaClasses PRODUCTION_CLASSES = new ClassFileImporter()
+        .importPackages("com.baiyue.firstleg");
+
+    @Test
+    void everyMapperInterfaceDeclaresItsRegistrationMarker() {
+        classes().that().areInterfaces().and().haveSimpleNameEndingWith("Mapper")
+            .should().beAnnotatedWith(Mapper.class)
+            .because("Mapper registration must fail during tests instead of service startup")
+            .check(PRODUCTION_CLASSES);
+    }
+}