优化

finance/src/test/java/com/baiyue/finance/FinancePhase1OperationBehaviorTest.java

@@ -18,6 +18,9 @@ import org.springframework.jdbc.core.RowMapper;
 import java.math.BigDecimal;
 import java.sql.ResultSet;
 import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.List;
 import java.util.Set;
 import java.util.concurrent.atomic.AtomicInteger;
@@ -29,6 +32,7 @@ import static org.mockito.ArgumentMatchers.anyString;
 import static org.mockito.ArgumentMatchers.eq;
 import static org.mockito.ArgumentMatchers.startsWith;
 import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.lenient;
 import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;
 
@@ -67,16 +71,46 @@ class FinancePhase1OperationBehaviorTest {
 
     @Test
     void ledgerRejectsInvalidCustomerBeforeAnyQuery() {
-        FinancePhase1OperationService service = new FinancePhase1OperationService(mock(JdbcTemplate.class), new ObjectMapper());
+        FinancePhase1OperationService service = new FinancePhase1OperationService(mock(JdbcTemplate.class), objectMapper());
         assertThatThrownBy(() -> service.listDerivedCustomerAccountLedger(0, 1, 20, null, null, null))
             .isInstanceOf(FinanceEventException.class)
             .extracting(error -> ((FinanceEventException) error).code()).isEqualTo("FIN-REQ-400");
     }
 
+    @Test
+    void accountListReturnsFixedPagedDto() {
+        AccountJdbc jdbc = new AccountJdbc();
+        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, objectMapper());
+
+        PageEnvelope<FinancePhase1Dtos.AccountSummary> result =
+            service.listDerivedCustomerAccounts(1, 20, "客户9", "ACTIVE");
+
+        assertThat(result.data()).singleElement().satisfies(account -> {
+            assertThat(account.customerId()).isEqualTo(9L);
+            assertThat(account.customerName()).isEqualTo("客户9");
+            assertThat(account.outstandingReceivable()).isEqualByComparingTo("100.00");
+        });
+        assertThat(result.page().total()).isEqualTo(1);
+        assertThat(result.requestId()).isNotBlank();
+        assertThat(result.traceId()).isNotBlank();
+    }
+
+    @Test
+    void ledgerQueriesEveryDerivedSourceWithinCustomerScope() {
+        AccountJdbc jdbc = new AccountJdbc();
+        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, objectMapper());
+
+        PageEnvelope<FinancePhase1Dtos.LedgerEntry> result =
+            service.listDerivedCustomerAccountLedger(9L, 1, 20, null, null, null);
+
+        assertThat(result.data()).isEmpty();
+        assertThat(jdbc.ledgerCustomerIds).containsExactly(9L, 9L, 9L);
+    }
+
     @Test
     void rejectedFeeCannotBeIncludedInSettlement() throws Exception {
         JdbcTemplate jdbc = feeSourceJdbc("REJECTED", false, 2);
-        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, new ObjectMapper());
+        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, objectMapper());
 
         assertThatThrownBy(() -> service.updateFeeSourceSettlementInclusion(88L, 71L, "include-key",
             new FinancePhase1Dtos.SettlementInclusionRequest(true, "进入结算", 2)))
@@ -84,6 +118,46 @@ class FinancePhase1OperationBehaviorTest {
             .extracting(error -> ((FinanceEventException) error).code()).isEqualTo("FIN-FEE-409");
     }
 
+    @Test
+    void feeSourceDetailUsesFixedDtoAndRealCustomerScope() throws Exception {
+        FinancePhase1OperationService service = new FinancePhase1OperationService(
+            feeSourceJdbc("APPROVED", true, 2), objectMapper());
+
+        FeeSourceDetail detail = service.getFinanceFeeSource(88L);
+
+        assertThat(detail.feeSourceId()).isEqualTo(88L);
+        assertThat(detail.customerId()).isEqualTo(9L);
+        assertThat(detail.currency()).isEqualTo("CNY");
+        assertThat(detail.reviewStatus()).isEqualTo("APPROVED");
+        assertThat(detail.settlementIncluded()).isTrue();
+    }
+
+    @Test
+    void approvedFeeCanBeIncludedWithExpectedVersion() throws Exception {
+        JdbcTemplate jdbc = mock(JdbcTemplate.class, invocation ->
+            "update".equals(invocation.getMethod().getName())
+                ? 1 : org.mockito.Mockito.RETURNS_DEFAULTS.answer(invocation));
+        AtomicInteger reads = new AtomicInteger();
+        when(jdbc.query(startsWith("SELECT * FROM fin_fee_source"), any(RowMapper.class), (Object[]) any())).thenAnswer(invocation -> {
+            @SuppressWarnings("unchecked") RowMapper<FeeSourceDetail> mapper = invocation.getArgument(1);
+            boolean included = reads.getAndIncrement() > 0;
+            return List.of(mapper.mapRow(resultSet("APPROVED", included, included ? 2 : 1), 0));
+        });
+        when(jdbc.queryForObject(startsWith("SELECT COUNT(*)>0"), eq(Boolean.class), eq(700L), eq(3))).thenReturn(false);
+        when(jdbc.query(startsWith("SELECT created_at,action"), any(RowMapper.class), eq(9L), eq(88L))).thenReturn(List.of());
+        when(jdbc.queryForList(startsWith("SELECT request_hash"), eq(9L), eq(71L),
+            eq("FEE_SOURCE_SETTLEMENT"), eq("include-key"))).thenReturn(List.of());
+        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, objectMapper());
+
+        FeeSourceDetail result = service.updateFeeSourceSettlementInclusion(88L, 71L, "include-key",
+            new FinancePhase1Dtos.SettlementInclusionRequest(true, "进入结算", 1));
+
+        assertThat(result.settlementIncluded()).isTrue();
+        assertThat(result.operationVersion()).isEqualTo(2);
+        verify(jdbc).update(startsWith("UPDATE fin_fee_source SET settlement_included="),
+            eq(true), eq("进入结算"), eq(88L), eq(1));
+    }
+
     @Test
     void reviewUsesExpectedVersionAndReturnsUpdatedDetail() throws Exception {
         JdbcTemplate jdbc = mock(JdbcTemplate.class);
@@ -96,12 +170,18 @@ class FinancePhase1OperationBehaviorTest {
         });
         when(jdbc.queryForObject(startsWith("SELECT COUNT(*)>0"), eq(Boolean.class), eq(700L), eq(3))).thenReturn(false);
         when(jdbc.query(startsWith("SELECT created_at,action"), any(RowMapper.class), eq(9L), eq(88L))).thenReturn(List.of());
