暂存提交

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/BaiyueWarehouseOverseasApplication.java

@@ -0,0 +1,14 @@
+package com.baiyue.warehouse;
+
+import org.mybatis.spring.annotation.MapperScan;
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+/**
+ * 仓库微服务启动入口，启用 Spring Boot 自动配置并扫描仓库服务的 MyBatis Mapper。
+ */
+@MapperScan("com.baiyue.warehouse.mapper")
+@SpringBootApplication(scanBasePackages = "com.baiyue")
+public class BaiyueWarehouseOverseasApplication {
+    public static void main(String[] args) { SpringApplication.run(BaiyueWarehouseOverseasApplication.class, args); }
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/config/WarehouseDatabaseGuardConfiguration.java

@@ -0,0 +1,27 @@
+package com.baiyue.warehouse.config;
+
+import org.springframework.beans.factory.config.BeanFactoryPostProcessor;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.core.env.Environment;
+
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/** Prevents the warehouse schema migration from ever running against another database. */
+@Configuration(proxyBeanMethods = false)
+public class WarehouseDatabaseGuardConfiguration {
+    private static final Pattern MYSQL_SCHEMA = Pattern.compile(
+        "^jdbc:mysql://[^/]+/([^?;]+)(?:[?;].*)?$", Pattern.CASE_INSENSITIVE);
+
+    @Bean
+    static BeanFactoryPostProcessor warehouseDatabaseGuard(Environment environment) {
+        String url = environment.getProperty("spring.datasource.url", "").trim();
+        Matcher matcher = MYSQL_SCHEMA.matcher(url);
+        if (!matcher.matches() || !"baiyue_warehouse_overseas".equalsIgnoreCase(matcher.group(1))) {
+            throw new IllegalStateException(
+                "warehouse-overseas-service requires spring.datasource.url to target the baiyue_warehouse_overseas database");
+        }
+        return beanFactory -> { };
+    }
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/controller/InternalWarehousePalletController.java

@@ -0,0 +1,25 @@
+package com.baiyue.warehouse.controller;
+
+import com.baiyue.common.core.api.ApiResponse;
+import com.baiyue.warehouse.dto.DropshipPalletRequests;
+import com.baiyue.warehouse.entity.WarehousePalletEntity;
+import com.baiyue.warehouse.security.InternalServiceTokenGuard;
+import com.baiyue.warehouse.service.WarehouseResourceService;
+import jakarta.annotation.Resource;
+import jakarta.validation.Valid;
+import org.springframework.web.bind.annotation.*;
+
+@RestController
+@RequestMapping("/internal/v1/warehouse-pallets")
+public class InternalWarehousePalletController {
+    @Resource private WarehouseResourceService service;
+    @Resource private InternalServiceTokenGuard tokenGuard;
+
+    @PostMapping("/ensure-dropship")
+    public ApiResponse<WarehousePalletEntity> ensure(
+        @RequestHeader(value = "X-Internal-Service-Token", required = false) String token,
+        @Valid @RequestBody DropshipPalletRequests.Ensure request) {
+        tokenGuard.verify(token);
+        return ApiResponse.success(service.ensureDropshipPallet(request.customerId(), request.warehouseId(), request.businessId()));
+    }
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/controller/InternalWarehouseResourceLockController.java

@@ -0,0 +1,70 @@
+package com.baiyue.warehouse.controller;
+
+import com.baiyue.common.core.api.ApiResponse;
+import com.baiyue.warehouse.dto.WarehouseResourceLockRequests;
+import com.baiyue.warehouse.dto.WarehouseResourceLockResponse;
+import com.baiyue.warehouse.dto.WarehousePalletScrapResponse;
+import com.baiyue.warehouse.entity.WarehouseLocationEntity;
+import com.baiyue.warehouse.security.InternalServiceTokenGuard;
+import com.baiyue.warehouse.service.WarehouseResourceLockService;
+import com.baiyue.warehouse.service.WarehouseResourceService;
+import jakarta.validation.Valid;
+import jakarta.annotation.Resource;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestHeader;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+@RequestMapping("/internal/v1/warehouse-resource-locks")
+public class InternalWarehouseResourceLockController {
+    @Resource private WarehouseResourceLockService service;
+    @Resource private WarehouseResourceService resourceService;
+    @Resource private InternalServiceTokenGuard tokenGuard;
+
+    @PostMapping
+    public ApiResponse<WarehouseResourceLockResponse> reserve(
+        @RequestHeader(value = "X-Internal-Service-Token", required = false) String token,
+        @Valid @RequestBody WarehouseResourceLockRequests.ReserveRequest request) {
+        tokenGuard.verify(token);
+        return ApiResponse.success(service.reserve(request));
+    }
+
+    @PostMapping("/{lockId}/release")
+    public ApiResponse<WarehouseResourceLockResponse> release(
+        @RequestHeader(value = "X-Internal-Service-Token", required = false) String token,
+        @PathVariable long lockId,
+        @Valid @RequestBody WarehouseResourceLockRequests.CloseRequest request) {
+        tokenGuard.verify(token);
+        return ApiResponse.success(service.release(request.customerId(), lockId));
+    }
+
+    @PostMapping("/{lockId}/scrap")
+    public ApiResponse<WarehouseResourceLockResponse> scrap(
+        @RequestHeader(value = "X-Internal-Service-Token", required = false) String token,
+        @PathVariable long lockId,
+        @Valid @RequestBody WarehouseResourceLockRequests.CloseRequest request) {
+        tokenGuard.verify(token);
+        return ApiResponse.success(service.scrap(request.customerId(), lockId));
+    }
+
+    @PostMapping("/pallets/{palletId}/scrap")
+    public ApiResponse<WarehousePalletScrapResponse> scrapPallet(
+        @RequestHeader(value = "X-Internal-Service-Token", required = false) String token,
+        @PathVariable long palletId,
+        @Valid @RequestBody WarehouseResourceLockRequests.CloseRequest request) {
+        tokenGuard.verify(token);
+        return ApiResponse.success(service.scrapByPallet(request.customerId(), palletId));
+    }
+
+    @PostMapping("/default-locations/ensure")
+    public ApiResponse<WarehouseLocationEntity> ensureDefaultLocation(
+        @RequestHeader(value = "X-Internal-Service-Token", required = false) String token,
+        @Valid @RequestBody WarehouseResourceLockRequests.DefaultLocationRequest request) {
+        tokenGuard.verify(token);
+        return ApiResponse.success(resourceService.ensureDefaultVirtualLocation(
+            request.customerId(), request.warehouseId()));
+    }
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/controller/MerchantWarehouseController.java

@@ -0,0 +1,67 @@
+package com.baiyue.warehouse.controller;
+
+import com.baiyue.common.core.api.ApiResponse;
+import com.baiyue.common.core.api.PageResult;
+import com.baiyue.common.security.AuthenticatedUser;
+import com.baiyue.warehouse.dto.WarehouseDetailResponse;
+import com.baiyue.warehouse.dto.WarehouseRequests;
+import com.baiyue.warehouse.entity.WarehouseEntity;
+import com.baiyue.warehouse.service.WarehouseApplicationService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.annotation.Resource;
+import jakarta.validation.Valid;
+import org.springframework.security.core.annotation.AuthenticationPrincipal;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+/**
+ * 商户端仓库查询接口，仅允许在认证令牌所属租户范围内读取仓库列表和详情。
+ */
+@Tag(
+    name = "Merchant warehouses / 商户仓库",
+    description = "Merchant read APIs restricted to the tenant in the authenticated JWT. / 商户端只读接口，租户范围取自认证 JWT。"
+)
+@RestController
+@RequestMapping("/api/merchant/v1/warehouses")
+public class MerchantWarehouseController {
+    @Resource
+    private WarehouseApplicationService service;
+
+    @Operation(
+        summary = "List available warehouses / 查询可用仓库",
+        description = "Tenant comes only from the authenticated JWT; clients cannot override it. / 租户仅从认证 JWT 获取，客户端不可覆盖。"
+    )
+    @ApiResponses({
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "Query succeeded / 查询成功"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "400", description = "Invalid query / 查询参数无效"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "401", description = "Authentication required / 需要登录")
+    })
+    @GetMapping
+    public ApiResponse<PageResult<WarehouseEntity>> page(
+        @AuthenticationPrincipal AuthenticatedUser user,
+        @Valid WarehouseRequests.QueryRequest query) {
+        return ApiResponse.success(service.page(user.tenantId(), query));
+    }
+
+    @Operation(
+        summary = "Get warehouse details / 查询仓库详情",
+        description = "Returns warehouse details only within the authenticated merchant tenant. / 仅返回当前认证商户租户内的仓库详情。"
+    )
+    @ApiResponses({
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "Query succeeded / 查询成功"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "401", description = "Authentication required / 需要登录"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "404", description = "Warehouse not found in current tenant / 当前租户下仓库不存在")
+    })
+    @GetMapping("/{id}")
+    public ApiResponse<WarehouseDetailResponse> detail(
+        @AuthenticationPrincipal AuthenticatedUser user,
+        @Parameter(description = "Warehouse ID / 仓库 ID", example = "190000000000000001", required = true)
+        @PathVariable long id) {
+        return ApiResponse.success(service.detail(user.tenantId(), id));
+    }
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/controller/MerchantWarehouseResourceController.java

@@ -0,0 +1,109 @@
+package com.baiyue.warehouse.controller;
+
+import com.baiyue.common.core.api.ApiResponse;
+import com.baiyue.common.core.api.PageResult;
+import com.baiyue.common.core.api.ResultCode;
+import com.baiyue.common.core.exception.BizException;
+import com.baiyue.common.security.AuthenticatedUser;
+import com.baiyue.warehouse.dto.LocationRequests;
+import com.baiyue.warehouse.dto.PalletRequests;
+import com.baiyue.warehouse.entity.WarehouseLocationEntity;
+import com.baiyue.warehouse.entity.WarehousePalletEntity;
+import com.baiyue.warehouse.service.WarehouseResourceService;
+import jakarta.validation.Valid;
+import jakarta.annotation.Resource;
+import org.springframework.security.core.annotation.AuthenticationPrincipal;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@Validated
+@RestController
+@RequestMapping("/api/merchant/v1/warehouses/{warehouseId}")
+public class MerchantWarehouseResourceController {
+    @Resource private WarehouseResourceService service;
+
+    @PostMapping("/locations")
+    public ApiResponse<Long> createLocation(@AuthenticationPrincipal AuthenticatedUser user,
+                                            @PathVariable long warehouseId,
+                                            @Valid @RequestBody LocationRequests.SaveRequest request) {
+        return ApiResponse.success(service.createLocation(tenant(user), warehouseId, request));
+    }
+
+    @PutMapping("/locations/{id}")
+    public ApiResponse<Void> updateLocation(@AuthenticationPrincipal AuthenticatedUser user,
+                                            @PathVariable long warehouseId, @PathVariable long id,
+                                            @Valid @RequestBody LocationRequests.SaveRequest request) {
+        service.updateLocation(tenant(user), warehouseId, id, request);
+        return ApiResponse.success(null);
+    }
+
+    @GetMapping("/locations")
+    public ApiResponse<PageResult<WarehouseLocationEntity>> locations(
+        @AuthenticationPrincipal AuthenticatedUser user, @PathVariable long warehouseId,
+        @Valid LocationRequests.QueryRequest query) {
+        return ApiResponse.success(service.locations(tenant(user), warehouseId, query));
+    }
+
+    @GetMapping("/locations/{id}")
+    public ApiResponse<WarehouseLocationEntity> location(@AuthenticationPrincipal AuthenticatedUser user,
+                                                         @PathVariable long warehouseId,
+                                                         @PathVariable long id) {
+        return ApiResponse.success(service.location(tenant(user), warehouseId, id));
+    }
+
+    @DeleteMapping("/locations/{id}")
+    public ApiResponse<Void> deleteLocation(@AuthenticationPrincipal AuthenticatedUser user,
+                                            @PathVariable long warehouseId, @PathVariable long id) {
+        service.deleteLocation(tenant(user), warehouseId, id);
+        return ApiResponse.success(null);
+    }
+
+    @PostMapping("/pallets")
+    public ApiResponse<Long> createPallet(@AuthenticationPrincipal AuthenticatedUser user,
+                                          @PathVariable long warehouseId,
+                                          @Valid @RequestBody PalletRequests.SaveRequest request) {
+        return ApiResponse.success(service.createPallet(tenant(user), warehouseId, request));
+    }
+
+    @PutMapping("/pallets/{id}")
+    public ApiResponse<Void> updatePallet(@AuthenticationPrincipal AuthenticatedUser user,
+                                          @PathVariable long warehouseId, @PathVariable long id,
+                                          @Valid @RequestBody PalletRequests.SaveRequest request) {
+        service.updatePallet(tenant(user), warehouseId, id, request);
+        return ApiResponse.success(null);
+    }
+
+    @GetMapping("/pallets")
+    public ApiResponse<PageResult<WarehousePalletEntity>> pallets(
+        @AuthenticationPrincipal AuthenticatedUser user, @PathVariable long warehouseId,
+        @Valid PalletRequests.QueryRequest query) {
+        return ApiResponse.success(service.pallets(tenant(user), warehouseId, query));
+    }
+
+    @GetMapping("/pallets/{id}")
+    public ApiResponse<WarehousePalletEntity> pallet(@AuthenticationPrincipal AuthenticatedUser user,
+                                                     @PathVariable long warehouseId, @PathVariable long id) {
+        return ApiResponse.success(service.pallet(tenant(user), warehouseId, id));
+    }
+
+    @DeleteMapping("/pallets/{id}")
+    public ApiResponse<Void> deletePallet(@AuthenticationPrincipal AuthenticatedUser user,
+                                          @PathVariable long warehouseId, @PathVariable long id) {
+        service.deletePallet(tenant(user), warehouseId, id);
+        return ApiResponse.success(null);
+    }
+
+    private static long tenant(AuthenticatedUser user) {
+        if (user == null || user.tenantId() == null || user.tenantId() <= 0) {
+            throw new BizException(ResultCode.UNAUTHORIZED, "认证租户缺失");
+        }
+        return user.tenantId();
+    }
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/controller/PlatformWarehouseController.java

@@ -0,0 +1,166 @@
+package com.baiyue.warehouse.controller;
+
+import com.baiyue.common.core.api.ApiResponse;
+import com.baiyue.common.core.api.PageResult;
+import com.baiyue.common.core.api.ResultCode;
+import com.baiyue.common.core.exception.BizException;
+import com.baiyue.common.security.AuthenticatedUser;
+import com.baiyue.warehouse.dto.WarehouseDetailResponse;
+import com.baiyue.warehouse.dto.WarehouseRequests;
+import com.baiyue.warehouse.entity.WarehouseEntity;
+import com.baiyue.warehouse.service.WarehouseApplicationService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.responses.ApiResponses;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.annotation.Resource;
+import jakarta.validation.Valid;
+import jakarta.validation.constraints.NotNull;
+import org.springframework.security.core.annotation.AuthenticationPrincipal;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PatchMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+/**
+ * 平台端仓库管理接口，提供跨租户管理场景下的仓库创建、修改、查询和状态维护能力。
+ */
+@Validated
+@Tag(
+    name = "Platform warehouse administration / 平台仓库管理",
+    description = "Platform APIs for managing warehouses across tenants. / 平台端按租户管理仓库的接口。"
+)
+@RestController
+@RequestMapping("/api/platform/v1/warehouse-admin")
+public class PlatformWarehouseController {
+    @Resource
+    private WarehouseApplicationService service;
+
+    @Operation(
+        summary = "Create warehouse / 新建仓库",
+        description = "Creates a warehouse, address and service capabilities for the target tenant. / 为目标租户创建仓库、地址和服务能力。"
+    )
+    @ApiResponses({
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "Created successfully / 创建成功"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "400", description = "Invalid request / 请求参数无效"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "403", description = "Platform access required / 需要平台端权限"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "409", description = "Warehouse code already exists / 仓库编码已存在")
+    })
+    @PostMapping
+    public ApiResponse<Long> create(@AuthenticationPrincipal AuthenticatedUser user,
+                                    @Valid @RequestBody WarehouseRequests.SaveRequest request) {
+        requirePlatform(user);
+        requireTenant(request.customerId());
+        return ApiResponse.success(service.create(request));
+    }
+
+    @Operation(
+        summary = "Update warehouse / 更新仓库",
+        description = "Updates the warehouse and replaces its address and capabilities. / 更新仓库，并整体替换地址和服务能力。"
+    )
+    @ApiResponses({
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "Updated successfully / 更新成功"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "400", description = "Invalid request / 请求参数无效"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "403", description = "Platform access or tenant validation failed / 平台权限或租户校验失败"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "404", description = "Warehouse not found / 仓库不存在"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "409", description = "Warehouse code already exists / 仓库编码已存在")
+    })
+    @PutMapping("/{id}")
+    public ApiResponse<Void> update(
+        @AuthenticationPrincipal AuthenticatedUser user,
+        @Parameter(description = "Target tenant ID / 目标租户 ID", example = "10001", required = true)
+        @RequestParam @NotNull Long customerId,
+        @Parameter(description = "Warehouse ID / 仓库 ID", example = "190000000000000001", required = true)
+        @PathVariable long id,
+        @Valid @RequestBody WarehouseRequests.SaveRequest request) {
+        requirePlatform(user);
+        requireTenant(customerId);
+        service.update(customerId, id, request);
+        return ApiResponse.success(null);
+    }
+
+    @Operation(
+        summary = "List tenant warehouses / 查询租户仓库",
+        description = "Returns a tenant-scoped warehouse page with optional country, capability and status filters. / 按租户分页查询仓库，可按国家、能力和状态筛选。"
+    )
+    @ApiResponses({
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "Query succeeded / 查询成功"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "400", description = "Invalid query / 查询参数无效"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "403", description = "Platform access required / 需要平台端权限")
+    })
+    @GetMapping
+    public ApiResponse<PageResult<WarehouseEntity>> page(
+        @AuthenticationPrincipal AuthenticatedUser user,
+        @Parameter(description = "Target tenant ID / 目标租户 ID", example = "10001", required = true)
+        @RequestParam @NotNull Long customerId,
+        @Valid WarehouseRequests.QueryRequest request) {
+        requirePlatform(user);
+        requireTenant(customerId);
+        return ApiResponse.success(service.page(customerId, request));
+    }
+
+    @Operation(
+        summary = "Get tenant warehouse details / 查询租户仓库详情",
+        description = "Returns the warehouse, addresses and service capabilities in the target tenant. / 返回目标租户下的仓库、地址及服务能力。"
+    )
+    @ApiResponses({
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "Query succeeded / 查询成功"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "403", description = "Platform access required / 需要平台端权限"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "404", description = "Warehouse not found / 仓库不存在")
+    })
+    @GetMapping("/{id}")
+    public ApiResponse<WarehouseDetailResponse> detail(
+        @AuthenticationPrincipal AuthenticatedUser user,
+        @Parameter(description = "Target tenant ID / 目标租户 ID", example = "10001", required = true)
+        @RequestParam @NotNull Long customerId,
+        @Parameter(description = "Warehouse ID / 仓库 ID", example = "190000000000000001", required = true)
+        @PathVariable long id) {
+        requirePlatform(user);
+        requireTenant(customerId);
+        return ApiResponse.success(service.detail(customerId, id));
+    }
+
+    @Operation(
+        summary = "Enable or disable warehouse / 启用或停用仓库",
+        description = "Changes warehouse status to ACTIVE or INACTIVE. / 将仓库状态切换为 ACTIVE 或 INACTIVE。"
+    )
+    @ApiResponses({
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "Status changed / 状态变更成功"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "400", description = "Invalid status / 状态无效"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "403", description = "Platform access required / 需要平台端权限"),
+        @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "404", description = "Warehouse not found / 仓库不存在")
+    })
+    @PatchMapping("/{id}/status")
+    public ApiResponse<Void> status(
+        @AuthenticationPrincipal AuthenticatedUser user,
+        @Parameter(description = "Target tenant ID / 目标租户 ID", example = "10001", required = true)
+        @RequestParam @NotNull Long customerId,
+        @Parameter(description = "Warehouse ID / 仓库 ID", example = "190000000000000001", required = true)
+        @PathVariable long id,
+        @Parameter(description = "Target status: ACTIVE or INACTIVE / 目标状态：ACTIVE 或 INACTIVE", example = "ACTIVE", required = true)
+        @RequestParam String status) {
+        requirePlatform(user);
+        requireTenant(customerId);
+        service.changeStatus(customerId, id, status);
+        return ApiResponse.success(null);
+    }
+
+    private static void requirePlatform(AuthenticatedUser user) {
+        if (user == null || !"PLATFORM".equals(user.appCode())) {
+            throw new BizException(ResultCode.FORBIDDEN, "Platform application required / 仅允许平台端访问");
+        }
+    }
+
+    private static void requireTenant(Long customerId) {
+        if (customerId == null || customerId <= 0) {
+            throw new BizException(ResultCode.BAD_REQUEST, "Target tenant is required / 必须指定有效目标租户");
+        }
+    }
+}
+

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/controller/PlatformWarehouseResourceController.java

