feat(lastleg): add direct inventory balance detail

lastleg-service/src/test/java/com/baiyue/lastleg/inventory/query/InventoryBalanceDetailContractTest.java

@@ -0,0 +1,67 @@
+package com.baiyue.lastleg.inventory.query;
+
+import com.baiyue.common.web.LongIdJacksonConfiguration;
+import com.baiyue.lastleg.inventory.query.controller.InventoryQueryController;
+import com.baiyue.lastleg.inventory.query.dto.InventoryBalanceView;
+import com.baiyue.lastleg.security.OverseasPermissions;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.autoconfigure.AutoConfigurations;
+import org.springframework.boot.autoconfigure.jackson.JacksonAutoConfiguration;
+import org.springframework.boot.test.context.runner.ApplicationContextRunner;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.web.bind.annotation.GetMapping;
+
+import java.nio.charset.StandardCharsets;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class InventoryBalanceDetailContractTest {
+    private static final long BALANCE_ID = 19_000_000_000_000_001L;
+    private static final long INBOUND_ORDER_ID = 19_000_000_000_000_002L;
+
+    @Test
+    void controllerFreezesDetailPathAndInventoryListPermission() throws Exception {
+        var method = InventoryQueryController.class.getMethod("balance",
+            com.baiyue.common.security.AuthenticatedUser.class, long.class, String.class);
+        GetMapping mapping = method.getAnnotation(GetMapping.class);
+        PreAuthorize permission = method.getAnnotation(PreAuthorize.class);
+
+        assertNotNull(mapping);
+        assertEquals("/api/platform/v1/last-leg/inventory/balances/{balanceId}", mapping.value()[0]);
+        assertNotNull(permission);
+        assertTrue(permission.value().contains(OverseasPermissions.INVENTORY_LIST));
+    }
+
+    @Test
+    void openApiDefinesDirectDetailResponseAndStringLongIds() throws Exception {
+        String yaml;
+        try (var stream = getClass().getClassLoader().getResourceAsStream("openapi/overseas-business-v1.yaml")) {
+            assertNotNull(stream);
+            yaml = new String(stream.readAllBytes(), StandardCharsets.UTF_8);
+        }
+
+        assertTrue(yaml.contains("/api/platform/v1/last-leg/inventory/balances/{balanceId}:"));
+        assertTrue(yaml.contains("$ref: '#/components/schemas/InventoryBalanceApiResponse'"));
+        assertTrue(yaml.contains("id: { type: string, pattern: '^[1-9][0-9]*$'"));
+    }
+
+    @Test
+    void balanceAndInboundOrderIdsSerializeAsJsonStrings() {
+        new ApplicationContextRunner().withConfiguration(AutoConfigurations.of(
+            JacksonAutoConfiguration.class, LongIdJacksonConfiguration.class)).run(context -> {
+                ObjectMapper mapper = context.getBean(ObjectMapper.class);
+                InventoryBalanceView view = new InventoryBalanceView(BALANCE_ID, "100", "Customer", "900",
+                    "US-LAX-01", "Los Angeles", "800", "ONT8", "ONT8", INBOUND_ORDER_ID,
+                    "IBP-1", "RK-1", "SKU-1", "产品", "Product", 3, 3, 0, 0, 0, 0, 0, 0, null);
+
+                JsonNode json = mapper.readTree(mapper.writeValueAsString(view));
+
+                assertEquals(Long.toString(BALANCE_ID), json.path("id").textValue());
+                assertEquals(Long.toString(INBOUND_ORDER_ID), json.path("inboundOrderId").textValue());
+            });
+    }
+}

lastleg-service/src/test/java/com/baiyue/lastleg/inventory/query/controller/InventoryQueryControllerTest.java

@@ -34,6 +34,20 @@ class InventoryQueryControllerTest {
         verify(service).balances(eq("10001"), eq(query));
     }
 
+    @Test
+    void platformBalanceDetailQueriesByIdWithoutPaging() {
+        controller.balance(user(0L, "PLATFORM"), 9007199254740993L, null);
+
+        verify(service).balance(null, 9007199254740993L);
+    }
+
+    @Test
+    void platformBalanceDetailUsesExplicitCustomerScope() {
+        controller.balance(user(0L, "PLATFORM"), 99L, " 10001 ");
+
+        verify(service).balance("10001", 99L);
+    }
+
     @Test
     void merchantCannotUsePlatformInventoryController() {
         assertThrows(ResponseStatusException.class,

lastleg-service/src/test/java/com/baiyue/lastleg/inventory/query/service/InventoryQueryServiceTest.java

@@ -19,6 +19,7 @@ import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyLong;
 import static org.mockito.ArgumentMatchers.eq;
 import static org.mockito.Mockito.mock;
 import static org.mockito.Mockito.never;
@@ -115,6 +116,32 @@ class InventoryQueryServiceTest {
         verify(mapper).countBalances(null, query);
     }
 
+    @Test
+    void platformBalanceDetailReadsOneVisibleBalanceWithoutPaging() {
+        InventoryBalance balance = new InventoryBalance();
+        balance.setId(99L);
+        balance.setCustomerId("200");
+        balance.setAvailablePackages(3L);
+        when(mapper.visibleBalance(99L)).thenReturn(balance);
+
+        var result = service.balance(null, 99L);
+
+        assertEquals(99L, result.id());
+        assertEquals("200", result.customerId());
+        assertEquals(3L, result.totalPackages());
+        verify(mapper).visibleBalance(99L);
+        verify(mapper, never()).countBalances(any(), any());
+        verify(mapper, never()).balances(any(), any(), anyLong(), anyLong());
+    }
+
+    @Test
+    void scopedBalanceDetailDoesNotLeakAnotherCustomer() {
+        assertThrows(ResponseStatusException.class, () -> service.balance("100", 99L));
+
+        verify(mapper).ownedVisibleBalance("100", 99L);
+        verify(mapper, never()).visibleBalance(99L);
+    }
+
     @Test
     void unknownStatusIsRejectedBeforeDatabaseQuery() {
         InventoryQueryRequests.BalanceQuery query = balanceQuery("DAMAGED");