-        when(jdbc.queryForList(startsWith("SELECT request_hash"), any(), any(), any(), any())).thenReturn(List.of());
-        when(jdbc.update(startsWith("INSERT INTO fin_idempotency_record"), (Object[]) any())).thenReturn(1);
-        when(jdbc.update(startsWith("UPDATE fin_fee_source SET review_status="), (Object[]) any())).thenReturn(1);
-        when(jdbc.update(startsWith("INSERT INTO fin_audit_log"), (Object[]) any())).thenReturn(1);
-        when(jdbc.update(startsWith("UPDATE fin_idempotency_record SET status='SUCCEEDED'"), (Object[]) any())).thenReturn(1);
-        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, new ObjectMapper());
+        when(jdbc.queryForList(startsWith("SELECT request_hash"), eq(9L), eq(71L),
+            eq("FEE_SOURCE_REVIEW"), eq("review-key"))).thenReturn(List.of());
+        when(jdbc.update(startsWith("INSERT INTO fin_idempotency_record"), eq(9L), eq(71L),
+            eq("FEE_SOURCE_REVIEW"), eq("review-key"), anyString())).thenReturn(1);
+        when(jdbc.update(startsWith("UPDATE fin_fee_source SET review_status="),
+            eq("APPROVED"), eq("核对无误"), eq(88L), eq(0))).thenReturn(1);
+        when(jdbc.update(startsWith("INSERT INTO fin_audit_log"), eq(9L), eq("FIN_FEE_SOURCE"),
+            eq(88L), eq("FEE_SOURCE_REVIEW_APPROVE"), eq("核对无误"), anyString(), anyString(),
+            eq(71L), eq("operator-71"), any(), any())).thenReturn(1);
+        when(jdbc.update(startsWith("UPDATE fin_idempotency_record SET status='SUCCEEDED'"),
+            eq(88L), eq(9L), eq(71L), eq("FEE_SOURCE_REVIEW"), eq("review-key"))).thenReturn(1);
+        FinancePhase1OperationService service = new FinancePhase1OperationService(jdbc, objectMapper());
 
         FeeSourceDetail result = service.reviewFinanceFeeSource(88L, 71L, "review-key",
             new FinancePhase1Dtos.ReviewRequest("APPROVE", "核对无误", 0));
@@ -119,7 +199,8 @@ class FinancePhase1OperationBehaviorTest {
         });
         when(jdbc.queryForObject(startsWith("SELECT COUNT(*)>0"), eq(Boolean.class), eq(700L), eq(3))).thenReturn(false);
         when(jdbc.query(startsWith("SELECT created_at,action"), any(RowMapper.class), eq(9L), eq(88L))).thenReturn(List.of());
-        when(jdbc.queryForList(anyString(), any(), any(), any(), any())).thenReturn(List.of());
+        lenient().when(jdbc.queryForList(startsWith("SELECT request_hash"), eq(9L), eq(71L),
+            eq("FEE_SOURCE_SETTLEMENT"), eq("include-key"))).thenReturn(List.of());
         return jdbc;
     }
 
@@ -146,4 +227,35 @@ class FinancePhase1OperationBehaviorTest {
         when(rs.getString("source_snapshot")).thenReturn("{\"customerName\":\"客户9\",\"businessDate\":\"2026-08-11\",\"chargeableQuantity\":\"10\",\"reviewStatus\":\"" + reviewStatus + "\",\"settlementIncluded\":" + included + ",\"operationVersion\":" + version + "}");
         return rs;
     }