@@ -0,0 +1,131 @@
+package com.baiyue.warehouse.controller;
+
+import com.baiyue.common.core.api.ApiResponse;
+import com.baiyue.common.core.api.PageResult;
+import com.baiyue.common.core.api.ResultCode;
+import com.baiyue.common.core.exception.BizException;
+import com.baiyue.common.security.AuthenticatedUser;
+import com.baiyue.warehouse.dto.LocationRequests;
+import com.baiyue.warehouse.dto.PalletRequests;
+import com.baiyue.warehouse.entity.WarehouseLocationEntity;
+import com.baiyue.warehouse.entity.WarehousePalletEntity;
+import com.baiyue.warehouse.service.WarehouseResourceService;
+import jakarta.validation.Valid;
+import jakarta.annotation.Resource;
+import jakarta.validation.constraints.NotNull;
+import org.springframework.security.core.annotation.AuthenticationPrincipal;
+import org.springframework.validation.annotation.Validated;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+@Validated
+@RestController
+@RequestMapping("/api/platform/v1/warehouse-admin/{warehouseId}")
+public class PlatformWarehouseResourceController {
+    @Resource private WarehouseResourceService service;
+
+    @PostMapping("/locations")
+    public ApiResponse<Long> createLocation(@AuthenticationPrincipal AuthenticatedUser user,
+                                            @RequestParam @NotNull Long customerId,
+                                            @PathVariable long warehouseId,
+                                            @Valid @RequestBody LocationRequests.SaveRequest request) {
+        requirePlatform(user, customerId);
+        return ApiResponse.success(service.createLocation(customerId, warehouseId, request));
+    }
+
+    @PutMapping("/locations/{id}")
+    public ApiResponse<Void> updateLocation(@AuthenticationPrincipal AuthenticatedUser user,
+                                            @RequestParam @NotNull Long customerId,
+                                            @PathVariable long warehouseId, @PathVariable long id,
+                                            @Valid @RequestBody LocationRequests.SaveRequest request) {
+        requirePlatform(user, customerId);
+        service.updateLocation(customerId, warehouseId, id, request);
+        return ApiResponse.success(null);
+    }
+
+    @GetMapping("/locations")
+    public ApiResponse<PageResult<WarehouseLocationEntity>> locations(
+        @AuthenticationPrincipal AuthenticatedUser user, @RequestParam @NotNull Long customerId,
+        @PathVariable long warehouseId, @Valid LocationRequests.QueryRequest query) {
+        requirePlatform(user, customerId);
+        return ApiResponse.success(service.locations(customerId, warehouseId, query));
+    }
+
+    @GetMapping("/locations/{id}")
+    public ApiResponse<WarehouseLocationEntity> location(@AuthenticationPrincipal AuthenticatedUser user,
+                                                         @RequestParam @NotNull Long customerId,
+                                                         @PathVariable long warehouseId,
+                                                         @PathVariable long id) {
+        requirePlatform(user, customerId);
+        return ApiResponse.success(service.location(customerId, warehouseId, id));
+    }
+
+    @DeleteMapping("/locations/{id}")
+    public ApiResponse<Void> deleteLocation(@AuthenticationPrincipal AuthenticatedUser user,
+                                            @RequestParam @NotNull Long customerId,
+                                            @PathVariable long warehouseId, @PathVariable long id) {
+        requirePlatform(user, customerId);
+        service.deleteLocation(customerId, warehouseId, id);
+        return ApiResponse.success(null);
+    }
+
+    @PostMapping("/pallets")
+    public ApiResponse<Long> createPallet(@AuthenticationPrincipal AuthenticatedUser user,
+                                          @RequestParam @NotNull Long customerId,
+                                          @PathVariable long warehouseId,
+                                          @Valid @RequestBody PalletRequests.SaveRequest request) {
+        requirePlatform(user, customerId);
+        return ApiResponse.success(service.createPallet(customerId, warehouseId, request));
+    }
+
+    @PutMapping("/pallets/{id}")
+    public ApiResponse<Void> updatePallet(@AuthenticationPrincipal AuthenticatedUser user,
+                                          @RequestParam @NotNull Long customerId,
+                                          @PathVariable long warehouseId, @PathVariable long id,
+                                          @Valid @RequestBody PalletRequests.SaveRequest request) {
+        requirePlatform(user, customerId);
+        service.updatePallet(customerId, warehouseId, id, request);
+        return ApiResponse.success(null);
+    }
+
+    @GetMapping("/pallets")
+    public ApiResponse<PageResult<WarehousePalletEntity>> pallets(
+        @AuthenticationPrincipal AuthenticatedUser user, @RequestParam @NotNull Long customerId,
+        @PathVariable long warehouseId, @Valid PalletRequests.QueryRequest query) {
+        requirePlatform(user, customerId);
+        return ApiResponse.success(service.pallets(customerId, warehouseId, query));
+    }
+
+    @GetMapping("/pallets/{id}")
+    public ApiResponse<WarehousePalletEntity> pallet(@AuthenticationPrincipal AuthenticatedUser user,
+                                                     @RequestParam @NotNull Long customerId,
+                                                     @PathVariable long warehouseId, @PathVariable long id) {
+        requirePlatform(user, customerId);
+        return ApiResponse.success(service.pallet(customerId, warehouseId, id));
+    }
+
+    @DeleteMapping("/pallets/{id}")
+    public ApiResponse<Void> deletePallet(@AuthenticationPrincipal AuthenticatedUser user,
+                                          @RequestParam @NotNull Long customerId,
+                                          @PathVariable long warehouseId, @PathVariable long id) {
+        requirePlatform(user, customerId);
+        service.deletePallet(customerId, warehouseId, id);
+        return ApiResponse.success(null);
+    }
+
+    private static void requirePlatform(AuthenticatedUser user, Long customerId) {
+        if (user == null || !"PLATFORM".equals(user.appCode())) {
+            throw new BizException(ResultCode.FORBIDDEN, "仅允许平台端访问");
+        }
+        if (customerId == null || customerId <= 0) {
+            throw new BizException(ResultCode.BAD_REQUEST, "必须指定有效目标租户");
+        }
+    }
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/controller/WarehouseHealthController.java

@@ -0,0 +1,26 @@
+package com.baiyue.warehouse.controller;
+
+import com.baiyue.common.core.api.ApiResponse;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.util.Map;
+
+/**
+ * 仓库微服务可用性接口，向平台端暴露服务逻辑状态。
+ */
+@Tag(name = "Warehouse service status / 仓储服务状态", description = "Warehouse service availability API. / 仓储服务可用性接口。")
+@RestController
+@RequestMapping("/api/platform/v1/warehouses")
+public class WarehouseHealthController {
+    @Operation(summary = "Get service status / 查询服务状态", description = "Returns the logical status of warehouse-overseas-service. / 返回 warehouse-overseas-service 的逻辑运行状态。")
+    @io.swagger.v3.oas.annotations.responses.ApiResponse(responseCode = "200", description = "Service is available / 服务可用")
+    @GetMapping("/status")
+    public ApiResponse<Map<String, String>> status() {
+        return ApiResponse.success(Map.of("service", "warehouse-overseas-service", "status", "UP"));
+    }
+}
+

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/dto/DropshipPalletRequests.java

@@ -0,0 +1,9 @@
+package com.baiyue.warehouse.dto;
+
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.Positive;
+
+public final class DropshipPalletRequests {
+    private DropshipPalletRequests() {}
+    public record Ensure(@Positive long customerId, @Positive long warehouseId, @NotBlank String businessId) {}
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/dto/LocationRequests.java

@@ -0,0 +1,39 @@
+package com.baiyue.warehouse.dto;
+
+import jakarta.validation.constraints.DecimalMin;
+import jakarta.validation.constraints.Max;
+import jakarta.validation.constraints.Min;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.Size;
+
+import java.math.BigDecimal;
+
+public final class LocationRequests {
+    private LocationRequests() {
+    }
+
+    public record SaveRequest(
+        @NotBlank @Size(max = 50) String zoneCode,
+        @NotBlank @Size(max = 64) String locationCode,
+        @NotBlank @Size(max = 32) String locationType,
+        @NotNull @DecimalMin(value = "0.000", inclusive = false) BigDecimal maxLoadKg,
+        @NotBlank String status,
+        @Size(max = 500) String remark
+    ) {
+    }
+
+    public record QueryRequest(
+        @Min(1) long page,
+        @Min(1) @Max(200) long size,
+        String zoneCode,
+        String locationType,
+        String status,
+        String keyword
+    ) {
+        public QueryRequest {
+            if (page == 0) page = 1;
+            if (size == 0) size = 20;
+        }
+    }
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/dto/PalletRequests.java

@@ -0,0 +1,45 @@
+package com.baiyue.warehouse.dto;
+
+import jakarta.validation.constraints.DecimalMin;
+import jakarta.validation.constraints.Max;
+import jakarta.validation.constraints.Min;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.Size;
+
+import java.math.BigDecimal;
+
+public final class PalletRequests {
+    private static final BigDecimal DEFAULT_CAPACITY = new BigDecimal("2.0000");
+
+    private PalletRequests() {
+    }
+
+    public record SaveRequest(
+        @Size(max = 128) String palletCode,
+        @NotBlank @Size(max = 32) String palletType,
+        @DecimalMin(value = "0.0000", inclusive = false) BigDecimal capacityCbm,
+        @NotNull @DecimalMin("0.00") BigDecimal unitPrice,
+        @NotBlank String status,
+        Long locationId,
+        @Size(max = 500) String remark
+    ) {
+        public SaveRequest {
+            if (capacityCbm == null) capacityCbm = DEFAULT_CAPACITY;
+        }
+    }
+
+    public record QueryRequest(
+        @Min(1) long page,
+        @Min(1) @Max(200) long size,
+        String palletType,
+        String status,
+        Long locationId,
+        String keyword
+    ) {
+        public QueryRequest {
+            if (page == 0) page = 1;
+            if (size == 0) size = 20;
+        }
+    }
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/dto/WarehouseDetailResponse.java

@@ -0,0 +1,19 @@
+package com.baiyue.warehouse.dto;
+
+import com.baiyue.warehouse.entity.ServiceCapabilityEntity;
+import com.baiyue.warehouse.entity.WarehouseAddressEntity;
+import com.baiyue.warehouse.entity.WarehouseEntity;
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import java.util.List;
+
+/**
+ * 仓库聚合详情响应，组合仓库主数据、地址列表和服务能力列表。
+ */
+@Schema(name = "WarehouseDetailResponse", description = "Warehouse aggregate details / 仓库聚合详情")
+public record WarehouseDetailResponse(
+    @Schema(description = "Warehouse master data / 仓库主数据") WarehouseEntity warehouse,
+    @Schema(description = "Warehouse addresses / 仓库地址列表") List<WarehouseAddressEntity> addresses,
+    @Schema(description = "Warehouse service capabilities / 仓库服务能力列表") List<ServiceCapabilityEntity> capabilities
+) {
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/dto/WarehousePalletScrapResponse.java

@@ -0,0 +1,4 @@
+package com.baiyue.warehouse.dto;
+
+public record WarehousePalletScrapResponse(long palletId, long warehouseId, Long locationId, String status) {
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/dto/WarehouseRequests.java

@@ -0,0 +1,117 @@
+package com.baiyue.warehouse.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.Valid;
+import jakarta.validation.constraints.Email;
+import jakarta.validation.constraints.Max;
+import jakarta.validation.constraints.Min;
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.Pattern;
+import jakarta.validation.constraints.Size;
+
+import java.math.BigDecimal;
+import java.time.LocalTime;
+import java.util.List;
+
+/**
+ * 仓库接口请求模型容器，集中定义仓库保存、地址、服务能力、查询和状态变更请求契约。
+ */
+public final class WarehouseRequests {
+    private WarehouseRequests() {
+    }
+
+    @Schema(name = "WarehouseSaveRequest", description = "Warehouse create or update request / 仓库新增或更新请求")
+    public record SaveRequest(
+        @Schema(description = "Target tenant ID / 目标租户 ID", example = "10001", requiredMode = Schema.RequiredMode.REQUIRED)
+        @NotNull Long customerId,
+        @Schema(description = "Tenant-unique warehouse code / 租户内唯一仓库编码", example = "US-LAX-01", maxLength = 50, requiredMode = Schema.RequiredMode.REQUIRED)
+        @NotBlank @Size(max = 50) String warehouseCode,
+        @Schema(description = "Warehouse name / 仓库名称", example = "Los Angeles Main Warehouse / 洛杉矶主仓", maxLength = 120, requiredMode = Schema.RequiredMode.REQUIRED)
+        @NotBlank @Size(max = 120) String warehouseName,
+        @Schema(description = "Warehouse type / 仓库类型", example = "OVERSEAS", requiredMode = Schema.RequiredMode.REQUIRED)
+        @NotBlank String warehouseType,
+        @Schema(description = "ISO 3166-1 alpha-2 country code / ISO 两位国家代码", example = "US", pattern = "[A-Z]{2}", requiredMode = Schema.RequiredMode.REQUIRED)
+        @NotBlank @Pattern(regexp = "[A-Z]{2}") String countryCode,
+        @Schema(description = "IANA timezone / IANA 时区", example = "America/Los_Angeles", requiredMode = Schema.RequiredMode.REQUIRED)
+        @NotBlank String timezone,
+        @Schema(description = "Contact name / 联系人姓名", example = "Alex Chen", maxLength = 64)
+        @Size(max = 64) String contactName,
+        @Schema(description = "Contact phone / 联系电话", example = "+1-213-555-0100", maxLength = 32)
+        @Size(max = 32) String contactPhone,
+        @Schema(description = "Contact email / 联系邮箱", example = "warehouse@example.com")
+        @Email String contactEmail,
+        @Schema(description = "Warehouse status / 仓库状态", example = "ACTIVE", allowableValues = {"ACTIVE", "INACTIVE"}, requiredMode = Schema.RequiredMode.REQUIRED)
+        @NotBlank String status,
+        @Schema(description = "Remark / 备注", example = "Supports appointment receiving / 支持预约入库", maxLength = 500)
+        @Size(max = 500) String remark,
+        @Schema(description = "Primary warehouse address / 仓库主地址", requiredMode = Schema.RequiredMode.REQUIRED)
+        @Valid @NotNull AddressRequest address,
+        @Schema(description = "Supported service capabilities / 支持的服务能力")
+        @Valid List<CapabilityRequest> capabilities
+    ) {
+    }
+
+    @Schema(name = "WarehouseAddressRequest", description = "Warehouse address / 仓库地址")
+    public record AddressRequest(
+        @Schema(description = "Address type / 地址类型", example = "WAREHOUSE", requiredMode = Schema.RequiredMode.REQUIRED)
+        @NotBlank String addressType,
+        @Schema(description = "ISO two-letter country code / ISO 两位国家代码", example = "US", requiredMode = Schema.RequiredMode.REQUIRED)
+        @NotBlank @Pattern(regexp = "[A-Z]{2}") String countryCode,
+        @Schema(description = "State or province / 州或省", example = "California", maxLength = 100)
+        @Size(max = 100) String stateProvince,
+        @Schema(description = "City / 城市", example = "Los Angeles", maxLength = 100, requiredMode = Schema.RequiredMode.REQUIRED)
+        @NotBlank @Size(max = 100) String city,
+        @Schema(description = "District / 区县", example = "Commerce", maxLength = 100)
+        @Size(max = 100) String district,
+        @Schema(description = "Postal code / 邮政编码", example = "90040", maxLength = 20)
+        @Size(max = 20) String postalCode,
+        @Schema(description = "Address line 1 / 地址第一行", example = "123 Logistics Ave", maxLength = 255, requiredMode = Schema.RequiredMode.REQUIRED)
+        @NotBlank @Size(max = 255) String addressLine1,
+        @Schema(description = "Address line 2 / 地址第二行", example = "Building A", maxLength = 255)
+        @Size(max = 255) String addressLine2,
+        @Schema(description = "Latitude / 纬度", example = "34.052235")
+        BigDecimal latitude,
+        @Schema(description = "Longitude / 经度", example = "-118.243683")
+        BigDecimal longitude
+    ) {
+    }
+
+    @Schema(name = "WarehouseCapabilityRequest", description = "Warehouse service capability / 仓库服务能力")
+    public record CapabilityRequest(
+        @Schema(description = "Capability code / 能力编码", example = "STORAGE", maxLength = 50, requiredMode = Schema.RequiredMode.REQUIRED)
+        @NotBlank @Size(max = 50) String capabilityCode,
+        @Schema(description = "Capability name / 能力名称", example = "Storage / 仓储", maxLength = 100, requiredMode = Schema.RequiredMode.REQUIRED)
+        @NotBlank @Size(max = 100) String capabilityName,
+        @Schema(description = "Whether enabled / 是否启用", example = "true", defaultValue = "true")
+        Boolean enabled,
+        @Schema(description = "Daily cutoff time / 每日截单时间", example = "16:00:00", type = "string", format = "time")
+        LocalTime cutoffTime,
+        @Schema(description = "Capability description / 能力说明", example = "Standard pallet storage / 标准托盘仓储", maxLength = 500)
+        @Size(max = 500) String description
+    ) {
+    }
+
+    @Schema(name = "WarehouseQueryRequest", description = "Warehouse page query / 仓库分页查询条件")
+    public record QueryRequest(
+        @Schema(description = "Page number, starting at 1 / 页码，从 1 开始", example = "1", defaultValue = "1", minimum = "1")
+        @Min(1) long page,
+        @Schema(description = "Page size / 每页条数", example = "20", defaultValue = "20", minimum = "1", maximum = "200")
+        @Min(1) @Max(200) long size,
+        @Schema(description = "Country filter / 国家筛选", example = "US")
+        String countryCode,
+        @Schema(description = "Enabled capability code filter / 已启用能力编码筛选", example = "STORAGE")
+        String capabilityCode,
+        @Schema(description = "Status filter / 状态筛选", example = "ACTIVE", allowableValues = {"ACTIVE", "INACTIVE"})
+        String status
+    ) {
+        public QueryRequest {
+            if (page == 0) {
+                page = 1;
+            }
+            if (size == 0) {
+                size = 20;
+            }
+        }
+    }
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/dto/WarehouseResourceLockRequests.java

@@ -0,0 +1,25 @@
+package com.baiyue.warehouse.dto;
+
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.Positive;
+
+public final class WarehouseResourceLockRequests {
+    private WarehouseResourceLockRequests() {}
+
+    public record ReserveRequest(
+        @Positive long customerId,
+        @Positive long warehouseId,
+        @Positive long palletId,
+        @Positive long locationId,
+        @NotBlank String businessType,
+        @NotBlank String businessId,
+        @NotBlank String reservationKey
+    ) {}
+
+    public record CloseRequest(@Positive long customerId) {}
+
+    public record DefaultLocationRequest(
+        @Positive long customerId,
+        @Positive long warehouseId
+    ) {}
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/dto/WarehouseResourceLockResponse.java

@@ -0,0 +1,25 @@
+package com.baiyue.warehouse.dto;
+
+import com.baiyue.warehouse.entity.WarehouseResourceLockEntity;
+
+import java.time.LocalDateTime;
+
+public record WarehouseResourceLockResponse(
+    long lockId,
+    long customerId,
+    long warehouseId,
+    long palletId,
+    long locationId,
+    String businessType,
+    String businessId,
+    String reservationKey,
+    String status,
+    LocalDateTime lockedAt,
+    LocalDateTime releasedAt
+) {
+    public static WarehouseResourceLockResponse from(WarehouseResourceLockEntity entity) {
+        return new WarehouseResourceLockResponse(entity.getId(), entity.getCustomerId(), entity.getWarehouseId(),
+            entity.getPalletId(), entity.getLocationId(), entity.getBusinessType(), entity.getBusinessId(),
+            entity.getReservationKey(), entity.getStatus(), entity.getLockedAt(), entity.getReleasedAt());
+    }
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/entity/ServiceCapabilityEntity.java

@@ -0,0 +1,57 @@
+package com.baiyue.warehouse.entity;
+
+import lombok.Getter;
+import lombok.Setter;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import com.baiyue.common.core.model.BaseEntity;
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import java.time.LocalTime;
+
+/**
+ * 仓库服务能力持久化实体，对应 {@code wh_service_capability} 表。
+ * 用于记录租户仓库可提供的能力、启用状态和每日截单时间。
+ */
+@Schema(name = "WarehouseServiceCapability", description = "仓库服务能力")
+@Getter
+@Setter
+@TableName("wh_service_capability")
+public class ServiceCapabilityEntity extends BaseEntity {
+    @Schema(description = "能力记录编号", example = "190000000000000021")
+    @TableId(type = IdType.ASSIGN_ID)
+    private Long id;
+    @Schema(description = "租户编号", example = "10001")
+    private Long customerId;
+    @Schema(description = "仓库编号", example = "190000000000000001")
+    private Long warehouseId;
+    @Schema(description = "能力编码", example = "STORAGE")
+    private String capabilityCode;
+    @Schema(description = "能力名称", example = "仓储")
+    private String capabilityName;
+    @Schema(description = "是否启用", example = "true")
+    private Boolean enabled;
+    @Schema(description = "每日截单时间", example = "16:00:00", type = "string", format = "time")
+    private LocalTime cutoffTime;
+    @Schema(description = "能力说明", example = "标准托盘仓储")
+    private String description;
+
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/entity/WarehouseAddressEntity.java

@@ -0,0 +1,77 @@
+package com.baiyue.warehouse.entity;
+
+import lombok.Getter;
+import lombok.Setter;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import com.baiyue.common.core.model.BaseEntity;
+import io.swagger.v3.oas.annotations.media.Schema;
+
+import java.math.BigDecimal;
+
+/**
+ * 仓库地址持久化实体，对应 {@code wh_warehouse_address} 表。
+ * 用于保存租户仓库的结构化地址与经纬度信息。
+ */
+@Schema(name = "WarehouseAddress", description = "仓库地址数据")
+@Getter
+@Setter
+@TableName("wh_warehouse_address")
+public class WarehouseAddressEntity extends BaseEntity {
+    @Schema(description = "地址编号", example = "190000000000000011")
+    @TableId(type = IdType.ASSIGN_ID)
+    private Long id;
+    @Schema(description = "租户编号", example = "10001")
+    private Long customerId;
+    @Schema(description = "仓库编号", example = "190000000000000001")
+    private Long warehouseId;
+    @Schema(description = "地址类型", example = "WAREHOUSE")
+    private String addressType;
+    @Schema(description = "ISO 两位国家代码", example = "US")
+    private String countryCode;
+    @Schema(description = "州或省", example = "California")
+    private String stateProvince;
+    @Schema(description = "城市", example = "Los Angeles")
+    private String city;
+    @Schema(description = "区县", example = "Commerce")
+    private String district;
+    @Schema(description = "邮政编码", example = "90040")
+    private String postalCode;
+    @Schema(description = "地址第一行", example = "123 Logistics Ave")
+    private String addressLine1;
+    @Schema(description = "地址第二行", example = "Building A")
+    private String addressLine2;
+    @Schema(description = "纬度", example = "34.052235")
+    private BigDecimal latitude;
+    @Schema(description = "经度", example = "-118.243683")
+    private BigDecimal longitude;
+
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/entity/WarehouseEntity.java

@@ -0,0 +1,71 @@
+package com.baiyue.warehouse.entity;
+
+import lombok.Getter;
+import lombok.Setter;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import com.baiyue.common.core.model.BaseEntity;
+import io.swagger.v3.oas.annotations.media.Schema;
+
+/**
+ * 仓库主数据持久化实体，对应 {@code wh_warehouse} 表。
+ * 用于记录租户下仓库的编码、类型、国家、联系方式和启停状态。
+ */
+@Schema(name = "Warehouse", description = "仓库主数据")
+@Getter
+@Setter
+@TableName("wh_warehouse")
+public class WarehouseEntity extends BaseEntity {
+    @Schema(description = "仓库编号", example = "190000000000000001")
+    @TableId(type = IdType.ASSIGN_ID)
+    private Long id;
+    @Schema(description = "租户编号", example = "10001")
+    private Long customerId;
+    @Schema(description = "仓库编码", example = "US-LAX-01")
+    private String warehouseCode;
+    @Schema(description = "仓库名称", example = "洛杉矶主仓")
+    private String warehouseName;
+    @Schema(description = "仓库类型", example = "OVERSEAS")
+    private String warehouseType;
+    @Schema(description = "ISO 两位国家代码", example = "US")
+    private String countryCode;
+    @Schema(description = "IANA 时区", example = "America/Los_Angeles")
+    private String timezone;
+    @Schema(description = "联系人", example = "陈先生")
+    private String contactName;
+    @Schema(description = "联系电话", example = "+1-213-555-0100")
+    private String contactPhone;
+    @Schema(description = "联系邮箱", example = "warehouse@example.com")
+    private String contactEmail;
+    @Schema(description = "仓库状态", example = "ACTIVE", allowableValues = {"ACTIVE", "INACTIVE"})
+    private String status;
+    @Schema(description = "备注", example = "支持预约入库")
+    private String remark;
+
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/entity/WarehouseLocationEntity.java

@@ -0,0 +1,26 @@
+package com.baiyue.warehouse.entity;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import com.baiyue.common.core.model.BaseEntity;
+import lombok.Getter;
+import lombok.Setter;
+
+import java.math.BigDecimal;
+
+@Getter
+@Setter
+@TableName("wh_location")
+public class WarehouseLocationEntity extends BaseEntity {
+    @TableId(type = IdType.ASSIGN_ID)
+    private Long id;
+    private Long customerId;
+    private Long warehouseId;
+    private String zoneCode;
+    private String locationCode;
+    private String locationType;
+    private BigDecimal maxLoadKg;
+    private String status;
+    private String remark;
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/entity/WarehousePalletBindingEntity.java

@@ -0,0 +1,19 @@
+package com.baiyue.warehouse.entity;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+import java.time.LocalDateTime;
+
+@Data
+@TableName("wh_pallet_business_binding")
+public class WarehousePalletBindingEntity {
+    @TableId(type = IdType.ASSIGN_ID) private Long id;
+    private Long customerId;
+    private Long warehouseId;
+    private String businessType;
+    private String businessId;
+    private Long palletId;
+    private LocalDateTime createdAt;
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/entity/WarehousePalletEntity.java

@@ -0,0 +1,27 @@
+package com.baiyue.warehouse.entity;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import com.baiyue.common.core.model.BaseEntity;
+import lombok.Getter;
+import lombok.Setter;
+
+import java.math.BigDecimal;
+
+@Getter
+@Setter
+@TableName("wh_pallet")
+public class WarehousePalletEntity extends BaseEntity {
+    @TableId(type = IdType.ASSIGN_ID)
+    private Long id;
+    private Long customerId;
+    private Long warehouseId;
+    private Long locationId;
+    private String palletCode;
+    private String palletType;
+    private BigDecimal capacityCbm;
+    private BigDecimal unitPrice;
+    private String status;
+    private String remark;
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/entity/WarehouseResourceLockEntity.java

@@ -0,0 +1,29 @@
+package com.baiyue.warehouse.entity;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Getter;
+import lombok.Setter;
+
+import java.time.LocalDateTime;
+
+@Getter
+@Setter
+@TableName("wh_resource_lock")
+public class WarehouseResourceLockEntity {
+    @TableId(type = IdType.ASSIGN_ID)
+    private Long id;
+    private Long customerId;
+    private Long warehouseId;
+    private Long palletId;
+    private Long locationId;
+    private String businessType;
+    private String businessId;
+    private String reservationKey;
+    private String status;
+    private LocalDateTime lockedAt;
+    private LocalDateTime releasedAt;
+    private LocalDateTime createdAt;
+    private LocalDateTime updatedAt;
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/mapper/ServiceCapabilityMapper.java

@@ -0,0 +1,16 @@
+package com.baiyue.warehouse.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.baiyue.warehouse.entity.ServiceCapabilityEntity;
+import org.apache.ibatis.annotations.Delete;
+import org.apache.ibatis.annotations.Param;
+
+/**
+ * 仓库服务能力 MyBatis-Plus Mapper，负责 {@code wh_service_capability} 表访问及仓库子记录的物理清理。
+ */
+public interface ServiceCapabilityMapper extends BaseMapper<ServiceCapabilityEntity> {
+
+    @Delete("DELETE FROM wh_service_capability WHERE customer_id = #{customerId} AND warehouse_id = #{warehouseId}")
+    int physicallyDeleteByWarehouse(@Param("customerId") long customerId,
+                                    @Param("warehouseId") long warehouseId);
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/mapper/WarehouseAddressMapper.java

@@ -0,0 +1,16 @@
+package com.baiyue.warehouse.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.baiyue.warehouse.entity.WarehouseAddressEntity;
+import org.apache.ibatis.annotations.Delete;
+import org.apache.ibatis.annotations.Param;
+
+/**
+ * 仓库地址 MyBatis-Plus Mapper，负责 {@code wh_warehouse_address} 表访问及仓库子记录的物理清理。
+ */
+public interface WarehouseAddressMapper extends BaseMapper<WarehouseAddressEntity> {
+
+    @Delete("DELETE FROM wh_warehouse_address WHERE customer_id = #{customerId} AND warehouse_id = #{warehouseId}")
+    int physicallyDeleteByWarehouse(@Param("customerId") long customerId,
+                                    @Param("warehouseId") long warehouseId);
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/mapper/WarehouseLocationMapper.java

@@ -0,0 +1,22 @@
+package com.baiyue.warehouse.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.baiyue.warehouse.entity.WarehouseLocationEntity;
+import org.apache.ibatis.annotations.Insert;
+import org.apache.ibatis.annotations.Param;
+
+public interface WarehouseLocationMapper extends BaseMapper<WarehouseLocationEntity> {
+    /**
+     * The unique location-code index makes this safe for concurrent first use of an older warehouse.
+     */
+    @Insert("""
+        INSERT IGNORE INTO wh_location
+          (id, customer_id, warehouse_id, zone_code, location_code, location_type,
+           max_load_kg, status, remark, deleted, version)
+        VALUES
+          (#{location.id}, #{location.customerId}, #{location.warehouseId}, #{location.zoneCode},
+           #{location.locationCode}, #{location.locationType}, #{location.maxLoadKg},
+           #{location.status}, #{location.remark}, 0, 0)
+        """)
+    int insertDefaultVirtualLocationIgnore(@Param("location") WarehouseLocationEntity location);
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/mapper/WarehouseMapper.java

@@ -0,0 +1,6 @@
+package com.baiyue.warehouse.mapper; import com.baomidou.mybatisplus.core.mapper.BaseMapper; import com.baiyue.warehouse.entity.WarehouseEntity;
+
+/**
+ * 仓库主数据 MyBatis-Plus Mapper，提供 {@code wh_warehouse} 表的单表持久化访问。
+ */
+public interface WarehouseMapper extends BaseMapper<WarehouseEntity> {}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/mapper/WarehousePalletBindingMapper.java

@@ -0,0 +1,13 @@
+package com.baiyue.warehouse.mapper;
+
+import com.baiyue.warehouse.entity.WarehousePalletBindingEntity;
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import org.apache.ibatis.annotations.Param;
+import org.apache.ibatis.annotations.Select;
+
+public interface WarehousePalletBindingMapper extends BaseMapper<WarehousePalletBindingEntity> {
+    @Select("SELECT * FROM wh_pallet_business_binding WHERE customer_id=#{customerId} AND warehouse_id=#{warehouseId} " +
+        "AND business_type=#{businessType} AND business_id=#{businessId} LIMIT 1")
+    WarehousePalletBindingEntity find(@Param("customerId") long customerId, @Param("warehouseId") long warehouseId,
+                                      @Param("businessType") String businessType, @Param("businessId") String businessId);
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/mapper/WarehousePalletMapper.java

@@ -0,0 +1,7 @@
+package com.baiyue.warehouse.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.baiyue.warehouse.entity.WarehousePalletEntity;
+
+public interface WarehousePalletMapper extends BaseMapper<WarehousePalletEntity> {
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/mapper/WarehouseResourceLockMapper.java

@@ -0,0 +1,100 @@
+package com.baiyue.warehouse.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.baiyue.warehouse.entity.WarehouseResourceLockEntity;
+import org.apache.ibatis.annotations.Param;
+import org.apache.ibatis.annotations.Select;
+import org.apache.ibatis.annotations.Update;
+
+public interface WarehouseResourceLockMapper extends BaseMapper<WarehouseResourceLockEntity> {
+    @Select("""
+        SELECT * FROM wh_resource_lock
+        WHERE customer_id = #{customerId} AND reservation_key = #{reservationKey}
+        LIMIT 1
+        """)
+    WarehouseResourceLockEntity findByReservationKey(@Param("customerId") long customerId,
+                                                       @Param("reservationKey") String reservationKey);
+
+    @Select("SELECT * FROM wh_resource_lock WHERE customer_id=#{customerId} AND pallet_id=#{palletId} " +
+        "AND status='ACTIVE' ORDER BY locked_at DESC LIMIT 1")
+    WarehouseResourceLockEntity findActiveByPallet(@Param("customerId") long customerId,
+                                                    @Param("palletId") long palletId);
+
+    @Update("""
+        UPDATE wh_pallet
+        SET status = 'OCCUPIED', location_id = #{locationId}, updated_at = CURRENT_TIMESTAMP(3), version = version + 1
+        WHERE id = #{palletId} AND customer_id = #{customerId} AND warehouse_id = #{warehouseId}
+          AND status = 'IDLE' AND deleted = 0
+        """)
+    int occupyPallet(@Param("customerId") long customerId, @Param("warehouseId") long warehouseId,
+                     @Param("palletId") long palletId, @Param("locationId") long locationId);
+
+    @Update("""
+        UPDATE wh_location
+        SET status = 'OCCUPIED', updated_at = CURRENT_TIMESTAMP(3), version = version + 1
+        WHERE id = #{locationId} AND customer_id = #{customerId} AND warehouse_id = #{warehouseId}
+          AND status = 'IDLE' AND deleted = 0
+        """)
+    int occupyLocation(@Param("customerId") long customerId, @Param("warehouseId") long warehouseId,
+                       @Param("locationId") long locationId);
+
+    @Update("""
+        UPDATE wh_pallet
+        SET status = 'IDLE', location_id = NULL, updated_at = CURRENT_TIMESTAMP(3), version = version + 1
+        WHERE id = #{palletId} AND customer_id = #{customerId} AND warehouse_id = #{warehouseId}
+          AND location_id = #{locationId} AND status = 'OCCUPIED' AND deleted = 0
+        """)
+    int releasePallet(@Param("customerId") long customerId, @Param("warehouseId") long warehouseId,
+                      @Param("palletId") long palletId, @Param("locationId") long locationId);
+
+    @Update("""
+        UPDATE wh_pallet
+        SET status = 'IDLE', updated_at = CURRENT_TIMESTAMP(3), version = version + 1
+        WHERE id = #{palletId} AND customer_id = #{customerId} AND warehouse_id = #{warehouseId}
+          AND location_id = #{locationId} AND status = 'OCCUPIED' AND deleted = 0
+        """)
+    int releasePalletAtVirtualLocation(@Param("customerId") long customerId,
+                                       @Param("warehouseId") long warehouseId,
+                                       @Param("palletId") long palletId,
+                                       @Param("locationId") long locationId);
+
+    @Update("""
+        UPDATE wh_location
+        SET status = 'IDLE', updated_at = CURRENT_TIMESTAMP(3), version = version + 1
+        WHERE id = #{locationId} AND customer_id = #{customerId} AND warehouse_id = #{warehouseId}
+          AND status = 'OCCUPIED' AND deleted = 0
+        """)
+    int releaseLocation(@Param("customerId") long customerId, @Param("warehouseId") long warehouseId,
+                        @Param("locationId") long locationId);
+
+    @Update("""
+        UPDATE wh_pallet
+        SET status = 'SCRAPPED', location_id = NULL, updated_at = CURRENT_TIMESTAMP(3), version = version + 1
+        WHERE id = #{palletId} AND customer_id = #{customerId} AND warehouse_id = #{warehouseId}
+          AND location_id = #{locationId} AND status = 'OCCUPIED' AND deleted = 0
+        """)
+    int scrapPallet(@Param("customerId") long customerId, @Param("warehouseId") long warehouseId,
+                    @Param("palletId") long palletId, @Param("locationId") long locationId);
+
+    @Update("""
+        UPDATE wh_pallet
+        SET status = 'SCRAPPED', updated_at = CURRENT_TIMESTAMP(3), version = version + 1
+        WHERE id = #{palletId} AND customer_id = #{customerId} AND warehouse_id = #{warehouseId}
+          AND location_id = #{locationId} AND status = 'OCCUPIED' AND deleted = 0
+        """)
+    int scrapPalletAtVirtualLocation(@Param("customerId") long customerId,
+                                     @Param("warehouseId") long warehouseId,
+                                     @Param("palletId") long palletId,
+                                     @Param("locationId") long locationId);
+
+    @Update("UPDATE wh_pallet SET status='SCRAPPED',updated_at=CURRENT_TIMESTAMP(3),version=version+1 " +
+        "WHERE customer_id=#{customerId} AND id=#{palletId} AND status='OCCUPIED' AND deleted=0")
+    int scrapPalletWithoutLock(@Param("customerId") long customerId, @Param("palletId") long palletId);
+
+    @Update("""
+        UPDATE wh_resource_lock
+        SET status = #{status}, released_at = CURRENT_TIMESTAMP(3), updated_at = CURRENT_TIMESTAMP(3)
+        WHERE id = #{id} AND status = 'ACTIVE'
+        """)
+    int closeLock(@Param("id") long id, @Param("status") String status);
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/repository/WarehouseRepository.java

@@ -0,0 +1,112 @@
+package com.baiyue.warehouse.repository;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import com.baiyue.common.core.api.PageResult;
+import com.baiyue.warehouse.dto.WarehouseRequests;
+import com.baiyue.warehouse.entity.ServiceCapabilityEntity;
+import com.baiyue.warehouse.entity.WarehouseAddressEntity;
+import com.baiyue.warehouse.entity.WarehouseEntity;
+import com.baiyue.warehouse.entity.WarehouseLocationEntity;
+import com.baiyue.warehouse.mapper.ServiceCapabilityMapper;
+import com.baiyue.warehouse.mapper.WarehouseAddressMapper;
+import com.baiyue.warehouse.mapper.WarehouseMapper;
+import com.baiyue.warehouse.mapper.WarehouseLocationMapper;
+import org.springframework.stereotype.Repository;
+import org.springframework.util.StringUtils;
+import jakarta.annotation.Resource;
+
+import java.util.List;
+
+/**
+ * 仓库聚合持久化仓储，组合仓库、地址和服务能力 Mapper，并强制按租户范围执行查询与写入。
+ */
+@Repository
+public class WarehouseRepository {
+    @Resource private WarehouseMapper warehouses;
+    @Resource private WarehouseLocationMapper locations;
+    @Resource private WarehouseAddressMapper addresses;
+    @Resource private ServiceCapabilityMapper capabilities;
+
+    public void insertWarehouse(WarehouseEntity warehouse) {
+        warehouses.insert(warehouse);
+    }
+
+    public void insertLocation(WarehouseLocationEntity location) {
+        locations.insert(location);
+    }
+
+    public boolean existsLocationCode(long customerId, long warehouseId, String locationCode) {
+        return locations.selectCount(new LambdaQueryWrapper<WarehouseLocationEntity>()
+            .eq(WarehouseLocationEntity::getCustomerId, customerId)
+            .eq(WarehouseLocationEntity::getWarehouseId, warehouseId)
+            .eq(WarehouseLocationEntity::getLocationCode, locationCode)) > 0;
+    }
+
+    public void saveWarehouse(WarehouseEntity warehouse) {
+        warehouses.updateById(warehouse);
+    }
+
+    public WarehouseEntity findOwned(long customerId, long id) {
+        return warehouses.selectOne(new LambdaQueryWrapper<WarehouseEntity>()
+            .eq(WarehouseEntity::getCustomerId, customerId)
+            .eq(WarehouseEntity::getId, id));
+    }
+
+    public boolean existsCode(long customerId, String code, Long excludedId) {
+        return warehouses.selectCount(new LambdaQueryWrapper<WarehouseEntity>()
+            .eq(WarehouseEntity::getCustomerId, customerId)
+            .eq(WarehouseEntity::getWarehouseCode, code)
+            .ne(excludedId != null, WarehouseEntity::getId, excludedId)) > 0;
+    }
+
+    public PageResult<WarehouseEntity> page(long customerId, WarehouseRequests.QueryRequest query) {
+        LambdaQueryWrapper<WarehouseEntity> wrapper = new LambdaQueryWrapper<WarehouseEntity>()
+            .eq(WarehouseEntity::getCustomerId, customerId)
+            .eq(StringUtils.hasText(query.status()), WarehouseEntity::getStatus, query.status())
+            .eq(StringUtils.hasText(query.countryCode()), WarehouseEntity::getCountryCode, query.countryCode())
+            .orderByDesc(WarehouseEntity::getCreatedAt);
+
+        if (StringUtils.hasText(query.capabilityCode())) {
+            List<Long> ids = capabilities.selectList(new LambdaQueryWrapper<ServiceCapabilityEntity>()
+                    .select(ServiceCapabilityEntity::getWarehouseId)
+                    .eq(ServiceCapabilityEntity::getCustomerId, customerId)
+                    .eq(ServiceCapabilityEntity::getCapabilityCode, query.capabilityCode())
+                    .eq(ServiceCapabilityEntity::getEnabled, true))
+                .stream()
+                .map(ServiceCapabilityEntity::getWarehouseId)
+                .distinct()
+                .toList();
+            if (ids.isEmpty()) {
+                return new PageResult<>(List.of(), query.page(), query.size(), 0, 0);
+            }
+            wrapper.in(WarehouseEntity::getId, ids);
+        }
+        return PageResult.from(warehouses.selectPage(new Page<>(query.page(), query.size()), wrapper));
+    }
+
+    public List<WarehouseAddressEntity> findAddresses(long customerId, long warehouseId) {
+        return addresses.selectList(new LambdaQueryWrapper<WarehouseAddressEntity>()
+            .eq(WarehouseAddressEntity::getCustomerId, customerId)
+            .eq(WarehouseAddressEntity::getWarehouseId, warehouseId));
+    }
+
+    public List<ServiceCapabilityEntity> findCapabilities(long customerId, long warehouseId) {
+        return capabilities.selectList(new LambdaQueryWrapper<ServiceCapabilityEntity>()
+            .eq(ServiceCapabilityEntity::getCustomerId, customerId)
+            .eq(ServiceCapabilityEntity::getWarehouseId, warehouseId));
+    }
+
+    public void physicallyDeleteChildren(long customerId, long warehouseId) {
+        addresses.physicallyDeleteByWarehouse(customerId, warehouseId);
+        capabilities.physicallyDeleteByWarehouse(customerId, warehouseId);
+    }
+
+    public void insertAddress(WarehouseAddressEntity address) {
+        addresses.insert(address);
+    }
+
+    public void insertCapability(ServiceCapabilityEntity capability) {
+        capabilities.insert(capability);
+    }
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/repository/WarehouseResourceLockRepository.java

@@ -0,0 +1,90 @@
+package com.baiyue.warehouse.repository;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baiyue.warehouse.entity.WarehouseLocationEntity;
+import com.baiyue.warehouse.entity.WarehousePalletEntity;
+import com.baiyue.warehouse.entity.WarehouseResourceLockEntity;
+import com.baiyue.warehouse.mapper.WarehouseLocationMapper;
+import com.baiyue.warehouse.mapper.WarehousePalletMapper;
+import com.baiyue.warehouse.mapper.WarehouseResourceLockMapper;
+import org.springframework.stereotype.Repository;
+import jakarta.annotation.Resource;
+
+@Repository
+public class WarehouseResourceLockRepository {
+    @Resource private WarehouseResourceLockMapper locks;
+    @Resource private WarehousePalletMapper pallets;
+    @Resource private WarehouseLocationMapper locations;
+
+    public WarehouseResourceLockEntity findByReservationKey(long customerId, String reservationKey) {
+        return locks.findByReservationKey(customerId, reservationKey);
+    }
+
+    public WarehouseResourceLockEntity find(long customerId, long lockId) {
+        return locks.selectOne(new LambdaQueryWrapper<WarehouseResourceLockEntity>()
+            .eq(WarehouseResourceLockEntity::getCustomerId, customerId)
+            .eq(WarehouseResourceLockEntity::getId, lockId));
+    }
+
+    public WarehouseResourceLockEntity findActiveByPallet(long customerId, long palletId) {
+        return locks.findActiveByPallet(customerId, palletId);
+    }
+
+    public WarehousePalletEntity findPallet(long customerId, long palletId) {
+        return pallets.selectOne(new LambdaQueryWrapper<WarehousePalletEntity>()
+            .eq(WarehousePalletEntity::getCustomerId, customerId)
+            .eq(WarehousePalletEntity::getId, palletId));
+    }
+
+    public WarehousePalletEntity findPallet(long customerId, long warehouseId, long palletId) {
+        return pallets.selectOne(new LambdaQueryWrapper<WarehousePalletEntity>()
+            .eq(WarehousePalletEntity::getCustomerId, customerId)
+            .eq(WarehousePalletEntity::getWarehouseId, warehouseId)
+            .eq(WarehousePalletEntity::getId, palletId));
+    }
+
+    public WarehouseLocationEntity findLocation(long customerId, long warehouseId, long locationId) {
+        return locations.selectOne(new LambdaQueryWrapper<WarehouseLocationEntity>()
+            .eq(WarehouseLocationEntity::getCustomerId, customerId)
+            .eq(WarehouseLocationEntity::getWarehouseId, warehouseId)
+            .eq(WarehouseLocationEntity::getId, locationId));
+    }
+
+    public int occupyPallet(long customerId, long warehouseId, long palletId, long locationId) {
+        return locks.occupyPallet(customerId, warehouseId, palletId, locationId);
+    }
+
+    public int occupyLocation(long customerId, long warehouseId, long locationId) {
+        return locks.occupyLocation(customerId, warehouseId, locationId);
+    }
+
+    public void insert(WarehouseResourceLockEntity lock) { locks.insert(lock); }
+
+    public int releasePallet(WarehouseResourceLockEntity lock) {
+        return locks.releasePallet(lock.getCustomerId(), lock.getWarehouseId(), lock.getPalletId(), lock.getLocationId());
+    }
+
+    public int releasePalletAtVirtualLocation(WarehouseResourceLockEntity lock) {
+        return locks.releasePalletAtVirtualLocation(lock.getCustomerId(), lock.getWarehouseId(),
+            lock.getPalletId(), lock.getLocationId());
+    }
+
+    public int scrapPallet(WarehouseResourceLockEntity lock) {
+        return locks.scrapPallet(lock.getCustomerId(), lock.getWarehouseId(), lock.getPalletId(), lock.getLocationId());
+    }
+
+    public int scrapPalletWithoutLock(long customerId, long palletId) {
+        return locks.scrapPalletWithoutLock(customerId, palletId);
+    }
+
+    public int scrapPalletAtVirtualLocation(WarehouseResourceLockEntity lock) {
+        return locks.scrapPalletAtVirtualLocation(lock.getCustomerId(), lock.getWarehouseId(),
+            lock.getPalletId(), lock.getLocationId());
+    }
+
+    public int releaseLocation(WarehouseResourceLockEntity lock) {
+        return locks.releaseLocation(lock.getCustomerId(), lock.getWarehouseId(), lock.getLocationId());
+    }
+
+    public int close(WarehouseResourceLockEntity lock, String status) { return locks.closeLock(lock.getId(), status); }
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/repository/WarehouseResourceRepository.java

@@ -0,0 +1,158 @@
+package com.baiyue.warehouse.repository;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import com.baiyue.common.core.api.PageResult;
+import com.baiyue.warehouse.dto.LocationRequests;
+import com.baiyue.warehouse.dto.PalletRequests;
+import com.baiyue.warehouse.entity.WarehouseEntity;
+import com.baiyue.warehouse.entity.WarehouseLocationEntity;
+import com.baiyue.warehouse.entity.WarehousePalletEntity;
+import com.baiyue.warehouse.mapper.WarehouseLocationMapper;
+import com.baiyue.warehouse.mapper.WarehouseMapper;
+import com.baiyue.warehouse.mapper.WarehousePalletMapper;
+import com.baiyue.warehouse.mapper.WarehousePalletBindingMapper;
+import com.baiyue.warehouse.entity.WarehousePalletBindingEntity;
+import org.springframework.stereotype.Repository;
+import org.springframework.util.StringUtils;
+import jakarta.annotation.Resource;
+
+@Repository
+public class WarehouseResourceRepository {
+    @Resource private WarehouseMapper warehouses;
+    @Resource private WarehouseLocationMapper locations;
+    @Resource private WarehousePalletMapper pallets;
+    @Resource private WarehousePalletBindingMapper bindings;
+
+    public WarehousePalletBindingEntity findPalletBinding(long customerId, long warehouseId,
+                                                           String businessType, String businessId) {
+        return bindings.find(customerId, warehouseId, businessType, businessId);
+    }
+
+    public void insertPalletBinding(WarehousePalletBindingEntity entity) {
+        bindings.insert(entity);
+    }
+
+    public boolean warehouseOwned(long customerId, long warehouseId) {
+        return warehouses.selectCount(new LambdaQueryWrapper<WarehouseEntity>()
+            .eq(WarehouseEntity::getCustomerId, customerId)
+            .eq(WarehouseEntity::getId, warehouseId)) > 0;
+    }
+
+    public WarehouseEntity findWarehouse(long customerId, long warehouseId) {
+        return warehouses.selectOne(new LambdaQueryWrapper<WarehouseEntity>()
+            .eq(WarehouseEntity::getCustomerId, customerId)
+            .eq(WarehouseEntity::getId, warehouseId));
+    }
+
+    public WarehouseLocationEntity findDefaultVirtualLocation(long customerId, long warehouseId) {
+        return locations.selectOne(new LambdaQueryWrapper<WarehouseLocationEntity>()
+            .eq(WarehouseLocationEntity::getCustomerId, customerId)
+            .eq(WarehouseLocationEntity::getWarehouseId, warehouseId)
+            .eq(WarehouseLocationEntity::getLocationType, "VIRTUAL")
+            .eq(WarehouseLocationEntity::getStatus, "ACTIVE")
+            .orderByAsc(WarehouseLocationEntity::getCreatedAt)
+            .last("LIMIT 1"));
+    }
+
+    public WarehouseLocationEntity findLocationByCode(long customerId, long warehouseId, String locationCode) {
+        return locations.selectOne(new LambdaQueryWrapper<WarehouseLocationEntity>()
+            .eq(WarehouseLocationEntity::getCustomerId, customerId)
+            .eq(WarehouseLocationEntity::getWarehouseId, warehouseId)
+            .eq(WarehouseLocationEntity::getLocationCode, locationCode));
+    }
+
+    public void insertLocation(WarehouseLocationEntity entity) {
+        locations.insert(entity);
+    }
+
+    public int insertDefaultVirtualLocationIgnore(WarehouseLocationEntity entity) {
+        return locations.insertDefaultVirtualLocationIgnore(entity);
+    }
+
+    public void updateLocation(WarehouseLocationEntity entity) {
+        locations.updateById(entity);
+    }
+
+    public WarehouseLocationEntity findLocation(long customerId, long warehouseId, long id) {
+        return locations.selectOne(new LambdaQueryWrapper<WarehouseLocationEntity>()
+            .eq(WarehouseLocationEntity::getCustomerId, customerId)
+            .eq(WarehouseLocationEntity::getWarehouseId, warehouseId)
+            .eq(WarehouseLocationEntity::getId, id));
+    }
+
+    public boolean locationCodeExists(long customerId, long warehouseId, String code, Long excludedId) {
+        return locations.selectCount(new LambdaQueryWrapper<WarehouseLocationEntity>()
+            .eq(WarehouseLocationEntity::getCustomerId, customerId)
+            .eq(WarehouseLocationEntity::getWarehouseId, warehouseId)
+            .eq(WarehouseLocationEntity::getLocationCode, code)
+            .ne(excludedId != null, WarehouseLocationEntity::getId, excludedId)) > 0;
+    }
+
+    public PageResult<WarehouseLocationEntity> pageLocations(long customerId, long warehouseId,
+                                                              LocationRequests.QueryRequest query) {
+        var wrapper = new LambdaQueryWrapper<WarehouseLocationEntity>()
+            .eq(WarehouseLocationEntity::getCustomerId, customerId)
+            .eq(WarehouseLocationEntity::getWarehouseId, warehouseId)
+            .eq(StringUtils.hasText(query.zoneCode()), WarehouseLocationEntity::getZoneCode, query.zoneCode())
+            .eq(StringUtils.hasText(query.locationType()), WarehouseLocationEntity::getLocationType, query.locationType())
+            .eq(StringUtils.hasText(query.status()), WarehouseLocationEntity::getStatus, query.status())
+            .and(StringUtils.hasText(query.keyword()), q -> q
+                .like(WarehouseLocationEntity::getLocationCode, query.keyword())
+                .or().like(WarehouseLocationEntity::getZoneCode, query.keyword()))
+            .orderByAsc(WarehouseLocationEntity::getZoneCode)
+            .orderByAsc(WarehouseLocationEntity::getLocationCode);
+        return PageResult.from(locations.selectPage(new Page<>(query.page(), query.size()), wrapper));
+    }
+
+    public void deleteLocation(long id) {
+        locations.deleteById(id);
+    }
+
+    public boolean locationHasPallets(long customerId, long warehouseId, long locationId) {
+        return pallets.selectCount(new LambdaQueryWrapper<WarehousePalletEntity>()
+            .eq(WarehousePalletEntity::getCustomerId, customerId)
+            .eq(WarehousePalletEntity::getWarehouseId, warehouseId)
+            .eq(WarehousePalletEntity::getLocationId, locationId)) > 0;
+    }
+
+    public void insertPallet(WarehousePalletEntity entity) {
+        pallets.insert(entity);
+    }
+
+    public void updatePallet(WarehousePalletEntity entity) {
+        pallets.updateById(entity);
+    }
+
+    public WarehousePalletEntity findPallet(long customerId, long warehouseId, long id) {
+        return pallets.selectOne(new LambdaQueryWrapper<WarehousePalletEntity>()
+            .eq(WarehousePalletEntity::getCustomerId, customerId)
+            .eq(WarehousePalletEntity::getWarehouseId, warehouseId)
+            .eq(WarehousePalletEntity::getId, id));
+    }
+
+    public boolean palletCodeExists(long customerId, long warehouseId, String code, Long excludedId) {
+        return pallets.selectCount(new LambdaQueryWrapper<WarehousePalletEntity>()
+            .eq(WarehousePalletEntity::getCustomerId, customerId)
+            .eq(WarehousePalletEntity::getWarehouseId, warehouseId)
+            .eq(WarehousePalletEntity::getPalletCode, code)
+            .ne(excludedId != null, WarehousePalletEntity::getId, excludedId)) > 0;
+    }
+
+    public PageResult<WarehousePalletEntity> pagePallets(long customerId, long warehouseId,
+                                                          PalletRequests.QueryRequest query) {
+        var wrapper = new LambdaQueryWrapper<WarehousePalletEntity>()
+            .eq(WarehousePalletEntity::getCustomerId, customerId)
+            .eq(WarehousePalletEntity::getWarehouseId, warehouseId)
+            .eq(StringUtils.hasText(query.palletType()), WarehousePalletEntity::getPalletType, query.palletType())
+            .eq(StringUtils.hasText(query.status()), WarehousePalletEntity::getStatus, query.status())
+            .eq(query.locationId() != null, WarehousePalletEntity::getLocationId, query.locationId())
+            .like(StringUtils.hasText(query.keyword()), WarehousePalletEntity::getPalletCode, query.keyword())
+            .orderByDesc(WarehousePalletEntity::getCreatedAt);
+        return PageResult.from(pallets.selectPage(new Page<>(query.page(), query.size()), wrapper));
+    }
+
+    public void deletePallet(long id) {
+        pallets.deleteById(id);
+    }
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/security/InternalServiceTokenGuard.java

@@ -0,0 +1,26 @@
+package com.baiyue.warehouse.security;
+
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.http.HttpStatus;
+import org.springframework.stereotype.Component;
+import org.springframework.web.server.ResponseStatusException;
+
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+
+@Component
+public class InternalServiceTokenGuard {
+    private final byte[] expected;
+
+    public InternalServiceTokenGuard(
+        @Value("${baiyue.internal-service.token:phase1-local-internal-token-at-least-32-bytes}") String token) {
+        this.expected = token.getBytes(StandardCharsets.UTF_8);
+    }
+
+    public void verify(String provided) {
+        byte[] actual = provided == null ? new byte[0] : provided.getBytes(StandardCharsets.UTF_8);
+        if (!MessageDigest.isEqual(expected, actual)) {
+            throw new ResponseStatusException(HttpStatus.UNAUTHORIZED, "Invalid internal service token");
+        }
+    }
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/service/WarehouseApplicationService.java

@@ -0,0 +1,176 @@
+package com.baiyue.warehouse.service;
+import jakarta.annotation.Resource;
+
+import com.baiyue.common.audit.BusinessAudit;
+import com.baiyue.common.core.api.PageResult;
+import com.baiyue.common.core.api.ResultCode;
+import com.baiyue.common.core.exception.BizException;
+import com.baiyue.warehouse.dto.WarehouseDetailResponse;
+import com.baiyue.warehouse.dto.WarehouseRequests;
+import com.baiyue.warehouse.entity.ServiceCapabilityEntity;
+import com.baiyue.warehouse.entity.WarehouseAddressEntity;
+import com.baiyue.warehouse.entity.WarehouseEntity;
+import com.baiyue.warehouse.entity.WarehouseLocationEntity;
+import com.baiyue.warehouse.repository.WarehouseRepository;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.List;
+import java.math.BigDecimal;
+
+/**
+ * 仓库应用服务，负责仓库主数据、地址和服务能力的租户级用例编排、事务控制与业务校验。
+ */
+@Service
+public class WarehouseApplicationService {
+    @Resource
+    private WarehouseRepository repository;
+
+
+    @Transactional
+    @BusinessAudit(
+        event = "WAREHOUSE_CREATE",
+        resourceType = "WAREHOUSE",
+        resourceId = "#r.warehouseCode",
+        description = "新建仓库",
+        captureBefore = false
+    )
+    public Long create(WarehouseRequests.SaveRequest request) {
+        ensureCodeUnique(request.customerId(), request.warehouseCode(), null);
+        WarehouseEntity warehouse = toEntity(request);
+        repository.insertWarehouse(warehouse);
+        ensureDefaultVirtualLocation(warehouse);
+        insertChildren(warehouse.getCustomerId(), warehouse.getId(), request.address(), request.capabilities());
+        return warehouse.getId();
+    }
+
+    private void ensureDefaultVirtualLocation(WarehouseEntity warehouse) {
+        String locationCode = "LOC-" + warehouse.getWarehouseCode() + "-DEFAULT";
+        if (repository.existsLocationCode(warehouse.getCustomerId(), warehouse.getId(), locationCode)) {
+            return;
+        }
+        WarehouseLocationEntity location = new WarehouseLocationEntity();
+        location.setCustomerId(warehouse.getCustomerId());
+        location.setWarehouseId(warehouse.getId());
+        location.setZoneCode("DEFAULT");
+        location.setLocationCode(locationCode);
+        location.setLocationType("VIRTUAL");
+        location.setMaxLoadKg(new BigDecimal("999999999.000"));
+        location.setStatus("ACTIVE");
+        location.setRemark("System default virtual location");
+        repository.insertLocation(location);
+    }
+
+    @Transactional
+    @BusinessAudit(
+        event = "WAREHOUSE_UPDATE",
+        resourceType = "WAREHOUSE",
+        resourceId = "#id",
+        description = "更新仓库"
+    )
+    public void update(long customerId, long id, WarehouseRequests.SaveRequest request) {
+        if (request.customerId() == null || customerId != request.customerId()) {
+            throw new BizException(ResultCode.FORBIDDEN, "租户不匹配");
+        }
+        WarehouseEntity old = owned(customerId, id);
+        ensureCodeUnique(customerId, request.warehouseCode(), id);
+
+        WarehouseEntity warehouse = toEntity(request);
+        warehouse.setId(old.getId());
+        repository.saveWarehouse(warehouse);
+
+        repository.physicallyDeleteChildren(customerId, id);
+        insertChildren(customerId, id, request.address(), request.capabilities());
+    }
+
+    public PageResult<WarehouseEntity> page(long customerId, WarehouseRequests.QueryRequest query) {
+        return repository.page(customerId, query);
+    }
+
+    public WarehouseDetailResponse detail(long customerId, long id) {
+        WarehouseEntity warehouse = owned(customerId, id);
+        List<WarehouseAddressEntity> addresses = repository.findAddresses(customerId, id);
+        List<ServiceCapabilityEntity> capabilities = repository.findCapabilities(customerId, id);
+        return new WarehouseDetailResponse(warehouse, addresses, capabilities);
+    }
+
+    @Transactional
+    @BusinessAudit(
+        event = "WAREHOUSE_STATUS_CHANGE",
+        resourceType = "WAREHOUSE",
+        resourceId = "#id",
+        description = "启用或停用仓库"
+    )
+    public void changeStatus(long customerId, long id, String status) {
+        if (!"ACTIVE".equals(status) && !"INACTIVE".equals(status)) {
+            throw new BizException("无效状态");
+        }
+        WarehouseEntity warehouse = owned(customerId, id);
+        warehouse.setStatus(status);
+        repository.saveWarehouse(warehouse);
+    }
+
+    private WarehouseEntity owned(long customerId, long id) {
+        WarehouseEntity warehouse = repository.findOwned(customerId, id);
+        if (warehouse == null) {
+            throw new BizException(ResultCode.NOT_FOUND, "仓库不存在");
+        }
+        return warehouse;
+    }
+
+    private void ensureCodeUnique(long customerId, String code, Long excludedId) {
+        if (repository.existsCode(customerId, code, excludedId)) {
+            throw new BizException(ResultCode.CONFLICT, "仓库编码已存在");
+        }
+    }
+
+    private WarehouseEntity toEntity(WarehouseRequests.SaveRequest request) {
+        WarehouseEntity warehouse = new WarehouseEntity();
+        warehouse.setCustomerId(request.customerId());
+        warehouse.setWarehouseCode(request.warehouseCode());
+        warehouse.setWarehouseName(request.warehouseName());
+        warehouse.setWarehouseType(request.warehouseType());
+        warehouse.setCountryCode(request.countryCode());
+        warehouse.setTimezone(request.timezone());
+        warehouse.setContactName(request.contactName());
+        warehouse.setContactPhone(request.contactPhone());
+        warehouse.setContactEmail(request.contactEmail());
+        warehouse.setStatus(request.status());
+        warehouse.setRemark(request.remark());
+        return warehouse;
+    }
+
+    private void insertChildren(long customerId, long warehouseId,
+                                WarehouseRequests.AddressRequest address,
+                                List<WarehouseRequests.CapabilityRequest> requestedCapabilities) {
+        WarehouseAddressEntity addressEntity = new WarehouseAddressEntity();
+        addressEntity.setCustomerId(customerId);
+        addressEntity.setWarehouseId(warehouseId);
+        addressEntity.setAddressType(address.addressType());
+        addressEntity.setCountryCode(address.countryCode());
+        addressEntity.setStateProvince(address.stateProvince());
+        addressEntity.setCity(address.city());
+        addressEntity.setDistrict(address.district());
+        addressEntity.setPostalCode(address.postalCode());
+        addressEntity.setAddressLine1(address.addressLine1());
+        addressEntity.setAddressLine2(address.addressLine2());
+        addressEntity.setLatitude(address.latitude());
+        addressEntity.setLongitude(address.longitude());
+        repository.insertAddress(addressEntity);
+
+        if (requestedCapabilities == null) {
+            return;
+        }
+        for (WarehouseRequests.CapabilityRequest capability : requestedCapabilities) {
+            ServiceCapabilityEntity entity = new ServiceCapabilityEntity();
+            entity.setCustomerId(customerId);
+            entity.setWarehouseId(warehouseId);
+            entity.setCapabilityCode(capability.capabilityCode());
+            entity.setCapabilityName(capability.capabilityName());
+            entity.setEnabled(capability.enabled() == null || capability.enabled());
+            entity.setCutoffTime(capability.cutoffTime());
+            entity.setDescription(capability.description());
+            repository.insertCapability(entity);
+        }
+    }
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/service/WarehouseResourceLockService.java

@@ -0,0 +1,158 @@
+package com.baiyue.warehouse.service;
+
+import com.baiyue.common.core.api.ResultCode;
+import com.baiyue.common.core.exception.BizException;
+import com.baiyue.warehouse.dto.WarehouseResourceLockRequests;
+import com.baiyue.warehouse.dto.WarehouseResourceLockResponse;
+import com.baiyue.warehouse.dto.WarehousePalletScrapResponse;
+import com.baiyue.warehouse.entity.WarehouseLocationEntity;
+import com.baiyue.warehouse.entity.WarehousePalletEntity;
+import com.baiyue.warehouse.entity.WarehouseResourceLockEntity;
+import com.baiyue.warehouse.repository.WarehouseResourceLockRepository;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Isolation;
+import org.springframework.transaction.annotation.Transactional;
+import jakarta.annotation.Resource;
+
+import java.time.LocalDateTime;
+import java.util.Objects;
+
+@Service
+public class WarehouseResourceLockService {
+    @Resource private WarehouseResourceLockRepository repository;
+
+    @Transactional(isolation = Isolation.READ_COMMITTED)
+    public WarehouseResourceLockResponse reserve(WarehouseResourceLockRequests.ReserveRequest request) {
+        WarehouseResourceLockEntity existing = repository.findByReservationKey(request.customerId(), request.reservationKey());
+        if (existing != null) return idempotentResult(existing, request);
+
+        WarehousePalletEntity pallet = repository.findPallet(request.customerId(), request.warehouseId(), request.palletId());
+        WarehouseLocationEntity location = repository.findLocation(request.customerId(), request.warehouseId(), request.locationId());
+        if (pallet == null || location == null) {
+            WarehouseResourceLockEntity concurrent =
+                repository.findByReservationKey(request.customerId(), request.reservationKey());
+            if (concurrent != null) return idempotentResult(concurrent, request);
+            throw new BizException(ResultCode.NOT_FOUND, "Pallet or location does not belong to the tenant warehouse");
+        }
+        boolean virtualLocation = isVirtual(location);
+        boolean locationAvailable = virtualLocation ? "ACTIVE".equals(location.getStatus()) : "IDLE".equals(location.getStatus());
+        if (!"IDLE".equals(pallet.getStatus()) || !locationAvailable) {
+            WarehouseResourceLockEntity concurrent =
+                repository.findByReservationKey(request.customerId(), request.reservationKey());
+            if (concurrent != null) return idempotentResult(concurrent, request);
+            throw new BizException(ResultCode.CONFLICT, "Only IDLE pallet and location can be reserved");
+        }
+        if (repository.occupyPallet(request.customerId(), request.warehouseId(), request.palletId(), request.locationId()) != 1) {
+            return concurrentIdempotentOrConflict(request);
+        }
+        if (!virtualLocation && repository.occupyLocation(request.customerId(), request.warehouseId(), request.locationId()) != 1) {
+            throw new BizException(ResultCode.CONFLICT, "Location is no longer IDLE");
+        }
+
+        WarehouseResourceLockEntity lock = new WarehouseResourceLockEntity();
+        lock.setCustomerId(request.customerId());
+        lock.setWarehouseId(request.warehouseId());
+        lock.setPalletId(request.palletId());
+        lock.setLocationId(request.locationId());
+        lock.setBusinessType(request.businessType());
+        lock.setBusinessId(request.businessId());
+        lock.setReservationKey(request.reservationKey());
+        lock.setStatus("ACTIVE");
+        lock.setLockedAt(LocalDateTime.now());
+        repository.insert(lock);
+        return WarehouseResourceLockResponse.from(lock);
+    }
+
+    @Transactional
+    public WarehouseResourceLockResponse release(long customerId, long lockId) {
+        WarehouseResourceLockEntity lock = requireLock(customerId, lockId);
+        if ("RELEASED".equals(lock.getStatus())) return WarehouseResourceLockResponse.from(lock);
+        requireActive(lock);
+        boolean virtualLocation = isVirtualLockLocation(lock);
+        int palletResult = virtualLocation ? repository.releasePalletAtVirtualLocation(lock) : repository.releasePallet(lock);
+        if (palletResult != 1 || (!virtualLocation && repository.releaseLocation(lock) != 1)
+            || repository.close(lock, "RELEASED") != 1) {
+            throw new BizException(ResultCode.CONFLICT, "Resource lock state changed concurrently");
+        }
+        lock.setStatus("RELEASED");
+        lock.setReleasedAt(LocalDateTime.now());
+        return WarehouseResourceLockResponse.from(lock);
+    }
+
+    @Transactional
+    public WarehouseResourceLockResponse scrap(long customerId, long lockId) {
+        WarehouseResourceLockEntity lock = requireLock(customerId, lockId);
+        if ("SCRAPPED".equals(lock.getStatus())) return WarehouseResourceLockResponse.from(lock);
+        requireActive(lock);
+        boolean virtualLocation = isVirtualLockLocation(lock);
+        int palletResult = virtualLocation ? repository.scrapPalletAtVirtualLocation(lock) : repository.scrapPallet(lock);
+        if (palletResult != 1 || (!virtualLocation && repository.releaseLocation(lock) != 1)
+            || repository.close(lock, "SCRAPPED") != 1) {
+            throw new BizException(ResultCode.CONFLICT, "Resource lock state changed concurrently");
+        }
+        lock.setStatus("SCRAPPED");
+        lock.setReleasedAt(LocalDateTime.now());
+        return WarehouseResourceLockResponse.from(lock);
+    }
+
+    @Transactional
+    public WarehousePalletScrapResponse scrapByPallet(long customerId, long palletId) {
+        WarehousePalletEntity pallet = repository.findPallet(customerId, palletId);
+        if (pallet == null) throw new BizException(ResultCode.NOT_FOUND, "Pallet not found");
+        if ("SCRAPPED".equals(pallet.getStatus())) {
+            return new WarehousePalletScrapResponse(palletId, pallet.getWarehouseId(), pallet.getLocationId(), "SCRAPPED");
+        }
+        if (!"OCCUPIED".equals(pallet.getStatus())) {
+            throw new BizException(ResultCode.CONFLICT, "Only an OCCUPIED pallet can be scrapped after shipment");
+        }
+        WarehouseResourceLockEntity lock = repository.findActiveByPallet(customerId, palletId);
+        if (lock != null) {
+            scrap(customerId, lock.getId());
+        } else if (repository.scrapPalletWithoutLock(customerId, palletId) != 1) {
+            throw new BizException(ResultCode.CONFLICT, "Pallet state changed concurrently");
+        }
+        return new WarehousePalletScrapResponse(palletId, pallet.getWarehouseId(), pallet.getLocationId(), "SCRAPPED");
+    }
+
+    private WarehouseResourceLockResponse concurrentIdempotentOrConflict(
+        WarehouseResourceLockRequests.ReserveRequest request) {
+        WarehouseResourceLockEntity existing = repository.findByReservationKey(request.customerId(), request.reservationKey());
+        if (existing != null) return idempotentResult(existing, request);
+        throw new BizException(ResultCode.CONFLICT, "Pallet is no longer IDLE");
+    }
+
+    private WarehouseResourceLockResponse idempotentResult(WarehouseResourceLockEntity existing,
+                                                            WarehouseResourceLockRequests.ReserveRequest request) {
+        if (existing.getWarehouseId() != request.warehouseId()
+            || existing.getPalletId() != request.palletId()
+            || existing.getLocationId() != request.locationId()
+            || !Objects.equals(existing.getBusinessType(), request.businessType())
+            || !Objects.equals(existing.getBusinessId(), request.businessId())) {
+            throw new BizException(ResultCode.CONFLICT, "Reservation key was already used with different resources");
+        }
+        return WarehouseResourceLockResponse.from(existing);
+    }
+
+    private WarehouseResourceLockEntity requireLock(long customerId, long lockId) {
+        WarehouseResourceLockEntity lock = repository.find(customerId, lockId);
+        if (lock == null) throw new BizException(ResultCode.NOT_FOUND, "Resource lock not found");
+        return lock;
+    }
+
+    private static void requireActive(WarehouseResourceLockEntity lock) {
+        if (!"ACTIVE".equals(lock.getStatus())) {
+            throw new BizException(ResultCode.CONFLICT, "Resource lock is not ACTIVE");
+        }
+    }
+
+
+    private boolean isVirtualLockLocation(WarehouseResourceLockEntity lock) {
+        WarehouseLocationEntity location = repository.findLocation(lock.getCustomerId(), lock.getWarehouseId(), lock.getLocationId());
+        if (location == null) throw new BizException(ResultCode.NOT_FOUND, "Resource lock location not found");
+        return isVirtual(location);
+    }
+
+    private static boolean isVirtual(WarehouseLocationEntity location) {
+        return "VIRTUAL".equals(location.getLocationType());
+    }
+}

warehouse-overseas-service/src/main/java/com/baiyue/warehouse/service/WarehouseResourceService.java

@@ -0,0 +1,282 @@
+package com.baiyue.warehouse.service;
+
+import com.baiyue.common.core.api.PageResult;
+import com.baiyue.common.core.api.ResultCode;
+import com.baiyue.common.core.exception.BizException;
+import com.baiyue.warehouse.dto.LocationRequests;
+import com.baiyue.warehouse.dto.PalletRequests;
+import com.baiyue.warehouse.entity.WarehouseLocationEntity;
+import com.baiyue.warehouse.entity.WarehousePalletEntity;
+import com.baiyue.warehouse.entity.WarehouseEntity;
+import com.baiyue.warehouse.entity.WarehousePalletBindingEntity;
+import com.baiyue.warehouse.repository.WarehouseResourceRepository;
+import com.baomidou.mybatisplus.core.toolkit.IdWorker;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+import jakarta.annotation.Resource;
+
+import java.util.Set;
+import java.time.LocalDate;
+import java.time.format.DateTimeFormatter;
+import org.springframework.util.StringUtils;
+
+@Service
+public class WarehouseResourceService {
+    private static final Set<String> LOCATION_STATUSES = Set.of("ACTIVE", "IDLE", "OCCUPIED", "INACTIVE");
+    private static final Set<String> PALLET_STATUSES = Set.of("IDLE", "OCCUPIED", "SCRAPPED");
+
+    @Resource private WarehouseResourceRepository repository;
+
+    @Transactional
+    public Long createLocation(long customerId, long warehouseId, LocationRequests.SaveRequest request) {
+        requireWarehouse(customerId, warehouseId);
+        validateLocation(request, customerId, warehouseId, null);
+        WarehouseLocationEntity entity = locationEntity(customerId, warehouseId, request);
+        repository.insertLocation(entity);
+        return entity.getId();
+    }
+
+    @Transactional
+    public void updateLocation(long customerId, long warehouseId, long id, LocationRequests.SaveRequest request) {
+        WarehouseLocationEntity existing = requireLocation(customerId, warehouseId, id);
+        if ("VIRTUAL".equals(existing.getLocationType())
+            && (!"VIRTUAL".equals(request.locationType()) || !"ACTIVE".equals(request.status())
+                || !existing.getLocationCode().equals(request.locationCode()))) {
+            throw new BizException(ResultCode.CONFLICT, "Default virtual location must remain VIRTUAL and ACTIVE");
+        }
+        validateLocation(request, customerId, warehouseId, id);
+        WarehouseLocationEntity entity = locationEntity(customerId, warehouseId, request);
+        entity.setId(existing.getId());
+        repository.updateLocation(entity);
+    }
+
+    public WarehouseLocationEntity location(long customerId, long warehouseId, long id) {
+        requireWarehouse(customerId, warehouseId);
+        return requireLocation(customerId, warehouseId, id);
+    }
+
+    public PageResult<WarehouseLocationEntity> locations(long customerId, long warehouseId,
+                                                          LocationRequests.QueryRequest query) {
+        requireWarehouse(customerId, warehouseId);
+        return repository.pageLocations(customerId, warehouseId, query);
+    }
+
+    @Transactional
+    public void deleteLocation(long customerId, long warehouseId, long id) {
+        WarehouseLocationEntity location = requireLocation(customerId, warehouseId, id);
+        if ("VIRTUAL".equals(location.getLocationType())) {
+            throw new BizException(ResultCode.CONFLICT, "Default virtual location cannot be deleted");
+        }
+        if (repository.locationHasPallets(customerId, warehouseId, id)) {
+            throw new BizException(ResultCode.CONFLICT, "库位仍绑定托盘，不能删除");
+        }
+        repository.deleteLocation(id);
+    }
+
+    @Transactional
+    public Long createPallet(long customerId, long warehouseId, PalletRequests.SaveRequest request) {
+        WarehouseEntity warehouse = requireWarehouseEntity(customerId, warehouseId);
+        validatePalletStatus(request.status());
+        Long palletId = IdWorker.getId();
+        String palletCode = StringUtils.hasText(request.palletCode()) ? request.palletCode().trim()
+            : generatedPalletCode(warehouse.getWarehouseCode(), palletId);
+        Long locationId = request.locationId();
+        if (locationId == null) {
+            locationId = ensureDefaultVirtualLocation(customerId, warehouseId).getId();
+        }
+        validatePallet(request, palletCode, locationId, customerId, warehouseId, null);
+        WarehousePalletEntity entity = palletEntity(customerId, warehouseId, request, palletCode, locationId);
+        entity.setId(palletId);
+        repository.insertPallet(entity);
+        return entity.getId();
+    }
+
+    @Transactional
+    public WarehousePalletEntity ensureDropshipPallet(long customerId, long warehouseId, String businessId) {
+        WarehousePalletBindingEntity existing = repository.findPalletBinding(customerId, warehouseId, "DROPSHIP", businessId);
+        if (existing != null) return requirePallet(customerId, warehouseId, existing.getPalletId());
+        Long palletId = createPallet(customerId, warehouseId,
+            new PalletRequests.SaveRequest(null, "DROPSHIP", null, java.math.BigDecimal.ZERO, "IDLE", null,
+                "Default dropship pallet for " + businessId));
+        WarehousePalletBindingEntity binding = new WarehousePalletBindingEntity();
+        binding.setId(IdWorker.getId()); binding.setCustomerId(customerId); binding.setWarehouseId(warehouseId);
+        binding.setBusinessType("DROPSHIP"); binding.setBusinessId(businessId); binding.setPalletId(palletId);
+        binding.setCreatedAt(java.time.LocalDateTime.now());
+        try {
+            repository.insertPalletBinding(binding);
+            return requirePallet(customerId, warehouseId, palletId);
+        } catch (org.springframework.dao.DuplicateKeyException duplicate) {
+            WarehousePalletBindingEntity winner = repository.findPalletBinding(customerId, warehouseId, "DROPSHIP", businessId);
+            if (winner == null) throw duplicate;
+            return requirePallet(customerId, warehouseId, winner.getPalletId());
+        }
+    }
+
+    /**
+     * Returns the warehouse-scoped virtual location used only as a pallet/inventory reference.
+     * It is deliberately never made IDLE/OCCUPIED by resource locking.
+     */
+    @Transactional
+    public WarehouseLocationEntity ensureDefaultVirtualLocation(long customerId, long warehouseId) {
+        WarehouseEntity warehouse = requireWarehouseEntity(customerId, warehouseId);
+        String locationCode = defaultLocationCode(warehouse.getWarehouseCode());
+        WarehouseLocationEntity existing = repository.findLocationByCode(customerId, warehouseId, locationCode);
+        if (existing != null) {
+            if (!"VIRTUAL".equals(existing.getLocationType()) || !"ACTIVE".equals(existing.getStatus())) {
+                throw new BizException(ResultCode.CONFLICT,
+                    "Default virtual location code is occupied by a non-active virtual location");
+            }
+            return existing;
+        }
+
+        WarehouseLocationEntity location = new WarehouseLocationEntity();
+        location.setId(IdWorker.getId());
+        location.setCustomerId(customerId);
+        location.setWarehouseId(warehouseId);
+        location.setZoneCode("DEFAULT");
+        location.setLocationCode(locationCode);
+        location.setLocationType("VIRTUAL");
+        location.setMaxLoadKg(new java.math.BigDecimal("999999999.000"));
+        location.setStatus("ACTIVE");
+        location.setRemark("System default virtual location");
+        repository.insertDefaultVirtualLocationIgnore(location);
+
+        WarehouseLocationEntity resolved = repository.findLocationByCode(customerId, warehouseId, locationCode);
+        if (resolved == null) {
+            throw new BizException(ResultCode.CONFLICT, "Default virtual location could not be created");
+        }
+        return resolved;
+    }
+
+    @Transactional
+    public void updatePallet(long customerId, long warehouseId, long id, PalletRequests.SaveRequest request) {
+        WarehousePalletEntity existing = requirePallet(customerId, warehouseId, id);
+        if ("SCRAPPED".equals(existing.getStatus()) && !"SCRAPPED".equals(request.status())) {
+            throw new BizException(ResultCode.CONFLICT, "SCRAPPED pallet cannot be reused");
+        }
+        String palletCode = StringUtils.hasText(request.palletCode()) ? request.palletCode().trim()
+            : existing.getPalletCode();
+        Long locationId = request.locationId() == null ? existing.getLocationId() : request.locationId();
+        validatePallet(request, palletCode, locationId, customerId, warehouseId, id);
+        WarehousePalletEntity entity = palletEntity(customerId, warehouseId, request, palletCode, locationId);
+        entity.setId(existing.getId());
+        repository.updatePallet(entity);
+    }
+
+    public WarehousePalletEntity pallet(long customerId, long warehouseId, long id) {
+        requireWarehouse(customerId, warehouseId);
+        return requirePallet(customerId, warehouseId, id);
+    }
+
+    public PageResult<WarehousePalletEntity> pallets(long customerId, long warehouseId,
+                                                      PalletRequests.QueryRequest query) {
+        requireWarehouse(customerId, warehouseId);
+        return repository.pagePallets(customerId, warehouseId, query);
+    }
+
+    @Transactional
+    public void deletePallet(long customerId, long warehouseId, long id) {
+        WarehousePalletEntity pallet = requirePallet(customerId, warehouseId, id);
+        if ("OCCUPIED".equals(pallet.getStatus())) {
+            throw new BizException(ResultCode.CONFLICT, "占用中的托盘不能删除");
+        }
+        if ("SCRAPPED".equals(pallet.getStatus())) {
+            throw new BizException(ResultCode.CONFLICT, "Scrapped pallet must be retained and cannot be reused");
+        }
+        repository.deletePallet(id);
+    }
+
+    private void requireWarehouse(long customerId, long warehouseId) {
+        if (!repository.warehouseOwned(customerId, warehouseId)) {
+            throw new BizException(ResultCode.NOT_FOUND, "当前租户下仓库不存在");
+        }
+    }
+
+    private WarehouseEntity requireWarehouseEntity(long customerId, long warehouseId) {
+        WarehouseEntity warehouse = repository.findWarehouse(customerId, warehouseId);
+        if (warehouse == null) {
+            throw new BizException(ResultCode.NOT_FOUND, "Tenant warehouse not found");
+        }
+        return warehouse;
+    }
+
+    private WarehouseLocationEntity requireLocation(long customerId, long warehouseId, long id) {
+        requireWarehouse(customerId, warehouseId);
+        WarehouseLocationEntity entity = repository.findLocation(customerId, warehouseId, id);
+        if (entity == null) throw new BizException(ResultCode.NOT_FOUND, "当前仓库下库位不存在");
+        return entity;
+    }
+
+    private WarehousePalletEntity requirePallet(long customerId, long warehouseId, long id) {
+        requireWarehouse(customerId, warehouseId);
+        WarehousePalletEntity entity = repository.findPallet(customerId, warehouseId, id);
+        if (entity == null) throw new BizException(ResultCode.NOT_FOUND, "当前仓库下托盘不存在");
+        return entity;
+    }
+
+    private void validateLocation(LocationRequests.SaveRequest request, long customerId,
+                                  long warehouseId, Long excludedId) {
+        if (!LOCATION_STATUSES.contains(request.status())) {
+            throw new BizException("库位状态仅支持 ACTIVE、IDLE、OCCUPIED、INACTIVE");
+        }
+        if (repository.locationCodeExists(customerId, warehouseId, request.locationCode(), excludedId)) {
+            throw new BizException(ResultCode.CONFLICT, "当前仓库下库位编码已存在");
+        }
+    }
+
+    private void validatePallet(PalletRequests.SaveRequest request, String palletCode, Long locationId,
+                                long customerId, long warehouseId, Long excludedId) {
+        validatePalletStatus(request.status());
+        if (repository.palletCodeExists(customerId, warehouseId, palletCode, excludedId)) {
+            throw new BizException(ResultCode.CONFLICT, "当前仓库下托盘编码已存在");
+        }
+        if (locationId != null) {
+            requireLocation(customerId, warehouseId, locationId);
+        }
+    }
+
+    private void validatePalletStatus(String status) {
+        if (!PALLET_STATUSES.contains(status)) {
+            throw new BizException("托盘状态仅支持 IDLE、OCCUPIED、SCRAPPED");
+        }
+    }
+
+    private WarehouseLocationEntity locationEntity(long customerId, long warehouseId,
+                                                     LocationRequests.SaveRequest request) {
+        WarehouseLocationEntity entity = new WarehouseLocationEntity();
+        entity.setCustomerId(customerId);
+        entity.setWarehouseId(warehouseId);
+        entity.setZoneCode(request.zoneCode());
+        entity.setLocationCode(request.locationCode());
+        entity.setLocationType(request.locationType());
+        entity.setMaxLoadKg(request.maxLoadKg());
+        entity.setStatus(request.status());
+        entity.setRemark(request.remark());
+        return entity;
+    }
+
+    private WarehousePalletEntity palletEntity(long customerId, long warehouseId,
+                                                 PalletRequests.SaveRequest request,
+                                                 String palletCode, Long locationId) {
+        WarehousePalletEntity entity = new WarehousePalletEntity();
+        entity.setCustomerId(customerId);
+        entity.setWarehouseId(warehouseId);
+        entity.setLocationId(locationId);
+        entity.setPalletCode(palletCode);
+        entity.setPalletType(request.palletType());
+        entity.setCapacityCbm(request.capacityCbm());
+        entity.setUnitPrice(request.unitPrice());
+        entity.setStatus(request.status());
+        entity.setRemark(request.remark());
+        return entity;
+    }
+
+    private static String generatedPalletCode(String warehouseCode, long palletId) {
+        return "PLT-" + warehouseCode + "-" + LocalDate.now().format(DateTimeFormatter.BASIC_ISO_DATE)
+            + "-" + Long.toUnsignedString(palletId);
+    }
+
+    private static String defaultLocationCode(String warehouseCode) {
+        return "LOC-" + warehouseCode + "-DEFAULT";
+    }
+}