feat(account): 대출 계좌 loan_amount/loan_rate/loan_method/loan_months/loan_start 필드 추가

- wallet 테이블: loan_amount(실행금액), loan_rate(연이자율%), loan_method(상환방식),
  loan_months(기간), loan_start(시작일) ALTER TABLE 추가
- Wallet 도메인/DTO/Mapper/Service 동기화
- WalletResponse.from()에 대출 필드 반영

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.gitignore

@@ -2,6 +2,10 @@ HELP.md
 .gradle
 build/
 
+# 로컬 전용 테스트/시드 스크립트 (실제 이메일·프리미엄 부여 포함 — 커밋 금지)
+scripts/seed-test-*.sql
+scripts/cleanup-test-*.sql
+
 # 환경변수 / 비밀 정보 (실제 .env 는 커밋 금지, .env.example 만 추적)
 .env
 !gradle/wrapper/gradle-wrapper.jar

src/main/java/com/sb/web/account/controller/BudgetController.java

@@ -50,8 +50,22 @@ public class BudgetController {
 
     @GetMapping
     public List<BudgetResponse> list(
+            @RequestParam int year,
+            @RequestParam int month,
             @RequestAttribute(AuthInterceptor.CURRENT_MEMBER) SessionUser current) {
-        return budgetService.list(current.getId());
+        return budgetService.list(current.getId(), year, month);
+    }
+
+    /** 다른 월의 예산을 이 달로 복사(전월 복사 등). 같은 분류는 덮어씀 */
+    @PostMapping("/copy")
+    public List<BudgetResponse> copy(
+            @RequestParam int fromYear,
+            @RequestParam int fromMonth,
+            @RequestParam int toYear,
+            @RequestParam int toMonth,
+            @RequestAttribute(AuthInterceptor.CURRENT_MEMBER) SessionUser current) {
+        budgetService.copy(current.getId(), fromYear, fromMonth, toYear, toMonth);
+        return budgetService.list(current.getId(), toYear, toMonth);
     }
 
     @GetMapping("/status")
@@ -74,9 +88,11 @@ public class BudgetController {
 
     @PostMapping
     public ResponseEntity<BudgetResponse> create(
+            @RequestParam int year,
+            @RequestParam int month,
             @Valid @RequestBody BudgetRequest req,
             @RequestAttribute(AuthInterceptor.CURRENT_MEMBER) SessionUser current) {
-        return ResponseEntity.status(HttpStatus.CREATED).body(budgetService.create(req, current.getId()));
+        return ResponseEntity.status(HttpStatus.CREATED).body(budgetService.create(req, current.getId(), year, month));
     }
 
     @PutMapping("/{id}")

src/main/java/com/sb/web/account/controller/FxController.java

@@ -0,0 +1,37 @@
+package com.sb.web.account.controller;
+
+import com.sb.web.account.service.FxService;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import java.math.BigDecimal;
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * 환율 조회 API. 외화 결제 입력 시 통화→원화 환율 자동 채움용.
+ *   GET /api/fx/rate?from=USD&to=KRW  →  { from, to, rate }
+ */
+@RestController
+@RequestMapping("/api/fx")
+public class FxController {
+
+    private final FxService fxService;
+
+    public FxController(FxService fxService) {
+        this.fxService = fxService;
+    }
+
+    @GetMapping("/rate")
+    public Map<String, Object> rate(@RequestParam String from,
+                                    @RequestParam(defaultValue = "KRW") String to) {
+        BigDecimal rate = fxService.getRate(from, to);
+        Map<String, Object> res = new HashMap<>();
+        res.put("from", from == null ? null : from.toUpperCase());
+        res.put("to", to == null ? null : to.toUpperCase());
+        res.put("rate", rate); // 조회 실패 시 null
+        return res;
+    }
+}

src/main/java/com/sb/web/account/domain/AccountEntry.java

@@ -6,6 +6,7 @@ import lombok.Data;
 import lombok.NoArgsConstructor;
 
 import java.io.Serializable;
+import java.math.BigDecimal;
 import java.time.LocalDate;
 import java.time.LocalDateTime;
 
@@ -30,6 +31,9 @@ public class AccountEntry implements Serializable {
     private Long toWalletId;    // 이체 입금 계좌
     private String toWalletName;
     private Integer installmentMonths; // 카드 할부 개월수(2~24, 일시불은 null)
+    private String currency;            // 외화 통화코드(USD 등). null/KRW = 원화
+    private BigDecimal originalAmount;  // 외화 원본 금액
+    private BigDecimal exchangeRate;    // 적용 환율(외화 1단위→원화)
     private Boolean pending;     // 확인 필요(미확정) 여부 — 알림 자동인식 건
     private String notifKey;     // 알림 자동인식 중복방지 키
     private LocalDateTime createdAt;

src/main/java/com/sb/web/account/domain/Budget.java

@@ -28,6 +28,8 @@ public class Budget implements Serializable {
     private Long weekly;
     private Long monthly;
     private Long yearly;
+    private Integer year;      // 예산 연도(월별 예산)
+    private Integer month;     // 예산 월(1~12)
     private LocalDateTime createdAt;
     private LocalDateTime updatedAt;
 }

src/main/java/com/sb/web/account/domain/Wallet.java

@@ -6,6 +6,7 @@ import lombok.Data;
 import lombok.NoArgsConstructor;
 
 import java.io.Serializable;
+import java.math.BigDecimal;
 import java.time.LocalDate;
 import java.time.LocalDateTime;
 
@@ -29,6 +30,11 @@ public class Wallet implements Serializable {
     private Long openingBalance;  // 초기 잔액(부호있음: 자산+, 부채-)
     private LocalDate openingDate;
     private Long currentValue;    // 현재 평가금액 (INVEST 전용, 수동 갱신)
+    private Long loanAmount;       // 대출 실행 금액(원금, 처음 빌린 금액) (LOAN 전용)
+    private BigDecimal loanRate;   // 연이자율(%) e.g. 5.25 (LOAN 전용)
+    private String loanMethod;     // 상환방식: EQUAL_PAYMENT / EQUAL_PRINCIPAL / BULLET (LOAN 전용)
+    private Integer loanMonths;    // 대출기간(개월) (LOAN 전용)
+    private LocalDate loanStart;   // 대출시작일 (LOAN 전용)
     private Integer sortOrder;    // 표시 순서 (타입 내 정렬)
     private LocalDateTime createdAt;
     private LocalDateTime updatedAt;

src/main/java/com/sb/web/account/dto/AccountEntryRequest.java

@@ -9,6 +9,7 @@ import jakarta.validation.constraints.PositiveOrZero;
 import jakarta.validation.constraints.Size;
 import lombok.Data;
 
+import java.math.BigDecimal;
 import java.time.LocalDate;
 import java.util.List;
 
@@ -48,4 +49,10 @@ public class AccountEntryRequest {
 
     /** 선택한 태그 ID 목록 (태그 관리에 등록된 태그, 선택) */
     private List<Long> tagIds;
+
+    /** 외화 결제(선택). currency 가 있으면 amount 는 환산된 원화여야 한다. */
+    @Size(max = 3, message = "통화코드가 올바르지 않습니다.")
+    private String currency;          // USD/JPY 등. null/KRW = 원화
+    private BigDecimal originalAmount; // 외화 원본 금액
+    private BigDecimal exchangeRate;   // 적용 환율(외화 1단위→원화)
 }

src/main/java/com/sb/web/account/dto/AccountEntryResponse.java

@@ -4,6 +4,7 @@ import com.sb.web.account.domain.AccountEntry;
 import lombok.Builder;
 import lombok.Data;
 
+import java.math.BigDecimal;
 import java.time.LocalDate;
 import java.util.List;
 
@@ -26,6 +27,9 @@ public class AccountEntryResponse {
     private String toWalletName;
     private Integer installmentMonths;
     private Boolean pending;
+    private String currency;
+    private BigDecimal originalAmount;
+    private BigDecimal exchangeRate;
     private List<String> tags;
 
     public static AccountEntryResponse from(AccountEntry e, List<String> tags) {
@@ -42,6 +46,9 @@ public class AccountEntryResponse {
                 .toWalletName(e.getToWalletName())
                 .installmentMonths(e.getInstallmentMonths())
                 .pending(Boolean.TRUE.equals(e.getPending()))
+                .currency(e.getCurrency())
+                .originalAmount(e.getOriginalAmount())
+                .exchangeRate(e.getExchangeRate())
                 .tags(tags)
                 .build();
     }

src/main/java/com/sb/web/account/dto/WalletRequest.java

@@ -1,10 +1,13 @@
 package com.sb.web.account.dto;
 
+import jakarta.validation.constraints.DecimalMax;
+import jakarta.validation.constraints.DecimalMin;
 import jakarta.validation.constraints.NotBlank;
 import jakarta.validation.constraints.Pattern;
 import jakarta.validation.constraints.Size;
 import lombok.Data;
 
+import java.math.BigDecimal;
 import java.time.LocalDate;
 
 /**
@@ -37,4 +40,17 @@ public class WalletRequest {
 
     /** 현재 평가금액 (INVEST 전용, 수동 갱신) */
     private Long currentValue;
+
+    // ===== 대출(LOAN) 전용 =====
+    private Long loanAmount;       // 대출 실행 금액(원금)
+
+    @DecimalMin(value = "0.0", inclusive = true)
+    @DecimalMax(value = "100.0", message = "이자율은 100% 이하여야 합니다.")
+    private BigDecimal loanRate;   // 연이자율(%)
+
+    @Pattern(regexp = "EQUAL_PAYMENT|EQUAL_PRINCIPAL|BULLET|", message = "상환방식이 올바르지 않습니다.")
+    private String loanMethod;     // 상환방식
+
+    private Integer loanMonths;    // 대출기간(개월)
+    private LocalDate loanStart;   // 대출시작일
 }

src/main/java/com/sb/web/account/dto/WalletResponse.java

@@ -4,6 +4,7 @@ import com.sb.web.account.domain.Wallet;
 import lombok.Builder;
 import lombok.Data;
 
+import java.math.BigDecimal;
 import java.time.LocalDate;
 
 /**
@@ -31,6 +32,13 @@ public class WalletResponse {
     private Long currentValue;    // 평가액 직접입력값(퇴직연금·연금 등 수동 갱신). 있으면 총평가로 사용
     private Boolean manualValuation; // true면 평가액 직접입력형(종목 자동계산 대신)
 
+    // 대출(LOAN) 전용
+    private Long loanAmount;       // 대출 실행 금액(원금)
+    private BigDecimal loanRate;   // 연이자율(%) e.g. 5.25
+    private String loanMethod;     // EQUAL_PAYMENT / EQUAL_PRINCIPAL / BULLET
+    private Integer loanMonths;    // 대출기간(개월)
+    private LocalDate loanStart;   // 대출시작일
+
     public static WalletResponse from(Wallet w, long balance) {
         return WalletResponse.builder()
                 .id(w.getId())
@@ -43,6 +51,11 @@ public class WalletResponse {
                 .openingDate(w.getOpeningDate())
                 .balance(balance)
                 .currentValue(w.getCurrentValue())
+                .loanAmount(w.getLoanAmount())
+                .loanRate(w.getLoanRate())
+                .loanMethod(w.getLoanMethod())
+                .loanMonths(w.getLoanMonths())
+                .loanStart(w.getLoanStart())
                 .build();
     }
 }

src/main/java/com/sb/web/account/mapper/BudgetMapper.java

@@ -12,13 +12,24 @@ import java.util.List;
 @Mapper
 public interface BudgetMapper {
 
-    List<Budget> findByMember(@Param("memberId") Long memberId);
+    List<Budget> findByMember(@Param("memberId") Long memberId,
+                              @Param("year") Integer year,
+                              @Param("month") Integer month);
 
     Budget findByIdAndMember(@Param("id") Long id, @Param("memberId") Long memberId);
 
     int countByCategory(@Param("memberId") Long memberId,
                         @Param("category") String category,
-                        @Param("excludeId") Long excludeId);
+                        @Param("excludeId") Long excludeId,
+                        @Param("year") Integer year,
+                        @Param("month") Integer month);
+
+    /** fromYear/fromMonth 예산을 toYear/toMonth 로 복사(같은 분류는 덮어씀). 복사된 건수 반환 */
+    int copyMonth(@Param("memberId") Long memberId,
+                  @Param("fromYear") Integer fromYear,
+                  @Param("fromMonth") Integer fromMonth,
+                  @Param("toYear") Integer toYear,
+                  @Param("toMonth") Integer toMonth);
 
     int insert(Budget budget);
 

src/main/java/com/sb/web/account/service/AccountService.java

@@ -234,6 +234,9 @@ public class AccountService {
                 .walletId(req.getWalletId())
                 .toWalletId(transfer ? req.getToWalletId() : null)
                 .installmentMonths(installmentOf(req))
+                .currency(req.getCurrency())
+                .originalAmount(req.getOriginalAmount())
+                .exchangeRate(req.getExchangeRate())
                 .build();
         mapper.insert(entry);
         applyTags(entry.getId(), req.getTagIds(), memberId);
@@ -253,6 +256,9 @@ public class AccountService {
         entry.setWalletId(req.getWalletId());
         entry.setToWalletId(transfer ? req.getToWalletId() : null);
         entry.setInstallmentMonths(installmentOf(req));
+        entry.setCurrency(req.getCurrency());
+        entry.setOriginalAmount(req.getOriginalAmount());
+        entry.setExchangeRate(req.getExchangeRate());
         mapper.update(entry);
 
         mapper.deleteEntryTagsByEntryId(id);
@@ -529,6 +535,12 @@ public class AccountService {
         wallet.setOpeningBalance(req.getOpeningBalance() != null ? req.getOpeningBalance() : 0L);
         wallet.setOpeningDate(req.getOpeningDate());
         wallet.setCurrentValue("INVEST".equals(req.getType()) ? req.getCurrentValue() : null);
+        boolean isLoan = "LOAN".equals(req.getType());
+        wallet.setLoanAmount(isLoan ? req.getLoanAmount() : null);
+        wallet.setLoanRate(isLoan ? req.getLoanRate() : null);
+        wallet.setLoanMethod(isLoan ? blankToNull(req.getLoanMethod()) : null);
+        wallet.setLoanMonths(isLoan ? req.getLoanMonths() : null);
+        wallet.setLoanStart(isLoan ? req.getLoanStart() : null);
         walletMapper.update(wallet);
         return WalletResponse.from(wallet, balanceMap(memberId).getOrDefault(id, wallet.getOpeningBalance()));
     }
@@ -558,6 +570,7 @@ public class AccountService {
     }
 
     private Wallet toWallet(WalletRequest req) {
+        boolean isLoan = "LOAN".equals(req.getType());
         return Wallet.builder()
                 .type(req.getType())
                 .name(req.getName().trim())
@@ -567,6 +580,11 @@ public class AccountService {
                 .openingBalance(req.getOpeningBalance() != null ? req.getOpeningBalance() : 0L)
                 .openingDate(req.getOpeningDate())
                 .currentValue("INVEST".equals(req.getType()) ? req.getCurrentValue() : null)
+                .loanAmount(isLoan ? req.getLoanAmount() : null)
+                .loanRate(isLoan ? req.getLoanRate() : null)
+                .loanMethod(isLoan ? blankToNull(req.getLoanMethod()) : null)
+                .loanMonths(isLoan ? req.getLoanMonths() : null)
+                .loanStart(isLoan ? req.getLoanStart() : null)
                 .build();
     }
 

src/main/java/com/sb/web/account/service/BackupService.java

@@ -156,11 +156,12 @@ public class BackupService {
             }
         }
 
-        // 7) 예산
+        // 7) 예산 — 복구 시 현재 월 예산으로 등록(백업엔 월 정보 없음)
         if (req.getBudgets() != null) {
+            java.time.LocalDate today = java.time.LocalDate.now();
             for (BudgetRequest b : req.getBudgets()) {
                 if (b == null || b.getCategory() == null) continue;
-                budgetService.create(b, memberId);
+                budgetService.create(b, memberId, today.getYear(), today.getMonthValue());
             }
         }
 

src/main/java/com/sb/web/account/service/BudgetService.java

@@ -31,36 +31,46 @@ public class BudgetService {
     private final BudgetMapper budgetMapper;
     private final AccountEntryMapper entryMapper;
 
-    public List<BudgetResponse> list(Long memberId) {
-        return budgetMapper.findByMember(memberId).stream().map(BudgetResponse::from).toList();
+    public List<BudgetResponse> list(Long memberId, int year, int month) {
+        return budgetMapper.findByMember(memberId, year, month).stream().map(BudgetResponse::from).toList();
     }
 
     @Transactional
-    public BudgetResponse create(BudgetRequest req, Long memberId) {
+    public BudgetResponse create(BudgetRequest req, Long memberId, int year, int month) {
         String category = req.getCategory().trim();
-        if (budgetMapper.countByCategory(memberId, category, null) > 0) {
+        if (budgetMapper.countByCategory(memberId, category, null, year, month) > 0) {
             throw new ApiException(HttpStatus.CONFLICT, "이미 예산이 설정된 카테고리입니다.");
         }
         Budget budget = toBudget(req, category);
         budget.setMemberId(memberId);
+        budget.setYear(year);
+        budget.setMonth(month);
         budgetMapper.insert(budget);
         return BudgetResponse.from(budget);
     }
 
     @Transactional
     public BudgetResponse update(Long id, BudgetRequest req, Long memberId) {
-        mustFind(id, memberId);
+        Budget existing = mustFind(id, memberId);
         String category = req.getCategory().trim();
-        if (budgetMapper.countByCategory(memberId, category, id) > 0) {
+        if (budgetMapper.countByCategory(memberId, category, id, existing.getYear(), existing.getMonth()) > 0) {
             throw new ApiException(HttpStatus.CONFLICT, "이미 예산이 설정된 카테고리입니다.");
         }
         Budget budget = toBudget(req, category);
         budget.setId(id);
         budget.setMemberId(memberId);
+        budget.setYear(existing.getYear());
+        budget.setMonth(existing.getMonth());
         budgetMapper.update(budget);
         return BudgetResponse.from(budget);
     }
 
+    /** fromYear/fromMonth 예산을 toYear/toMonth 로 복사(같은 분류 덮어씀). 복사된 건수 반환 */
+    @Transactional
+    public int copy(Long memberId, int fromYear, int fromMonth, int toYear, int toMonth) {
+        return budgetMapper.copyMonth(memberId, fromYear, fromMonth, toYear, toMonth);
+    }
+
     @Transactional
     public void delete(Long id, Long memberId) {
         mustFind(id, memberId);
@@ -79,7 +89,7 @@ public class BudgetService {
         }
 
         List<BudgetStatus> result = new ArrayList<>();
-        for (Budget b : budgetMapper.findByMember(memberId)) {
+        for (Budget b : budgetMapper.findByMember(memberId, year, month)) {
             long monthlyBudget = monthlyBudget(b, daysInMonth);
             long spent = spentByCategory.getOrDefault(b.getCategory(), 0L);
             result.add(BudgetStatus.builder()
@@ -103,7 +113,8 @@ public class BudgetService {
         int y = year != null ? year : Year.now().getValue();
         int m = month != null ? month : 1;
 
-        List<Budget> budgets = budgetMapper.findByMember(memberId);
+        // 기간 차트는 선택 월의 예산을 기준으로 각 버킷에 적용(월별 예산 도입 전 동작과 동일)
+        List<Budget> budgets = budgetMapper.findByMember(memberId, y, m);
         Map<String, Long> expense = new HashMap<>();
         for (Map<String, Object> row : entryMapper.statsByPeriod(memberId, unit, year, month)) {
             expense.put(String.valueOf(((Number) row.get("bucket")).longValue()),

src/main/java/com/sb/web/account/service/FxService.java

@@ -0,0 +1,64 @@
+package com.sb.web.account.service;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+import org.springframework.web.client.RestClient;
+
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * 환율 조회. open.er-api.com(무료·무인증) 사용. 통화(base)별로 하루 1회만 호출하고 캐시.
+ * 실패해도 예외를 던지지 않고 null(또는 직전 캐시) 반환.
+ */
+@Slf4j
+@Service
+public class FxService {
+
+    private static final String URL = "https://open.er-api.com/v6/latest/{base}";
+    private final RestClient restClient = RestClient.builder().build();
+
+    private record Cached(LocalDate date, JsonNode rates) {}
+    private final Map<String, Cached> cache = new ConcurrentHashMap<>();
+
+    /** from 통화 1단위 → to 통화 환율. 조회 실패 시 null. */
+    public BigDecimal getRate(String from, String to) {
+        if (from == null || to == null) return null;
+        String base = from.trim().toUpperCase();
+        String target = to.trim().toUpperCase();
+        if (base.isEmpty() || target.isEmpty()) return null;
+        if (base.equals(target)) return BigDecimal.ONE;
+        JsonNode rates = ratesFor(base);
+        if (rates == null) return null;
+        JsonNode r = rates.get(target);
+        return (r != null && r.isNumber()) ? r.decimalValue() : null;
+    }
+
+    private JsonNode ratesFor(String base) {
+        Cached c = cache.get(base);
+        LocalDate today = LocalDate.now();
+        if (c != null && c.date().equals(today)) return c.rates();
+        try {
+            JsonNode root = restClient.get()
+                    .uri(URL, base)
+                    .header("User-Agent", "Mozilla/5.0")
+                    .retrieve()
+                    .body(JsonNode.class);
+            if (root == null || !"success".equals(root.path("result").asText())) {
+                return c != null ? c.rates() : null;
+            }
+            JsonNode rates = root.path("rates");
+            if (rates.isMissingNode() || !rates.isObject()) {
+                return c != null ? c.rates() : null;
+            }
+            cache.put(base, new Cached(today, rates));
+            return rates;
+        } catch (Exception e) {
+            log.warn("환율 조회 실패 base={}: {}", base, e.toString());
+            return c != null ? c.rates() : null; // 실패 시 직전 캐시라도
+        }
+    }
+}

src/main/java/com/sb/web/common/config/WebConfig.java

@@ -28,7 +28,7 @@ public class WebConfig implements WebMvcConfigurer {
                 .addPathPatterns("/api/auth/me", "/api/auth/points", "/api/auth/point-history",
                         "/api/auth/logout", "/api/auth/password",
                         "/api/auth/verify-password", "/api/auth/profile", "/api/auth/profile-image",
-                        "/api/board/**", "/api/admin/**", "/api/account/**", "/api/billing/**")
+                        "/api/board/**", "/api/admin/**", "/api/account/**", "/api/billing/**", "/api/fx/**")
                 // Google Play RTDN(서버 알림)은 비인증 — Google 이 호출
                 .excludePathPatterns("/api/billing/google/rtdn");
         // 인가: 관리자 전용 경로 (authInterceptor 다음에 실행되어 role 검사)

src/main/resources/db/account.sql

@@ -28,6 +28,11 @@ ALTER TABLE wallet ADD COLUMN IF NOT EXISTS opening_balance BIGINT NOT NULL DEFA
 ALTER TABLE wallet ADD COLUMN IF NOT EXISTS opening_date DATE NULL;
 ALTER TABLE wallet ADD COLUMN IF NOT EXISTS current_value BIGINT NULL;
 ALTER TABLE wallet ADD COLUMN IF NOT EXISTS sort_order INT NOT NULL DEFAULT 0;
+ALTER TABLE wallet ADD COLUMN IF NOT EXISTS loan_rate    DECIMAL(7,4) NULL COMMENT '연이자율(%) 예: 5.2500';
+ALTER TABLE wallet ADD COLUMN IF NOT EXISTS loan_method  VARCHAR(20)  NULL COMMENT '상환방식: EQUAL_PAYMENT/EQUAL_PRINCIPAL/BULLET';
+ALTER TABLE wallet ADD COLUMN IF NOT EXISTS loan_months  INT          NULL COMMENT '대출기간(개월)';
+ALTER TABLE wallet ADD COLUMN IF NOT EXISTS loan_start   DATE         NULL COMMENT '대출시작일';
+ALTER TABLE wallet ADD COLUMN IF NOT EXISTS loan_amount  BIGINT       NULL COMMENT '대출 실행 금액(원금, 처음 빌린 금액)';
 -- 계좌번호 암호화 저장(AES-GCM)으로 평문보다 길어 VARCHAR(255) 필요 — 운영 적용 완료(CREATE TABLE 정의에 반영).
 -- 매 기동 MODIFY 는 라이브 테이블 락 위험이 있어 제거. 기존 환경 확장이 필요하면 1회 수동 적용:
 --   ALTER TABLE wallet MODIFY account_number VARCHAR(255) NULL;
@@ -59,6 +64,10 @@ ALTER TABLE account_entry ADD COLUMN IF NOT EXISTS installment_months INT NULL;
 ALTER TABLE account_entry ADD COLUMN IF NOT EXISTS pending TINYINT(1) NOT NULL DEFAULT 0 COMMENT '확인 필요(미확정) 여부';
 ALTER TABLE account_entry ADD COLUMN IF NOT EXISTS notif_key VARCHAR(160) NULL COMMENT '알림 자동인식 중복방지 키';
 ALTER TABLE account_entry ADD INDEX IF NOT EXISTS idx_entry_notif (member_id, notif_key);
+-- 외화 결제: amount 는 환산된 원화(표준값, 통계·예산은 이 값 사용). 아래는 외화 원본 보존용.
+ALTER TABLE account_entry ADD COLUMN IF NOT EXISTS currency VARCHAR(3) NULL COMMENT '통화코드(USD/JPY 등). NULL/KRW=원화';
+ALTER TABLE account_entry ADD COLUMN IF NOT EXISTS original_amount DECIMAL(18,2) NULL COMMENT '외화 원본 금액';
+ALTER TABLE account_entry ADD COLUMN IF NOT EXISTS exchange_rate DECIMAL(18,6) NULL COMMENT '적용 환율(외화 1단위→원화)';
 
 -- 가계부 태그 (사용자별 관리 — 게시판 태그와 분리)
 CREATE TABLE IF NOT EXISTS account_tag (
@@ -161,6 +170,15 @@ CREATE TABLE IF NOT EXISTS budget (
     UNIQUE KEY uk_budget_member_category (member_id, category)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
 
+-- 월별 예산: 예산을 연/월별로 분리(전월 복사로 다음 달에 동일 예산 저장 가능).
+ALTER TABLE budget ADD COLUMN IF NOT EXISTS `year`  INT NULL COMMENT '예산 연도';
+ALTER TABLE budget ADD COLUMN IF NOT EXISTS `month` INT NULL COMMENT '예산 월(1~12)';
+-- 기존 상시 예산을 현재 연/월로 1회 이관
+UPDATE budget SET `year` = YEAR(NOW()), `month` = MONTH(NOW()) WHERE `year` IS NULL OR `month` IS NULL;
+-- 분류 유니크를 (member,category) → (member,category,year,month) 로 교체
+ALTER TABLE budget DROP INDEX IF EXISTS uk_budget_member_category;
+ALTER TABLE budget ADD UNIQUE KEY IF NOT EXISTS uk_budget_member_cat_ym (member_id, category, `year`, `month`);
+
 -- 가계부 항목 - 태그 (다대다, tag_id 는 account_tag.id 참조)
 CREATE TABLE IF NOT EXISTS account_entry_tag (
     entry_id BIGINT NOT NULL,

src/main/resources/mapper/AccountEntryMapper.xml

@@ -18,6 +18,9 @@
         <result property="installmentMonths" column="installment_months"/>
         <result property="pending" column="pending"/>
         <result property="notifKey" column="notif_key"/>
+        <result property="currency" column="currency"/>
+        <result property="originalAmount" column="original_amount"/>
+        <result property="exchangeRate" column="exchange_rate"/>
         <result property="createdAt" column="created_at"/>
         <result property="updatedAt" column="updated_at"/>
     </resultMap>
@@ -32,6 +35,7 @@
         e.wallet_id, w.name AS wallet_name,
         e.to_wallet_id, tw.name AS to_wallet_name,
         e.installment_months, e.pending, e.notif_key,
+        e.currency, e.original_amount, e.exchange_rate,
         e.created_at, e.updated_at
     </sql>
     <sql id="entryJoins">
@@ -141,17 +145,20 @@
             useGeneratedKeys="true" keyProperty="id">
         INSERT INTO account_entry (member_id, entry_date, type, category, amount, memo,
                                    wallet_id, to_wallet_id, installment_months, pending, notif_key,
+                                   currency, original_amount, exchange_rate,
                                    created_at, updated_at)
         VALUES (#{memberId}, #{entryDate}, #{type}, #{category}, #{amount}, #{memo},
                 #{walletId}, #{toWalletId}, #{installmentMonths},
-                COALESCE(#{pending}, 0), #{notifKey}, NOW(), NOW())
+                COALESCE(#{pending}, 0), #{notifKey},
+                #{currency}, #{originalAmount}, #{exchangeRate}, NOW(), NOW())
     </insert>
 
     <update id="update" parameterType="com.sb.web.account.domain.AccountEntry">
         UPDATE account_entry
         SET entry_date = #{entryDate}, type = #{type}, category = #{category},
             amount = #{amount}, memo = #{memo}, wallet_id = #{walletId}, to_wallet_id = #{toWalletId},
-            installment_months = #{installmentMonths}
+            installment_months = #{installmentMonths},
+            currency = #{currency}, original_amount = #{originalAmount}, exchange_rate = #{exchangeRate}
         WHERE id = #{id} AND member_id = #{memberId}
     </update>
 

src/main/resources/mapper/BudgetMapper.xml

@@ -14,15 +14,19 @@
         <result property="weekly" column="weekly"/>
         <result property="monthly" column="monthly"/>
         <result property="yearly" column="yearly"/>
+        <result property="year" column="year"/>
+        <result property="month" column="month"/>
         <result property="createdAt" column="created_at"/>
         <result property="updatedAt" column="updated_at"/>
     </resultMap>
 
     <sql id="cols">id, member_id, category, fixed, base_unit, base_amount,
-        daily, weekly, monthly, yearly, created_at, updated_at</sql>
+        daily, weekly, monthly, yearly, `year`, `month`, created_at, updated_at</sql>
 
-    <select id="findByMember" parameterType="long" resultMap="budgetResultMap">
-        SELECT <include refid="cols"/> FROM budget WHERE member_id = #{memberId} ORDER BY category
+    <select id="findByMember" resultMap="budgetResultMap">
+        SELECT <include refid="cols"/> FROM budget
+        WHERE member_id = #{memberId} AND `year` = #{year} AND `month` = #{month}
+        ORDER BY category
     </select>
 
     <select id="findByIdAndMember" resultMap="budgetResultMap">
@@ -32,15 +36,30 @@
     <select id="countByCategory" resultType="int">
         SELECT COUNT(*) FROM budget
         WHERE member_id = #{memberId} AND category = #{category}
+          AND `year` = #{year} AND `month` = #{month}
         <if test="excludeId != null">AND id != #{excludeId}</if>
     </select>
 
     <insert id="insert" parameterType="com.sb.web.account.domain.Budget"
             useGeneratedKeys="true" keyProperty="id">
         INSERT INTO budget (member_id, category, fixed, base_unit, base_amount,
-                            daily, weekly, monthly, yearly, created_at, updated_at)
+                            daily, weekly, monthly, yearly, `year`, `month`, created_at, updated_at)
         VALUES (#{memberId}, #{category}, #{fixed}, #{baseUnit}, #{baseAmount},
-                #{daily}, #{weekly}, #{monthly}, #{yearly}, NOW(), NOW())
+                #{daily}, #{weekly}, #{monthly}, #{yearly}, #{year}, #{month}, NOW(), NOW())
+    </insert>
+
+    <!-- 전월(또는 임의 월) 예산을 다른 월로 복사. 같은 분류는 덮어씀(ON DUPLICATE) -->
+    <insert id="copyMonth">
+        INSERT INTO budget (member_id, category, fixed, base_unit, base_amount,
+                            daily, weekly, monthly, yearly, `year`, `month`, created_at, updated_at)
+        SELECT member_id, category, fixed, base_unit, base_amount,
+               daily, weekly, monthly, yearly, #{toYear}, #{toMonth}, NOW(), NOW()
+        FROM budget
+        WHERE member_id = #{memberId} AND `year` = #{fromYear} AND `month` = #{fromMonth}
+        ON DUPLICATE KEY UPDATE
+            fixed = VALUES(fixed), base_unit = VALUES(base_unit), base_amount = VALUES(base_amount),
+            daily = VALUES(daily), weekly = VALUES(weekly), monthly = VALUES(monthly),
+            yearly = VALUES(yearly), updated_at = NOW()
     </insert>
 
     <update id="update" parameterType="com.sb.web.account.domain.Budget">

src/main/resources/mapper/WalletMapper.xml

@@ -15,13 +15,20 @@
         <result property="openingBalance" column="opening_balance"/>
         <result property="openingDate" column="opening_date"/>
         <result property="currentValue" column="current_value"/>
+        <result property="loanAmount" column="loan_amount"/>
+        <result property="loanRate" column="loan_rate"/>
+        <result property="loanMethod" column="loan_method"/>
+        <result property="loanMonths" column="loan_months"/>
+        <result property="loanStart" column="loan_start"/>
         <result property="sortOrder" column="sort_order"/>
         <result property="createdAt" column="created_at"/>
         <result property="updatedAt" column="updated_at"/>
     </resultMap>
 
     <sql id="cols">id, member_id, type, name, issuer, account_number, card_type,
-        opening_balance, opening_date, current_value, sort_order, created_at, updated_at</sql>
+        opening_balance, opening_date, current_value,
+        loan_amount, loan_rate, loan_method, loan_months, loan_start,
+        sort_order, created_at, updated_at</sql>
 
     <select id="findByMember" parameterType="long" resultMap="walletResultMap">
         SELECT <include refid="cols"/> FROM wallet
@@ -37,10 +44,14 @@
     <insert id="insert" parameterType="com.sb.web.account.domain.Wallet"
             useGeneratedKeys="true" keyProperty="id">
         INSERT INTO wallet (member_id, type, name, issuer, account_number, card_type,
-                            opening_balance, opening_date, current_value, sort_order, created_at, updated_at)
+                            opening_balance, opening_date, current_value,
+                            loan_amount, loan_rate, loan_method, loan_months, loan_start,
+                            sort_order, created_at, updated_at)
         VALUES (#{memberId}, #{type}, #{name}, #{issuer},
                 #{accountNumber, typeHandler=com.sb.web.common.crypto.EncryptedStringTypeHandler}, #{cardType},
-                #{openingBalance}, #{openingDate}, #{currentValue}, #{sortOrder}, NOW(), NOW())
+                #{openingBalance}, #{openingDate}, #{currentValue},
+                #{loanAmount}, #{loanRate}, #{loanMethod}, #{loanMonths}, #{loanStart},
+                #{sortOrder}, NOW(), NOW())
     </insert>
 
     <update id="update" parameterType="com.sb.web.account.domain.Wallet">
@@ -49,7 +60,10 @@
             account_number = #{accountNumber, typeHandler=com.sb.web.common.crypto.EncryptedStringTypeHandler},
             card_type = #{cardType},
             opening_balance = #{openingBalance}, opening_date = #{openingDate},
-            current_value = #{currentValue}
+            current_value = #{currentValue},
+            loan_amount = #{loanAmount},
+            loan_rate = #{loanRate}, loan_method = #{loanMethod},
+            loan_months = #{loanMonths}, loan_start = #{loanStart}
         WHERE id = #{id} AND member_id = #{memberId}
     </update>