+
+    private static ObjectMapper objectMapper() {
+        return new ObjectMapper().findAndRegisterModules();
+    }
+
+    private static final class AccountJdbc extends JdbcTemplate {
+        private final List<Long> ledgerCustomerIds = new ArrayList<>();
+
+        @Override
+        public <T> T queryForObject(String sql, Class<T> requiredType, Object... args) {
+            if (sql.startsWith("SELECT COUNT(*)")) return requiredType.cast(1L);
+            return null;
+        }
+
+        @Override
+        @SuppressWarnings("unchecked")
+        public <T> List<T> query(String sql, RowMapper<T> rowMapper, Object... args) {
+            if (sql.startsWith("SELECT c.customer_id")) {
+                return (List<T>) List.of(new FinancePhase1Dtos.AccountSummary(
+                    9L, "9", "客户9", null, null, new BigDecimal("100.00"),
+                    new BigDecimal("20.00"), new BigDecimal("30.00"), BigDecimal.ZERO,
+                    "ACTIVE", LocalDateTime.of(2026, 8, 11, 10, 0)));
+            }
+            if (sql.startsWith("SELECT id,bill_no") || sql.startsWith("SELECT id,receipt_no")
+                || sql.startsWith("SELECT id,cost_no")) {
+                ledgerCustomerIds.add(((Number) Arrays.asList(args).get(0)).longValue());
+                return List.of();
+            }
+            return List.of();
+        }
+    }
 }

finance/src/test/java/com/baiyue/finance/FinanceSettlementBehaviorTest.java

