feat(finance): add customer wallet recharge flow

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

@@ -374,6 +374,7 @@ class FinancePhase1OperationBehaviorTest {
                     9L, "9", "客户9", null, null, new BigDecimal("100.00"),
                     new BigDecimal("20.00"), new BigDecimal("30.00"), BigDecimal.ZERO,
                     BigDecimal.ZERO, BigDecimal.ZERO,
+                    BigDecimal.ZERO, BigDecimal.ZERO, BigDecimal.ZERO, 0, 0,
                     "ACTIVE", LocalDateTime.of(2026, 8, 11, 10, 0)));
             }
             if (sql.startsWith("SELECT id,bill_no") || sql.startsWith("SELECT id,receipt_no")

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

@@ -43,8 +43,8 @@ class FinanceSqlCommentContractTest {
                 missing.add(currentTable + "." + column.group(1));
             }
         }
-        assertThat(tableCount).isEqualTo(17);
-        assertThat(columnCount).isEqualTo(265);
+        assertThat(tableCount).isEqualTo(20);
+        assertThat(columnCount).isEqualTo(310);
         assertThat(missing).as("缺少中文业务注释的Finance字段").isEmpty();
     }
 

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

@@ -0,0 +1,77 @@
+package com.baiyue.finance;
+
+import com.baiyue.finance.client.FinanceFileClient;
+import com.baiyue.finance.dto.FinanceWalletDtos.AccountAdjustmentRequest;
+import com.baiyue.finance.service.FinanceDocumentNumberGenerator;
+import com.baiyue.finance.service.FinanceEventException;
+import com.baiyue.finance.service.FinanceWalletService;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.junit.jupiter.api.Test;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.jdbc.core.RowMapper;
+
+import java.math.BigDecimal;
+import java.sql.ResultSet;
+import java.sql.Timestamp;
+import java.time.LocalDate;
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.ArgumentMatchers.*;
+import static org.mockito.Mockito.*;
+
+class FinanceWalletBehaviorTest {
+    @Test
+    void missingAccountReadsAsZeroWithoutCreatingData() {
+        JdbcTemplate jdbc = mock(JdbcTemplate.class);
+        when(jdbc.query(startsWith("SELECT currency_code"), any(RowMapper.class), eq(9L))).thenReturn(List.of());
+
+        var account = service(jdbc, "https://pay.example/wechat.png", "").account(9L);
+
+        assertThat(account.actualBalance()).isEqualByComparingTo("0.00");
+        assertThat(account.frozenBalance()).isEqualByComparingTo("0.00");
+        assertThat(account.availableBalance()).isEqualByComparingTo("0.00");
+        verify(jdbc, never()).update(anyString(), any(Object[].class));
+    }
+
+    @Test
+    void rechargeChannelsAreEnabledOnlyWhenQrCodeIsConfigured() {
+        var channels = service(mock(JdbcTemplate.class), "https://pay.example/wechat.png", "").channels();
+
+        assertThat(channels).satisfiesExactly(
+            wechat -> { assertThat(wechat.paymentMethod()).isEqualTo("WECHAT"); assertThat(wechat.enabled()).isTrue(); },
+            alipay -> { assertThat(alipay.paymentMethod()).isEqualTo("ALIPAY"); assertThat(alipay.enabled()).isFalse(); });
+    }
+
+    @Test
+    void manualDeductionCannotExceedAvailableBalance() throws Exception {
+        JdbcTemplate jdbc = mock(JdbcTemplate.class);
+        when(jdbc.queryForList(startsWith("SELECT request_hash"), any(Object[].class))).thenReturn(List.of());
+        when(jdbc.update(startsWith("INSERT INTO fin_idempotency_record"), any(Object[].class))).thenReturn(1);
+        when(jdbc.update(startsWith("INSERT IGNORE INTO fin_wallet_account"), any(Object[].class))).thenReturn(1);
+        when(jdbc.queryForObject(startsWith("SELECT currency_code"), any(RowMapper.class), eq(9L))).thenAnswer(invocation -> {
+            @SuppressWarnings("unchecked") RowMapper<Object> mapper = invocation.getArgument(1);
+            ResultSet rs = mock(ResultSet.class);
+            when(rs.getString("currency_code")).thenReturn("CNY");
+            when(rs.getBigDecimal("actual_balance")).thenReturn(new BigDecimal("10.00"));
+            when(rs.getBigDecimal("frozen_balance")).thenReturn(BigDecimal.ZERO);
+            when(rs.getBigDecimal("available_balance")).thenReturn(new BigDecimal("10.00"));
+            when(rs.getInt("version")).thenReturn(2);
+            when(rs.getTimestamp("updated_at")).thenReturn(Timestamp.valueOf("2026-09-05 08:00:00"));
+            return mapper.mapRow(rs, 0);
+        });
+
+        assertThatThrownBy(() -> service(jdbc, "x", "y").adjust(9L, 7L, "财务员", "deduct-1",
+            new AccountAdjustmentRequest("DEDUCTION", new BigDecimal("10.01"), LocalDate.now(),
+                "BANK_TRANSFER", "REF-1", "人工扣款", 2)))
+            .isInstanceOf(FinanceEventException.class)
+            .extracting(error -> ((FinanceEventException) error).code()).isEqualTo("FIN-WALLET-INSUFFICIENT");
+        verify(jdbc, never()).update(startsWith("UPDATE fin_wallet_account SET actual_balance="), any(Object[].class));
+    }
+
+    private static FinanceWalletService service(JdbcTemplate jdbc, String wechat, String alipay) {
+        return new FinanceWalletService(jdbc, new ObjectMapper().findAndRegisterModules(),
+            mock(FinanceFileClient.class), mock(FinanceDocumentNumberGenerator.class), "token", wechat, alipay);
+    }
+}

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

@@ -0,0 +1,41 @@
+package com.baiyue.finance;
+
+import org.junit.jupiter.api.Test;
+
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class FinanceWalletContractTest {
+    @Test
+    void schemaKeepsBalancesConsistentAndRechargeReviewTraceable() throws Exception {
+        String sql = Files.readString(Path.of("src/main/resources/db/finance.sql"), StandardCharsets.UTF_8);
+        assertThat(sql)
+            .contains("CREATE TABLE IF NOT EXISTS fin_wallet_account")
+            .contains("actual_balance = frozen_balance + available_balance")
+            .contains("CREATE TABLE IF NOT EXISTS fin_recharge_request")
+            .contains("status IN ('PENDING','APPROVED','REJECTED')")
+            .contains("CREATE TABLE IF NOT EXISTS fin_wallet_ledger")
+            .contains("amount <> 0")
+            .contains("uk_fin_wallet_ledger_no")
+            .contains("idx_fin_recharge_customer_status");
+    }
+
+    @Test
+    void controllersEnforceCustomerScopeAndSeparateWritePermissions() throws Exception {
+        String client = Files.readString(Path.of("src/main/java/com/baiyue/finance/controller/ClientFinanceWalletController.java"));
+        String platform = Files.readString(Path.of("src/main/java/com/baiyue/finance/controller/PlatformFinanceWalletController.java"));
+        assertThat(client)
+            .contains("user.tenantId()")
+            .contains("merchant:finance:account:view")
+            .contains("merchant:finance:recharge:create")
+            .contains("consumes = \"multipart/form-data\"")
+            .doesNotContain("@RequestParam long customerId");
+        assertThat(platform)
+            .contains("platform:finance:recharge:review")
+            .contains("platform:finance:customer-account:adjust")
+            .contains("Idempotency-Key");
+    }
+}