@@ -0,0 +1,181 @@
+package com.baiyue.finance;
+
+import com.baiyue.common.core.api.ApiResponse;
+import com.baiyue.common.security.AuthenticatedUser;
+import com.baiyue.finance.client.FinanceFileClient;
+import com.baiyue.finance.controller.FinanceSettlementController;
+import com.baiyue.finance.dto.FinanceSettlementDtos.CreatePayableSettlementRequest;
+import com.baiyue.finance.dto.FinanceSettlementDtos.CreateReceivableSettlementRequest;
+import com.baiyue.finance.dto.FinanceSettlementDtos.CreateSettlementPaymentRequest;
+import com.baiyue.finance.dto.FinanceSettlementDtos.SettlementDetail;
+import com.baiyue.finance.dto.FinanceSettlementDtos.SettlementSummary;
+import com.baiyue.finance.service.FinanceEventException;
+import com.baiyue.finance.service.FinanceSettlementService;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.security.access.AccessDeniedException;
+import org.springframework.test.util.ReflectionTestUtils;
+
+import java.math.BigDecimal;
+import java.sql.Date;
+import java.sql.Timestamp;
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.ArgumentMatchers.startsWith;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+@ExtendWith(MockitoExtension.class)
+class FinanceSettlementBehaviorTest {
+    @Mock FinanceSettlementService controllerService;
+
+    @Test
+    void controllerReturnsFixedEnvelopeAndEnforcesDirectionPermission() {
+        FinanceSettlementController controller = new FinanceSettlementController(controllerService);
+        SettlementDetail payable = detail("PAYABLE", "ISSUED", BigDecimal.ZERO, new BigDecimal("100.00"), 0);
+        when(controllerService.getSettlement(88L)).thenReturn(payable);
+        AuthenticatedUser apViewer = user(Set.of("platform:finance:settlement-ap:view"));
+
+        var response = controller.getSettlement(apViewer, 88L);
+
+        assertThat(response.code()).isEqualTo("200");
+        assertThat(response.data()).isSameAs(payable);
+        assertThat(response.requestId()).isNotBlank();
+        assertThatThrownBy(() -> controller.getSettlement(
+            user(Set.of("platform:finance:settlement-ar:view")), 88L)).isInstanceOf(AccessDeniedException.class);
+    }
+
+    @Test
+    void arCreationRejectsNonCnyBeforeDatabaseAccess() {
+        JdbcTemplate jdbc = org.mockito.Mockito.mock(JdbcTemplate.class);
+        FinanceSettlementService service = service(jdbc, org.mockito.Mockito.mock(FinanceFileClient.class));
+
+        assertCode(() -> service.createReceivableSettlement(7L, "ar-key",
+            new CreateReceivableSettlementRequest(9L, "USD")), "FIN_400");
+
+        verify(jdbc, never()).queryForList(anyString(), (Object[]) any());
+    }
+
+    @Test
+    void payableCreationRejectsDuplicateSourcesBeforeIdempotencyReservation() {
+        JdbcTemplate jdbc = org.mockito.Mockito.mock(JdbcTemplate.class);
+        FinanceSettlementService service = service(jdbc, org.mockito.Mockito.mock(FinanceFileClient.class));
+
+        assertCode(() -> service.createPayableSettlement(7L, "ap-key",
+            new CreatePayableSettlementRequest(10L, 20L, List.of(3L, 3L), LocalDate.now(), "CNY")), "FIN_400");
+
+        verify(jdbc, never()).update(startsWith("INSERT INTO fin_idempotency_record"), (Object[]) any());
+    }
+
+    @Test
+    void paymentFailsClosedWhenFileServiceIsUnavailable() {
+        JdbcTemplate jdbc = org.mockito.Mockito.mock(JdbcTemplate.class);
+        FinanceFileClient fileClient = org.mockito.Mockito.mock(FinanceFileClient.class);
+        when(jdbc.queryForList(startsWith("SELECT id,tenant_id,direction"), eq(88L)))
+            .thenReturn(List.of(settlementRow("PAYABLE", "ISSUED", BigDecimal.ZERO, new BigDecimal("100.00"), 0)));
+        when(jdbc.queryForList(startsWith("SELECT request_hash"), eq(10L), eq(7L),
+            eq("SETTLEMENT_PAYMENT_CREATE"), eq("pay-key"))).thenReturn(List.of());
+        when(fileClient.metadata("internal-token", 10L, 10L, 91L)).thenThrow(new IllegalStateException("down"));
+        FinanceSettlementService service = service(jdbc, fileClient);
+
+        assertCode(() -> service.createSettlementPayment(88L, 7L, "pay-key",
+            payment(new BigDecimal("40.00"), 0)), "FIN_503");
+
+        verify(jdbc, never()).update(startsWith("INSERT INTO fin_settlement_payment"), (Object[]) any());
+        verify(jdbc, never()).update(startsWith("UPDATE fin_settlement SET paid_amount"), (Object[]) any());
+    }
+
+    @Test
+    void partialPaymentUpdatesOutstandingAndReturnsTypedDetail() {
+        JdbcTemplate jdbc = org.mockito.Mockito.mock(JdbcTemplate.class, invocation ->
+            "update".equals(invocation.getMethod().getName())
+                ? 1 : org.mockito.Mockito.RETURNS_DEFAULTS.answer(invocation));
+        FinanceFileClient fileClient = org.mockito.Mockito.mock(FinanceFileClient.class);
+        Map<String, Object> before = settlementRow("PAYABLE", "ISSUED", BigDecimal.ZERO,
+            new BigDecimal("100.00"), 0);
+        Map<String, Object> after = settlementRow("PAYABLE", "PARTIALLY_PAID", new BigDecimal("40.00"),
+            new BigDecimal("60.00"), 1);
+        when(jdbc.queryForList(startsWith("SELECT id,tenant_id,direction"), eq(88L))).thenReturn(List.of(before));
+        when(jdbc.queryForList(startsWith("SELECT request_hash"), eq(10L), eq(7L),
+            eq("SETTLEMENT_PAYMENT_CREATE"), eq("pay-key"))).thenReturn(List.of());
+        when(jdbc.queryForList(startsWith("SELECT id,tenant_id,settlement_no"), eq(88L))).thenReturn(List.of(after));
+        when(jdbc.queryForList(startsWith("SELECT f.id fee_source_id"), eq(10L), eq(88L))).thenReturn(List.of());
+        when(jdbc.queryForList(startsWith("SELECT id,transaction_type"), eq(10L), eq(88L))).thenReturn(List.of(Map.of(
+            "id", 501L, "transaction_type", "PAYMENT", "transaction_date", Date.valueOf(LocalDate.of(2026, 8, 11)),
+            "amount", new BigDecimal("40.00"), "method", "BANK_TRANSFER", "reference_no", "BANK-1",
+            "voucher_file_ids", "[\"91\"]", "created_by", 7L,
+            "created_at", Timestamp.valueOf(LocalDateTime.of(2026, 8, 11, 10, 0)), "remark", "首笔付款")));
+        when(jdbc.queryForList(startsWith("SELECT action,reason"), eq(10L), eq(88L))).thenReturn(List.of());
+        when(fileClient.metadata("internal-token", 10L, 10L, 91L)).thenReturn(ApiResponse.success(
+            new FinanceFileClient.Metadata(91L, 10L, "FINANCE_VOUCHER", "10", "pay.png", "abc", "image/png", 10L)));
+        FinanceSettlementService service = service(jdbc, fileClient);
+
+        SettlementDetail result = service.createSettlementPayment(88L, 7L, "pay-key",
+            payment(new BigDecimal("40.00"), 0));
+
+        assertThat(result.summary().status()).isEqualTo("PARTIALLY_PAID");
+        assertThat(result.summary().paidAmount()).isEqualByComparingTo("40.00");
+        assertThat(result.summary().outstandingAmount()).isEqualByComparingTo("60.00");
+        assertThat(result.transactions()).singleElement().extracting(transaction -> transaction.transactionType())
+            .isEqualTo("PAYMENT");
+        verify(jdbc).update(startsWith("UPDATE fin_settlement SET paid_amount"),
+            any(), any(), any(), any(), any(), any(), any(), any());
+    }
+
+    private static FinanceSettlementService service(JdbcTemplate jdbc, FinanceFileClient fileClient) {
+        FinanceSettlementService service = new FinanceSettlementService(
+            jdbc, new ObjectMapper().findAndRegisterModules(), fileClient);
+        ReflectionTestUtils.setField(service, "fileToken", "internal-token");
+        return service;
+    }
+
+    private static CreateSettlementPaymentRequest payment(BigDecimal amount, int version) {
+        return new CreateSettlementPaymentRequest(LocalDate.of(2026, 8, 11), amount, "CNY", "BANK_TRANSFER",
+            "BANK-1", List.of("91"), version, "首笔付款");
+    }
+
+    private static Map<String, Object> settlementRow(String direction, String status, BigDecimal paid,
+                                                     BigDecimal outstanding, int version) {
+        return new java.util.HashMap<>(Map.ofEntries(
+            Map.entry("id", 88L), Map.entry("tenant_id", 10L), Map.entry("settlement_no", "AP-20260811-001"),
+            Map.entry("direction", direction), Map.entry("customer_name_snapshot", "客户10"),
+            Map.entry("supplier_id", 20L), Map.entry("supplier_name_snapshot", "供应商20"),
+            Map.entry("business_period", "2026-08"), Map.entry("currency_code", "CNY"),
+            Map.entry("total_amount", new BigDecimal("100.00")), Map.entry("paid_amount", paid),
+            Map.entry("outstanding_amount", outstanding), Map.entry("generated_date", Date.valueOf("2026-08-11")),
+            Map.entry("due_date", Date.valueOf("2026-09-10")),
+            Map.entry("payment_status", paid.signum() == 0 ? "UNPAID" : status), Map.entry("status", status),
+            Map.entry("version", version)));
+    }
+
+    private static SettlementDetail detail(String direction, String status, BigDecimal paid,
+                                           BigDecimal outstanding, int version) {
+        return new SettlementDetail(new SettlementSummary(88L, "SET-88", direction, 10L, "客户10", 20L,
+            "供应商20", null, "2026-08", "CNY", paid.add(outstanding), paid, outstanding,
+            LocalDate.of(2026, 8, 11), LocalDate.of(2026, 9, 10), paid.signum() == 0 ? "UNPAID" : status,
+            status, version), List.of(), List.of(), List.of());
+    }
+
+    private static AuthenticatedUser user(Set<String> permissions) {
+        return new AuthenticatedUser(7L, null, null, null, "finance", "ADMIN", "WEB", permissions);
+    }
+
+    private static void assertCode(org.assertj.core.api.ThrowableAssert.ThrowingCallable call, String code) {
+        assertThatThrownBy(call).isInstanceOf(FinanceEventException.class)
+            .extracting(error -> ((FinanceEventException) error).code()).isEqualTo(code);
+    }
+}

finance/src/test/java/com/baiyue/finance/ReconciliationStatementBehaviorTest.java

@@ -0,0 +1,257 @@
+package com.baiyue.finance;
+
+import com.baiyue.common.security.AuthenticatedUser;
+import com.baiyue.finance.controller.ReconciliationStatementController;
+import com.baiyue.finance.dto.ReconciliationStatementDtos.CreateReconciliationRequest;
+import com.baiyue.finance.dto.ReconciliationStatementDtos.DocumentActionRequest;
+import com.baiyue.finance.service.FinanceEventException;
+import com.baiyue.finance.service.ReconciliationStatementService;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.jdbc.core.PreparedStatementCreator;
+import org.springframework.jdbc.core.RowMapper;
+import org.springframework.jdbc.support.KeyHolder;
+
+import java.math.BigDecimal;
+import java.sql.ResultSet;
+import java.sql.Timestamp;
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyString;
+import static org.mockito.ArgumentMatchers.eq;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.RETURNS_DEFAULTS;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.verifyNoInteractions;
+import static org.mockito.Mockito.when;
+
+@ExtendWith(MockitoExtension.class)
+class ReconciliationStatementBehaviorTest {
+    @Mock ReconciliationStatementService service;
+
+    @Test
+    void controllerUsesAuthenticatedOperatorAndStableTraceResponse() {
+        ReconciliationStatementController controller = new ReconciliationStatementController(service);
+        AuthenticatedUser user = new AuthenticatedUser(71L, null, null, null, "finance", "ADMIN", "WEB", Set.of());
+        CreateReconciliationRequest create = new CreateReconciliationRequest(9L, "SELECTED", List.of(88L),
+            LocalDate.of(2026, 8, 1), LocalDate.of(2026, 8, 31), "八月对账");
+        DocumentActionRequest action = new DocumentActionRequest("SUBMIT", "提交审核", 0);
+
+        var created = controller.createReconciliationStatement(user, "create-key", create);
+        var acted = controller.actionReconciliationStatement(user, 501L, "action-key", action);
+
+        verify(service).create(71L, "create-key", create);
+        verify(service).action(71L, 501L, "action-key", action);
+        assertThat(created.requestId()).isNotBlank();
+        assertThat(created.traceId()).isNotBlank();
+        assertThat(acted.requestId()).isNotBlank();
+        assertThat(acted.traceId()).isNotBlank();
+    }
+
+    @Test
+    void selectedModeRejectsDuplicateFeeSourcesBeforeWriting() {
+        JdbcTemplate jdbc = mock(JdbcTemplate.class);
+        ReconciliationStatementService target = new ReconciliationStatementService(jdbc, new ObjectMapper().findAndRegisterModules());
+        CreateReconciliationRequest request = new CreateReconciliationRequest(9L, "SELECTED", List.of(88L, 88L),
+            LocalDate.of(2026, 8, 1), LocalDate.of(2026, 8, 31), null);
+
+        assertThatThrownBy(() -> target.create(71L, "create-key", request))
+            .isInstanceOf(FinanceEventException.class)
+            .extracting(error -> ((FinanceEventException) error).code()).isEqualTo("FIN-REQ-400");
+        verifyNoInteractions(jdbc);
+    }
+
+    @Test
+    void selectedEligibleCnySourceCreatesStableDraftAndLocksSource() throws Exception {
+        JdbcTemplate jdbc = createJdbc();
+        ReconciliationStatementService target = new ReconciliationStatementService(jdbc, new ObjectMapper().findAndRegisterModules());
+        CreateReconciliationRequest request = new CreateReconciliationRequest(9L, "SELECTED", List.of(88L),
+            LocalDate.of(2026, 8, 1), LocalDate.of(2026, 8, 31), "八月对账");
+
+        var result = target.create(71L, "create-key", request);
+
+        assertThat(result.statementId()).isEqualTo(501L);
+        assertThat(result.statementNo()).isEqualTo("REC-00000000000000000501");
+        assertThat(result.currency()).isEqualTo("CNY");
+        assertThat(result.totalReceivable()).isEqualByComparingTo("100.00");
+        assertThat(result.lines()).hasSize(1);
+        verify(jdbc).update(org.mockito.ArgumentMatchers.startsWith("UPDATE fin_fee_source SET status='LOCKED'"), eq(88L), eq(9L));
+    }
+
+    @Test
+    void submitUsesExpectedVersionAndPersistsRevisionBeforeStateChange() throws Exception {
+        JdbcTemplate jdbc = actionJdbc("DRAFT", "PENDING_REVIEW", "submit-key");
+        ReconciliationStatementService target = new ReconciliationStatementService(jdbc, new ObjectMapper().findAndRegisterModules());
+
+        var result = target.action(71L, 501L, "submit-key",
+            new DocumentActionRequest("SUBMIT", "提交审核", 0));
+
+        assertThat(result.customerId()).isEqualTo(9L);
+        assertThat(result.status()).isEqualTo("PENDING_REVIEW");
+        assertThat(result.version()).isEqualTo(1);
+        assertThat(result.periodStart()).isEqualTo(LocalDate.of(2026, 8, 1));
+        verify(jdbc).update(anyString(), eq(9L), eq(501L), eq(0), eq("提交审核"), anyString(), anyString(), eq(71L));
+        verify(jdbc).update(org.mockito.ArgumentMatchers.startsWith("UPDATE fin_bill SET status="),
+            eq("PENDING_REVIEW"), eq("PENDING_REVIEW"), eq("PENDING_REVIEW"), eq(71L),
+            eq("PENDING_REVIEW"), eq("PENDING_REVIEW"), eq(71L), eq("PENDING_REVIEW"),
+            eq("提交审核"), eq(71L), eq(501L), eq(9L), eq("DRAFT"), eq(0));
+        verify(jdbc, never()).update(org.mockito.ArgumentMatchers.startsWith("UPDATE fin_fee_source f JOIN"), (Object[]) any());
+    }
+
+    @Test
+    void approveFreezesInternalBillAndReturnsContractStatus() throws Exception {
+        JdbcTemplate jdbc = actionJdbc("PENDING_REVIEW", "ISSUED", "approve-key");
+        ReconciliationStatementService target = new ReconciliationStatementService(jdbc, new ObjectMapper().findAndRegisterModules());
+
+        var result = target.action(71L, 501L, "approve-key",
+            new DocumentActionRequest("APPROVE", "审核通过", 1));
+
+        assertThat(result.status()).isEqualTo("APPROVED");
+        assertThat(result.version()).isEqualTo(2);
+        verify(jdbc).update(org.mockito.ArgumentMatchers.startsWith("UPDATE fin_fee_source f JOIN"), eq(9L), eq(501L), eq(9L));
+    }
+
+    @Test
+    void sameIdempotencyKeyWithDifferentActionBodyIsRejected() throws Exception {
+        JdbcTemplate jdbc = mock(JdbcTemplate.class);
+        when(jdbc.query(anyString(), any(RowMapper.class), (Object[]) any())).thenAnswer(invocation -> {
+            @SuppressWarnings("unchecked") RowMapper<Object> mapper = invocation.getArgument(1);
+            return List.of(mapper.mapRow(billResultSet("DRAFT", 0), 0));
+        });
+        when(jdbc.queryForList(org.mockito.ArgumentMatchers.startsWith("SELECT request_hash"),
+            eq(9L), eq(71L), eq("RECONCILIATION_ACTION"), eq("used-key"))).thenReturn(List.of(Map.of(
+            "request_hash", "different-request", "status", "SUCCEEDED", "result_resource_id", 501L,
+            "updated_at", LocalDateTime.now())));
+        ReconciliationStatementService target = new ReconciliationStatementService(jdbc, new ObjectMapper().findAndRegisterModules());
+
+        assertThatThrownBy(() -> target.action(71L, 501L, "used-key",
+            new DocumentActionRequest("SUBMIT", "提交审核", 0)))
+            .isInstanceOf(FinanceEventException.class)
+            .extracting(error -> ((FinanceEventException) error).code()).isEqualTo("FIN-IDEM-409");
+        verify(jdbc, never()).update(org.mockito.ArgumentMatchers.startsWith("INSERT INTO fin_bill_revision"), (Object[]) any());
+    }
+
+    private static JdbcTemplate actionJdbc(String beforeStatus, String afterStatus, String key) throws Exception {
+        JdbcTemplate jdbc = mock(JdbcTemplate.class, invocation -> {
+            if ("update".equals(invocation.getMethod().getName()) && invocation.getMethod().getReturnType() == int.class) return 1;
+            return RETURNS_DEFAULTS.answer(invocation);
+        });
+        when(jdbc.query(anyString(), any(RowMapper.class), (Object[]) any())).thenAnswer(invocation -> {
+            String sql = invocation.getArgument(0);
+            @SuppressWarnings("unchecked") RowMapper<Object> mapper = invocation.getArgument(1);
+            return List.of(mapper.mapRow(billResultSet(beforeStatus, "PENDING_REVIEW".equals(beforeStatus) ? 1 : 0), 0));
+        });
+        when(jdbc.query(org.mockito.ArgumentMatchers.startsWith("SELECT b.*"), any(RowMapper.class), eq(501L), eq(9L))).thenAnswer(invocation -> {
+            @SuppressWarnings("unchecked") RowMapper<Object> mapper = invocation.getArgument(1);
+            return List.of(mapper.mapRow(billResultSet(afterStatus, "ISSUED".equals(afterStatus) ? 2 : 1), 0));
+        });
+        when(jdbc.query(org.mockito.ArgumentMatchers.startsWith("SELECT after_data"), any(RowMapper.class), eq(9L), eq(501L)))
+            .thenReturn(List.of("{\"generationMode\":\"SELECTED\",\"periodStart\":\"2026-08-01\",\"periodEnd\":\"2026-08-31\"}"));
+        when(jdbc.query(org.mockito.ArgumentMatchers.startsWith("SELECT f.id"), any(RowMapper.class), eq(9L), eq(501L))).thenReturn(List.of());
+        when(jdbc.query(org.mockito.ArgumentMatchers.startsWith("SELECT r.id"), any(RowMapper.class), eq(9L), eq(501L))).thenReturn(List.of());
+        when(jdbc.queryForList(org.mockito.ArgumentMatchers.startsWith("SELECT request_hash"),
+            eq(9L), eq(71L), eq("RECONCILIATION_ACTION"), eq(key))).thenReturn(List.of());
+        when(jdbc.queryForList(org.mockito.ArgumentMatchers.startsWith("SELECT * FROM fin_bill_line"), eq(9L), eq(501L))).thenReturn(List.of());
+        return jdbc;
+    }
+
+    private static JdbcTemplate createJdbc() throws Exception {
+        JdbcTemplate jdbc = mock(JdbcTemplate.class, invocation -> {
+            if ("update".equals(invocation.getMethod().getName()) && invocation.getMethod().getReturnType() == int.class) return 1;
+            return RETURNS_DEFAULTS.answer(invocation);
+        });
+        LocalDate start = LocalDate.of(2026, 8, 1);
+        LocalDate end = LocalDate.of(2026, 8, 31);
+        when(jdbc.query(org.mockito.ArgumentMatchers.startsWith("SELECT customer_name_snapshot"), any(RowMapper.class), eq(9L))).thenAnswer(invocation -> {
+            @SuppressWarnings("unchecked") RowMapper<Object> mapper = invocation.getArgument(1);
+            ResultSet rs = mock(ResultSet.class);
+            when(rs.getString("customer_name_snapshot")).thenReturn("客户9");
+            when(rs.getInt("credit_days")).thenReturn(30);
+            return List.of(mapper.mapRow(rs, 0));
+        });
+        when(jdbc.query(org.mockito.ArgumentMatchers.startsWith("SELECT id FROM fin_subject"), any(RowMapper.class))).thenAnswer(invocation -> {
+            @SuppressWarnings("unchecked") RowMapper<Object> mapper = invocation.getArgument(1);
+            ResultSet rs = mock(ResultSet.class);
+            when(rs.getLong(1)).thenReturn(1L);
+            return List.of(mapper.mapRow(rs, 0));
+        });
+        when(jdbc.query(org.mockito.ArgumentMatchers.startsWith("SELECT id,source_fee_id"), any(RowMapper.class),
+            eq(9L), eq(start), eq(end), eq(88L))).thenAnswer(invocation -> {
+            @SuppressWarnings("unchecked") RowMapper<Object> mapper = invocation.getArgument(1);
+            return List.of(mapper.mapRow(sourceResultSet(), 0));
+        });
+        org.mockito.Mockito.lenient().doAnswer(invocation -> {
+            KeyHolder holder = invocation.getArgument(1);
+            holder.getKeyList().add(Map.of("GENERATED_KEY", 501L));
+            return 1;
+        }).when(jdbc).update(any(PreparedStatementCreator.class), any(KeyHolder.class));
+        when(jdbc.query(org.mockito.ArgumentMatchers.startsWith("SELECT b.*"), any(RowMapper.class), eq(501L), eq(9L))).thenAnswer(invocation -> {
+            @SuppressWarnings("unchecked") RowMapper<Object> mapper = invocation.getArgument(1);
+            ResultSet rs = billResultSet("DRAFT", 0);
+            when(rs.getBigDecimal("total_amount")).thenReturn(new BigDecimal("100.00"));
+            when(rs.getBigDecimal("outstanding_amount")).thenReturn(new BigDecimal("100.00"));
+            return List.of(mapper.mapRow(rs, 0));
+        });
+        when(jdbc.query(org.mockito.ArgumentMatchers.startsWith("SELECT after_data"), any(RowMapper.class), eq(9L), eq(501L)))
+            .thenReturn(List.of("{\"generationMode\":\"SELECTED\",\"periodStart\":\"2026-08-01\",\"periodEnd\":\"2026-08-31\"}"));
+        when(jdbc.query(org.mockito.ArgumentMatchers.startsWith("SELECT f.id"), any(RowMapper.class), eq(9L), eq(501L))).thenAnswer(invocation -> {
+            @SuppressWarnings("unchecked") RowMapper<Object> mapper = invocation.getArgument(1);
+            return List.of(mapper.mapRow(sourceResultSet(), 0));
+        });
+        when(jdbc.query(org.mockito.ArgumentMatchers.startsWith("SELECT r.id"), any(RowMapper.class), eq(9L), eq(501L))).thenReturn(List.of());
+        when(jdbc.queryForList(org.mockito.ArgumentMatchers.startsWith("SELECT request_hash"),
+            eq(9L), eq(71L), eq("RECONCILIATION_CREATE"), eq("create-key"))).thenReturn(List.of());
+        return jdbc;
+    }
+
+    private static ResultSet sourceResultSet() throws Exception {
+        ResultSet rs = mock(ResultSet.class, org.mockito.Mockito.withSettings().lenient());
+        when(rs.getLong("id")).thenReturn(88L);
+        when(rs.getLong("source_fee_id")).thenReturn(700L);
+        when(rs.getInt("source_fee_version")).thenReturn(3);
+        when(rs.getString("source_type")).thenReturn("INBOUND_FEE");
+        when(rs.getString("source_no")).thenReturn("IN-202608-1");
+        when(rs.getString("direction")).thenReturn("RECEIVABLE");
+        when(rs.getLong("customer_id")).thenReturn(9L);
+        when(rs.getLong("order_id")).thenReturn(300L);
+        when(rs.getLong("inbound_id")).thenReturn(400L);
+        when(rs.getLong("container_id")).thenReturn(0L);
+        when(rs.getString("fee_item_code")).thenReturn("FREIGHT");
+        when(rs.getString("fee_item_name")).thenReturn("头程运费");
+        when(rs.getBigDecimal("amount")).thenReturn(new BigDecimal("100.00"));
+        when(rs.getString("currency_code")).thenReturn("CNY");
+        when(rs.getString("status")).thenReturn("LOCKED");
+        return rs;
+    }
+
+    private static ResultSet billResultSet(String status, int version) throws Exception {
+        ResultSet rs = mock(ResultSet.class);
+        when(rs.getLong("id")).thenReturn(501L);
+        when(rs.getLong("tenant_id")).thenReturn(9L);
+        when(rs.getString("bill_no")).thenReturn("REC-00000000000000000501");
+        when(rs.getString("customer_name_snapshot")).thenReturn("客户9");
+        when(rs.getString("status")).thenReturn(status);
+        when(rs.getBigDecimal("total_amount")).thenReturn(new BigDecimal("300.00"));
+        when(rs.getBigDecimal("received_amount")).thenReturn(BigDecimal.ZERO);
+        when(rs.getBigDecimal("outstanding_amount")).thenReturn(new BigDecimal("300.00"));
+        when(rs.getInt("version")).thenReturn(version);
+        when(rs.getInt("credit_days")).thenReturn(30);
+        when(rs.getString("remark")).thenReturn("八月对账");
+        Timestamp timestamp = Timestamp.valueOf("2026-08-11 10:00:00");
+        when(rs.getTimestamp("created_at")).thenReturn(timestamp);
+        when(rs.getTimestamp("updated_at")).thenReturn(timestamp);
+        return rs;
+    }
+}