detail(@PathVariable Long reconOutId) {
return ApiResponse.ok(service.detail(reconOutId));
}
+ /** 회신 이력 신규 등록(READY 상태로 시작). 같은 보험사+정산월 중복 등록은 거부됩니다. */
@PostMapping
@RequirePermission(menu = "RECON_OUT", perm = "CREATE")
@DataChangeLog(menu = "RECON_OUT", table = "carrier_reconciliation_out")
@@ -40,6 +51,7 @@ public class CarrierReconciliationOutController {
return ApiResponse.ok(service.create(req));
}
+ /** 전송 실패(FAIL) 건 재전송. 상태를 READY 로 되돌려 배치가 다시 처리하도록 합니다. */
@PostMapping("/{reconOutId}/retry")
@RequirePermission(menu = "RECON_OUT", perm = "UPDATE")
@DataChangeLog(menu = "RECON_OUT", table = "carrier_reconciliation_out")
diff --git a/ga-api/src/main/java/com/ga/api/controller/settle/ChargebackController.java b/ga-api/src/main/java/com/ga/api/controller/settle/ChargebackController.java
index b306be0..1708a12 100644
--- a/ga-api/src/main/java/com/ga/api/controller/settle/ChargebackController.java
+++ b/ga-api/src/main/java/com/ga/api/controller/settle/ChargebackController.java
@@ -17,6 +17,18 @@ import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;
+/**
+ * 환수(chargeback) 자료 관리 컨트롤러.
+ *
+ * "환수"란 이미 설계사에게 지급한 수수료를 도로 거둬들이는 것입니다. 계약이 일찍 해지/실효되면
+ * 보험사가 GA에게 수수료를 돌려달라 하고, GA는 그만큼을 설계사 정산에서 회수합니다.
+ *
+ *
주 업무는 보험사가 보내준 환수 엑셀(증권번호·환수금액·실효월·환수율)을 업로드(upload)해
+ * chargeback 테이블에 적재하는 것입니다. 존재하지 않는 증권번호나 잘못된 금액은 에러행으로 돌려주고,
+ * 같은 계약+정산월 중복은 건너뜁니다(스킵).
+ *
+ *
권한(menu=CHARGEBACK_DATA): 조회 READ, 엑셀 EXPORT, 업로드 CREATE.
+ */
@Tag(name = "환수자료 관리")
@Validated
@RestController
diff --git a/ga-api/src/main/java/com/ga/api/controller/settle/CommissionDisputeController.java b/ga-api/src/main/java/com/ga/api/controller/settle/CommissionDisputeController.java
index 544c221..b4bfa98 100644
--- a/ga-api/src/main/java/com/ga/api/controller/settle/CommissionDisputeController.java
+++ b/ga-api/src/main/java/com/ga/api/controller/settle/CommissionDisputeController.java
@@ -16,6 +16,18 @@ import org.springframework.web.bind.annotation.*;
import java.math.BigDecimal;
import java.util.Map;
+/**
+ * 수수료 이의신청(commission_dispute) 관리 컨트롤러.
+ *
+ *
설계사가 "내 수수료 정산 금액이 이상하다"고 문제를 제기하면 이의신청 건이 만들어집니다.
+ * 담당자는 검토를 시작(startReview)하고, 타당하면 승인(approve)하며 보정 금액을 정정(correction)과 연결하거나,
+ * 타당하지 않으면 기각(reject)합니다.
+ *
+ *
상태 흐름(DisputeStatus): OPEN(접수) → IN_REVIEW(검토중) → APPROVED(승인)/REJECTED(기각).
+ * 승인/기각은 IN_REVIEW 상태에서만 가능합니다.
+ *
+ *
권한(menu=DISPUTE): 조회 READ, 접수 CREATE, 검토시작 UPDATE, 승인/기각 APPROVE.
+ */
@Tag(name = "수수료 이의신청 관리")
@RestController
@RequestMapping("/api/disputes")
@@ -24,18 +36,21 @@ public class CommissionDisputeController {
private final CommissionDisputeService service;
+ /** 이의신청 목록 조회(검색 + 페이징). */
@GetMapping
@RequirePermission(menu = "DISPUTE", perm = "READ")
public ApiResponse> list(@ModelAttribute CommissionDisputeSearchParam param) {
return ApiResponse.ok(service.list(param));
}
+ /** 이의신청 단건 상세 조회. */
@GetMapping("/{disputeId}")
@RequirePermission(menu = "DISPUTE", perm = "READ")
public ApiResponse detail(@PathVariable Long disputeId) {
return ApiResponse.ok(service.detail(disputeId));
}
+ /** 이의신청 접수(OPEN 상태로 생성). */
@PostMapping
@RequirePermission(menu = "DISPUTE", perm = "CREATE")
@DataChangeLog(menu = "DISPUTE", table = "commission_dispute")
@@ -43,6 +58,7 @@ public class CommissionDisputeController {
return ApiResponse.ok(service.create(req));
}
+ /** 검토 시작(OPEN → IN_REVIEW). */
@PostMapping("/{disputeId}/review")
@RequirePermission(menu = "DISPUTE", perm = "UPDATE")
@DataChangeLog(menu = "DISPUTE", table = "commission_dispute")
@@ -51,6 +67,10 @@ public class CommissionDisputeController {
return ApiResponse.ok();
}
+ /**
+ * 이의신청 승인(IN_REVIEW → APPROVED).
+ * body 의 resolution(처리내용), adjustmentAmount(보정금액, 선택), correctionId(연결된 정산정정ID, 선택)를 받습니다.
+ */
@PostMapping("/{disputeId}/approve")
@RequirePermission(menu = "DISPUTE", perm = "APPROVE")
@DataChangeLog(menu = "DISPUTE", table = "commission_dispute")
@@ -64,6 +84,7 @@ public class CommissionDisputeController {
return ApiResponse.ok();
}
+ /** 이의신청 기각(IN_REVIEW → REJECTED). body 의 resolution 에 기각 사유를 담습니다. */
@PostMapping("/{disputeId}/reject")
@RequirePermission(menu = "DISPUTE", perm = "APPROVE")
@DataChangeLog(menu = "DISPUTE", table = "commission_dispute")
diff --git a/ga-api/src/main/java/com/ga/api/controller/settle/IncentivePaymentController.java b/ga-api/src/main/java/com/ga/api/controller/settle/IncentivePaymentController.java
index d425180..f0b0bb5 100644
--- a/ga-api/src/main/java/com/ga/api/controller/settle/IncentivePaymentController.java
+++ b/ga-api/src/main/java/com/ga/api/controller/settle/IncentivePaymentController.java
@@ -15,6 +15,17 @@ import org.springframework.web.bind.annotation.*;
import java.util.Map;
+/**
+ * 시책 지급(incentive_payment) 관리 컨트롤러.
+ *
+ * "시책"은 보험사/GA가 특정 기간·상품에 거는 추가 인센티브(판매 장려금)입니다.
+ * 시책 프로그램(incentive_program) 조건을 충족한 설계사에게 지급할 금액을 건별로 만들어 확정/취소합니다.
+ *
+ *
상태 흐름(IncentivePayStatus): CALCULATED(산출) → CONFIRMED(확정) → PAID(지급완료), 또는 CANCELLED(취소).
+ * 확정은 CALCULATED 상태에서만, 취소는 PAID 가 아닐 때만 가능합니다. 생성·확정 시 정산월 마감 여부를 확인합니다.
+ *
+ *
권한(menu=INCENTIVE_PAY): 조회 READ, 생성 CREATE, 확정 APPROVE, 취소 UPDATE.
+ */
@Tag(name = "시책 지급 관리")
@RestController
@RequestMapping("/api/incentive-payments")
@@ -23,18 +34,21 @@ public class IncentivePaymentController {
private final IncentivePaymentService service;
+ /** 시책 지급 목록 조회(검색 + 페이징). */
@GetMapping
@RequirePermission(menu = "INCENTIVE_PAY", perm = "READ")
public ApiResponse> list(@ModelAttribute IncentivePaymentSearchParam param) {
return ApiResponse.ok(service.list(param));
}
+ /** 시책 지급 단건 상세 조회. */
@GetMapping("/{incentivePayId}")
@RequirePermission(menu = "INCENTIVE_PAY", perm = "READ")
public ApiResponse detail(@PathVariable Long incentivePayId) {
return ApiResponse.ok(service.detail(incentivePayId));
}
+ /** 시책 지급 생성(CALCULATED 상태). 해당 정산월이 마감되어 있으면 거부됩니다. */
@PostMapping
@RequirePermission(menu = "INCENTIVE_PAY", perm = "CREATE")
@DataChangeLog(menu = "INCENTIVE_PAY", table = "incentive_payment")
@@ -42,6 +56,7 @@ public class IncentivePaymentController {
return ApiResponse.ok(service.create(req));
}
+ /** 시책 지급 확정(CALCULATED → CONFIRMED). 마감 가드 적용. APPROVE 권한 필요. */
@PostMapping("/{incentivePayId}/confirm")
@RequirePermission(menu = "INCENTIVE_PAY", perm = "APPROVE")
@DataChangeLog(menu = "INCENTIVE_PAY", table = "incentive_payment")
@@ -50,6 +65,7 @@ public class IncentivePaymentController {
return ApiResponse.ok();
}
+ /** 시책 지급 취소(→ CANCELLED). body 의 cancelReason 에 취소 사유를 담습니다. 지급완료건은 취소 불가. */
@PostMapping("/{incentivePayId}/cancel")
@RequirePermission(menu = "INCENTIVE_PAY", perm = "UPDATE")
@DataChangeLog(menu = "INCENTIVE_PAY", table = "incentive_payment")
diff --git a/ga-api/src/main/java/com/ga/api/controller/settle/IncentiveProgramController.java b/ga-api/src/main/java/com/ga/api/controller/settle/IncentiveProgramController.java
index b21183b..c5eacd7 100644
--- a/ga-api/src/main/java/com/ga/api/controller/settle/IncentiveProgramController.java
+++ b/ga-api/src/main/java/com/ga/api/controller/settle/IncentiveProgramController.java
@@ -15,6 +15,16 @@ import org.springframework.web.bind.annotation.*;
import java.util.Map;
+/**
+ * 시책 프로그램(incentive_program) 관리 컨트롤러.
+ *
+ * 시책 "프로그램"은 인센티브 지급의 규칙 정의입니다. 대상(등급/조직/상품군), 기간(시작월~종료월),
+ * 지급 방식(정률 payRate 또는 정액 payAmountFixed), 예산(budgetAmount) 등을 설정합니다.
+ * 실제 지급(incentive_payment)은 이 프로그램 조건에 따라 산출됩니다.
+ *
+ *
활성/비활성(isActive)은 toggleActive 로 전환합니다. 비활성 프로그램은 신규 지급 대상에서 제외됩니다.
+ * 권한(menu=INCENTIVE_PROG): 조회 READ, 생성 CREATE, 수정/활성토글 UPDATE.
+ */
@Tag(name = "시책 프로그램 관리")
@RestController
@RequestMapping("/api/incentive-programs")
@@ -23,18 +33,21 @@ public class IncentiveProgramController {
private final IncentiveProgramService service;
+ /** 시책 프로그램 목록 조회(검색 + 페이징). */
@GetMapping
@RequirePermission(menu = "INCENTIVE_PROG", perm = "READ")
public ApiResponse> list(@ModelAttribute IncentiveProgramSearchParam param) {
return ApiResponse.ok(service.list(param));
}
+ /** 시책 프로그램 단건 상세 조회. */
@GetMapping("/{programId}")
@RequirePermission(menu = "INCENTIVE_PROG", perm = "READ")
public ApiResponse detail(@PathVariable Long programId) {
return ApiResponse.ok(service.detail(programId));
}
+ /** 시책 프로그램 신규 등록(기본 활성 상태로 생성). */
@PostMapping
@RequirePermission(menu = "INCENTIVE_PROG", perm = "CREATE")
@DataChangeLog(menu = "INCENTIVE_PROG", table = "incentive_program")
@@ -42,6 +55,7 @@ public class IncentiveProgramController {
return ApiResponse.ok(service.create(req));
}
+ /** 시책 프로그램 수정(전체 필드 갱신). */
@PutMapping("/{programId}")
@RequirePermission(menu = "INCENTIVE_PROG", perm = "UPDATE")
@DataChangeLog(menu = "INCENTIVE_PROG", table = "incentive_program")
@@ -50,6 +64,7 @@ public class IncentiveProgramController {
return ApiResponse.ok();
}
+ /** 활성/비활성 토글. body 의 isActive(true/false)로 사용 여부를 전환합니다. */
@PutMapping("/{programId}/active")
@RequirePermission(menu = "INCENTIVE_PROG", perm = "UPDATE")
@DataChangeLog(menu = "INCENTIVE_PROG", table = "incentive_program")
diff --git a/ga-api/src/main/java/com/ga/api/controller/settle/PaymentBatchController.java b/ga-api/src/main/java/com/ga/api/controller/settle/PaymentBatchController.java
index 77dc984..069b426 100644
--- a/ga-api/src/main/java/com/ga/api/controller/settle/PaymentBatchController.java
+++ b/ga-api/src/main/java/com/ga/api/controller/settle/PaymentBatchController.java
@@ -16,6 +16,18 @@ import jakarta.validation.Valid;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.*;
+/**
+ * 지급대상 배치(payment_batch) 관리 컨트롤러.
+ *
+ * "배치"는 한 정산월에 실제로 돈을 보낼 대상 설계사들을 한 묶음으로 모은 작업 단위입니다.
+ * 담당자는 배치를 만들어(create) 대상 명단을 확인하고, 빼야 할 사람은 제외(updateItem)한 뒤,
+ * 최종 확정(finalize)하여 이후 이체 처리로 넘깁니다.
+ *
+ *
상태 흐름(PaymentBatchStatus): DRAFT(작성중) → FINALIZED(확정) / CANCELLED(취소).
+ * 수정(updateItem)은 DRAFT 상태에서만 가능합니다.
+ *
+ *
권한(menu=PAYMENT_TARGET): 생성 CREATE, 조회/엑셀 READ, 항목수정 UPDATE, 확정 EXECUTE.
+ */
@Tag(name = "지급대상 배치 관리")
@RestController
@RequestMapping("/api/payment-batches")
diff --git a/ga-api/src/main/java/com/ga/api/controller/settle/PaymentController.java b/ga-api/src/main/java/com/ga/api/controller/settle/PaymentController.java
index d676c37..e1096bf 100644
--- a/ga-api/src/main/java/com/ga/api/controller/settle/PaymentController.java
+++ b/ga-api/src/main/java/com/ga/api/controller/settle/PaymentController.java
@@ -16,6 +16,19 @@ import lombok.RequiredArgsConstructor;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;
+/**
+ * 지급(payment) 관리 컨트롤러.
+ *
+ *
정산 마스터가 "이번 달 줄 금액"을 확정하면, 실제 계좌로 보낼 한 건 한 건이 payment(지급) 레코드가 됩니다.
+ * 이 컨트롤러는 지급 건 목록 조회, 상태 변경, 세금 계산, 차감 적용, 은행 이체파일 생성을 담당합니다.
+ *
+ *
지급 한 건의 금액 계산 순서(도메인):
+ * payAmount(지급원금) → 세금(소득세·지방세·부가세) 차감 → 각종 공제(차감) 차감 → netAmount(실지급액).
+ * 이 netAmount 가 최종적으로 설계사 통장에 들어가는 금액입니다.
+ *
+ *
@Validated + @Pattern 으로 settleMonth 는 YYYYMM(숫자 6자리) 형식만 허용합니다.
+ * 권한(menu=PAYMENT): 조회 READ, 상태/세금/차감 변경 UPDATE, 이체파일 생성 EXPORT.
+ */
@Tag(name = "지급 관리")
@Validated
@RestController
@@ -25,12 +38,14 @@ public class PaymentController {
private final PaymentService paymentService;
+ /** 지급 건 목록 조회(검색 + 페이징). */
@GetMapping
@RequirePermission(menu = "PAYMENT", perm = "READ")
public ApiResponse> list(@ModelAttribute SettleSearchParam param) {
return ApiResponse.ok(paymentService.list(param));
}
+ /** 지급 상태 수동 변경(예: 실패 처리). 실패 시 req.failReason 에 사유를 담아 기록합니다. */
@PutMapping("/{paymentId}/status")
@RequirePermission(menu = "PAYMENT", perm = "UPDATE")
@DataChangeLog(menu = "PAYMENT", table = "payment")
diff --git a/ga-api/src/main/java/com/ga/api/controller/settle/PaymentStatusUpdateReq.java b/ga-api/src/main/java/com/ga/api/controller/settle/PaymentStatusUpdateReq.java
index d0db4d5..1f618f6 100644
--- a/ga-api/src/main/java/com/ga/api/controller/settle/PaymentStatusUpdateReq.java
+++ b/ga-api/src/main/java/com/ga/api/controller/settle/PaymentStatusUpdateReq.java
@@ -4,6 +4,10 @@ import jakarta.validation.constraints.NotBlank;
import lombok.Getter;
import lombok.Setter;
+/**
+ * 지급 상태 변경 요청 DTO.
+ * status: 변경할 상태값(필수). failReason: 실패 처리 시 사유(선택).
+ */
@Getter
@Setter
public class PaymentStatusUpdateReq {
diff --git a/ga-api/src/main/java/com/ga/api/controller/settle/PeriodCloseController.java b/ga-api/src/main/java/com/ga/api/controller/settle/PeriodCloseController.java
index b2f9717..c450b70 100644
--- a/ga-api/src/main/java/com/ga/api/controller/settle/PeriodCloseController.java
+++ b/ga-api/src/main/java/com/ga/api/controller/settle/PeriodCloseController.java
@@ -15,6 +15,15 @@ import org.springframework.web.bind.annotation.*;
import java.util.Map;
+/**
+ * 정산 마감(period_close) 관리 컨트롤러.
+ *
+ * "마감"은 특정 정산월의 정산 데이터를 잠그는 작업입니다. 마감된 월에는 정정·시책지급 등 금액을 바꾸는
+ * 작업이 막혀(마감 가드), 이미 확정된 숫자가 사후에 흔들리는 것을 방지합니다.
+ *
+ *
마감(close) 후 정정이 필요하면 재오픈(reopen)으로 잠금을 풀 수 있으며, 재오픈 사유를 함께 기록합니다.
+ * 권한(menu=PERIOD_CLOSE): 조회 READ, 마감 CREATE, 재오픈 UPDATE.
+ */
@Tag(name = "정산 마감 관리")
@RestController
@RequestMapping("/api/period-close")
@@ -23,18 +32,21 @@ public class PeriodCloseController {
private final PeriodCloseService service;
+ /** 마감 이력 목록 조회(검색 + 페이징). */
@GetMapping
@RequirePermission(menu = "PERIOD_CLOSE", perm = "READ")
public ApiResponse> list(@ModelAttribute PeriodCloseSearchParam param) {
return ApiResponse.ok(service.list(param));
}
+ /** 마감 이력 단건 상세 조회. */
@GetMapping("/{closeId}")
@RequirePermission(menu = "PERIOD_CLOSE", perm = "READ")
public ApiResponse detail(@PathVariable Long closeId) {
return ApiResponse.ok(service.detail(closeId));
}
+ /** 정산월 마감 실행. 이미 마감된 월이면 거부됩니다. */
@PostMapping
@RequirePermission(menu = "PERIOD_CLOSE", perm = "CREATE")
@DataChangeLog(menu = "PERIOD_CLOSE", table = "period_close")
@@ -43,6 +55,7 @@ public class PeriodCloseController {
return ApiResponse.ok();
}
+ /** 마감 재오픈(잠금 해제). body 의 reopenReason 에 재오픈 사유를 담습니다. */
@PostMapping("/{closeId}/reopen")
@RequirePermission(menu = "PERIOD_CLOSE", perm = "UPDATE")
@DataChangeLog(menu = "PERIOD_CLOSE", table = "period_close")
diff --git a/ga-api/src/main/java/com/ga/api/controller/settle/SettleController.java b/ga-api/src/main/java/com/ga/api/controller/settle/SettleController.java
index f27abd6..4924e12 100644
--- a/ga-api/src/main/java/com/ga/api/controller/settle/SettleController.java
+++ b/ga-api/src/main/java/com/ga/api/controller/settle/SettleController.java
@@ -14,6 +14,18 @@ import org.springframework.web.bind.annotation.*;
import java.util.List;
import java.util.Map;
+/**
+ * 정산 마스터(settle_master) 관리 컨트롤러.
+ *
+ * 정산 마스터는 "설계사 1명 × 정산월 1개" 단위로 그 달에 줄 수수료 합계를 모아둔 표(원장)입니다.
+ * 매달 배치가 각종 원장을 집계해 settle_master 한 행을 만들고, 담당자가 이 화면에서 확인/승인합니다.
+ *
+ *
상태 흐름(SettleStatus): CALCULATED(산출완료) → CONFIRMED(확정) → PAID(지급완료).
+ * 중간에 문제가 있으면 HOLD(보류)로 묶었다가 release 로 다시 CALCULATED 로 풀 수 있습니다.
+ *
+ *
권한(menu=SETTLE_LIST): 조회는 READ, 확정/보류/해제 같은 상태변경은 APPROVE 권한이 필요합니다.
+ * 상태변경 엔드포인트에는 @DataChangeLog 가 붙어 누가 무엇을 바꿨는지 변경이력이 자동 기록됩니다.
+ */
@Tag(name = "정산 관리")
@RestController
@RequestMapping("/api/settle")
@@ -22,12 +34,14 @@ public class SettleController {
private final SettleService service;
+ /** 정산 마스터 목록 조회(검색조건 + 페이징). 요청: SettleSearchParam, 응답: 페이지 형태의 정산 요약 목록. */
@GetMapping
@RequirePermission(menu = "SETTLE_LIST", perm = "READ")
public ApiResponse> list(@ModelAttribute SettleSearchParam param) {
return ApiResponse.ok(service.list(param));
}
+ /** 정산 마스터 단건 상세 조회. 키는 "설계사ID + 정산월(YYYYMM)" 조합입니다. */
@GetMapping("/{agentId}/months/{settleMonth}")
@RequirePermission(menu = "SETTLE_LIST", perm = "READ")
public ApiResponse detail(@PathVariable Long agentId,
@@ -35,18 +49,21 @@ public class SettleController {
return ApiResponse.ok(service.detail(agentId, settleMonth));
}
+ /** 특정 정산월 전체 합계 요약(총 인원, 총 지급액 등 대시보드용 집계). */
@GetMapping("/summary")
@RequirePermission(menu = "SETTLE_LIST", perm = "READ")
public ApiResponse> summary(@RequestParam String settleMonth) {
return ApiResponse.ok(service.summary(settleMonth));
}
+ /** 특정 정산월의 조직(지점)별 합계 요약. summary 를 조직 단위로 쪼갠 목록입니다. */
@GetMapping("/org-summary")
@RequirePermission(menu = "SETTLE_LIST", perm = "READ")
public ApiResponse>> orgSummary(@RequestParam String settleMonth) {
return ApiResponse.ok(service.orgSummary(settleMonth));
}
+ /** 정산 확정(CONFIRMED). 확정 후에는 금액이 잠겨 지급 단계로 넘어갑니다. APPROVE 권한 필요. */
@PutMapping("/{settleId}/confirm")
@RequirePermission(menu = "SETTLE_LIST", perm = "APPROVE")
@DataChangeLog(menu = "SETTLE_LIST", table = "settle_master")
@@ -55,6 +72,7 @@ public class SettleController {
return ApiResponse.ok();
}
+ /** 정산 보류(HOLD). body 의 reason(사유)·reasonCode(사유코드)를 함께 기록합니다. 지급완료건은 보류 불가. */
@PutMapping("/{settleId}/hold")
@RequirePermission(menu = "SETTLE_LIST", perm = "APPROVE")
@DataChangeLog(menu = "SETTLE_LIST", table = "settle_master")
@@ -63,6 +81,7 @@ public class SettleController {
return ApiResponse.ok();
}
+ /** 보류 해제(release). HOLD 상태를 다시 CALCULATED 로 되돌려 정상 흐름에 복귀시킵니다. */
@PutMapping("/{settleId}/release")
@RequirePermission(menu = "SETTLE_LIST", perm = "APPROVE")
@DataChangeLog(menu = "SETTLE_LIST", table = "settle_master")
diff --git a/ga-api/src/main/java/com/ga/api/controller/settle/SettleCorrectionController.java b/ga-api/src/main/java/com/ga/api/controller/settle/SettleCorrectionController.java
index aa295d4..9c68ae6 100644
--- a/ga-api/src/main/java/com/ga/api/controller/settle/SettleCorrectionController.java
+++ b/ga-api/src/main/java/com/ga/api/controller/settle/SettleCorrectionController.java
@@ -16,6 +16,18 @@ import org.springframework.web.bind.annotation.*;
import java.util.List;
import java.util.Map;
+/**
+ * 정산 정정(settle_correction) 관리 컨트롤러.
+ *
+ * 이미 산출된 정산 금액을 사후에 바로잡는 화면입니다. 원래 정산(originalSettleId)을 기준으로
+ * 변경 전(beforeAmount)·후(afterAmount) 금액과 차액(diffAmount), 사유를 기록합니다.
+ *
+ *
상태 흐름(CorrectionStatus): DRAFT(작성) → APPROVED(승인) → APPLIED(반영완료), 또는 취소.
+ * 승인은 DRAFT 상태에서만, 취소는 이미 반영(APPLIED)되지 않은 건만 가능합니다.
+ * 생성 시 해당 정산월이 마감되어 있으면 거부됩니다(마감 가드).
+ *
+ *
권한(menu=SETTLE_CORRECTION): 조회 READ, 생성 CREATE, 승인 APPROVE, 취소 UPDATE.
+ */
@Tag(name = "정산 정정 관리")
@RestController
@RequestMapping("/api/settle-corrections")
@@ -24,24 +36,28 @@ public class SettleCorrectionController {
private final SettleCorrectionService service;
+ /** 정정 목록 조회(검색 + 페이징). */
@GetMapping
@RequirePermission(menu = "SETTLE_CORRECTION", perm = "READ")
public ApiResponse> list(@ModelAttribute SettleCorrectionSearchParam param) {
return ApiResponse.ok(service.list(param));
}
+ /** 정정 단건 상세 조회. */
@GetMapping("/{correctionId}")
@RequirePermission(menu = "SETTLE_CORRECTION", perm = "READ")
public ApiResponse detail(@PathVariable Long correctionId) {
return ApiResponse.ok(service.detail(correctionId));
}
+ /** 특정 원본 정산(originalSettleId)에 달린 정정 이력 전체 조회. */
@GetMapping("/by-settle/{originalSettleId}")
@RequirePermission(menu = "SETTLE_CORRECTION", perm = "READ")
public ApiResponse> listByOriginalSettle(@PathVariable Long originalSettleId) {
return ApiResponse.ok(service.listByOriginalSettle(originalSettleId));
}
+ /** 정정 생성(DRAFT 상태). 차액(diffAmount)은 후-전 금액으로 자동 계산됩니다. 마감 가드 적용. */
@PostMapping
@RequirePermission(menu = "SETTLE_CORRECTION", perm = "CREATE")
@DataChangeLog(menu = "SETTLE_CORRECTION", table = "settle_correction")
@@ -49,6 +65,7 @@ public class SettleCorrectionController {
return ApiResponse.ok(service.create(req));
}
+ /** 정정 승인(DRAFT → APPROVED). APPROVE 권한 필요. */
@PostMapping("/{correctionId}/approve")
@RequirePermission(menu = "SETTLE_CORRECTION", perm = "APPROVE")
@DataChangeLog(menu = "SETTLE_CORRECTION", table = "settle_correction")
@@ -57,6 +74,7 @@ public class SettleCorrectionController {
return ApiResponse.ok();
}
+ /** 정정 취소. body 의 cancelReason 에 사유를 담습니다. 이미 반영(APPLIED)된 정정은 취소 불가. */
@PostMapping("/{correctionId}/cancel")
@RequirePermission(menu = "SETTLE_CORRECTION", perm = "UPDATE")
@DataChangeLog(menu = "SETTLE_CORRECTION", table = "settle_correction")
diff --git a/ga-api/src/main/java/com/ga/api/controller/settle/TaxInvoiceController.java b/ga-api/src/main/java/com/ga/api/controller/settle/TaxInvoiceController.java
index ed7a0a1..fa59fa4 100644
--- a/ga-api/src/main/java/com/ga/api/controller/settle/TaxInvoiceController.java
+++ b/ga-api/src/main/java/com/ga/api/controller/settle/TaxInvoiceController.java
@@ -15,6 +15,15 @@ import org.springframework.web.bind.annotation.*;
import java.util.Map;
+/**
+ * 세금계산서(tax_invoice) 관리 컨트롤러.
+ *
+ * 수수료 지급/거래에 대한 세금계산서 발행 이력을 관리합니다. 공급가액(supplyAmount) + 세액(taxAmount) =
+ * 합계(totalAmount)로 구성되며, 거래 상대방(상호·사업자번호·대표·주소) 정보를 함께 보관합니다.
+ *
+ *
발행번호(invoiceNo)는 유일해야 하며 중복 시 등록이 거부됩니다. 잘못 발행한 계산서는 취소(cancel)로 처리합니다.
+ * 권한(menu=TAX_INVOICE): 조회 READ, 발행 CREATE, 취소 UPDATE.
+ */
@Tag(name = "세금계산서 관리")
@RestController
@RequestMapping("/api/tax-invoices")
@@ -23,18 +32,21 @@ public class TaxInvoiceController {
private final TaxInvoiceService service;
+ /** 세금계산서 목록 조회(검색 + 페이징). */
@GetMapping
@RequirePermission(menu = "TAX_INVOICE", perm = "READ")
public ApiResponse> list(@ModelAttribute TaxInvoiceSearchParam param) {
return ApiResponse.ok(service.list(param));
}
+ /** 세금계산서 단건 상세 조회. */
@GetMapping("/{invoiceId}")
@RequirePermission(menu = "TAX_INVOICE", perm = "READ")
public ApiResponse detail(@PathVariable Long invoiceId) {
return ApiResponse.ok(service.detail(invoiceId));
}
+ /** 세금계산서 발행(등록). 발행번호 중복은 거부됩니다. 합계금액은 공급가액+세액으로 자동 계산됩니다. */
@PostMapping
@RequirePermission(menu = "TAX_INVOICE", perm = "CREATE")
@DataChangeLog(menu = "TAX_INVOICE", table = "tax_invoice")
@@ -42,6 +54,7 @@ public class TaxInvoiceController {
return ApiResponse.ok(service.create(req));
}
+ /** 세금계산서 취소. body 의 cancelReason 에 취소 사유를 담습니다(취소일은 서버 기준 오늘). */
@PostMapping("/{invoiceId}/cancel")
@RequirePermission(menu = "TAX_INVOICE", perm = "UPDATE")
@DataChangeLog(menu = "TAX_INVOICE", table = "tax_invoice")
diff --git a/ga-api/src/main/java/com/ga/api/controller/settle/TerminationSettlementController.java b/ga-api/src/main/java/com/ga/api/controller/settle/TerminationSettlementController.java
index ef44f19..611c907 100644
--- a/ga-api/src/main/java/com/ga/api/controller/settle/TerminationSettlementController.java
+++ b/ga-api/src/main/java/com/ga/api/controller/settle/TerminationSettlementController.java
@@ -13,6 +13,17 @@ import jakarta.validation.Valid;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.*;
+/**
+ * 해촉 정산(termination_settlement) 관리 컨트롤러.
+ *
+ * "해촉"은 설계사 위촉계약이 끝나는 것입니다. 그만둘 때 미지급 수수료(모집/분할/시책)는 정산해 주고,
+ * 향후 발생할 환수 예상액 등은 차감하여 최종 지급액(finalPayAmount)을 산출하는 일회성 정산입니다.
+ *
+ *
상태 흐름(TermSettleStatus): CALCULATING(산출중) → CONFIRMED(확정), 또는 CANCELLED(취소).
+ * 수정·확정은 CALCULATING 상태에서만 가능합니다. 한 설계사에 진행 중인 해촉 정산이 이미 있으면 중복 생성이 거부됩니다.
+ *
+ *
권한(menu=TERM_SETTLE): 조회 READ, 생성/process CREATE, 수정 UPDATE, 확정 APPROVE.
+ */
@Tag(name = "해촉 정산 관리")
@RestController
@RequestMapping("/api/termination-settlements")
@@ -21,18 +32,21 @@ public class TerminationSettlementController {
private final TerminationSettlementService service;
+ /** 해촉 정산 목록 조회(검색 + 페이징). */
@GetMapping
@RequirePermission(menu = "TERM_SETTLE", perm = "READ")
public ApiResponse> list(@ModelAttribute TerminationSettlementSearchParam param) {
return ApiResponse.ok(service.list(param));
}
+ /** 해촉 정산 단건 상세 조회. */
@GetMapping("/{termSettleId}")
@RequirePermission(menu = "TERM_SETTLE", perm = "READ")
public ApiResponse detail(@PathVariable Long termSettleId) {
return ApiResponse.ok(service.detail(termSettleId));
}
+ /** 해촉 정산 생성(CALCULATING 상태). 진행 중인 해촉 정산이 있으면 거부됩니다. */
@PostMapping
@RequirePermission(menu = "TERM_SETTLE", perm = "CREATE")
@DataChangeLog(menu = "TERM_SETTLE", table = "termination_settlement")
@@ -40,6 +54,7 @@ public class TerminationSettlementController {
return ApiResponse.ok(service.create(req));
}
+ /** 해촉 정산 금액 수정. 산출 중(CALCULATING) 상태에서만 가능합니다. */
@PutMapping("/{termSettleId}")
@RequirePermission(menu = "TERM_SETTLE", perm = "UPDATE")
@DataChangeLog(menu = "TERM_SETTLE", table = "termination_settlement")
@@ -48,6 +63,7 @@ public class TerminationSettlementController {
return ApiResponse.ok();
}
+ /** 해촉 발생 시 자동 처리 진입점. 내부적으로 create 와 동일하게 CALCULATING 레코드를 만듭니다. */
@PostMapping("/process")
@RequirePermission(menu = "TERM_SETTLE", perm = "CREATE")
@DataChangeLog(menu = "TERM_SETTLE", table = "termination_settlement")
@@ -55,6 +71,7 @@ public class TerminationSettlementController {
return ApiResponse.ok(service.process(req));
}
+ /** 해촉 정산 확정(CALCULATING → CONFIRMED). APPROVE 권한 필요. */
@PostMapping("/{termSettleId}/confirm")
@RequirePermission(menu = "TERM_SETTLE", perm = "APPROVE")
@DataChangeLog(menu = "TERM_SETTLE", table = "termination_settlement")
diff --git a/ga-api/src/main/java/com/ga/api/controller/statement/CommissionStatementController.java b/ga-api/src/main/java/com/ga/api/controller/statement/CommissionStatementController.java
index 9f7b9bd..d9b2c0c 100644
--- a/ga-api/src/main/java/com/ga/api/controller/statement/CommissionStatementController.java
+++ b/ga-api/src/main/java/com/ga/api/controller/statement/CommissionStatementController.java
@@ -21,6 +21,15 @@ import java.io.IOException;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
+/**
+ * [수수료 명세서 API]
+ *
+ * 신입 개발자 안내:
+ * - 설계사에게 "이번 달 얼마를 어떻게 지급했는지"를 정리한 문서가 수수료 명세서다.
+ * - 데이터 출처: 지급(payment) 내역을 설계사+정산월 단위로 합산(StatementAggregator)하여
+ * 총지급액/원천세/지방소득세/부가세/공제/실수령액을 산출하고, 엑셀 파일로 만들어 보관한다.
+ * - 발급: 단건(generate) 또는 월별 일괄(generateForMonth). 다운로드 시 상태가 DOWNLOADED 로 바뀐다.
+ */
@Tag(name = "수수료 명세서")
@Validated
@RestController
@@ -30,12 +39,14 @@ public class CommissionStatementController {
private final CommissionStatementService statementService;
+ // 명세서 목록 (검색/페이징)
@GetMapping
@RequirePermission(menu = "STATEMENT", perm = "READ")
public ApiResponse> list(@ModelAttribute CommissionStatementSearchParam param) {
return ApiResponse.ok(statementService.list(param));
}
+ // 명세서 1건 상세
@GetMapping("/{statementId}")
@RequirePermission(menu = "STATEMENT", perm = "READ")
public ApiResponse detail(@PathVariable Long statementId) {
@@ -61,6 +72,7 @@ public class CommissionStatementController {
return ApiResponse.ok();
}
+ // 발급된 명세서 엑셀 파일을 내려준다. 한글 파일명은 RFC5987(filename*=UTF-8'')로 인코딩해 깨짐을 방지.
@Operation(summary = "명세서 다운로드")
@GetMapping("/{statementId}/download")
@RequirePermission(menu = "STATEMENT", perm = "READ")
diff --git a/ga-api/src/main/java/com/ga/api/controller/succession/ContractSuccessionController.java b/ga-api/src/main/java/com/ga/api/controller/succession/ContractSuccessionController.java
index ad337ac..0ab816c 100644
--- a/ga-api/src/main/java/com/ga/api/controller/succession/ContractSuccessionController.java
+++ b/ga-api/src/main/java/com/ga/api/controller/succession/ContractSuccessionController.java
@@ -13,6 +13,15 @@ import jakarta.validation.Valid;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.*;
+/**
+ * 계약 승계 관리 API.
+ *
+ * 승계란 한 계약의 담당(귀속) 설계사를 전임(fromAgent)에서 후임(toAgent)으로 넘기는 것을 말한다.
+ * 퇴사·조직이동 등으로 담당자가 바뀌면, 승계일(successionDate) 이후의 유지수수료는 후임 설계사에게 귀속된다.
+ * 정산 배치가 이 승계 정보를 참고해 원장의 agent를 이관한다.
+ *
+ * 메뉴 CONTRACT_SUCCESSION 권한으로 보호된다.
+ */
@Tag(name = "계약 승계")
@RestController
@RequestMapping("/api/contract-successions")
@@ -21,6 +30,7 @@ public class ContractSuccessionController {
private final ContractSuccessionService service;
+ /** 승계 내역 목록 조회(페이징). READ 권한 필요. */
@GetMapping
@RequirePermission(menu = "CONTRACT_SUCCESSION", perm = "READ")
public ApiResponse> list(
@@ -28,12 +38,14 @@ public class ContractSuccessionController {
return ApiResponse.ok(service.list(param));
}
+ /** 승계 단건 상세 조회. READ 권한 필요. */
@GetMapping("/{successionId}")
@RequirePermission(menu = "CONTRACT_SUCCESSION", perm = "READ")
public ApiResponse detail(@PathVariable Long successionId) {
return ApiResponse.ok(service.detail(successionId));
}
+ /** 승계 등록(담당 설계사 이관 예약). 전임/후임이 같으면 거부된다. CREATE 권한 필요. */
@PostMapping
@RequirePermission(menu = "CONTRACT_SUCCESSION", perm = "CREATE")
@DataChangeLog(menu = "CONTRACT_SUCCESSION", table = "contract_succession")
@@ -41,6 +53,7 @@ public class ContractSuccessionController {
return ApiResponse.ok(service.create(req));
}
+ /** 승계 취소(status=CANCELED). 취소 후 정산월부터 유지수수료는 다시 직전 귀속 설계사에게 돌아간다. UPDATE 권한 필요. */
@PostMapping("/{successionId}/cancel")
@RequirePermission(menu = "CONTRACT_SUCCESSION", perm = "UPDATE")
@DataChangeLog(menu = "CONTRACT_SUCCESSION", table = "contract_succession")
@@ -49,6 +62,7 @@ public class ContractSuccessionController {
return ApiResponse.ok();
}
+ /** 승계 레코드 물리 삭제. DELETE 권한 필요. */
@DeleteMapping("/{successionId}")
@RequirePermission(menu = "CONTRACT_SUCCESSION", perm = "DELETE")
@DataChangeLog(menu = "CONTRACT_SUCCESSION", table = "contract_succession")
diff --git a/ga-api/src/main/java/com/ga/api/controller/system/RoleController.java b/ga-api/src/main/java/com/ga/api/controller/system/RoleController.java
index d301446..f0a1282 100644
--- a/ga-api/src/main/java/com/ga/api/controller/system/RoleController.java
+++ b/ga-api/src/main/java/com/ga/api/controller/system/RoleController.java
@@ -12,6 +12,13 @@ import org.springframework.web.bind.annotation.*;
import java.util.List;
import java.util.Map;
+/**
+ * 역할(Role) 및 권한 관리 API.
+ *
+ * 역할은 메뉴별 권한(menuId + permCode)의 묶음이다. 사용자에게 역할을 부여해
+ * 접근 권한을 통제한다(RBAC). 역할별 권한 매핑은 savePermissions에서 전체 교체 방식으로 저장된다.
+ * 메뉴 SYSTEM_ROLE 권한으로 보호된다.
+ */
@Tag(name = "역할 관리")
@RestController
@RequestMapping("/api/system/roles")
@@ -20,24 +27,28 @@ public class RoleController {
private final RoleService roleService;
+ /** 역할 전체 목록 조회. READ 권한 필요. */
@GetMapping
@RequirePermission(menu = "SYSTEM_ROLE", perm = "READ")
public ApiResponse> list() {
return ApiResponse.ok(roleService.list());
}
+ /** 역할 단건 상세 조회. READ 권한 필요. */
@GetMapping("/{roleId}")
@RequirePermission(menu = "SYSTEM_ROLE", perm = "READ")
public ApiResponse detail(@PathVariable Long roleId) {
return ApiResponse.ok(roleService.detail(roleId));
}
+ /** 역할에 부여된 메뉴별 권한 목록 조회. READ 권한 필요. */
@GetMapping("/{roleId}/permissions")
@RequirePermission(menu = "SYSTEM_ROLE", perm = "READ")
public ApiResponse>> permissions(@PathVariable Long roleId) {
return ApiResponse.ok(roleService.permissions(roleId));
}
+ /** 역할 신규 등록. CREATE 권한 필요. */
@PostMapping
@RequirePermission(menu = "SYSTEM_ROLE", perm = "CREATE")
@DataChangeLog(menu = "SYSTEM_ROLE", table = "role")
@@ -45,6 +56,7 @@ public class RoleController {
return ApiResponse.ok(roleService.create(vo));
}
+ /** 역할 정보 수정. UPDATE 권한 필요. */
@PutMapping("/{roleId}")
@RequirePermission(menu = "SYSTEM_ROLE", perm = "UPDATE")
@DataChangeLog(menu = "SYSTEM_ROLE", table = "role")
@@ -53,6 +65,7 @@ public class RoleController {
return ApiResponse.ok();
}
+ /** 역할 삭제. DELETE 권한 필요. */
@DeleteMapping("/{roleId}")
@RequirePermission(menu = "SYSTEM_ROLE", perm = "DELETE")
@DataChangeLog(menu = "SYSTEM_ROLE", table = "role")
@@ -61,6 +74,7 @@ public class RoleController {
return ApiResponse.ok();
}
+ /** 역할의 권한 매핑 일괄 저장(기존 전체 삭제 후 재삽입). UPDATE 권한 필요. */
@PutMapping("/{roleId}/permissions")
@RequirePermission(menu = "SYSTEM_ROLE", perm = "UPDATE")
@DataChangeLog(menu = "SYSTEM_ROLE", table = "role_permission")
diff --git a/ga-api/src/main/java/com/ga/api/controller/system/UserController.java b/ga-api/src/main/java/com/ga/api/controller/system/UserController.java
index 2fe9ae6..c0f0fe9 100644
--- a/ga-api/src/main/java/com/ga/api/controller/system/UserController.java
+++ b/ga-api/src/main/java/com/ga/api/controller/system/UserController.java
@@ -13,6 +13,13 @@ import jakarta.validation.Valid;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.*;
+/**
+ * 시스템 사용자(로그인 계정) 관리 API.
+ *
+ * 사용자 계정의 생성·수정·비밀번호 초기화·잠금 해제·전화번호 정정을 제공한다.
+ * 사용자는 역할(role)을 통해 권한을 부여받는다(roleIds). 로그인 ID는 중복 불가다.
+ * 메뉴 SYSTEM_USER 권한으로 보호된다.
+ */
@Tag(name = "사용자 관리")
@RestController
@RequestMapping("/api/system/users")
@@ -21,18 +28,21 @@ public class UserController {
private final UserService service;
+ /** 사용자 목록 조회(페이징). READ 권한 필요. */
@GetMapping
@RequirePermission(menu = "SYSTEM_USER", perm = "READ")
public ApiResponse> list(@ModelAttribute UserSearchParam param) {
return ApiResponse.ok(service.list(param));
}
+ /** 사용자 단건 상세 조회(역할 코드 포함). READ 권한 필요. */
@GetMapping("/{userId}")
@RequirePermission(menu = "SYSTEM_USER", perm = "READ")
public ApiResponse detail(@PathVariable Long userId) {
return ApiResponse.ok(service.detail(userId));
}
+ /** 사용자 신규 등록. 비밀번호 미지정 시 임시 비밀번호로 생성하고 역할을 부여한다. CREATE 권한 필요. */
@PostMapping
@RequirePermission(menu = "SYSTEM_USER", perm = "CREATE")
@DataChangeLog(menu = "SYSTEM_USER", table = "users")
@@ -40,6 +50,7 @@ public class UserController {
return ApiResponse.ok(service.create(req));
}
+ /** 사용자 정보 수정. roleIds가 오면 역할을 전체 교체한다. UPDATE 권한 필요. */
@PutMapping("/{userId}")
@RequirePermission(menu = "SYSTEM_USER", perm = "UPDATE")
@DataChangeLog(menu = "SYSTEM_USER", table = "users")
@@ -48,6 +59,7 @@ public class UserController {
return ApiResponse.ok();
}
+ /** 비밀번호 초기화(임시 비밀번호 발급). UPDATE 권한 필요. */
@PutMapping("/{userId}/reset-password")
@RequirePermission(menu = "SYSTEM_USER", perm = "UPDATE")
public ApiResponse resetPassword(@PathVariable Long userId) {
@@ -55,6 +67,7 @@ public class UserController {
return ApiResponse.ok();
}
+ /** 계정 잠금 해제(로그인 실패 횟수 초기화 + ACTIVE 복귀). UPDATE 권한 필요. */
@PutMapping("/{userId}/unlock")
@RequirePermission(menu = "SYSTEM_USER", perm = "UPDATE")
public ApiResponse unlock(@PathVariable Long userId) {
diff --git a/ga-api/src/main/java/com/ga/api/controller/tax/VatReportController.java b/ga-api/src/main/java/com/ga/api/controller/tax/VatReportController.java
index b8e4beb..7315c29 100644
--- a/ga-api/src/main/java/com/ga/api/controller/tax/VatReportController.java
+++ b/ga-api/src/main/java/com/ga/api/controller/tax/VatReportController.java
@@ -17,6 +17,14 @@ import org.springframework.web.bind.annotation.*;
import java.util.List;
import java.util.Map;
+/**
+ * [부가세 분기신고 API]
+ *
+ * 신입 개발자 안내:
+ * - 부가세(VAT)는 분기 단위(1~4분기)로 신고한다. 과세사업자인 설계사의 지급분에 붙은 부가세를 분기별로 모은다.
+ * - 흐름: regenerate(분기 재집계 → vat_report UPSERT) → 목록/상세 확인 → complete(신고 제출 완료 표시).
+ * - settleQuarter 형식은 보통 "YYYYQ"(예: 2026년 1분기)처럼 분기를 식별하는 값이다.
+ */
@Tag(name = "부가세 분기신고")
@RestController
@RequestMapping("/api/vat-reports")
@@ -48,6 +56,7 @@ public class VatReportController {
return ApiResponse.ok(service.regenerate(req));
}
+ // 선택한 신고건들의 상태를 "신고 완료(FILED)"로 변경 (실제 국세청 제출은 외부 절차, 여기선 상태만 갱신)
@PutMapping("/complete")
@Operation(summary = "부가세 분기신고 제출 완료 처리")
@RequirePermission(menu = "VAT_REPORT", perm = "EXECUTE")
diff --git a/ga-api/src/main/java/com/ga/api/controller/tax/WithholdingTaxReportController.java b/ga-api/src/main/java/com/ga/api/controller/tax/WithholdingTaxReportController.java
index 818105b..31ff8b7 100644
--- a/ga-api/src/main/java/com/ga/api/controller/tax/WithholdingTaxReportController.java
+++ b/ga-api/src/main/java/com/ga/api/controller/tax/WithholdingTaxReportController.java
@@ -17,6 +17,14 @@ import org.springframework.web.bind.annotation.*;
import java.util.List;
import java.util.Map;
+/**
+ * [원천세 분기신고 API]
+ *
+ * 신입 개발자 안내:
+ * - 원천세(원천징수세)는 설계사에게 지급할 때 회사가 미리 떼어 국세청에 대신 납부하는 세금이다.
+ * 사업소득은 3.3%(소득세 3% + 지방소득세 0.3%), 기타소득은 8.8%(소득세 8% + 지방소득세 0.8%)가 일반적이다.
+ * - 분기별로 떼어둔 원천세를 모아 신고한다. 흐름: regenerate(분기 재집계) → 목록/상세 → complete(제출 완료 표시).
+ */
@Tag(name = "원천세 분기신고")
@RestController
@RequestMapping("/api/withholding-tax-reports")
@@ -48,6 +56,7 @@ public class WithholdingTaxReportController {
return ApiResponse.ok(service.regenerate(req));
}
+ // 선택한 신고건들의 상태를 "신고 완료(FILED)"로 변경 (상태 갱신만, 실제 제출은 외부 절차)
@PutMapping("/complete")
@Operation(summary = "원천세 분기신고 제출 완료 처리")
@RequirePermission(menu = "WITHHOLDING_TAX", perm = "EXECUTE")
diff --git a/ga-api/src/main/java/com/ga/api/controller/training/AgentTrainingController.java b/ga-api/src/main/java/com/ga/api/controller/training/AgentTrainingController.java
index 350e6f6..f986cc8 100644
--- a/ga-api/src/main/java/com/ga/api/controller/training/AgentTrainingController.java
+++ b/ga-api/src/main/java/com/ga/api/controller/training/AgentTrainingController.java
@@ -14,6 +14,17 @@ import org.springframework.web.bind.annotation.*;
import java.math.BigDecimal;
import java.util.List;
+/**
+ * 보수교육(자격 유지교육) 관리 API.
+ *
+ * 보험설계사는 법정 의무로 매년 일정 시간의 교육을 이수해야 한다. 이 도메인은 두 부분으로 나뉜다.
+ *
+ * - 교육 이수 내역(agent_training): 설계사가 들은 개별 교육(과정/일자/시간/수료증 등).
+ * - 연도별 의무 기준(training_requirement): 해당 연도에 요구되는 최소 이수 시간.
+ *
+ * annual-hours로 설계사의 연간 누적 이수 시간을 조회해 의무 충족 여부를 판단한다.
+ * 메뉴 AGENT_TRAINING 권한으로 보호된다.
+ */
@Tag(name = "보수교육 관리")
@RestController
@RequiredArgsConstructor
@@ -23,18 +34,21 @@ public class AgentTrainingController {
// ── Training ──────────────────────────────────────────────────────────────
+ /** 교육 이수 내역 목록 조회(페이징). READ 권한 필요. */
@GetMapping("/api/agent-trainings")
@RequirePermission(menu = "AGENT_TRAINING", perm = "READ")
public ApiResponse> list(@ModelAttribute AgentTrainingSearchParam param) {
return ApiResponse.ok(service.list(param));
}
+ /** 교육 이수 단건 상세 조회. READ 권한 필요. */
@GetMapping("/api/agent-trainings/{trainingId}")
@RequirePermission(menu = "AGENT_TRAINING", perm = "READ")
public ApiResponse detail(@PathVariable Long trainingId) {
return ApiResponse.ok(service.detail(trainingId));
}
+ /** 설계사의 특정 연도 누적 이수 시간 조회(의무 충족 판단용). READ 권한 필요. */
@GetMapping("/api/agent-trainings/annual-hours")
@RequirePermission(menu = "AGENT_TRAINING", perm = "READ")
public ApiResponse annualHours(@RequestParam Long agentId,
@@ -42,6 +56,7 @@ public class AgentTrainingController {
return ApiResponse.ok(service.annualHours(agentId, year));
}
+ /** 교육 이수 내역 등록. CREATE 권한 필요. */
@PostMapping("/api/agent-trainings")
@RequirePermission(menu = "AGENT_TRAINING", perm = "CREATE")
@DataChangeLog(menu = "AGENT_TRAINING", table = "agent_training")
@@ -49,6 +64,7 @@ public class AgentTrainingController {
return ApiResponse.ok(service.create(req));
}
+ /** 교육 이수 내역 수정. UPDATE 권한 필요. */
@PutMapping("/api/agent-trainings/{trainingId}")
@RequirePermission(menu = "AGENT_TRAINING", perm = "UPDATE")
@DataChangeLog(menu = "AGENT_TRAINING", table = "agent_training")
@@ -58,6 +74,7 @@ public class AgentTrainingController {
return ApiResponse.ok();
}
+ /** 교육 이수 내역 삭제. DELETE 권한 필요. */
@DeleteMapping("/api/agent-trainings/{trainingId}")
@RequirePermission(menu = "AGENT_TRAINING", perm = "DELETE")
@DataChangeLog(menu = "AGENT_TRAINING", table = "agent_training")
@@ -68,6 +85,7 @@ public class AgentTrainingController {
// ── Requirement ───────────────────────────────────────────────────────────
+ /** 연도별 의무 교육시간 기준 목록 조회. READ 권한 필요. */
@GetMapping("/api/training-requirements")
@RequirePermission(menu = "AGENT_TRAINING", perm = "READ")
public ApiResponse> listRequirements(
@@ -75,12 +93,14 @@ public class AgentTrainingController {
return ApiResponse.ok(service.listRequirements(param));
}
+ /** 특정 연도의 의무 교육시간 기준 조회. READ 권한 필요. */
@GetMapping("/api/training-requirements/{year}")
@RequirePermission(menu = "AGENT_TRAINING", perm = "READ")
public ApiResponse requirementByYear(@PathVariable int year) {
return ApiResponse.ok(service.requirementByYear(year));
}
+ /** 연도별 의무 교육시간 기준 저장(있으면 수정, 없으면 신규 = upsert). UPDATE 권한 필요. */
@PostMapping("/api/training-requirements")
@RequirePermission(menu = "AGENT_TRAINING", perm = "UPDATE")
@DataChangeLog(menu = "AGENT_TRAINING", table = "training_requirement")
diff --git a/ga-api/src/main/java/com/ga/api/controller/upload/UploadController.java b/ga-api/src/main/java/com/ga/api/controller/upload/UploadController.java
index e7f21e3..6cd97ad 100644
--- a/ga-api/src/main/java/com/ga/api/controller/upload/UploadController.java
+++ b/ga-api/src/main/java/com/ga/api/controller/upload/UploadController.java
@@ -18,15 +18,27 @@ import org.springframework.web.multipart.MultipartFile;
import java.util.List;
import java.util.Map;
+/**
+ * [엑셀 업로드 API]
+ *
+ * 신입 개발자 안내:
+ * - 보험사/내부에서 받은 엑셀을 "업로드 템플릿(templateCode)"의 규칙대로 파싱·변환하여 DB에 적재한다.
+ * - 템플릿은 "엑셀의 어느 컬럼(A,B,C..)을 어느 DB 필드(target_field)에 어떻게 변환해 넣을지"를 정의한다.
+ * - 흐름: (1) 샘플 헤더 추출 → (2) 미리보기로 변환 결과 확인 → (3) 실제 업로드(DB INSERT).
+ * - 실제 적재/검증 로직은 UploadService 가 담당하고, 여기서는 HTTP 입출력만 연결한다.
+ */
@Tag(name = "엑셀 업로드")
@Validated
@RestController
@RequiredArgsConstructor
public class UploadController {
+ // 업로드 파싱·변환·적재 핵심 서비스
private final UploadService uploadService;
+ // target_table 별 사용 가능한 컬럼 메타(화이트리스트 + 프론트 옵션) 제공 서비스
private final TargetFieldMetaService metaService;
+ // [실제 업로드] 파일을 템플릿 규칙대로 파싱·변환·검증 후 배치 INSERT 하고 처리 결과(성공/오류 건수 등)를 돌려준다.
@Operation(summary = "엑셀 업로드 처리",
description = "templateCode 에 해당하는 템플릿으로 파일을 파싱 · 변환 · 배치 INSERT 한다.")
@PostMapping("/api/upload/{templateCode}")
@@ -37,6 +49,7 @@ public class UploadController {
return ApiResponse.ok(result);
}
+ // [미리보기] DB에 저장하지 않고 상위 N행을 템플릿대로 변환만 해 보여준다. 매핑이 맞는지 사전 확인용.
@Operation(summary = "업로드 미리보기 (상위 5행)",
description = "DB 에 저장하지 않고 변환 결과만 반환한다.")
@PostMapping("/api/upload-templates/{templateCode}/preview")
@@ -49,6 +62,7 @@ public class UploadController {
return ApiResponse.ok(rows);
}
+ // [헤더 추출] 템플릿을 만들기 전 단계. 샘플 엑셀의 헤더 행과 몇 줄을 읽어 프론트가 컬럼 매핑 UI를 자동 구성하게 한다.
@Operation(summary = "샘플 엑셀 헤더 추출",
description = "템플릿 등록 전에 샘플 파일 첫 행 헤더 + 미리보기 행을 추출한다. " +
"프론트는 이 결과로 sourceColumn(A,B,C..) + sourceHeader 를 자동 채운다.")
@@ -62,6 +76,7 @@ public class UploadController {
return ApiResponse.ok(uploadService.extractHeaders(file, headerRow, sheetIndex, previewRows));
}
+ // [컬럼 메타] 특정 대상 테이블에 넣을 수 있는 DB 필드 목록(한글명/타입/필수여부)을 반환. 매핑 시 어떤 필드를 고를지 안내.
@Operation(summary = "target_table 별 사용 가능한 컬럼 메타",
description = "프론트의 target_field Select 옵션 + 타입 자동 채우기에 사용한다.")
@GetMapping("/api/upload-templates/target-fields/{targetTable}")
@@ -70,6 +85,7 @@ public class UploadController {
return ApiResponse.ok(metaService.getFields(targetTable));
}
+ // [대상 테이블 목록] 업로드로 적재 가능한 테이블 이름들(화이트리스트)을 반환.
@Operation(summary = "사용 가능한 target_table 목록")
@GetMapping("/api/upload-templates/target-tables")
@RequirePermission(menu = "SYSTEM_UPLOAD_TEMPLATE", perm = "READ")
diff --git a/ga-api/src/main/java/com/ga/api/controller/upload/UploadTemplateController.java b/ga-api/src/main/java/com/ga/api/controller/upload/UploadTemplateController.java
index 4ce00e4..4e559a6 100644
--- a/ga-api/src/main/java/com/ga/api/controller/upload/UploadTemplateController.java
+++ b/ga-api/src/main/java/com/ga/api/controller/upload/UploadTemplateController.java
@@ -14,6 +14,16 @@ import org.springframework.web.bind.annotation.*;
import java.util.List;
+/**
+ * [업로드 템플릿 관리 API]
+ *
+ * 신입 개발자 안내:
+ * - "업로드 템플릿"이란 엑셀 → DB 적재 규칙의 묶음이다.
+ * 템플릿 본체(upload_template) + 컬럼 매핑 정의(upload_template_column) + 업로드 이력(upload_history)으로 구성된다.
+ * - 컬럼 매핑은 "엑셀 컬럼(sourceColumn) → 변환규칙(transformRule) → DB 필드(targetField)"를 한 줄씩 정의한다.
+ * - 실제 엑셀 파싱/적재는 UploadController + UploadService 가 담당하고, 여기는 템플릿 CRUD/이력 조회만 다룬다.
+ * - @DataChangeLog: 변경(등록/수정/삭제)은 감사 로그로 남긴다.
+ */
@Tag(name = "업로드 템플릿 관리")
@RestController
@RequestMapping("/api/upload-templates")
@@ -22,6 +32,7 @@ public class UploadTemplateController {
private final UploadTemplateService templateService;
+ // 템플릿 목록 (검색/페이징)
@Operation(summary = "템플릿 목록 조회")
@GetMapping
@RequirePermission(menu = "SYSTEM_UPLOAD_TEMPLATE", perm = "READ")
@@ -29,6 +40,7 @@ public class UploadTemplateController {
return ApiResponse.ok(templateService.list(param));
}
+ // 템플릿 1건 + 그 컬럼 매핑 정의까지 함께 조회
@Operation(summary = "템플릿 상세 조회 (컬럼 포함)")
@GetMapping("/{templateId}")
@RequirePermission(menu = "SYSTEM_UPLOAD_TEMPLATE", perm = "READ")
@@ -36,6 +48,7 @@ public class UploadTemplateController {
return ApiResponse.ok(templateService.detail(templateId));
}
+ // 템플릿 신규 등록 (templateCode 중복 불가). 컬럼 정의를 함께 보내면 같이 저장된다.
@Operation(summary = "템플릿 등록")
@PostMapping
@RequirePermission(menu = "SYSTEM_UPLOAD_TEMPLATE", perm = "CREATE")
@@ -44,6 +57,7 @@ public class UploadTemplateController {
return ApiResponse.ok(templateService.create(req));
}
+ // 템플릿 수정. 컬럼 정의가 함께 오면 기존 컬럼을 지우고 재등록한다(전체 교체).
@Operation(summary = "템플릿 수정")
@PutMapping("/{templateId}")
@RequirePermission(menu = "SYSTEM_UPLOAD_TEMPLATE", perm = "UPDATE")
@@ -54,6 +68,7 @@ public class UploadTemplateController {
return ApiResponse.ok();
}
+ // 템플릿 삭제 (컬럼 정의도 함께 삭제)
@Operation(summary = "템플릿 삭제")
@DeleteMapping("/{templateId}")
@RequirePermission(menu = "SYSTEM_UPLOAD_TEMPLATE", perm = "DELETE")
@@ -63,6 +78,7 @@ public class UploadTemplateController {
return ApiResponse.ok();
}
+ // 템플릿의 컬럼 매핑 정의만 따로 조회
@Operation(summary = "템플릿 컬럼 목록 조회")
@GetMapping("/{templateId}/columns")
@RequirePermission(menu = "SYSTEM_UPLOAD_TEMPLATE", perm = "READ")
@@ -70,6 +86,7 @@ public class UploadTemplateController {
return ApiResponse.ok(templateService.columns(templateId));
}
+ // 컬럼 매핑만 통째로 교체(기존 전체 삭제 후 새로 등록). 매핑 편집 화면 저장에 사용.
@Operation(summary = "템플릿 컬럼 전체 갱신 (기존 삭제 후 재등록)")
@PutMapping("/{templateId}/columns")
@RequirePermission(menu = "SYSTEM_UPLOAD_TEMPLATE", perm = "UPDATE")
@@ -80,6 +97,7 @@ public class UploadTemplateController {
return ApiResponse.ok();
}
+ // 이 템플릿으로 수행한 과거 업로드 이력(성공/오류 건수, 상태 등) 조회
@Operation(summary = "템플릿 업로드 이력 조회")
@GetMapping("/{templateId}/history")
@RequirePermission(menu = "SYSTEM_UPLOAD_TEMPLATE", perm = "READ")
diff --git a/ga-api/src/main/java/com/ga/api/controller/withdraw/WithdrawRequestController.java b/ga-api/src/main/java/com/ga/api/controller/withdraw/WithdrawRequestController.java
index 406afae..73f9a83 100644
--- a/ga-api/src/main/java/com/ga/api/controller/withdraw/WithdrawRequestController.java
+++ b/ga-api/src/main/java/com/ga/api/controller/withdraw/WithdrawRequestController.java
@@ -13,6 +13,17 @@ import jakarta.validation.Valid;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.*;
+/**
+ * 출금 신청(withdraw_request) 컨트롤러.
+ *
+ * 설계사가 자기 정산 잔액에서 돈을 빼달라고 요청하는 화면입니다. 신청하면 결재(승인) 절차가 자동으로 연동되고,
+ * 승인 후 펌뱅킹(은행 이체)으로 실제 입금이 처리됩니다.
+ *
+ *
상태 흐름(WithdrawStatus): REQUESTED(신청) → APPROVED(승인) → SENT(이체요청) → COMPLETED(입금완료).
+ * 취소는 아직 신청(REQUESTED) 상태일 때만 가능합니다. 응답의 계좌번호(accountNo)는 뒤 4자리만 보이도록 마스킹됩니다.
+ *
+ *
권한(menu=WITHDRAW): 조회 READ, 신청 CREATE, 취소 UPDATE.
+ */
@Tag(name = "출금 신청")
@RestController
@RequestMapping("/api/withdraw-requests")
@@ -21,18 +32,21 @@ public class WithdrawRequestController {
private final WithdrawRequestService service;
+ /** 출금 신청 목록 조회(검색 + 페이징). 계좌번호는 마스킹되어 반환됩니다. */
@GetMapping
@RequirePermission(menu = "WITHDRAW", perm = "READ")
public ApiResponse> list(@ModelAttribute WithdrawRequestSearchParam param) {
return ApiResponse.ok(service.list(param));
}
+ /** 출금 신청 단건 상세 조회. 계좌번호는 마스킹되어 반환됩니다. */
@GetMapping("/{requestId}")
@RequirePermission(menu = "WITHDRAW", perm = "READ")
public ApiResponse detail(@PathVariable Long requestId) {
return ApiResponse.ok(service.detail(requestId));
}
+ /** 출금 신청 등록(REQUESTED 상태). 등록과 동시에 결재 요청이 자동 생성됩니다. */
@PostMapping
@RequirePermission(menu = "WITHDRAW", perm = "CREATE")
@DataChangeLog(menu = "WITHDRAW", table = "withdraw_request")
@@ -40,6 +54,7 @@ public class WithdrawRequestController {
return ApiResponse.ok(service.create(req));
}
+ /** 출금 신청 취소. 신청(REQUESTED) 상태에서만 가능합니다. */
@PostMapping("/{requestId}/cancel")
@RequirePermission(menu = "WITHDRAW", perm = "UPDATE")
@DataChangeLog(menu = "WITHDRAW", table = "withdraw_request")
diff --git a/ga-api/src/main/java/com/ga/api/service/accounting/ContractAccountingService.java b/ga-api/src/main/java/com/ga/api/service/accounting/ContractAccountingService.java
index 033742e..926d6f6 100644
--- a/ga-api/src/main/java/com/ga/api/service/accounting/ContractAccountingService.java
+++ b/ga-api/src/main/java/com/ga/api/service/accounting/ContractAccountingService.java
@@ -19,6 +19,13 @@ import java.time.LocalDate;
import java.util.ArrayList;
import java.util.List;
+/**
+ * 계약 회계 분개(contract_accounting_entry) 서비스.
+ *
+ * 수수료 지급(payment) 건을 복식부기 분개로 자동 변환합니다.
+ * 분개 1건 = 차변(8350 지급수수료) / 대변(2530 미지급금), 금액은 실지급액(netAmount, 없으면 payAmount)을 사용합니다.
+ * generateFromPayments 로 분개를 일괄 생성하고, closeJournal 로 전표번호를 부여해 마감합니다.
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -30,11 +37,13 @@ public class ContractAccountingService {
private final ContractAccountingEntryMapper entryMapper;
private final PaymentMapper paymentMapper;
+ /** 분개 엔트리 목록 조회(페이징). */
public PageResponse list(ContractAccountingEntrySearchParam param) {
param.startPage();
return PageResponse.of(entryMapper.selectList(param));
}
+ /** 지급건들을 분개로 변환해 일괄 INSERT. 대상이 하나도 없으면 NOT_FOUND. 반환값은 생성된 분개 수. */
@Transactional
public int generateFromPayments(GenerateEntriesReq req) {
List payments = resolvePayments(req);
@@ -47,6 +56,7 @@ public class ContractAccountingService {
return entryMapper.insertBatch(entries);
}
+ /** 지정한 분개들에 전표번호를 부여해 마감. 반환값은 마감 처리된 분개 수. */
@Transactional
public int closeJournal(CloseJournalReq req) {
if (req.getEntryIds() == null || req.getEntryIds().isEmpty()) {
@@ -55,6 +65,7 @@ public class ContractAccountingService {
return entryMapper.closeJournal(req.getEntryIds(), req.getJournalNo());
}
+ /** 분개 대상 지급건 결정: paymentIds 우선, 없으면 settleMonth 전체, 둘 다 없으면 빈 목록. */
private List resolvePayments(GenerateEntriesReq req) {
if (req.getPaymentIds() != null && !req.getPaymentIds().isEmpty()) {
List result = new ArrayList<>();
@@ -70,6 +81,7 @@ public class ContractAccountingService {
return List.of();
}
+ /** 지급 1건 → 분개 VO 변환(분개일=오늘, 금액=netAmount 우선). */
private ContractAccountingEntryVO buildEntry(PaymentVO p) {
ContractAccountingEntryVO vo = new ContractAccountingEntryVO();
vo.setPaymentId(p.getPaymentId());
diff --git a/ga-api/src/main/java/com/ga/api/service/approval/ApprovalService.java b/ga-api/src/main/java/com/ga/api/service/approval/ApprovalService.java
index 813acc9..12543e8 100644
--- a/ga-api/src/main/java/com/ga/api/service/approval/ApprovalService.java
+++ b/ga-api/src/main/java/com/ga/api/service/approval/ApprovalService.java
@@ -33,6 +33,21 @@ import org.springframework.transaction.annotation.Transactional;
import java.time.LocalDateTime;
import java.util.List;
+/**
+ * 전자결재 도메인 비즈니스 로직.
+ *
+ * 결재선(line)과 결재 단계(step) 템플릿을 관리하고, 결재 요청(request)을 단계별로 진행시킨다.
+ * 핵심 흐름:
+ *
+ * - 상신: createRequest → 상태 PENDING, currentStep=1, 1단계 결재자 알림.
+ * - 진행: advance → 이력 INSERT 후 APPROVE/REJECT 처리. REJECT면 즉시 REJECTED 종료,
+ * APPROVE면 다음 단계로 진행하거나(현재단계 < maxStep) 마지막 단계면 APPROVED 후 콜백.
+ * - 최종 승인 콜백(handleApprovalCallback): targetType별로 출금/정산/이의신청/시책 도메인 상태를 갱신.
+ * 출금(WITHDRAW)은 추가로 펌뱅킹 어댑터에 이체를 요청한다(어댑터 실패해도 결재 흐름은 깨지지 않음).
+ *
+ * 외부 발송(SMS/펌뱅킹)은 비핵심(non-critical)으로 처리해 실패 시 로깅만 하고 결재 트랜잭션은 진행한다.
+ * 클래스 전체는 읽기 전용이며 쓰기 메서드만 별도 트랜잭션을 건다.
+ */
@Slf4j
@Service
@RequiredArgsConstructor
@@ -58,21 +73,25 @@ public class ApprovalService {
// ── Line ──────────────────────────────────────────────────────────────────
+ /** 결재선 목록 조회(페이징). */
public PageResponse listLines(ApprovalLineSearchParam param) {
param.startPage();
return PageResponse.of(lineMapper.selectList(param));
}
+ /** 결재선 상세 조회. 없으면 NOT_FOUND. */
public ApprovalLineResp detailLine(Long lineId) {
ApprovalLineResp resp = lineMapper.selectById(lineId);
if (resp == null) throw new BizException(ErrorCode.NOT_FOUND);
return resp;
}
+ /** 특정 결재선의 단계 목록 조회. */
public List stepsOfLine(Long lineId) {
return stepMapper.selectByLine(lineId);
}
+ /** 결재선 등록. 활성 상태로 시작하고 작성자를 기록한다. */
@Transactional
public Long createLine(ApprovalLineSaveReq req) {
ApprovalLineVO vo = new ApprovalLineVO();
@@ -86,6 +105,7 @@ public class ApprovalService {
return vo.getLineId();
}
+ /** 결재선 수정. 존재 검증 후 갱신한다. */
@Transactional
public void updateLine(Long lineId, ApprovalLineSaveReq req) {
ApprovalLineResp existing = lineMapper.selectById(lineId);
@@ -99,6 +119,7 @@ public class ApprovalService {
lineMapper.update(vo);
}
+ /** 결재선에 단계(step) 추가. 단계 순번(stepNo)과 결재 역할(roleCode)을 저장한다. */
@Transactional
public void addStep(ApprovalLineStepSaveReq req) {
ApprovalLineStepVO vo = new ApprovalLineStepVO();
@@ -110,6 +131,7 @@ public class ApprovalService {
// ── Request ───────────────────────────────────────────────────────────────
+ /** 결재 요청 전체 목록 조회(페이징). */
public PageResponse listRequests(ApprovalRequestSearchParam param) {
param.startPage();
return PageResponse.of(requestMapper.selectList(param));
@@ -129,12 +151,14 @@ public class ApprovalService {
return PageResponse.of(requestMapper.selectList(param));
}
+ /** 결재 요청 상세 조회. 없으면 NOT_FOUND. */
public ApprovalRequestResp detailRequest(Long requestId) {
ApprovalRequestResp resp = requestMapper.selectById(requestId);
if (resp == null) throw new BizException(ErrorCode.NOT_FOUND);
return resp;
}
+ /** 결재 요청의 단계별 처리 이력 조회. */
public List historyOfRequest(Long requestId) {
return historyMapper.selectByRequest(requestId);
}
diff --git a/ga-api/src/main/java/com/ga/api/service/attachment/AttachmentService.java b/ga-api/src/main/java/com/ga/api/service/attachment/AttachmentService.java
index 27c5a94..ec13884 100644
--- a/ga-api/src/main/java/com/ga/api/service/attachment/AttachmentService.java
+++ b/ga-api/src/main/java/com/ga/api/service/attachment/AttachmentService.java
@@ -22,6 +22,13 @@ import java.nio.file.Paths;
import java.util.List;
import java.util.UUID;
+/**
+ * 첨부파일 도메인 비즈니스 로직.
+ *
+ * 파일은 {@code app.attachment.path}(기본 ./uploads) 아래 refType별 폴더에 UUID 접두 파일명으로 저장하고,
+ * 메타는 DB에 적재한다. 파일 저장이 실패해도 메타는 남기되 경로를 {@code [STORAGE_FAILED]} 로 표시해
+ * 다운로드를 막는다(데이터 유실 추적 가능). 클래스 전체는 읽기 전용이며 쓰기 메서드만 별도 트랜잭션을 건다.
+ */
@Slf4j
@Service
@RequiredArgsConstructor
@@ -33,15 +40,18 @@ public class AttachmentService {
@Value("${app.attachment.path:./uploads}")
private String uploadBasePath;
+ /** 첨부 메타 목록 조회(페이징). */
public PageResponse list(AttachmentSearchParam param) {
param.startPage();
return PageResponse.of(mapper.selectList(param));
}
+ /** 특정 대상(refType+refId)에 연결된 첨부 목록 조회. */
public List listByRef(String refType, Long refId) {
return mapper.selectByRef(refType, refId);
}
+ /** 첨부 메타 단건 조회. 없으면 NOT_FOUND. */
public AttachmentResp detail(Long attachmentId) {
AttachmentResp resp = mapper.selectById(attachmentId);
if (resp == null) throw new BizException(ErrorCode.NOT_FOUND);
diff --git a/ga-api/src/main/java/com/ga/api/service/chargeback/ChargebackCalculator.java b/ga-api/src/main/java/com/ga/api/service/chargeback/ChargebackCalculator.java
index 10ebaa9..cd382fc 100644
--- a/ga-api/src/main/java/com/ga/api/service/chargeback/ChargebackCalculator.java
+++ b/ga-api/src/main/java/com/ga/api/service/chargeback/ChargebackCalculator.java
@@ -11,26 +11,41 @@ import java.time.LocalDate;
import java.time.format.DateTimeFormatter;
import java.time.temporal.ChronoUnit;
+/**
+ * 차등환수 금액 계산기.
+ * 조기해지 시 "경과개월수 → 적용 환수율 → 환수액" 순으로 계산한다.
+ * 핵심 공식: 환수액 = 원수수료 × 환수율(%) / 100 (소수점 반올림).
+ */
@Component
@RequiredArgsConstructor
public class ChargebackCalculator {
+ /** 환수 등급의 유효기간 비교에 쓰는 날짜 포맷. */
private static final DateTimeFormatter DATE_FMT = DateTimeFormatter.ofPattern("yyyy-MM-dd");
private final ChargebackGradeMapper gradeMapper;
+ /**
+ * 환수액을 계산한다.
+ * 1) 계약일~해지일의 경과개월수(monthsElapsed)를 구한다.
+ * 2) 상품분류·경과월·기준일에 맞는 환수 등급(환수율 구간)을 조회한다.
+ * 3) 해당 구간이 없으면 환수 0원, 있으면 원수수료 × 환수율로 환수액을 산출한다.
+ */
public ChargebackResult calculate(LocalDate contractDate, LocalDate terminationDate,
BigDecimal originalCommission, String productCategory) {
int monthsElapsed = (int) ChronoUnit.MONTHS.between(contractDate, terminationDate);
String today = LocalDate.now().format(DATE_FMT);
+ // 상품분류 + 경과월이 속한 환수율 구간을 조회(오늘 기준 유효한 등급)
ChargebackGradeVO grade = gradeMapper.selectByMonths(productCategory, monthsElapsed, today);
if (grade == null) {
+ // 적용할 환수 구간이 없으면 환수하지 않음(0원)
return new ChargebackResult(BigDecimal.ZERO, monthsElapsed, BigDecimal.ZERO,
"적용 환수 구간 없음");
}
+ // 환수액 = 원수수료 × 환수율 / 100, 원 단위 반올림(HALF_UP)
BigDecimal chargebackAmount = originalCommission
.multiply(grade.getChargebackPercent())
.divide(BigDecimal.valueOf(100), 0, RoundingMode.HALF_UP);
diff --git a/ga-api/src/main/java/com/ga/api/service/chargeback/ChargebackGradeService.java b/ga-api/src/main/java/com/ga/api/service/chargeback/ChargebackGradeService.java
index 0b82da2..be21b8f 100644
--- a/ga-api/src/main/java/com/ga/api/service/chargeback/ChargebackGradeService.java
+++ b/ga-api/src/main/java/com/ga/api/service/chargeback/ChargebackGradeService.java
@@ -15,20 +15,28 @@ import org.springframework.transaction.annotation.Transactional;
import java.time.LocalDate;
import java.time.format.DateTimeFormatter;
+/**
+ * 차등환수 등급(chargeback_grade) 마스터 비즈니스 로직 서비스.
+ * "경과개월 구간별 환수율(%)" 기준표를 CRUD 하고 활성/비활성을 관리한다.
+ * 이 기준표가 ChargebackCalculator 의 환수율 조회 대상이 된다.
+ */
@Service
@RequiredArgsConstructor
public class ChargebackGradeService {
+ /** 등급 유효기간 비교용 날짜 포맷. */
private static final DateTimeFormatter DATE_FMT = DateTimeFormatter.ofPattern("yyyy-MM-dd");
private final ChargebackGradeMapper gradeMapper;
+ /** 환수 등급표 목록 페이징 조회. */
@Transactional(readOnly = true)
public PageResponse list(ChargebackGradeSearchParam param) {
param.startPage();
return PageResponse.of(gradeMapper.selectList(param));
}
+ /** 환수 등급 상세 조회. 없으면 NOT_FOUND. */
@Transactional(readOnly = true)
public ChargebackGradeResp detail(Long gradeId) {
ChargebackGradeResp resp = gradeMapper.selectDetailById(gradeId);
@@ -36,6 +44,7 @@ public class ChargebackGradeService {
return resp;
}
+ /** 환수 등급 신규 등록. 같은 상품분류의 시작개월(monthsFrom) 구간이 이미 활성이면 중복 오류. */
@Transactional
public void create(ChargebackGradeSaveReq req) {
String today = LocalDate.now().format(DATE_FMT);
@@ -47,6 +56,7 @@ public class ChargebackGradeService {
gradeMapper.insert(toVO(req));
}
+ /** 환수 등급 수정. 활성 여부(isActive)는 기존 값을 유지(수정 API로는 변경하지 않음). */
@Transactional
public void update(Long gradeId, ChargebackGradeSaveReq req) {
ChargebackGradeVO existing = gradeMapper.selectById(gradeId);
@@ -57,6 +67,7 @@ public class ChargebackGradeService {
gradeMapper.update(vo);
}
+ /** 환수 등급 비활성화. 이미 비활성이면 잘못된 요청 처리. */
@Transactional
public void deactivate(Long gradeId) {
ChargebackGradeVO existing = gradeMapper.selectById(gradeId);
@@ -67,11 +78,13 @@ public class ChargebackGradeService {
gradeMapper.updateStatus(gradeId, false);
}
+ /** 상품분류·경과월·기준일에 해당하는 환수율 구간 1건 조회(계산기가 사용). */
@Transactional(readOnly = true)
public ChargebackGradeVO selectByMonths(String productCategory, Integer monthsElapsed, String baseDate) {
return gradeMapper.selectByMonths(productCategory, monthsElapsed, baseDate);
}
+ /** 저장 요청 DTO(SaveReq)를 DB 엔티티(VO)로 변환하는 내부 헬퍼. 신규는 항상 활성(true). */
private ChargebackGradeVO toVO(ChargebackGradeSaveReq req) {
ChargebackGradeVO vo = new ChargebackGradeVO();
vo.setProductCategory(req.getProductCategory());
diff --git a/ga-api/src/main/java/com/ga/api/service/chargeback/ChargebackResult.java b/ga-api/src/main/java/com/ga/api/service/chargeback/ChargebackResult.java
index 57a2065..351bd75 100644
--- a/ga-api/src/main/java/com/ga/api/service/chargeback/ChargebackResult.java
+++ b/ga-api/src/main/java/com/ga/api/service/chargeback/ChargebackResult.java
@@ -2,6 +2,13 @@ package com.ga.api.service.chargeback;
import java.math.BigDecimal;
+/**
+ * 차등환수 계산 결과를 담는 불변 레코드(record).
+ * - chargebackAmount : 환수(회수)할 금액
+ * - monthsElapsed : 계약일~해지일 경과개월수
+ * - appliedPercent : 적용된 환수율(%)
+ * - reason : 계산 근거 설명 문구
+ */
public record ChargebackResult(
BigDecimal chargebackAmount,
int monthsElapsed,
diff --git a/ga-api/src/main/java/com/ga/api/service/commission/AdvancePaymentService.java b/ga-api/src/main/java/com/ga/api/service/commission/AdvancePaymentService.java
index cddb6be..62f03a0 100644
--- a/ga-api/src/main/java/com/ga/api/service/commission/AdvancePaymentService.java
+++ b/ga-api/src/main/java/com/ga/api/service/commission/AdvancePaymentService.java
@@ -14,6 +14,15 @@ import org.springframework.transaction.annotation.Transactional;
import java.math.BigDecimal;
+/**
+ * 선지급정산 서비스.
+ *
+ * 선지급(advance): 미래 수수료를 미리 지급(가불)하고 추후 회수하는 제도.
+ * 잔액(balance) = 원금(principal) - 회수누계(recovered). 상태는 OUTSTANDING/PARTIAL/CLEARED/WAIVED.
+ *
+ * 클래스에 @Transactional(readOnly=true)가 걸려 있어 기본은 읽기 전용이고,
+ * 데이터를 바꾸는 메서드만 @Transactional 로 쓰기 트랜잭션을 연다.
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -21,11 +30,13 @@ public class AdvancePaymentService {
private final AdvancePaymentMapper mapper;
+ /** 선지급 목록 조회. startPage()로 PageHelper 페이징을 건 뒤 결과를 PageResponse 로 감싼다. */
public PageResponse list(AdvancePaymentSearchParam param) {
param.startPage();
return PageResponse.of(mapper.selectList(param));
}
+ /** 선지급 단건 상세 조회. 없으면 NOT_FOUND 예외. */
public AdvancePaymentResp detail(Long advanceId) {
AdvancePaymentResp resp = mapper.selectById(advanceId);
if (resp == null) throw new BizException(ErrorCode.NOT_FOUND);
@@ -33,7 +44,8 @@ public class AdvancePaymentService {
}
/**
- * 선지급 등록 — balance = principal, status = OUTSTANDING.
+ * 선지급 등록 — 처음에는 아직 한 푼도 회수하지 않았으므로
+ * 회수누계(recovered)=0, 잔액(balance)=원금(principal), 상태=OUTSTANDING(미상환)으로 시작한다.
*/
@Transactional
public Long create(AdvancePaymentSaveReq req) {
@@ -50,12 +62,14 @@ public class AdvancePaymentService {
}
/**
- * 선지급 면제 — status = WAIVED, balance = 0.
+ * 선지급 면제 — 남은 잔액 회수를 포기한다. 상태=WAIVED, 잔액=0 으로 바꾼다.
+ * 이미 완전회수(CLEARED)됐거나 이미 면제(WAIVED)된 건은 면제할 수 없어 INVALID_PARAMETER 예외.
*/
@Transactional
public void waive(Long advanceId) {
AdvancePaymentResp resp = mapper.selectById(advanceId);
if (resp == null) throw new BizException(ErrorCode.NOT_FOUND);
+ // 이미 종료(CLEARED) 또는 면제(WAIVED) 상태면 다시 면제 불가
if ("CLEARED".equals(resp.getStatus()) || "WAIVED".equals(resp.getStatus())) {
throw new BizException(ErrorCode.INVALID_PARAMETER);
}
diff --git a/ga-api/src/main/java/com/ga/api/service/commission/AwardService.java b/ga-api/src/main/java/com/ga/api/service/commission/AwardService.java
index 410ef8f..bdc3edb 100644
--- a/ga-api/src/main/java/com/ga/api/service/commission/AwardService.java
+++ b/ga-api/src/main/java/com/ga/api/service/commission/AwardService.java
@@ -14,6 +14,15 @@ import java.math.BigDecimal;
import java.math.RoundingMode;
import java.time.LocalDate;
+/**
+ * 시상(award) 서비스.
+ *
+ * 시상: 실적 조건 달성 설계사에게 주는 포상금. 규칙(Rule)에 산식이 정의된다.
+ * - calcType=FIXED: 정액(award_fixed) 지급 / calcType=RATE: 정률(실적 base x award_rate) 지급
+ * - thresholdAmount: 이 금액 이상 실적이어야 시상 발동(미달이면 시상 없음)
+ * - netAmount(실지급액) = awardAmount(시상액) - clawbackAmount(환수액)
+ * 상태: CALCULATED(산출) → CLAWED_BACK(환수적용) / CANCELLED(취소).
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -22,7 +31,7 @@ public class AwardService {
private final AwardRuleMapper ruleMapper;
private final AwardLedgerMapper ledgerMapper;
- // ── Rule ──────────────────────────────────────────────────────────────────
+ // ── Rule (시상 규칙) ────────────────────────────────────────────────────
public PageResponse listRules(AwardRuleSearchParam param) {
param.startPage();
@@ -72,7 +81,7 @@ public class AwardService {
ruleMapper.delete(ruleId);
}
- // ── Ledger ────────────────────────────────────────────────────────────────
+ // ── Ledger (시상 원장) ──────────────────────────────────────────────────
public PageResponse listLedgers(AwardLedgerSearchParam param) {
param.startPage();
@@ -85,9 +94,16 @@ public class AwardService {
return resp;
}
+ /**
+ * 시상 원장 생성(시상금 산출).
+ * 1) 시상유형(awardType)에 해당하는 현재 유효한 규칙을 찾는다.
+ * 2) 기준 실적(baseAmount)이 시상 기준(thresholdAmount) 미달이면 시상하지 않고 예외.
+ * 3) 규칙의 계산 방식(FIXED/RATE)에 따라 시상액(awardAmount)을 계산한다.
+ * 4) 환수액(clawback)을 빼서 실지급액(netAmount)을 구하고 상태 CALCULATED 로 저장한다.
+ */
@Transactional
public Long createLedger(AwardLedgerSaveReq req) {
- // 룰 조회로 calc_type 결정
+ // 룰 조회로 calc_type 결정 — 현재 날짜에 유효한(effective) 규칙을 가져온다
AwardRuleVO rule = ruleMapper.selectActiveRule(req.getAwardType(), LocalDate.now());
if (rule == null) throw new BizException(ErrorCode.NOT_FOUND);
@@ -101,21 +117,24 @@ public class AwardService {
BigDecimal awardAmount;
if ("FIXED".equals(rule.getCalcType())) {
+ // 정액 시상: 규칙에 정해진 고정 금액(award_fixed)을 그대로 지급
if (rule.getAwardFixed() == null) {
throw new BizException(ErrorCode.BAD_REQUEST, "FIXED 시상 룰에 award_fixed 가 설정되지 않았습니다");
}
awardAmount = rule.getAwardFixed().setScale(2, RoundingMode.HALF_UP);
} else {
- // RATE: base × award_rate
+ // RATE: 정률 시상 → 시상액 = 기준 실적(base) × 시상률(award_rate)
awardAmount = req.getBaseAmount()
.multiply(rule.getAwardRate())
.setScale(2, RoundingMode.HALF_UP);
}
+ // 환수액이 없으면 0으로 두고, 환수액이 시상액보다 크면 음수 지급이 되므로 금지
BigDecimal clawback = req.getClawbackAmount() != null ? req.getClawbackAmount() : BigDecimal.ZERO;
if (clawback.compareTo(awardAmount) > 0) {
throw new BizException(ErrorCode.INVALID_PARAMETER, "환수액이 시상액을 초과합니다");
}
+ // 실지급액 = 시상액 - 환수액
BigDecimal netAmount = awardAmount.subtract(clawback).setScale(2, RoundingMode.HALF_UP);
AwardLedgerVO vo = new AwardLedgerVO();
@@ -131,6 +150,11 @@ public class AwardService {
return vo.getLedgerId();
}
+ /**
+ * 이미 산출된 시상금에 환수(clawback)를 적용한다.
+ * 취소(CANCELLED)된 원장에는 적용 불가, 환수액은 시상액을 넘을 수 없다.
+ * 실지급액(net) = 시상액 - 환수액 으로 다시 계산하고 상태를 CLAWED_BACK 으로 바꾼다.
+ */
@Transactional
public void applyClawback(Long ledgerId, com.ga.api.controller.commission.AwardClawbackReq req) {
AwardLedgerResp ledger = ledgerMapper.selectById(ledgerId);
@@ -141,6 +165,7 @@ public class AwardService {
if (req.getClawbackAmount().compareTo(ledger.getAwardAmount()) > 0) {
throw new BizException(ErrorCode.INVALID_PARAMETER, "환수액이 시상액을 초과합니다");
}
+ // 환수 적용 후 실지급액 = 시상액 - 환수액
BigDecimal netAmount = ledger.getAwardAmount()
.subtract(req.getClawbackAmount())
.setScale(2, RoundingMode.HALF_UP);
diff --git a/ga-api/src/main/java/com/ga/api/service/commission/BranchAllowanceService.java b/ga-api/src/main/java/com/ga/api/service/commission/BranchAllowanceService.java
index d29adf7..01de9e5 100644
--- a/ga-api/src/main/java/com/ga/api/service/commission/BranchAllowanceService.java
+++ b/ga-api/src/main/java/com/ga/api/service/commission/BranchAllowanceService.java
@@ -13,6 +13,13 @@ import org.springframework.transaction.annotation.Transactional;
import java.math.BigDecimal;
import java.math.RoundingMode;
+/**
+ * 지점장수당 서비스.
+ *
+ * 지점장수당: 지점 실적(baseAmount)에 지급률(allowanceRate)을 곱해 지점장에게 주는 수당.
+ * 단, 상한(capAmount)이 있으면 그 이상은 지급하지 않는다 → allowance = min(base x rate, cap).
+ * (cap 이 NULL 이면 상한 없음). 규칙(Rule)에 직급별 지급률/상한을 정의한다.
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -21,7 +28,7 @@ public class BranchAllowanceService {
private final BranchMgrAllowanceRuleMapper ruleMapper;
private final BranchMgrAllowanceLedgerMapper ledgerMapper;
- // ── Rule ──────────────────────────────────────────────────────────────────
+ // ── Rule (수당 규칙) ────────────────────────────────────────────────────
public PageResponse listRules(BranchMgrAllowanceRuleSearchParam param) {
param.startPage();
@@ -67,7 +74,7 @@ public class BranchAllowanceService {
ruleMapper.delete(ruleId);
}
- // ── Ledger ────────────────────────────────────────────────────────────────
+ // ── Ledger (수당 원장) ──────────────────────────────────────────────────
public PageResponse listLedgers(BranchMgrAllowanceLedgerSearchParam param) {
param.startPage();
@@ -80,9 +87,13 @@ public class BranchAllowanceService {
return resp;
}
+ /**
+ * 지점장수당 원장 생성(수당 산출).
+ * 수당액 = min(기준실적 × 지급률, 상한). 상한(cap)이 없으면 그대로 지급.
+ */
@Transactional
public Long createLedger(BranchMgrAllowanceLedgerSaveReq req) {
- // 수당액 = min(base × rate, cap) — cap NULL이면 상한 없음
+ // 1단계: 상한 적용 전 원래 수당액 raw = 기준실적(base) × 지급률(rate)
BigDecimal raw = req.getBaseAmount()
.multiply(req.getAllowanceRate())
.setScale(2, RoundingMode.HALF_UP);
diff --git a/ga-api/src/main/java/com/ga/api/service/commission/CarrierReconciliationInService.java b/ga-api/src/main/java/com/ga/api/service/commission/CarrierReconciliationInService.java
index e8bf239..e38b228 100644
--- a/ga-api/src/main/java/com/ga/api/service/commission/CarrierReconciliationInService.java
+++ b/ga-api/src/main/java/com/ga/api/service/commission/CarrierReconciliationInService.java
@@ -13,6 +13,13 @@ import org.springframework.transaction.annotation.Transactional;
import java.math.BigDecimal;
+/**
+ * 정산대사(입수) 서비스.
+ *
+ * 보험사가 보내준 정산 명세(reportedTotal)와 우리 시스템이 계산한 수입수수료 합계(systemTotal)를 맞춰 보고
+ * 그 차이(variance = reported - system)를 확인한다.
+ * 상태 흐름: RECEIVED(자료 입수) → reconcile() → MATCHED(차이<1, 일치) 또는 VARIANCE(차이 있음) → approve() → APPROVED(확정).
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -52,8 +59,10 @@ public class CarrierReconciliationInService {
}
/**
- * 대사 실행 — system_total = income_commission 집계, variance = reported − system.
- * |variance| < 1 이면 MATCHED, 아니면 VARIANCE.
+ * 대사 실행 — 시스템 합계(system_total)는 해당 보험사·정산월의 수입수수료를 집계해 구하고,
+ * 차이(variance) = 보험사 명세 합계(reported) - 시스템 합계(system) 로 계산한다.
+ * 차이의 절댓값이 1원 미만이면 사실상 일치로 보아 MATCHED, 그 외에는 VARIANCE 상태로 둔다.
+ * 이미 승인(APPROVED)된 건은 다시 대사할 수 없다.
*/
@Transactional
public void reconcile(Long reconId) {
@@ -61,11 +70,14 @@ public class CarrierReconciliationInService {
if (resp == null) throw new BizException(ErrorCode.NOT_FOUND);
if ("APPROVED".equals(resp.getStatus())) throw new BizException(ErrorCode.INVALID_PARAMETER);
+ // 우리 시스템이 계산한 수입수수료 합계(없으면 0)
BigDecimal systemTotal = incomeMapper.sumByCarrierAndMonth(
resp.getCompanyId(), resp.getSettleMonth());
if (systemTotal == null) systemTotal = BigDecimal.ZERO;
+ // 차이 = 보험사가 보고한 금액 - 시스템 계산 금액
BigDecimal variance = resp.getReportedTotal().subtract(systemTotal);
+ // |차이| < 1원 이면 일치(MATCHED), 아니면 차이남(VARIANCE)
String newStatus = variance.abs().compareTo(BigDecimal.ONE) < 0 ? "MATCHED" : "VARIANCE";
CarrierReconciliationInVO vo = buildVO(resp);
@@ -76,7 +88,8 @@ public class CarrierReconciliationInService {
}
/**
- * 승인 처리 — status = APPROVED.
+ * 승인 처리 — 대사 결과를 확정(status=APPROVED)한다.
+ * 아직 대사를 돌리지 않은 RECEIVED 상태에서는 바로 승인할 수 없다(먼저 reconcile 필요).
*/
@Transactional
public void approve(Long reconId) {
@@ -88,6 +101,7 @@ public class CarrierReconciliationInService {
mapper.update(vo);
}
+ /** 조회용 Resp 를 업데이트용 VO 로 그대로 복사하는 헬퍼(상태/금액만 바꿔 update 에 넘기기 위함). */
private CarrierReconciliationInVO buildVO(CarrierReconciliationInResp resp) {
CarrierReconciliationInVO vo = new CarrierReconciliationInVO();
vo.setReconId(resp.getReconId());
diff --git a/ga-api/src/main/java/com/ga/api/service/commission/ChargebackWaiverService.java b/ga-api/src/main/java/com/ga/api/service/commission/ChargebackWaiverService.java
index 75f4a9b..5361cff 100644
--- a/ga-api/src/main/java/com/ga/api/service/commission/ChargebackWaiverService.java
+++ b/ga-api/src/main/java/com/ga/api/service/commission/ChargebackWaiverService.java
@@ -12,6 +12,13 @@ import org.springframework.transaction.annotation.Transactional;
import java.time.LocalDateTime;
+/**
+ * 환수감면신청 서비스.
+ *
+ * 환수(chargeback): 지급했던 수수료를 회수하는 것. 감면(waiver): 그 환수액을 줄여 달라는 신청.
+ * 신청액(waiverAmount)은 원래 환수액(originalChargeback)을 넘을 수 없다.
+ * 승인 상태 흐름: REQUESTED(신청) → APPROVED(승인) 또는 REJECTED(반려). 승인/반려는 REQUESTED 상태에서만 가능.
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -31,10 +38,12 @@ public class ChargebackWaiverService {
}
/**
- * 감면 신청 등록 — waiver_amount <= original_chargeback 검증.
+ * 감면 신청 등록. 감면 신청액은 원래 환수액 이하여야 한다(초과 시 INVALID_PARAMETER).
+ * 등록 시 승인 상태는 REQUESTED(신청 접수)로 시작하며, 신청자(현재 사용자)를 기록한다.
*/
@Transactional
public Long create(ChargebackWaiverRequestSaveReq req) {
+ // 감면액이 원래 환수액보다 크면 말이 안 되므로 거절
if (req.getWaiverAmount().compareTo(req.getOriginalChargeback()) > 0) {
throw new BizException(ErrorCode.INVALID_PARAMETER);
}
@@ -52,7 +61,8 @@ public class ChargebackWaiverService {
}
/**
- * 승인 처리 — approval_status = APPROVED, approver_id = 현재 사용자, approved_at = now.
+ * 승인 처리 — 신청을 승인한다. 승인 상태를 APPROVED 로 바꾸고 승인자(현재 사용자)와 승인 시각을 기록한다.
+ * REQUESTED(신청) 상태가 아니면(이미 승인/반려됨) 처리할 수 없다.
*/
@Transactional
public void approve(Long requestId) {
@@ -63,7 +73,7 @@ public class ChargebackWaiverService {
}
/**
- * 반려 처리 — approval_status = REJECTED.
+ * 반려 처리 — 신청을 반려한다(승인 상태 REJECTED). REQUESTED 상태에서만 가능.
*/
@Transactional
public void reject(Long requestId) {
diff --git a/ga-api/src/main/java/com/ga/api/service/commission/ClawbackInstallmentService.java b/ga-api/src/main/java/com/ga/api/service/commission/ClawbackInstallmentService.java
index 36f6f17..ab242b0 100644
--- a/ga-api/src/main/java/com/ga/api/service/commission/ClawbackInstallmentService.java
+++ b/ga-api/src/main/java/com/ga/api/service/commission/ClawbackInstallmentService.java
@@ -16,6 +16,12 @@ import java.math.RoundingMode;
import java.util.ArrayList;
import java.util.List;
+/**
+ * 환수분할상환 서비스.
+ *
+ * 환수채권(받아야 할 환수금)을 N개월에 걸쳐 나눠 갚도록 회차별 상환 계획을 만든다.
+ * 회차 상태: SCHEDULED(예정) → 납입 시 별도 처리, 또는 CANCELLED(취소).
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -41,8 +47,10 @@ public class ClawbackInstallmentService {
/**
* 환수채권을 N회차로 균등 분할상환 계획 생성.
- * 마지막 회차는 잔차(총액 - 앞 회차 합계) 흡수.
- * 기준월: baseMonth(YYYYMM), due_month = baseMonth + (회차-1)
+ * 1원 단위 반올림 오차 때문에 회차를 똑같이 나누면 합계가 안 맞으므로,
+ * 앞 회차는 unit(버림 분할)로 채우고 마지막 회차가 잔차(총액 - 앞 회차 합계)를 흡수해 합계를 정확히 맞춘다.
+ * 회차별 납기(due_month) = baseMonth + (회차 - 1)개월.
+ * 이미 SCHEDULED 계획이 있으면 중복 생성 금지(DUPLICATE_DATA).
*/
@Transactional
public void generate(Long receivableId, int count, String baseMonth) {
@@ -57,14 +65,17 @@ public class ClawbackInstallmentService {
ClawbackReceivableResp receivableResp = receivableMapper.selectById(receivableId);
if (receivableResp == null) throw new BizException(ErrorCode.NOT_FOUND);
+ // 분할 대상 총액 = 환수채권 잔액. 0 이하이면 분할할 게 없으므로 예외
BigDecimal total = receivableResp.getBalance();
if (total == null || total.compareTo(BigDecimal.ZERO) <= 0)
throw new BizException(ErrorCode.INVALID_PARAMETER);
+ // 한 회차 금액(unit) = 총액 / 회차수 (소수점 버림), 마지막 회차(last)가 잔차를 흡수
BigDecimal unit = total.divide(BigDecimal.valueOf(count), 2, RoundingMode.DOWN);
BigDecimal sumBefore = unit.multiply(BigDecimal.valueOf(count - 1));
BigDecimal last = total.subtract(sumBefore);
+ // 1회차부터 count회차까지 SCHEDULED 상태로 생성(마지막 회차만 last 금액)
List plans = new ArrayList<>();
for (int i = 1; i <= count; i++) {
ClawbackInstallmentPlanVO vo = new ClawbackInstallmentPlanVO();
@@ -79,7 +90,7 @@ public class ClawbackInstallmentService {
}
/**
- * 분할상환 계획 취소 (SCHEDULED → CANCELLED).
+ * 분할상환 회차 취소. 아직 예정(SCHEDULED) 상태인 회차만 CANCELLED 로 바꿀 수 있다.
*/
@Transactional
public void cancel(Long planId) {
diff --git a/ga-api/src/main/java/com/ga/api/service/commission/ClawbackReceivableExcelRow.java b/ga-api/src/main/java/com/ga/api/service/commission/ClawbackReceivableExcelRow.java
index 4da2491..7e3e0e9 100644
--- a/ga-api/src/main/java/com/ga/api/service/commission/ClawbackReceivableExcelRow.java
+++ b/ga-api/src/main/java/com/ga/api/service/commission/ClawbackReceivableExcelRow.java
@@ -7,6 +7,11 @@ import java.math.BigDecimal;
/**
* 환수채권 엑셀 export 행.
+ *
+ * 환수채권(받아야 할 환수금) 목록을 엑셀로 내려받을 때 한 줄(row)에 들어갈 데이터를 담는 DTO.
+ * 각 필드의 @ExcelColumn(header/order/width)이 엑셀의 열 제목/순서/너비를 정의하고,
+ * codeGroup 이 붙은 필드(status)는 코드값을 한글 라벨로 변환해 출력한다.
+ *
* ga-core ClawbackReceivableResp 에 @ExcelColumn 없으므로 ga-api 전용 프로젝션.
* TODO: ga-core 에 ClawbackReceivableExcelVO + selectCursorForExcel 추가 후 이 클래스 제거 가능.
*/
diff --git a/ga-api/src/main/java/com/ga/api/service/commission/ClawbackReceivableService.java b/ga-api/src/main/java/com/ga/api/service/commission/ClawbackReceivableService.java
index c04df06..c8248e1 100644
--- a/ga-api/src/main/java/com/ga/api/service/commission/ClawbackReceivableService.java
+++ b/ga-api/src/main/java/com/ga/api/service/commission/ClawbackReceivableService.java
@@ -18,6 +18,12 @@ import java.util.Iterator;
import java.util.List;
import java.util.Map;
+/**
+ * 환수채권 관리 서비스.
+ *
+ * 환수채권(받아야 할 환수금) 조회·집계·대손처리·엑셀export 담당.
+ * 채권 상태 흐름: OUTSTANDING(미회수)/RECOVERING(회수중) → CLEARED(완전회수) 또는 WRITTEN_OFF(대손상각, 손실처리).
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -42,19 +48,23 @@ public class ClawbackReceivableService {
}
/**
- * 대손/직접상환 처리.
- * OUTSTANDING 또는 RECOVERING 채권만 허용, 전이 상태는 CLEARED/WRITTEN_OFF 만 가능.
+ * 대손/직접상환 처리(채권 종결).
+ * 아직 살아있는 채권(OUTSTANDING/RECOVERING)만 종결할 수 있고,
+ * 바꿀 수 있는 종결 상태는 CLEARED(전액 회수 완료) 또는 WRITTEN_OFF(회수 불가 → 손실처리)뿐이다.
+ * userId(처리자)와 종결 사유를 함께 기록한다.
*/
@Transactional
public void writeOff(Long id, ClawbackReceivableSaveReq req, Long userId) {
ClawbackReceivableResp target = mapper.selectById(id);
if (target == null) throw new BizException(ErrorCode.NOT_FOUND);
+ // 이미 종결(CLEARED/WRITTEN_OFF)된 채권은 다시 처리 불가
String currentStatus = target.getStatus();
if (!"OUTSTANDING".equals(currentStatus) && !"RECOVERING".equals(currentStatus)) {
throw new BizException(ErrorCode.INVALID_PARAMETER, "이미 종결된 채권입니다");
}
+ // 요청한 새 상태가 허용된 종결 상태인지 검증
String newStatus = req.getStatus();
if (!"CLEARED".equals(newStatus) && !"WRITTEN_OFF".equals(newStatus)) {
throw new BizException(ErrorCode.INVALID_PARAMETER, "전이 가능한 상태는 CLEARED 또는 WRITTEN_OFF 입니다");
diff --git a/ga-api/src/main/java/com/ga/api/service/commission/CollectionCommissionService.java b/ga-api/src/main/java/com/ga/api/service/commission/CollectionCommissionService.java
index d20fa09..e483362 100644
--- a/ga-api/src/main/java/com/ga/api/service/commission/CollectionCommissionService.java
+++ b/ga-api/src/main/java/com/ga/api/service/commission/CollectionCommissionService.java
@@ -10,6 +10,12 @@ import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
+/**
+ * 수금수수료 서비스.
+ *
+ * 수금수수료: 설계사가 보험료를 정상 수금한 것에 대한 수수료. 계산식 = 보험료(premium) x 수수료율(rate).
+ * 규칙(Rule)은 상품·납입주기별 수수료율을 정의하고, 원장(Ledger)에 실제 산출액을 기록한다.
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -18,7 +24,7 @@ public class CollectionCommissionService {
private final CollectionCommissionRuleMapper ruleMapper;
private final CollectionCommissionLedgerMapper ledgerMapper;
- // ── Rule ──────────────────────────────────────────────────────────────────
+ // ── Rule (수금수수료 규칙) ──────────────────────────────────────────────
public PageResponse listRules(CollectionCommissionRuleSearchParam param) {
param.startPage();
@@ -64,7 +70,7 @@ public class CollectionCommissionService {
ruleMapper.delete(ruleId);
}
- // ── Ledger ────────────────────────────────────────────────────────────────
+ // ── Ledger (수금수수료 원장) ────────────────────────────────────────────
public PageResponse listLedgers(CollectionCommissionLedgerSearchParam param) {
param.startPage();
@@ -77,6 +83,7 @@ public class CollectionCommissionService {
return resp;
}
+ /** 수금수수료 원장 생성. 수수료액 = 보험료 × 수수료율. 상태는 CALCULATED 로 저장. */
@Transactional
public Long createLedger(CollectionCommissionLedgerSaveReq req) {
CollectionCommissionLedgerVO vo = new CollectionCommissionLedgerVO();
diff --git a/ga-api/src/main/java/com/ga/api/service/commission/CommissionMasterService.java b/ga-api/src/main/java/com/ga/api/service/commission/CommissionMasterService.java
index 2138b88..8a753c3 100644
--- a/ga-api/src/main/java/com/ga/api/service/commission/CommissionMasterService.java
+++ b/ga-api/src/main/java/com/ga/api/service/commission/CommissionMasterService.java
@@ -12,6 +12,12 @@ import org.springframework.transaction.annotation.Transactional;
import java.util.List;
+/**
+ * 수수료 마스터 서비스.
+ *
+ * 수수료 마스터: 설계사·정산월 단위로 각종 수수료를 모아 최종 지급액을 관리하는 핵심 원장.
+ * 조회(목록/상세/설계사월별/월집계)와 상태 변경, 삭제를 담당한다.
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -19,25 +25,30 @@ public class CommissionMasterService {
private final CommissionMasterMapper mapper;
+ /** 수수료 마스터 목록 조회(검색 + 페이징). */
public PageResponse list(CommissionMasterSearchParam param) {
param.startPage();
return PageResponse.of(mapper.selectList(param));
}
+ /** 수수료 마스터 단건 상세. 없으면 NOT_FOUND. */
public CommissionMasterResp detail(Long masterId) {
CommissionMasterResp resp = mapper.selectById(masterId);
if (resp == null) throw new BizException(ErrorCode.NOT_FOUND);
return resp;
}
+ /** 특정 설계사의 특정 정산월 수수료 내역 조회. */
public List listByAgentAndMonth(Long agentId, String settleMonth) {
return mapper.selectByAgentAndMonth(agentId, settleMonth);
}
+ /** 정산월 단위 전체 집계(설계사별 합계 등) 조회. */
public List aggregatedByMonth(String settleMonth) {
return mapper.selectAggregatedByMonth(settleMonth);
}
+ /** 정산 상태 변경(예: CALCULATED → CONFIRMED → PAID 등 운영 단계 전이). 대상이 없으면 NOT_FOUND. */
@Transactional
public void updateStatus(Long masterId, String status) {
CommissionMasterResp resp = mapper.selectById(masterId);
@@ -45,6 +56,7 @@ public class CommissionMasterService {
mapper.updateStatus(masterId, status);
}
+ /** 수수료 마스터 삭제. 대상이 없으면 NOT_FOUND. */
@Transactional
public void delete(Long masterId) {
CommissionMasterResp resp = mapper.selectById(masterId);
diff --git a/ga-api/src/main/java/com/ga/api/service/commission/CommissionSimulationService.java b/ga-api/src/main/java/com/ga/api/service/commission/CommissionSimulationService.java
index 6d77fe9..fb842d6 100644
--- a/ga-api/src/main/java/com/ga/api/service/commission/CommissionSimulationService.java
+++ b/ga-api/src/main/java/com/ga/api/service/commission/CommissionSimulationService.java
@@ -16,12 +16,20 @@ import org.springframework.transaction.annotation.Transactional;
import java.math.BigDecimal;
import java.math.RoundingMode;
+/**
+ * 수수료 시뮬레이터 서비스.
+ *
+ * 실제 정산 전에 "이 조건이면 설계사가 얼마 받을까"를 미리 계산해 결과를 저장·반환한다(실지급에는 영향 없음).
+ * 계산 단계: 보험사지급액 → 설계사수수료 → 원천징수세(3.3%) 차감 → 실수령액, 그리고 예상 환수액까지 추정한다.
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
public class CommissionSimulationService {
+ /** 사업소득 원천징수 세율 3.3% (설계사 수수료에서 떼는 세금). */
private static final BigDecimal WITHHOLDING_TAX_RATE = new BigDecimal("0.033");
+ /** 예상 환수액 기본 추정 비율 50% (입력값이 없을 때 13개월 유지 가정으로 사용). */
private static final BigDecimal DEFAULT_CHARGEBACK_RATE = new BigDecimal("0.5");
private final CommissionSimulationMapper simulationMapper;
@@ -48,22 +56,27 @@ public class CommissionSimulationService {
*/
@Transactional
public CommissionSimulationResp simulate(CommissionSimulationSaveReq req) {
+ // 1) 보험사지급액 = 보험료 × 보험사요율 (GA가 보험사로부터 받는 돈)
BigDecimal companyPayment = req.getPremiumAmount()
.multiply(req.getCompanyRate())
.setScale(2, RoundingMode.HALF_UP);
+ // 2) 설계사수수료 = 보험사지급액 × 설계사 지급률
BigDecimal agentCommission = companyPayment
.multiply(req.getPayoutRate())
.setScale(2, RoundingMode.HALF_UP);
+ // 3) 원천징수세 = 설계사수수료 × 3.3%
BigDecimal withholdingTax = agentCommission
.multiply(WITHHOLDING_TAX_RATE)
.setScale(2, RoundingMode.HALF_UP);
+ // 4) 실수령액 = 설계사수수료 - 원천징수세
BigDecimal netAmount = agentCommission
.subtract(withholdingTax)
.setScale(2, RoundingMode.HALF_UP);
+ // 5) 예상 환수액: 입력값이 있으면 그대로, 없으면 설계사수수료 × 50%로 추정
BigDecimal expectedChargeback;
if (req.getExpectedChargeback() != null) {
expectedChargeback = req.getExpectedChargeback().setScale(2, RoundingMode.HALF_UP);
diff --git a/ga-api/src/main/java/com/ga/api/service/commission/GradeEvaluationService.java b/ga-api/src/main/java/com/ga/api/service/commission/GradeEvaluationService.java
index 437b9e9..3e2c5f9 100644
--- a/ga-api/src/main/java/com/ga/api/service/commission/GradeEvaluationService.java
+++ b/ga-api/src/main/java/com/ga/api/service/commission/GradeEvaluationService.java
@@ -19,6 +19,12 @@ import org.springframework.transaction.annotation.Transactional;
import java.time.LocalDate;
+/**
+ * 등급평가 서비스.
+ *
+ * 설계사 실적점수(performanceScore)를 규칙(Rule: 등급별 최소점수 minScore)에 맞춰 등급을 매긴다.
+ * 평가 상태: EVALUATED(평가 완료, 미반영) → applyEval() → APPLIED(실제 등급에 반영).
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -27,7 +33,7 @@ public class GradeEvaluationService {
private final GradeEvalRuleMapper ruleMapper;
private final AgentGradeEvaluationMapper evalMapper;
- // ── Rule ──────────────────────────────────────────────────────────────────
+ // ── Rule (평가 규칙) ────────────────────────────────────────────────────
public PageResponse listRules(GradeEvalRuleSearchParam param) {
param.startPage();
@@ -71,7 +77,7 @@ public class GradeEvaluationService {
ruleMapper.delete(ruleId);
}
- // ── Evaluation ────────────────────────────────────────────────────────────
+ // ── Evaluation (평가 결과) ──────────────────────────────────────────────
public PageResponse listEvals(AgentGradeEvaluationSearchParam param) {
param.startPage();
@@ -85,15 +91,17 @@ public class GradeEvaluationService {
}
/**
- * 등급평가 생성.
- * selectActiveRuleByScore(score, 기준일)로 evaluated_grade_id 결정.
- * 매칭 룰 없으면 prevGradeId 유지 또는 null.
+ * 등급평가 생성. 실적점수에 해당하는 유효 규칙을 찾아 평가등급(evaluatedGradeId)을 결정한다.
+ * 점수에 맞는 규칙이 없으면 기존 등급(prevGradeId)을 그대로 유지한다(없으면 null).
+ * 생성 시 상태는 EVALUATED(아직 미반영).
*/
@Transactional
public Long createEval(AgentGradeEvaluationSaveReq req) {
+ // 오늘 기준 유효한 규칙 중, 이 실적점수가 충족하는 등급 규칙을 찾는다
LocalDate baseDate = LocalDate.now();
GradeEvalRuleVO matchedRule = ruleMapper.selectActiveRuleByScore(req.getPerformanceScore(), baseDate);
+ // 매칭 규칙이 있으면 그 등급, 없으면 기존 등급 유지
Long evaluatedGradeId = (matchedRule != null) ? matchedRule.getGradeId() : req.getPrevGradeId();
AgentGradeEvaluationVO vo = new AgentGradeEvaluationVO();
@@ -108,7 +116,8 @@ public class GradeEvaluationService {
}
/**
- * 등급평가 반영 액션 (EVALUATED → APPLIED).
+ * 등급평가 반영. 평가된 등급을 실제 설계사 등급에 적용한다(상태 EVALUATED → APPLIED).
+ * 이미 반영(APPLIED)된 건은 중복 반영할 수 없다.
*/
@Transactional
public void applyEval(Long evalId) {
@@ -120,6 +129,7 @@ public class GradeEvaluationService {
evalMapper.updateStatus(evalId, "APPLIED");
}
+ /** 등급평가 삭제. 대상이 없으면 NOT_FOUND. */
@Transactional
public void deleteEval(Long evalId) {
AgentGradeEvaluationResp resp = evalMapper.selectById(evalId);
diff --git a/ga-api/src/main/java/com/ga/api/service/commission/GuaranteeInsuranceService.java b/ga-api/src/main/java/com/ga/api/service/commission/GuaranteeInsuranceService.java
index 8d90a0f..7388e0d 100644
--- a/ga-api/src/main/java/com/ga/api/service/commission/GuaranteeInsuranceService.java
+++ b/ga-api/src/main/java/com/ga/api/service/commission/GuaranteeInsuranceService.java
@@ -12,6 +12,12 @@ import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
+/**
+ * 보증보험 서비스.
+ *
+ * 보증보험: 설계사가 선지급금 등 채무를 못 갚을 때를 대비한 보험. 설계사별 가입 정보(증권번호/보장한도/기간)를 관리.
+ * 등록 시 상태는 ACTIVE(유효)로 시작한다.
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -30,6 +36,7 @@ public class GuaranteeInsuranceService {
return resp;
}
+ /** 보증보험 가입 등록. 상태 ACTIVE 로 시작. 응답: 생성된 guaranteeId. */
@Transactional
public Long create(AgentGuaranteeInsuranceSaveReq req) {
AgentGuaranteeInsuranceVO vo = new AgentGuaranteeInsuranceVO();
diff --git a/ga-api/src/main/java/com/ga/api/service/commission/HqSettleService.java b/ga-api/src/main/java/com/ga/api/service/commission/HqSettleService.java
index 6ee785a..ec1c4da 100644
--- a/ga-api/src/main/java/com/ga/api/service/commission/HqSettleService.java
+++ b/ga-api/src/main/java/com/ga/api/service/commission/HqSettleService.java
@@ -15,6 +15,12 @@ import org.springframework.transaction.annotation.Transactional;
import java.math.BigDecimal;
+/**
+ * 본사정산 서비스.
+ *
+ * 본사 손익 항목(item)을 정산월·유형(INCOME 수입/EXPENSE 비용)별로 관리하고 손익을 집계한다.
+ * 본사손익(profit) = 수입 합계(income) - 비용 합계(expense). 항목 등록 시 상태는 REGISTERED.
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -22,6 +28,7 @@ public class HqSettleService {
private final HqSettleItemMapper itemMapper;
+ /** 본사손익 요약 응답 DTO: 정산월, 수입 합계, 비용 합계, 손익(수입-비용). */
@Data
public static class HqSummaryResp {
private final String settleMonth;
@@ -42,18 +49,20 @@ public class HqSettleService {
}
/**
- * 본사손익 집계: income − expense.
- * 둘 다 null이면 0으로 처리.
+ * 본사손익 집계 — 해당 정산월의 수입(INCOME)/비용(EXPENSE) 합계를 구해 손익(수입-비용)을 계산한다.
+ * 집계 결과가 없으면(null) 0으로 처리한다.
*/
public HqSummaryResp summary(String settleMonth) {
BigDecimal income = itemMapper.sumByMonthAndType(settleMonth, "INCOME");
BigDecimal expense = itemMapper.sumByMonthAndType(settleMonth, "EXPENSE");
if (income == null) income = BigDecimal.ZERO;
if (expense == null) expense = BigDecimal.ZERO;
+ // 손익 = 수입 합계 - 비용 합계
BigDecimal profit = income.subtract(expense);
return new HqSummaryResp(settleMonth, income, expense, profit);
}
+ /** 본사정산 항목 신규 등록. 상태 REGISTERED 로 시작. 응답: 생성된 itemId. */
@Transactional
public Long create(HqSettleItemSaveReq req) {
HqSettleItemVO vo = new HqSettleItemVO();
diff --git a/ga-api/src/main/java/com/ga/api/service/commission/IncomeCommissionService.java b/ga-api/src/main/java/com/ga/api/service/commission/IncomeCommissionService.java
index 810d1d0..dcc86c0 100644
--- a/ga-api/src/main/java/com/ga/api/service/commission/IncomeCommissionService.java
+++ b/ga-api/src/main/java/com/ga/api/service/commission/IncomeCommissionService.java
@@ -13,6 +13,12 @@ import org.springframework.transaction.annotation.Transactional;
import java.math.BigDecimal;
import java.math.RoundingMode;
+/**
+ * 수입수수료/수지차 서비스.
+ *
+ * 수입수수료(income) = 보험료 × 보험사요율 (GA가 보험사로부터 받는 돈).
+ * 수지차(margin) = 정산월 수입수수료 합 - 설계사 지급액 합 (GA의 마진). 양수면 흑자, 음수면 적자.
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -34,6 +40,7 @@ public class IncomeCommissionService {
return resp;
}
+ /** 수입수수료 원장 생성. 수입액 = 보험료 × 보험사요율. 상태 CALCULATED 로 저장. */
@Transactional
public Long createLedger(IncomeCommissionLedgerSaveReq req) {
IncomeCommissionLedgerVO vo = new IncomeCommissionLedgerVO();
@@ -74,18 +81,23 @@ public class IncomeCommissionService {
*/
@Transactional
public Long recalcMargin(String settleMonth, Long agentId) {
+ // 수입 합계: 해당 정산월의 수입수수료 총합(없으면 0)
BigDecimal incomeTotal = marginMapper.sumIncomeByMonth(settleMonth);
if (incomeTotal == null) incomeTotal = BigDecimal.ZERO;
+ // 지급 합계: 해당 정산월의 설계사 지급액 총합(agentId 지정 시 그 설계사만, 없으면 0)
BigDecimal payoutTotal = marginMapper.sumPayoutByMonth(settleMonth, agentId);
if (payoutTotal == null) payoutTotal = BigDecimal.ZERO;
+ // 수지차 = 수입 합계 - 지급 합계
BigDecimal marginAmount = incomeTotal.subtract(payoutTotal).setScale(2, RoundingMode.HALF_UP);
+ // 수지차율 = 수지차 / 수입 합계 (0으로 나누기 방지: 수입이 0보다 클 때만 계산, 아니면 0)
BigDecimal marginRate = BigDecimal.ZERO;
if (incomeTotal.compareTo(BigDecimal.ZERO) > 0) {
marginRate = marginAmount.divide(incomeTotal, 4, RoundingMode.HALF_UP);
}
+ // 같은 (정산월, 설계사) 집계가 이미 있으면 갱신(update), 없으면 신규 생성(insert) — upsert 패턴
MarginSummaryVO existing = marginMapper.selectByMonthAndAgent(settleMonth, agentId);
if (existing != null) {
existing.setIncomeTotal(incomeTotal);
diff --git a/ga-api/src/main/java/com/ga/api/service/commission/JointContractService.java b/ga-api/src/main/java/com/ga/api/service/commission/JointContractService.java
index 17db645..e7281f7 100644
--- a/ga-api/src/main/java/com/ga/api/service/commission/JointContractService.java
+++ b/ga-api/src/main/java/com/ga/api/service/commission/JointContractService.java
@@ -14,6 +14,12 @@ import org.springframework.transaction.annotation.Transactional;
import java.math.BigDecimal;
+/**
+ * 공동계약 서비스.
+ *
+ * 한 계약을 여러 설계사가 함께 모집했을 때 지분(share_rate)을 나눠 갖는 구조.
+ * 핵심 규칙: 한 계약에 속한 모든 설계사의 지분율 합이 1.0(=100%)을 넘으면 안 된다(초과 시 예외).
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -80,9 +86,11 @@ public class JointContractService {
* sumShareByContract는 계약 전체 합을 반환하므로, 수정 시 기존 자신의 share_rate를 차감.
*/
private void validateShareRate(Long contractId, Long excludeJointId, BigDecimal newShareRate) {
+ // 이 계약에 이미 등록된 지분율 합계(없으면 0)
BigDecimal existingSum = jointContractMapper.sumShareByContract(contractId);
if (existingSum == null) existingSum = BigDecimal.ZERO;
+ // 수정(update)일 때는 자기 자신의 기존 지분을 합계에서 빼야 중복 합산되지 않는다
if (excludeJointId != null) {
JointContractResp existing = jointContractMapper.selectById(excludeJointId);
if (existing != null) {
@@ -90,6 +98,7 @@ public class JointContractService {
}
}
+ // (기존 합 + 새 지분)이 1.0(100%)을 넘으면 지분 초과로 거절
if (existingSum.add(newShareRate).compareTo(BigDecimal.ONE) > 0) {
throw new BizException(ErrorCode.INVALID_PARAMETER, "계약별 지분율 합이 1을 초과합니다.");
}
diff --git a/ga-api/src/main/java/com/ga/api/service/commission/LapsedReinstatementService.java b/ga-api/src/main/java/com/ga/api/service/commission/LapsedReinstatementService.java
index 6efe8df..6cba61a 100644
--- a/ga-api/src/main/java/com/ga/api/service/commission/LapsedReinstatementService.java
+++ b/ga-api/src/main/java/com/ga/api/service/commission/LapsedReinstatementService.java
@@ -9,6 +9,12 @@ import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
+/**
+ * 익월부활재지급 서비스.
+ *
+ * 실효 시 환수했던 수수료(withheldAmount = 보류해 둔 금액)를 익월 부활 시 다시 지급(재지급/회수)한다.
+ * 상태 흐름: PENDING(부활 등록, 재지급 대기) → REPAID(재지급 완료) 또는 CANCELLED(취소).
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -28,7 +34,8 @@ public class LapsedReinstatementService {
}
/**
- * 부활 등록 — withheld_amount 입력, status = PENDING.
+ * 부활 재지급 건 등록 — 실효 시 보류했던 금액(withheld_amount)을 기록하고,
+ * 아직 재지급 전이므로 재지급액(repaid)=0, 상태=PENDING 으로 시작한다.
*/
@Transactional
public Long create(LapsedReinstatementRecoverySaveReq req) {
@@ -45,7 +52,8 @@ public class LapsedReinstatementService {
}
/**
- * 재지급 처리 — status = REPAID, repaid_amount = withheld_amount.
+ * 재지급 처리 — 부활이 확정되어 보류했던 금액 전액을 다시 지급한다.
+ * 상태를 REPAID 로 바꾸고 재지급액(repaid)을 보류금액(withheld)과 같게 만든다. PENDING 상태에서만 가능.
*/
@Transactional
public void repay(Long recoveryId) {
@@ -56,7 +64,8 @@ public class LapsedReinstatementService {
}
/**
- * 취소 — status = CANCELLED.
+ * 취소 — 재지급을 하지 않고 종료한다(상태 CANCELLED, 재지급액 0).
+ * 이미 재지급(REPAID)됐거나 이미 취소(CANCELLED)된 건은 취소할 수 없다.
*/
@Transactional
public void cancel(Long recoveryId) {
diff --git a/ga-api/src/main/java/com/ga/api/service/commission/LifeSupportService.java b/ga-api/src/main/java/com/ga/api/service/commission/LifeSupportService.java
index 298ce80..f560b09 100644
--- a/ga-api/src/main/java/com/ga/api/service/commission/LifeSupportService.java
+++ b/ga-api/src/main/java/com/ga/api/service/commission/LifeSupportService.java
@@ -13,6 +13,12 @@ import org.springframework.transaction.annotation.Transactional;
import java.math.BigDecimal;
import java.math.RoundingMode;
+/**
+ * 생보운영지원수수료 서비스.
+ *
+ * 지원수수료 = 기준액(base) × 지원율(support_rate). 규칙(Rule)은 설계사 등급별 지원율을 정의한다.
+ * 실지급액(net) = 지원수수료 - 환수액. 환수액은 0 이상이며 지원수수료를 넘을 수 없다(실지급 음수 방지).
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -21,7 +27,7 @@ public class LifeSupportService {
private final LifeSupportRuleMapper ruleMapper;
private final LifeSupportLedgerMapper ledgerMapper;
- // ── Rule ──────────────────────────────────────────────────────────────────
+ // ── Rule (지원수수료 규칙) ──────────────────────────────────────────────
public PageResponse listRules(LifeSupportRuleSearchParam param) {
param.startPage();
@@ -65,7 +71,7 @@ public class LifeSupportService {
ruleMapper.delete(ruleId);
}
- // ── Ledger ────────────────────────────────────────────────────────────────
+ // ── Ledger (지원수수료 원장) ────────────────────────────────────────────
public PageResponse listLedgers(LifeSupportLedgerSearchParam param) {
param.startPage();
@@ -78,6 +84,7 @@ public class LifeSupportService {
return resp;
}
+ /** 지원수수료 원장 생성. 지원수수료=base×rate, 실지급액=지원수수료-환수액. 상태 CALCULATED 로 저장. */
@Transactional
public Long createLedger(LifeSupportLedgerSaveReq req) {
// 지원수수료 = base × support_rate
diff --git a/ga-api/src/main/java/com/ga/api/service/commission/OverrideLedgerService.java b/ga-api/src/main/java/com/ga/api/service/commission/OverrideLedgerService.java
index f651b18..916552b 100644
--- a/ga-api/src/main/java/com/ga/api/service/commission/OverrideLedgerService.java
+++ b/ga-api/src/main/java/com/ga/api/service/commission/OverrideLedgerService.java
@@ -12,6 +12,13 @@ import org.springframework.transaction.annotation.Transactional;
import java.util.List;
+/**
+ * 오버라이드 원장 서비스.
+ *
+ * 오버라이드: 상위 직급자가 하위 설계사 실적에 대해 일정 비율로 추가로 받는 수수료.
+ * 이 서비스는 조회·집계 전용이다(생성/계산은 배치 등 다른 로직에서 처리).
+ * summaryByAgentAndMonth 는 특정 수령자(toAgentId)의 정산월 집계를 반환한다.
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
diff --git a/ga-api/src/main/java/com/ga/api/service/commission/PersistencyBonusService.java b/ga-api/src/main/java/com/ga/api/service/commission/PersistencyBonusService.java
index cf63c57..a2dd489 100644
--- a/ga-api/src/main/java/com/ga/api/service/commission/PersistencyBonusService.java
+++ b/ga-api/src/main/java/com/ga/api/service/commission/PersistencyBonusService.java
@@ -13,6 +13,13 @@ import org.springframework.transaction.annotation.Transactional;
import java.math.BigDecimal;
import java.math.RoundingMode;
+/**
+ * 유지보너스(유지보수수당) 서비스.
+ *
+ * 계약이 일정 회차(retentionMonth)까지 잘 유지되고 유지율(retentionRate)이 기준(threshold) 이상일 때 지급하는 보너스.
+ * 규칙(Rule)이 FIXED형이면 지급액은 규칙의 정액(bonus_value)으로 결정된다.
+ * bonus 저장은 (설계사, 기준월, 유지회차) 유니크 키 기준 upsert(있으면 갱신, 없으면 생성).
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -21,7 +28,7 @@ public class PersistencyBonusService {
private final PersistencyBonusRuleMapper ruleMapper;
private final PersistencyBonusMapper bonusMapper;
- // ── Rule ──────────────────────────────────────────────────────────────────
+ // ── Rule (유지보너스 규칙) ──────────────────────────────────────────────
public PageResponse listRules(PersistencyBonusRuleSearchParam param) {
param.startPage();
@@ -71,7 +78,7 @@ public class PersistencyBonusService {
ruleMapper.delete(ruleId);
}
- // ── Bonus ─────────────────────────────────────────────────────────────────
+ // ── Bonus (유지보너스 산출 내역) ────────────────────────────────────────
public PageResponse listBonuses(PersistencyBonusSearchParam param) {
param.startPage();
diff --git a/ga-api/src/main/java/com/ga/api/service/commission/RecognizedPerformanceService.java b/ga-api/src/main/java/com/ga/api/service/commission/RecognizedPerformanceService.java
index 48a3881..a4335d7 100644
--- a/ga-api/src/main/java/com/ga/api/service/commission/RecognizedPerformanceService.java
+++ b/ga-api/src/main/java/com/ga/api/service/commission/RecognizedPerformanceService.java
@@ -13,6 +13,13 @@ import org.springframework.transaction.annotation.Transactional;
import java.math.BigDecimal;
import java.math.RoundingMode;
+/**
+ * 인정실적 서비스.
+ *
+ * 인정실적 = 환산보험료 × 인정률. 환산보험료 = 보험료 × 상품환산율(conversion_rate).
+ * 즉 보험료에 상품별 환산율을 곱해 "환산보험료"를 만들고, 거기에 인정률을 곱해 "회사가 인정하는 실적"을 산출한다.
+ * 규칙(Rate)은 상품별 환산율을 정의한다.
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -21,7 +28,7 @@ public class RecognizedPerformanceService {
private final ProductConversionRateMapper conversionRateMapper;
private final RecognizedPerformanceLedgerMapper ledgerMapper;
- // ── Product Conversion Rate (rule) ────────────────────────────────────────
+ // ── Product Conversion Rate (상품 환산율 규칙) ──────────────────────────
public PageResponse listRates(ProductConversionRateSearchParam param) {
param.startPage();
@@ -65,7 +72,7 @@ public class RecognizedPerformanceService {
conversionRateMapper.delete(rateId);
}
- // ── Ledger ────────────────────────────────────────────────────────────────
+ // ── Ledger (인정실적 원장) ──────────────────────────────────────────────
public PageResponse listLedgers(RecognizedPerformanceLedgerSearchParam param) {
param.startPage();
@@ -78,6 +85,7 @@ public class RecognizedPerformanceService {
return resp;
}
+ /** 인정실적 원장 생성. 환산보험료=보험료×환산율, 인정실적=환산보험료×인정률. 상태 CALCULATED 로 저장. */
@Transactional
public Long createLedger(RecognizedPerformanceLedgerSaveReq req) {
// 환산보험료 = premium × conversion_rate
diff --git a/ga-api/src/main/java/com/ga/api/service/commission/RecruiterCommissionService.java b/ga-api/src/main/java/com/ga/api/service/commission/RecruiterCommissionService.java
index 5d8020c..0d8950f 100644
--- a/ga-api/src/main/java/com/ga/api/service/commission/RecruiterCommissionService.java
+++ b/ga-api/src/main/java/com/ga/api/service/commission/RecruiterCommissionService.java
@@ -14,6 +14,13 @@ import java.math.BigDecimal;
import java.math.RoundingMode;
import java.util.List;
+/**
+ * 도입수수료 서비스.
+ *
+ * 도입수수료: 새 설계사를 데려온(도입한) 사람에게 지급하는 수수료.
+ * 규칙(Rule)의 계산방식에 따라: RATE = 기준액(base) × 수수료율, FIXED = 정액(fixed_amount).
+ * 유효한 규칙이 없으면 요청에 들어온 수동 입력 금액(commissionAmount)을 그대로 사용한다.
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -22,7 +29,7 @@ public class RecruiterCommissionService {
private final RecruiterCommissionRuleMapper ruleMapper;
private final RecruiterCommissionLedgerMapper ledgerMapper;
- // ── Rule ──────────────────────────────────────────────────────────────────
+ // ── Rule (도입수수료 규칙) ──────────────────────────────────────────────
public PageResponse listRules(RecruiterCommissionRuleSearchParam param) {
param.startPage();
@@ -70,7 +77,7 @@ public class RecruiterCommissionService {
ruleMapper.delete(ruleId);
}
- // ── Ledger ────────────────────────────────────────────────────────────────
+ // ── Ledger (도입수수료 원장) ────────────────────────────────────────────
public PageResponse listLedgers(RecruiterCommissionLedgerSearchParam param) {
param.startPage();
diff --git a/ga-api/src/main/java/com/ga/api/service/commission/ReferralCommissionService.java b/ga-api/src/main/java/com/ga/api/service/commission/ReferralCommissionService.java
index 8c84747..e57aab7 100644
--- a/ga-api/src/main/java/com/ga/api/service/commission/ReferralCommissionService.java
+++ b/ga-api/src/main/java/com/ga/api/service/commission/ReferralCommissionService.java
@@ -13,6 +13,13 @@ import org.springframework.transaction.annotation.Transactional;
import java.math.BigDecimal;
import java.math.RoundingMode;
+/**
+ * 소개·이관수수료 서비스.
+ *
+ * 소개수수료: 고객/계약을 소개해 준 사람에게 주는 수수료. 규칙(Rule)의 계산방식에 따라
+ * RATE = 기준액(base) × 수수료율, FIXED = 정액(fixed_amount)으로 산출한다.
+ * 유효 규칙이 없으면 요청에 들어온 수수료율(commissionRate)로 수동 계산한다(둘 다 없으면 예외).
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -21,7 +28,7 @@ public class ReferralCommissionService {
private final ReferralCommissionRuleMapper ruleMapper;
private final ReferralCommissionLedgerMapper ledgerMapper;
- // ── Rule ──────────────────────────────────────────────────────────────────
+ // ── Rule (소개수수료 규칙) ──────────────────────────────────────────────
public PageResponse listRules(ReferralCommissionRuleSearchParam param) {
param.startPage();
@@ -69,7 +76,7 @@ public class ReferralCommissionService {
ruleMapper.delete(ruleId);
}
- // ── Ledger ────────────────────────────────────────────────────────────────
+ // ── Ledger (소개수수료 원장) ────────────────────────────────────────────
public PageResponse listLedgers(ReferralCommissionLedgerSearchParam param) {
param.startPage();
diff --git a/ga-api/src/main/java/com/ga/api/service/commission/ReinstatementCommissionService.java b/ga-api/src/main/java/com/ga/api/service/commission/ReinstatementCommissionService.java
index 9614f1b..1b45bae 100644
--- a/ga-api/src/main/java/com/ga/api/service/commission/ReinstatementCommissionService.java
+++ b/ga-api/src/main/java/com/ga/api/service/commission/ReinstatementCommissionService.java
@@ -12,6 +12,13 @@ import org.springframework.transaction.annotation.Transactional;
import java.math.BigDecimal;
+/**
+ * 부활수수료 서비스.
+ *
+ * 부활(실효 계약이 다시 살아남) 시 지급하는 수수료. 규칙(Rule)에 상품·지급방식(payType)별 요율/정액을 정의한다.
+ * 실수령 수수료(netCommission) = 수수료액(commissionAmount) + 환수복원액(chargebackReversal).
+ * 환수복원: 실효 때 환수했던 금액을 부활로 되돌려 주는 부분.
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -20,7 +27,7 @@ public class ReinstatementCommissionService {
private final ReinstatementCommissionRuleMapper ruleMapper;
private final ReinstatementCommissionLedgerMapper ledgerMapper;
- // ── Rule ──────────────────────────────────────────────────────────────────
+ // ── Rule (부활수수료 규칙) ──────────────────────────────────────────────
public PageResponse listRules(ReinstatementCommissionRuleSearchParam param) {
param.startPage();
@@ -70,7 +77,7 @@ public class ReinstatementCommissionService {
ruleMapper.delete(ruleId);
}
- // ── Ledger ────────────────────────────────────────────────────────────────
+ // ── Ledger (부활수수료 원장) ────────────────────────────────────────────
public PageResponse listLedgers(ReinstatementCommissionLedgerSearchParam param) {
param.startPage();
diff --git a/ga-api/src/main/java/com/ga/api/service/commission/RenewalCommissionService.java b/ga-api/src/main/java/com/ga/api/service/commission/RenewalCommissionService.java
index 38720c6..4673323 100644
--- a/ga-api/src/main/java/com/ga/api/service/commission/RenewalCommissionService.java
+++ b/ga-api/src/main/java/com/ga/api/service/commission/RenewalCommissionService.java
@@ -10,6 +10,12 @@ import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
+/**
+ * 갱신수수료 서비스.
+ *
+ * 계약 갱신 시 지급하는 수수료. 규칙(Rule)에 상품·지급방식(payType)별 요율/정액을 정의한다.
+ * 원장 생성은 요청에 들어온 수수료액(commissionAmount)을 그대로 기록한다(상태 CALCULATED).
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -18,7 +24,7 @@ public class RenewalCommissionService {
private final RenewalCommissionRuleMapper ruleMapper;
private final RenewalCommissionLedgerMapper ledgerMapper;
- // ── Rule ──────────────────────────────────────────────────────────────────
+ // ── Rule (갱신수수료 규칙) ──────────────────────────────────────────────
public PageResponse listRules(RenewalCommissionRuleSearchParam param) {
param.startPage();
@@ -66,7 +72,7 @@ public class RenewalCommissionService {
ruleMapper.delete(ruleId);
}
- // ── Ledger ────────────────────────────────────────────────────────────────
+ // ── Ledger (갱신수수료 원장) ────────────────────────────────────────────
public PageResponse listLedgers(RenewalCommissionLedgerSearchParam param) {
param.startPage();
diff --git a/ga-api/src/main/java/com/ga/api/service/commission/ReserveFundService.java b/ga-api/src/main/java/com/ga/api/service/commission/ReserveFundService.java
index 37b08da..f99539c 100644
--- a/ga-api/src/main/java/com/ga/api/service/commission/ReserveFundService.java
+++ b/ga-api/src/main/java/com/ga/api/service/commission/ReserveFundService.java
@@ -15,6 +15,13 @@ import org.springframework.transaction.annotation.Transactional;
import java.math.BigDecimal;
import java.math.RoundingMode;
+/**
+ * 적립금 서비스.
+ *
+ * 적립금: 환수 등에 대비해 수수료 일부를 떼어 모아 두는 돈. 월별로 잔액(balance)을 이월·누적 관리한다.
+ * 잔액 = 직전월 잔액 + 이번달 적립(reserveIn) - 이번달 사용(reserveOut).
+ * 같은 (설계사, 정산월) 레코드가 있으면 갱신, 없으면 신규 생성(upsert).
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -40,16 +47,19 @@ public class ReserveFundService {
*/
@Transactional
public Long create(AgentReserveFundSaveReq req) {
+ // 직전월 잔액을 가져와 이월(없으면 0부터 시작)
AgentReserveFundVO prevMonth = reserveFundMapper.selectLatestBefore(req.getAgentId(), req.getSettleMonth());
BigDecimal prevBalance = (prevMonth != null && prevMonth.getBalance() != null)
? prevMonth.getBalance()
: BigDecimal.ZERO;
+ // 이번달 잔액 = 직전월 잔액 + 적립 - 사용
BigDecimal balance = prevBalance
.add(req.getReserveIn())
.subtract(req.getReserveOut())
.setScale(2, RoundingMode.HALF_UP);
+ // 같은 (설계사, 정산월) 레코드가 있으면 갱신, 없으면 아래에서 신규 생성
AgentReserveFundVO existing = reserveFundMapper.selectByAgentAndMonth(req.getAgentId(), req.getSettleMonth());
if (existing != null) {
existing.setReserveIn(req.getReserveIn());
diff --git a/ga-api/src/main/java/com/ga/api/service/commission/SettlingSupportService.java b/ga-api/src/main/java/com/ga/api/service/commission/SettlingSupportService.java
index 7118dcf..7784822 100644
--- a/ga-api/src/main/java/com/ga/api/service/commission/SettlingSupportService.java
+++ b/ga-api/src/main/java/com/ga/api/service/commission/SettlingSupportService.java
@@ -13,6 +13,13 @@ import org.springframework.transaction.annotation.Transactional;
import java.math.BigDecimal;
import java.math.RoundingMode;
+/**
+ * 정착지원금 서비스.
+ *
+ * 신입 설계사 안착을 위해 일정 기간 지급하는 지원금. 규칙(Rule)은 등급별 지원금액/지급기간(durationMonths)/
+ * 환수대상기간(clawbackMonths)을 정의한다.
+ * 실지급액(net) = 지원금(supportAmount) - 환수액. 환수액은 0 이상이며 지원금을 넘을 수 없다(실지급 음수 방지).
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -21,7 +28,7 @@ public class SettlingSupportService {
private final SettlingSupportRuleMapper ruleMapper;
private final SettlingSupportLedgerMapper ledgerMapper;
- // ── Rule ──────────────────────────────────────────────────────────────────
+ // ── Rule (정착지원금 규칙) ──────────────────────────────────────────────
public PageResponse listRules(SettlingSupportRuleSearchParam param) {
param.startPage();
@@ -69,7 +76,7 @@ public class SettlingSupportService {
ruleMapper.delete(ruleId);
}
- // ── Ledger ────────────────────────────────────────────────────────────────
+ // ── Ledger (정착지원금 원장) ────────────────────────────────────────────
public PageResponse listLedgers(SettlingSupportLedgerSearchParam param) {
param.startPage();
diff --git a/ga-api/src/main/java/com/ga/api/service/commission/StatuteService.java b/ga-api/src/main/java/com/ga/api/service/commission/StatuteService.java
index a3cc083..60a0f3e 100644
--- a/ga-api/src/main/java/com/ga/api/service/commission/StatuteService.java
+++ b/ga-api/src/main/java/com/ga/api/service/commission/StatuteService.java
@@ -14,6 +14,12 @@ import org.springframework.transaction.annotation.Transactional;
import java.util.List;
+/**
+ * 환수시효관리 서비스.
+ *
+ * 시효(statute): 환수채권을 회수할 수 있는 법적 기한. 설정(config)에 대상유형별 만료개월(expirationMonths)을 둔다.
+ * expireOverdue: 기준월에서 만료개월을 뺀 시점(beforeMonth)보다 오래된 채권을 일괄 대손(EXPIRED) 처리한다.
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -56,15 +62,18 @@ public class StatuteService {
/**
* 만료 대상 채권 일괄 대손 처리.
- * beforeMonth = baseMonth - expiration_months (YYYYMM 연산).
- * 처리 건수 반환.
+ * 환수채권용 시효설정이 활성(Y)일 때만 동작한다(없거나 비활성이면 NOT_FOUND).
+ * 기준월(baseMonth)에서 만료개월수를 뺀 시점(beforeMonth) 이전에 발생한 채권을 EXPIRED 로 일괄 대손 처리하고
+ * 처리 건수를 반환한다.
*/
@Transactional
public int expireOverdue(String baseMonth) {
+ // 환수채권(CLAWBACK_RECEIVABLE) 시효 설정 조회 — 비활성이면 처리하지 않음
StatuteConfigResp config = configMapper.selectByEntityType("CLAWBACK_RECEIVABLE");
if (config == null || !"Y".equals(config.getIsActive())) {
throw new BizException(ErrorCode.NOT_FOUND);
}
+ // 만료 기준 시점 = 기준월 - 만료개월수 (이보다 오래된 채권이 시효 만료 대상)
String beforeMonth = DateUtil.addMonth(baseMonth, -config.getExpirationMonths());
return receivableMapper.writeOffExpired(beforeMonth, "EXPIRED");
}
diff --git a/ga-api/src/main/java/com/ga/api/service/commission/StepCloseService.java b/ga-api/src/main/java/com/ga/api/service/commission/StepCloseService.java
index eca9af4..929fa0d 100644
--- a/ga-api/src/main/java/com/ga/api/service/commission/StepCloseService.java
+++ b/ga-api/src/main/java/com/ga/api/service/commission/StepCloseService.java
@@ -15,6 +15,13 @@ import org.springframework.transaction.annotation.Transactional;
import java.util.List;
+/**
+ * 단계마감 서비스.
+ *
+ * 월 정산을 단계(step)별로 나눠 마감(잠금)/해제(다시 열기)한다.
+ * 상태 흐름: OPEN(열림, 수정 가능) → close() → CLOSED(마감, 잠금) → reopen() → OPEN.
+ * 마감/해제 시 처리자(현재 로그인 사용자)를 기록한다.
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -37,6 +44,7 @@ public class StepCloseService {
return resp;
}
+ /** 단계마감 항목 생성. 처음에는 열린 상태(OPEN)로 시작한다. */
@Transactional
public Long create(StepCloseSaveReq req) {
StepCloseVO vo = new StepCloseVO();
@@ -48,6 +56,7 @@ public class StepCloseService {
return vo.getStepCloseId();
}
+ /** 단계 마감(잠금). 이미 마감(CLOSED)된 단계는 다시 마감할 수 없다. 처리자 기록. */
@Transactional
public void close(Long stepCloseId) {
StepCloseResp resp = stepCloseMapper.selectById(stepCloseId);
@@ -58,6 +67,7 @@ public class StepCloseService {
stepCloseMapper.updateStatus(stepCloseId, "CLOSED", SecurityUtil.getCurrentUserId());
}
+ /** 단계 마감 해제(다시 열기). 이미 열린(OPEN) 단계는 다시 열 수 없다. 처리자 기록. */
@Transactional
public void reopen(Long stepCloseId) {
StepCloseResp resp = stepCloseMapper.selectById(stepCloseId);
diff --git a/ga-api/src/main/java/com/ga/api/service/complaint/ComplaintService.java b/ga-api/src/main/java/com/ga/api/service/complaint/ComplaintService.java
index 92fd1e3..78b680d 100644
--- a/ga-api/src/main/java/com/ga/api/service/complaint/ComplaintService.java
+++ b/ga-api/src/main/java/com/ga/api/service/complaint/ComplaintService.java
@@ -9,6 +9,13 @@ import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
+/**
+ * 민원 도메인 비즈니스 로직.
+ *
+ * 상태 전이: 접수 시 OPEN → 처리완료 시 CLOSED. 한 번 CLOSED가 되면 다시 close 할 수 없다.
+ * 심각도(severity) 기본값은 MID. 환수 유발 플래그(chargebackTriggered)는 여기서 저장만 하고,
+ * 실제 수수료 환수 원장(chargeback_ledger) 생성은 정산 배치(P5)가 담당한다.
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -16,17 +23,20 @@ public class ComplaintService {
private final ComplaintMapper mapper;
+ /** 민원 목록 조회(페이징). */
public PageResponse list(ComplaintSearchParam param) {
param.startPage();
return PageResponse.of(mapper.selectList(param));
}
+ /** 민원 상세 조회. 없으면 NOT_FOUND. */
public ComplaintResp detail(Long complaintId) {
ComplaintResp resp = mapper.selectById(complaintId);
if (resp == null) throw new BizException(ErrorCode.NOT_FOUND);
return resp;
}
+ /** 민원 접수. 심각도 미지정 시 MID, 상태는 OPEN으로 시작한다. */
@Transactional
public Long create(ComplaintSaveReq req) {
ComplaintVO vo = new ComplaintVO();
@@ -45,6 +55,7 @@ public class ComplaintService {
return vo.getComplaintId();
}
+ /** 민원 내용 수정. 존재 검증 후 일반 정보를 갱신하며 상태는 건드리지 않는다. */
@Transactional
public void update(Long complaintId, ComplaintSaveReq req) {
ComplaintResp existing = mapper.selectById(complaintId);
@@ -77,6 +88,7 @@ public class ComplaintService {
mapper.updateStatus(complaintId, ComplaintStatus.CLOSED.name(), resolution);
}
+ /** 민원 레코드 삭제. 존재 검증 후 삭제한다. */
@Transactional
public void delete(Long complaintId) {
ComplaintResp existing = mapper.selectById(complaintId);
diff --git a/ga-api/src/main/java/com/ga/api/service/contract/AgentContractService.java b/ga-api/src/main/java/com/ga/api/service/contract/AgentContractService.java
index 6c38e05..20afe74 100644
--- a/ga-api/src/main/java/com/ga/api/service/contract/AgentContractService.java
+++ b/ga-api/src/main/java/com/ga/api/service/contract/AgentContractService.java
@@ -11,6 +11,12 @@ import org.springframework.transaction.annotation.Transactional;
import java.time.LocalDateTime;
+/**
+ * 위촉계약(설계사-보험사 모집 위탁) 도메인 비즈니스 로직.
+ *
+ * 상태 전이: 등록 시 ACTIVE → 해촉 시 TERMINATED. 한 번 TERMINATED가 된 계약은 다시 해촉할 수 없다.
+ * 클래스 전체는 읽기 전용이며 쓰기 메서드만 별도 트랜잭션을 건다.
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -18,17 +24,20 @@ public class AgentContractService {
private final AgentContractMapper mapper;
+ /** 위촉계약 목록 조회(페이징). */
public PageResponse list(AgentContractSearchParam param) {
param.startPage();
return PageResponse.of(mapper.selectList(param));
}
+ /** 위촉계약 상세 조회. 없으면 NOT_FOUND. */
public AgentContractResp detail(Long contractId) {
AgentContractResp resp = mapper.selectById(contractId);
if (resp == null) throw new BizException(ErrorCode.NOT_FOUND);
return resp;
}
+ /** 위촉계약 신규 등록. 상태를 ACTIVE로 고정해 저장한다. */
@Transactional
public Long create(AgentContractSaveReq req) {
AgentContractVO vo = new AgentContractVO();
@@ -44,6 +53,7 @@ public class AgentContractService {
return vo.getContractId();
}
+ /** 위촉계약 수정. 존재 검증 후 일반 정보만 갱신하며 상태(status)는 건드리지 않는다. */
@Transactional
public void update(Long contractId, AgentContractSaveReq req) {
AgentContractResp existing = mapper.selectById(contractId);
@@ -60,6 +70,7 @@ public class AgentContractService {
mapper.update(vo);
}
+ /** 위촉계약 해촉. 이미 TERMINATED면 상태 오류로 막고, 그렇지 않으면 사유와 함께 TERMINATED로 전이한다. */
@Transactional
public void terminate(Long contractId, String reason) {
AgentContractResp existing = mapper.selectById(contractId);
@@ -70,6 +81,7 @@ public class AgentContractService {
mapper.updateStatus(contractId, AgentContractStatus.TERMINATED.name(), reason);
}
+ /** 위촉계약 레코드 삭제. 존재 검증 후 삭제한다. */
@Transactional
public void delete(Long contractId) {
AgentContractResp existing = mapper.selectById(contractId);
diff --git a/ga-api/src/main/java/com/ga/api/service/deduction/DeductionService.java b/ga-api/src/main/java/com/ga/api/service/deduction/DeductionService.java
index b4f60cb..da2d5ee 100644
--- a/ga-api/src/main/java/com/ga/api/service/deduction/DeductionService.java
+++ b/ga-api/src/main/java/com/ga/api/service/deduction/DeductionService.java
@@ -17,6 +17,16 @@ import java.math.BigDecimal;
import java.util.List;
import java.util.stream.Collectors;
+/**
+ * 공제/차감(agent_deduction) 서비스.
+ *
+ * 설계사 수수료에서 미리 빼야 할 금액(차감)을 등록/수정/취소하고, 지급 처리에 필요한 PENDING 차감 조회와
+ * "적용됨(APPLIED)" 상태 전환을 제공합니다. PaymentService 가 지급 시 이 PENDING 차감을 가져가 실지급액에서 빼고
+ * markAsApplied 로 상태를 마무리합니다.
+ *
+ *
상태(DeductionStatus): PENDING → APPLIED, 또는 CANCELLED.
+ * 같은 설계사+정산월+차감유형 조합은 중복 등록 불가. 수정·취소는 PENDING(미적용) 상태에서만 가능합니다.
+ */
@Service
@RequiredArgsConstructor
public class DeductionService {
@@ -75,22 +85,26 @@ public class DeductionService {
mapper.updateStatus(deductionId, DeductionStatus.CANCELLED.name());
}
+ /** 특정 설계사·정산월의 PENDING 차감 합계(없으면 0). 지급 예상액 미리보기 등에 사용. */
@Transactional(readOnly = true)
public BigDecimal sumPendingByAgent(Long agentId, String settleMonth) {
BigDecimal sum = mapper.sumPendingByAgent(agentId, settleMonth);
return sum != null ? sum : BigDecimal.ZERO;
}
+ /** 정산월 전체의 PENDING 차감 목록. */
@Transactional(readOnly = true)
public List selectPendingByMonth(String settleMonth) {
return mapper.selectPendingByMonth(settleMonth);
}
+ /** 특정 설계사·정산월의 PENDING 차감 목록. 지급 처리(PaymentService.applyDeductions)에서 호출. */
@Transactional(readOnly = true)
public List selectPendingByAgent(Long agentId, String settleMonth) {
return mapper.selectPendingByAgent(agentId, settleMonth);
}
+ /** 차감들을 APPLIED(적용완료) 상태로 일괄 전환. 지급에 반영된 직후 호출됩니다. */
@Transactional
public void markAsApplied(List deductionIds) {
if (deductionIds.isEmpty()) return;
diff --git a/ga-api/src/main/java/com/ga/api/service/dict/DataDictionaryService.java b/ga-api/src/main/java/com/ga/api/service/dict/DataDictionaryService.java
index dc32194..c9e89ff 100644
--- a/ga-api/src/main/java/com/ga/api/service/dict/DataDictionaryService.java
+++ b/ga-api/src/main/java/com/ga/api/service/dict/DataDictionaryService.java
@@ -15,31 +15,42 @@ import org.springframework.transaction.annotation.Transactional;
import java.util.List;
+/**
+ * 데이터 사전 도메인 비즈니스 로직.
+ *
+ * 테이블/컬럼 메타데이터 항목의 CRUD를 담당한다. 항목에 도메인 코드를 지정할 경우
+ * 실존하는 도메인인지(countDomainByCode) 검증해 깨진 참조를 막는다.
+ */
@Service
@RequiredArgsConstructor
public class DataDictionaryService {
private final DataDictionaryMapper mapper;
+ /** 데이터 사전 항목 목록 조회(페이징). */
public PageResponse list(DataDictionarySearchParam param) {
param.startPage();
return PageResponse.of(mapper.selectList(param));
}
+ /** 사전에 등록된 테이블명 목록 조회. */
public List tables() {
return mapper.selectTables();
}
+ /** 사전 뷰 기반 통합 조회(테이블명 선택). 컬럼+도메인 결합 정보를 반환한다. */
public List full(String tableName) {
return mapper.selectFromView(tableName);
}
+ /** 데이터 사전 항목 단건 조회. 없으면 NOT_FOUND. */
public DataDictionaryResp detail(Long dictId) {
DataDictionaryResp resp = mapper.selectById(dictId);
if (resp == null) throw new BizException(ErrorCode.NOT_FOUND);
return resp;
}
+ /** 항목 등록. 도메인 코드가 있으면 실존 여부를 검증한 뒤 저장한다. */
@Transactional
public void create(DataDictionarySaveReq req) {
if (req.getDomainCode() != null && !req.getDomainCode().isBlank()) {
@@ -50,6 +61,7 @@ public class DataDictionaryService {
mapper.insert(req.toVO());
}
+ /** 항목 수정. 존재 검증 + 도메인 코드 실존 검증 후 갱신한다. */
@Transactional
public void update(Long dictId, DataDictionarySaveReq req) {
DataDictionaryResp existing = mapper.selectById(dictId);
@@ -64,6 +76,7 @@ public class DataDictionaryService {
mapper.update(vo);
}
+ /** 항목 삭제. 삭제된 행이 없으면(없는 ID) NOT_FOUND. */
@Transactional
public void delete(Long dictId) {
if (mapper.delete(dictId) == 0) {
diff --git a/ga-api/src/main/java/com/ga/api/service/dict/DataDomainService.java b/ga-api/src/main/java/com/ga/api/service/dict/DataDomainService.java
index 760a93a..87e5798 100644
--- a/ga-api/src/main/java/com/ga/api/service/dict/DataDomainService.java
+++ b/ga-api/src/main/java/com/ga/api/service/dict/DataDomainService.java
@@ -15,27 +15,38 @@ import org.springframework.transaction.annotation.Transactional;
import java.util.List;
+/**
+ * 데이터 도메인 사전 도메인 비즈니스 로직.
+ *
+ * 도메인 코드(domainCode)를 PK로 하는 메타데이터의 CRUD를 담당한다.
+ * 등록 시 코드 중복을 막고, 삭제 시 이 도메인을 참조하는 컬럼이 남아 있으면(countUsageByCode)
+ * 의존 데이터 오류로 막아 참조 무결성을 지킨다.
+ */
@Service
@RequiredArgsConstructor
public class DataDomainService {
private final DataDomainMapper mapper;
+ /** 도메인 목록 조회(페이징). */
public PageResponse list(DataDomainSearchParam param) {
param.startPage();
return PageResponse.of(mapper.selectList(param));
}
+ /** 선택 옵션용 도메인 전체 목록 조회. */
public List options() {
return mapper.selectAll();
}
+ /** 도메인 단건 조회(코드 기준). 없으면 NOT_FOUND. */
public DataDomainResp detail(String domainCode) {
DataDomainResp resp = mapper.selectByCode(domainCode);
if (resp == null) throw new BizException(ErrorCode.NOT_FOUND);
return resp;
}
+ /** 도메인 등록. 동일 코드가 이미 있으면 중복 오류. */
@Transactional
public void create(DataDomainSaveReq req) {
if (mapper.selectByCode(req.getDomainCode()) != null) {
@@ -44,6 +55,7 @@ public class DataDomainService {
mapper.insert(req.toVO());
}
+ /** 도메인 수정. 존재 검증 후 갱신한다(코드는 경로 값으로 고정). */
@Transactional
public void update(String domainCode, DataDomainSaveReq req) {
if (mapper.selectByCode(domainCode) == null) {
@@ -54,6 +66,7 @@ public class DataDomainService {
mapper.update(vo);
}
+ /** 도메인 삭제. 참조 중인 컬럼이 있으면 의존 데이터 오류로 막고, 없으면 삭제한다. */
@Transactional
public void delete(String domainCode) {
int usageCount = mapper.countUsageByCode(domainCode);
diff --git a/ga-api/src/main/java/com/ga/api/service/endorse/ContractEndorsementService.java b/ga-api/src/main/java/com/ga/api/service/endorse/ContractEndorsementService.java
index b1131b3..786726e 100644
--- a/ga-api/src/main/java/com/ga/api/service/endorse/ContractEndorsementService.java
+++ b/ga-api/src/main/java/com/ga/api/service/endorse/ContractEndorsementService.java
@@ -9,6 +9,13 @@ import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
+/**
+ * 계약 변경(배서) 도메인 비즈니스 로직.
+ *
+ * 배서 레코드의 등록/조회/처리완료/삭제만 담당한다. 보험료 변동에 따른 수수료 재계산은
+ * 여기서 수행하지 않고 정산 배치(P5)가 담당하며, 이 서비스의 process()는 처리 완료 플래그만 올린다.
+ * 클래스 전체는 읽기 전용이고 쓰기 메서드만 별도 트랜잭션을 건다.
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -16,17 +23,20 @@ public class ContractEndorsementService {
private final ContractEndorsementMapper mapper;
+ /** 배서 목록 조회(페이징). */
public PageResponse list(ContractEndorsementSearchParam param) {
param.startPage();
return PageResponse.of(mapper.selectList(param));
}
+ /** 배서 상세 조회. 없으면 NOT_FOUND. */
public ContractEndorsementResp detail(Long endorsementId) {
ContractEndorsementResp resp = mapper.selectById(endorsementId);
if (resp == null) throw new BizException(ErrorCode.NOT_FOUND);
return resp;
}
+ /** 배서 등록. 변경 전/후 값과 수수료 재계산 필요 여부를 저장하고 미처리(processed=false) 상태로 시작한다. */
@Transactional
public Long create(ContractEndorsementSaveReq req) {
ContractEndorsementVO vo = new ContractEndorsementVO();
@@ -53,6 +63,7 @@ public class ContractEndorsementService {
mapper.markProcessed(endorsementId);
}
+ /** 배서 레코드 삭제. 존재 검증 후 삭제한다. */
@Transactional
public void delete(Long endorsementId) {
ContractEndorsementResp existing = mapper.selectById(endorsementId);
diff --git a/ga-api/src/main/java/com/ga/api/service/external/ExternalCallLogService.java b/ga-api/src/main/java/com/ga/api/service/external/ExternalCallLogService.java
index 724562d..76cc982 100644
--- a/ga-api/src/main/java/com/ga/api/service/external/ExternalCallLogService.java
+++ b/ga-api/src/main/java/com/ga/api/service/external/ExternalCallLogService.java
@@ -30,12 +30,14 @@ public class ExternalCallLogService {
mapper.insertOne(vo);
}
+ /** 외부 호출 이력 목록 조회(페이징). */
@Transactional(readOnly = true)
public PageResponse list(ExternalCallLogSearchParam param) {
param.startPage();
return PageResponse.of(mapper.selectList(param));
}
+ /** 외부 호출 이력 단건 조회. */
@Transactional(readOnly = true)
public ExternalCallLogResp detail(Long logId) {
return mapper.selectById(logId);
diff --git a/ga-api/src/main/java/com/ga/api/service/income/AgentAnnualIncomeService.java b/ga-api/src/main/java/com/ga/api/service/income/AgentAnnualIncomeService.java
index 2f3580a..27a45bb 100644
--- a/ga-api/src/main/java/com/ga/api/service/income/AgentAnnualIncomeService.java
+++ b/ga-api/src/main/java/com/ga/api/service/income/AgentAnnualIncomeService.java
@@ -10,6 +10,13 @@ import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
+/**
+ * [연간 사업소득 서비스]
+ *
+ * 신입 개발자 안내:
+ * - 조회(list/detail)와 연도 단위 재집계(regenerate=UPSERT)만 제공하는 단순 서비스.
+ * - 실제 합산 SQL 은 매퍼의 upsertAggregate 가 수행한다(월별 지급 → 연간 합계).
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
diff --git a/ga-api/src/main/java/com/ga/api/service/income/YearEndStatementService.java b/ga-api/src/main/java/com/ga/api/service/income/YearEndStatementService.java
index 6b608c7..1aa14e5 100644
--- a/ga-api/src/main/java/com/ga/api/service/income/YearEndStatementService.java
+++ b/ga-api/src/main/java/com/ga/api/service/income/YearEndStatementService.java
@@ -14,6 +14,15 @@ import org.apache.ibatis.cursor.Cursor;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
+/**
+ * [연말 지급명세서 서비스]
+ *
+ * 신입 개발자 안내:
+ * - regenerate: 연도(+선택 설계사들) 기준으로 연간소득 집계를 명세서 테이블에 UPSERT.
+ * - generate: 명세서 1건의 파일(XLSX/PDF)을 만들고 file_path 저장 + 상태 GENERATED 로 전이.
+ * - send: 대상 명세서들을 발송 처리(상태/수신자 기록).
+ * - exportCursor: 엑셀 대량 다운로드용 Cursor 반환(컨트롤러의 ExcelService 와 함께 트랜잭션 내 소비).
+ */
@Slf4j
@Service
@RequiredArgsConstructor
diff --git a/ga-api/src/main/java/com/ga/api/service/installment/InstallmentPlanGenerator.java b/ga-api/src/main/java/com/ga/api/service/installment/InstallmentPlanGenerator.java
index ab0b9d4..7243653 100644
--- a/ga-api/src/main/java/com/ga/api/service/installment/InstallmentPlanGenerator.java
+++ b/ga-api/src/main/java/com/ga/api/service/installment/InstallmentPlanGenerator.java
@@ -26,16 +26,26 @@ public class InstallmentPlanGenerator {
/**
* 계약 체결일 기준 1~7차년 분급 계획 생성.
* ratioPercent 합이 100%가 안 되는 경우 각 연차별 비율만큼 지급.
+ *
+ * [신입용 설명] 분급은 1200%룰 한도 초과분을 여러 해에 나눠 지급하기 위한 예정표다.
+ * ga-batch의 BatchInstallmentPlanGenerator와 동일 로직(온라인/배치 결과 일관성).
+ *
+ * @param contractId 계약 ID
+ * @param totalCommission 분급(이연)할 총액
+ * @param contractDate 계약 체결일(각 회차 도래 정산월 계산 기준)
+ * @param productCategory 상품군(적용 분급 비율 마스터 선택 키)
+ * @return SCHEDULED 상태 분급 계획 목록
*/
public List generate(Long contractId, BigDecimal totalCommission,
LocalDate contractDate, String productCategory) {
String baseDate = contractDate.format(DATE_FMT);
+ // 계약일 시점 유효한 해당 상품군의 활성 분급 비율을 연차순으로 조회.
List ratios = ratioMapper.selectAllActiveRatios(productCategory, baseDate);
// 비율 합이 정확히 100%인 정규 스케줄이면 마지막 회차가 반올림 잔차를 흡수
// → 분급 합계 == 원 수수료 보장 (부분지급 스케줄은 회차별 반올림 유지).
boolean fullSchedule = sumRatios(ratios).compareTo(BigDecimal.valueOf(100)) == 0;
- BigDecimal allocated = BigDecimal.ZERO;
+ BigDecimal allocated = BigDecimal.ZERO; // 배분 누계(마지막 회차 잔차 흡수용)
List plans = new ArrayList<>();
for (int i = 0; i < ratios.size(); i++) {
@@ -45,8 +55,10 @@ public class InstallmentPlanGenerator {
BigDecimal amount;
if (fullSchedule && i == ratios.size() - 1) {
+ // 정규(합 100%) 스케줄의 마지막 회차: 남은 전액 배정 → 반올림 잔차 흡수, 합계=원금 보장.
amount = totalCommission.subtract(allocated);
} else {
+ // 일반 회차: 총액 × 연차비율 ÷ 100, 원 단위 반올림.
amount = totalCommission.multiply(ratio.getRatioPercent())
.divide(BigDecimal.valueOf(100), 0, RoundingMode.HALF_UP);
}
@@ -54,18 +66,20 @@ public class InstallmentPlanGenerator {
InstallmentPlanVO plan = new InstallmentPlanVO();
plan.setContractId(contractId);
- plan.setPlanYear(ratio.getPlanYear());
- plan.setPlanMonth(planMonth);
+ plan.setPlanYear(ratio.getPlanYear()); // 몇 차년 지급분
+ plan.setPlanMonth(planMonth); // 그 해의 몇 월 회차
+ // 도래 정산월 = 계약일 + planYear년 + (planMonth-1)개월("yyyyMM"). 지급 시점 판정 기준.
plan.setSettleMonth(
contractDate.plusYears(ratio.getPlanYear()).plusMonths(planMonth - 1L).format(MONTH_FMT)
);
- plan.setExpectedAmount(amount);
- plan.setStatus(InstallmentStatus.SCHEDULED.code());
+ plan.setExpectedAmount(amount); // 회차 예정 지급액
+ plan.setStatus(InstallmentStatus.SCHEDULED.code()); // 미지급(예정) 상태로 생성
plans.add(plan);
}
return plans;
}
+ /** 분급 비율 합(%). 100%면 정규 스케줄(마지막 회차가 잔차 흡수)로 판정. */
private BigDecimal sumRatios(List ratios) {
return ratios.stream()
.map(InstallmentRatioVO::getRatioPercent)
diff --git a/ga-api/src/main/java/com/ga/api/service/installment/InstallmentService.java b/ga-api/src/main/java/com/ga/api/service/installment/InstallmentService.java
index 07cd9b5..7c2806b 100644
--- a/ga-api/src/main/java/com/ga/api/service/installment/InstallmentService.java
+++ b/ga-api/src/main/java/com/ga/api/service/installment/InstallmentService.java
@@ -22,6 +22,19 @@ import java.time.LocalDate;
import java.time.LocalDateTime;
import java.util.List;
+/**
+ * 분급(이연 차액) 계획 관리 서비스.
+ *
+ * [신입용 설명]
+ * - "분급(installment)"은 1200%룰 한도를 넘어 당월에 다 줄 수 없는 모집수수료 차액을
+ * 여러 해에 나눠 지급하기 위한 "지급 예정표(installment_plan)"다.
+ * - 이 서비스는 분급 계획의 조회/생성과 상태 전이(예정→지급/유예/취소)를 담당한다.
+ *
+ * [분급 상태(InstallmentStatus)]
+ * SCHEDULED(예정) → PAID(지급완료) : 정상 흐름. 도래월에 지급되면 PAID.
+ * SCHEDULED → DEFERRED(유예) : 사정상 그 달 지급을 미룸. 이후 PAID 가능.
+ * SCHEDULED/DEFERRED → CANCELLED(취소): 환수/해지 등으로 더 이상 지급하지 않음. PAID는 취소 불가.
+ */
@Service
@RequiredArgsConstructor
public class InstallmentService {
@@ -45,6 +58,7 @@ public class InstallmentService {
return resp;
}
+ /** 특정 정산월에 지급 예정(SCHEDULED)인 분급 목록 조회. 도래월 지급 처리의 입력으로 쓰인다. */
@Transactional(readOnly = true)
public List selectScheduledForMonth(String settleMonth) {
return planMapper.selectScheduledByMonth(settleMonth);
@@ -60,6 +74,10 @@ public class InstallmentService {
// ---- Plan 생성 ----
+ /**
+ * 이연할 총액(totalCommission)을 연차별로 쪼개 분급 계획을 만들어 저장.
+ * 1200%룰 초과분을 분급으로 돌릴 때 호출된다. 생성된 계획이 없으면 INSERT 생략.
+ */
@Transactional
public void createPlan(Long contractId, BigDecimal totalCommission,
LocalDate contractDate, String productCategory) {
@@ -71,6 +89,10 @@ public class InstallmentService {
// ---- Plan 상태 전이 ----
+ /**
+ * 분급 1건을 지급 완료(PAID)로 전이.
+ * 예정(SCHEDULED) 또는 유예(DEFERRED) 상태만 지급 가능 — 이미 PAID/CANCELLED면 거부(중복지급 방지).
+ */
@Transactional
public void payPlan(Long planId, Long paymentId, BigDecimal paidAmount) {
InstallmentPlanVO plan = requirePlan(planId);
@@ -85,6 +107,7 @@ public class InstallmentService {
planMapper.update(plan);
}
+ /** 분급 1건을 유예(DEFERRED)로 전이. 예정(SCHEDULED) 상태만 유예 가능. */
@Transactional
public void deferPlan(Long planId) {
InstallmentPlanVO plan = requirePlan(planId);
@@ -94,6 +117,7 @@ public class InstallmentService {
planMapper.updateStatus(planId, InstallmentStatus.DEFERRED.code());
}
+ /** 분급 1건을 취소(CANCELLED)로 전이. 이미 지급 완료(PAID)된 건은 취소 불가(돈이 이미 나갔으므로). */
@Transactional
public void cancelPlan(Long planId) {
InstallmentPlanVO plan = requirePlan(planId);
@@ -103,6 +127,11 @@ public class InstallmentService {
planMapper.updateStatus(planId, InstallmentStatus.CANCELLED.code());
}
+ /**
+ * 해당 정산월에 도래한 예정 분급들을 일괄 지급 처리.
+ * 각 건의 예정금액(expectedAmount)을 그대로 지급액으로 확정하고 PAID로 전이한다.
+ * (배치/도래월 지급 흐름에서 사용. 한 건씩 처리하는 payPlan과 달리 결제 ID 없이 예정금액 그대로 지급.)
+ */
@Transactional
public void payScheduledForMonth(String settleMonth) {
List scheduled = planMapper.selectScheduledByMonth(settleMonth);
diff --git a/ga-api/src/main/java/com/ga/api/service/kpi/ForecastKpiMonthlyService.java b/ga-api/src/main/java/com/ga/api/service/kpi/ForecastKpiMonthlyService.java
index ad23282..4f2a2cf 100644
--- a/ga-api/src/main/java/com/ga/api/service/kpi/ForecastKpiMonthlyService.java
+++ b/ga-api/src/main/java/com/ga/api/service/kpi/ForecastKpiMonthlyService.java
@@ -17,12 +17,18 @@ import java.util.List;
import java.util.Map;
import java.util.Set;
+/**
+ * 차월 KPI 예측 비즈니스 로직 서비스.
+ * 과거 실적의 단순이동평균(SMA) 등으로 다음 달 KPI를 예측해 저장한다.
+ * 예측 방식(method)에 따라 사용하는 과거 표본 개월수(sampleSize)가 달라진다.
+ */
@Slf4j
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
public class ForecastKpiMonthlyService {
+ /** 예측 방식별 과거 표본 개월수: SMA3=3개월, SMA6=6개월, NAIVE=직전 1개월. */
private static final Map SAMPLE_SIZE = Map.of(
"SMA3", 3,
"SMA6", 6,
@@ -31,6 +37,7 @@ public class ForecastKpiMonthlyService {
private final ForecastKpiMonthlyMapper mapper;
+ /** 예측값 목록 페이징 조회. */
public PageResponse list(ForecastKpiMonthlySearchParam param) {
param.startPage();
return PageResponse.of(mapper.selectList(param));
@@ -38,6 +45,7 @@ public class ForecastKpiMonthlyService {
/**
* 차월 예측 재산출. forecastMonth 기준 직전 N개월 평균/표준편차 → 4 metric UPSERT.
+ * (입력 검증 → 방식별 표본수 결정 → DB에서 예측 계산 → 결과 일괄 UPSERT 순서)
*/
@Transactional
public int regenerate(ForecastKpiMonthlySaveReq req) {
diff --git a/ga-api/src/main/java/com/ga/api/service/kpi/KpiService.java b/ga-api/src/main/java/com/ga/api/service/kpi/KpiService.java
index 97aa686..1677a47 100644
--- a/ga-api/src/main/java/com/ga/api/service/kpi/KpiService.java
+++ b/ga-api/src/main/java/com/ga/api/service/kpi/KpiService.java
@@ -11,6 +11,11 @@ import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
+/**
+ * KPI 대시보드 비즈니스 로직 서비스(읽기 전용).
+ * 실적 집계 쿼리를 관점별(월별/조직별/유지율/누적)로 호출해 페이징 결과를 돌려준다.
+ * 클래스 레벨 @Transactional(readOnly=true) 로 모든 조회 메서드가 읽기 전용 트랜잭션으로 동작한다.
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -18,21 +23,25 @@ public class KpiService {
private final KpiMapper kpiMapper;
+ /** 월별 실적 요약 집계 조회. */
public PageResponse monthlySummary(KpiSearchParam param) {
param.startPage();
return PageResponse.of(kpiMapper.selectMonthlySummary(param));
}
+ /** 조직별 실적 요약 집계 조회. */
public PageResponse orgSummary(KpiSearchParam param) {
param.startPage();
return PageResponse.of(kpiMapper.selectOrgSummary(param));
}
+ /** 계약 유지율 지표 집계 조회. */
public PageResponse retention(KpiSearchParam param) {
param.startPage();
return PageResponse.of(kpiMapper.selectRetention(param));
}
+ /** 누적 실적 추이 집계 조회. */
public PageResponse cumulative(KpiSearchParam param) {
param.startPage();
return PageResponse.of(kpiMapper.selectCumulative(param));
diff --git a/ga-api/src/main/java/com/ga/api/service/kpi/RetentionAnomalyAlertService.java b/ga-api/src/main/java/com/ga/api/service/kpi/RetentionAnomalyAlertService.java
index a169216..5a41e41 100644
--- a/ga-api/src/main/java/com/ga/api/service/kpi/RetentionAnomalyAlertService.java
+++ b/ga-api/src/main/java/com/ga/api/service/kpi/RetentionAnomalyAlertService.java
@@ -17,21 +17,28 @@ import org.springframework.transaction.annotation.Transactional;
import java.util.List;
import java.util.Set;
+/**
+ * 유지율 이상치 알림 비즈니스 로직 서비스.
+ * 유지율이 평소 대비 비정상적으로 떨어진 케이스를 탐지·저장하고, 담당자의 검토 상태를 관리한다.
+ */
@Slf4j
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
public class RetentionAnomalyAlertService {
+ /** 알림 처리 상태 허용값: NEW(신규)/REVIEWED(검토됨)/RESOLVED(완료). */
private static final Set VALID_STATUS = Set.of("NEW", "REVIEWED", "RESOLVED");
private final RetentionAnomalyAlertMapper mapper;
+ /** 이상치 알림 목록 페이징 조회. */
public PageResponse list(RetentionAnomalyAlertSearchParam param) {
param.startPage();
return PageResponse.of(mapper.selectList(param));
}
+ /** 이상치 알림 상세 조회. 없으면 NOT_FOUND. */
public RetentionAnomalyAlertResp detail(Long alertId) {
RetentionAnomalyAlertResp resp = mapper.selectDetailById(alertId);
if (resp == null) throw new BizException(ErrorCode.NOT_FOUND);
@@ -57,6 +64,7 @@ public class RetentionAnomalyAlertService {
return n;
}
+ /** 선택한 이상치들을 일괄 검토 처리. 상태 미지정 시 REVIEWED, 허용 상태값만 통과. 처리자/메모도 함께 기록. */
@Transactional
public void review(RetentionAnomalyAlertSaveReq req) {
if (req.getIds() == null || req.getIds().isEmpty()) {
diff --git a/ga-api/src/main/java/com/ga/api/service/ledger/LedgerService.java b/ga-api/src/main/java/com/ga/api/service/ledger/LedgerService.java
index 53f8214..f1036e1 100644
--- a/ga-api/src/main/java/com/ga/api/service/ledger/LedgerService.java
+++ b/ga-api/src/main/java/com/ga/api/service/ledger/LedgerService.java
@@ -16,6 +16,10 @@ import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
+/**
+ * 수수료 원장(ledger) 비즈니스 로직 서비스.
+ * 모집·유지·예외 세 종류 원장을 각각의 매퍼로 조회/등록/엑셀추출하고, 예외원장 승인 절차를 처리한다.
+ */
@Service
@RequiredArgsConstructor
public class LedgerService {
@@ -25,24 +29,28 @@ public class LedgerService {
private final ExceptionLedgerMapper exceptionMapper;
private final ExceptionLedgerMapStruct exceptionLedgerMapStruct;
+ /** 모집수수료 원장 목록 페이징 조회. */
@Transactional(readOnly = true)
public PageResponse listRecruit(LedgerSearchParam param) {
param.startPage();
return PageResponse.of(recruitMapper.selectList(param));
}
+ /** 유지수수료 원장 목록 페이징 조회. */
@Transactional(readOnly = true)
public PageResponse listMaintain(LedgerSearchParam param) {
param.startPage();
return PageResponse.of(maintainMapper.selectList(param));
}
+ /** 예외수수료 원장 목록 페이징 조회. */
@Transactional(readOnly = true)
public PageResponse listException(LedgerSearchParam param) {
param.startPage();
return PageResponse.of(exceptionMapper.selectList(param));
}
+ /** 모집수수료 원장 상세 조회. 없으면 NOT_FOUND. */
@Transactional(readOnly = true)
public LedgerResp detailRecruit(Long ledgerId) {
LedgerResp r = recruitMapper.selectDetailById(ledgerId);
@@ -50,6 +58,7 @@ public class LedgerService {
return r;
}
+ /** 유지수수료 원장 상세 조회. 없으면 NOT_FOUND. */
@Transactional(readOnly = true)
public LedgerResp detailMaintain(Long ledgerId) {
LedgerResp r = maintainMapper.selectDetailById(ledgerId);
@@ -57,6 +66,7 @@ public class LedgerService {
return r;
}
+ /** 예외수수료 원장 상세 조회. 없으면 NOT_FOUND. */
@Transactional(readOnly = true)
public ExceptionLedgerResp detailException(Long ledgerId) {
ExceptionLedgerResp r = exceptionMapper.selectDetailById(ledgerId);
@@ -64,6 +74,11 @@ public class LedgerService {
return r;
}
+ /**
+ * 예외수수료 원장 수기 등록.
+ * recurringLeft(남은 반복 지급 횟수)를 입력한 반복개월수로 초기화하고,
+ * 승인상태=PENDING(승인대기), 처리상태=NEW(신규)로 저장한다.
+ */
@Transactional
public Long createException(ExceptionLedgerSaveReq req) {
ExceptionLedgerVO vo = exceptionLedgerMapStruct.toVO(req);
@@ -74,14 +89,20 @@ public class LedgerService {
return vo.getLedgerId();
}
+ /** 모집원장 엑셀 추출용 커서(한 건씩 스트리밍) 반환. */
public Cursor exportRecruitCursor(LedgerSearchParam param) {
return recruitMapper.selectCursorForExcel(param);
}
+ /** 유지원장 엑셀 추출용 커서(한 건씩 스트리밍) 반환. */
public Cursor exportMaintainCursor(LedgerSearchParam param) {
return maintainMapper.selectCursorForExcel(param);
}
+ /**
+ * 예외수수료 원장 승인/반려 처리.
+ * status 는 APPROVED/REJECTED 만 허용하고, 로그인한 사용자를 승인자(approverId)로 기록한다.
+ */
@Transactional
public void approveException(Long ledgerId, String status) {
if (!ApproveStatus.APPROVED.name().equals(status) && !ApproveStatus.REJECTED.name().equals(status)) {
diff --git a/ga-api/src/main/java/com/ga/api/service/license/AgentLicenseService.java b/ga-api/src/main/java/com/ga/api/service/license/AgentLicenseService.java
index fcb1849..fafd9a2 100644
--- a/ga-api/src/main/java/com/ga/api/service/license/AgentLicenseService.java
+++ b/ga-api/src/main/java/com/ga/api/service/license/AgentLicenseService.java
@@ -11,6 +11,12 @@ import org.springframework.transaction.annotation.Transactional;
import java.util.List;
+/**
+ * 설계사 자격(License) 도메인 비즈니스 로직.
+ *
+ * 자격 등록 시 ACTIVE 상태로 시작한다. expiring()은 만료일이 지정 일수 이내인 자격을 조회해
+ * 갱신 관리에 활용한다. 클래스 전체는 읽기 전용이며 쓰기 메서드만 별도 트랜잭션을 건다.
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -18,21 +24,25 @@ public class AgentLicenseService {
private final AgentLicenseMapper mapper;
+ /** 자격 목록 조회(페이징). */
public PageResponse list(AgentLicenseSearchParam param) {
param.startPage();
return PageResponse.of(mapper.selectList(param));
}
+ /** 자격 상세 조회. 없으면 NOT_FOUND. */
public AgentLicenseResp detail(Long licenseId) {
AgentLicenseResp resp = mapper.selectById(licenseId);
if (resp == null) throw new BizException(ErrorCode.NOT_FOUND);
return resp;
}
+ /** 만료일이 지정 일수(days) 이내인 자격 목록 조회. */
public List expiring(int days) {
return mapper.selectExpiringWithin(days);
}
+ /** 자격 등록. 상태를 ACTIVE로 고정해 저장한다. */
@Transactional
public Long create(AgentLicenseSaveReq req) {
AgentLicenseVO vo = new AgentLicenseVO();
@@ -47,6 +57,7 @@ public class AgentLicenseService {
return vo.getLicenseId();
}
+ /** 자격 수정. 존재 검증 후 갱신하며 상태는 건드리지 않는다. */
@Transactional
public void update(Long licenseId, AgentLicenseSaveReq req) {
AgentLicenseResp existing = mapper.selectById(licenseId);
@@ -62,6 +73,7 @@ public class AgentLicenseService {
mapper.update(vo);
}
+ /** 자격 레코드 삭제. 존재 검증 후 삭제한다. */
@Transactional
public void delete(Long licenseId) {
AgentLicenseResp existing = mapper.selectById(licenseId);
diff --git a/ga-api/src/main/java/com/ga/api/service/mobile/MobileMeService.java b/ga-api/src/main/java/com/ga/api/service/mobile/MobileMeService.java
index db0d464..e64dc5c 100644
--- a/ga-api/src/main/java/com/ga/api/service/mobile/MobileMeService.java
+++ b/ga-api/src/main/java/com/ga/api/service/mobile/MobileMeService.java
@@ -70,6 +70,7 @@ public class MobileMeService {
deviceTokenMapper.deactivate(token, currentUserId());
}
+ /** 홈 요약 집계(명세서 수/출금 신청 수/미읽음 알림 수). agent 미연결이면 건수는 0. */
@Transactional(readOnly = true)
public MeSummary summary() {
Long userId = currentUserId();
@@ -103,6 +104,7 @@ public class MobileMeService {
.build();
}
+ /** 내 명세서 목록. 클라이언트가 보낸 agentId는 무시하고 본인 것으로 강제 덮어쓴다. */
@Transactional(readOnly = true)
public PageResponse statements(CommissionStatementSearchParam param) {
Long agentId = requireAgentId();
@@ -111,6 +113,7 @@ public class MobileMeService {
return PageResponse.of(statementMapper.selectList(param));
}
+ /** 내 출금 신청 목록. agentId를 본인 것으로 강제 덮어쓴다. */
@Transactional(readOnly = true)
public PageResponse withdrawRequests(WithdrawRequestSearchParam param) {
Long agentId = requireAgentId();
@@ -119,6 +122,7 @@ public class MobileMeService {
return PageResponse.of(withdrawMapper.selectList(param));
}
+ /** 내 알림 목록. userId를 본인 것으로 강제 덮어쓴다. */
@Transactional(readOnly = true)
public PageResponse notifications(UserNotificationSearchParam param) {
Long userId = currentUserId();
@@ -127,6 +131,7 @@ public class MobileMeService {
return PageResponse.of(notificationMapper.selectList(param));
}
+ /** 내 알림 단건 읽음 처리(본인 userId 기준). */
@Transactional
public void markNotificationRead(Long notificationId) {
Long userId = currentUserId();
diff --git a/ga-api/src/main/java/com/ga/api/service/notice/NoticeService.java b/ga-api/src/main/java/com/ga/api/service/notice/NoticeService.java
index 49be7de..e5dc843 100644
--- a/ga-api/src/main/java/com/ga/api/service/notice/NoticeService.java
+++ b/ga-api/src/main/java/com/ga/api/service/notice/NoticeService.java
@@ -13,6 +13,13 @@ import org.springframework.transaction.annotation.Transactional;
import java.util.List;
+/**
+ * 공지사항 + 사용자 알림 도메인 비즈니스 로직.
+ *
+ * 공지사항(notice)은 등록 시 활성 상태로 시작하며, activeList()는 노출 기간/활성 조건을 만족하는 것만 반환한다.
+ * 사용자 알림(user_notification)은 읽음 처리/미읽음 개수 집계를 담당한다.
+ * 클래스 전체는 읽기 전용이며 쓰기 메서드만 별도 트랜잭션을 건다.
+ */
@Service
@RequiredArgsConstructor
@Transactional(readOnly = true)
@@ -23,21 +30,25 @@ public class NoticeService {
// ── Notice ────────────────────────────────────────────────────────────────
+ /** 공지사항 목록 조회(페이징). */
public PageResponse list(NoticeSearchParam param) {
param.startPage();
return PageResponse.of(noticeMapper.selectList(param));
}
+ /** 공지사항 상세 조회. 없으면 NOT_FOUND. */
public NoticeResp detail(Long noticeId) {
NoticeResp resp = noticeMapper.selectById(noticeId);
if (resp == null) throw new BizException(ErrorCode.NOT_FOUND);
return resp;
}
+ /** 현재 노출 가능한(기간 내 + 활성) 공지 목록 조회. */
public List activeList() {
return noticeMapper.selectActive();
}
+ /** 공지사항 등록. 활성(isActive=true)으로 시작하고 작성자를 기록한다. */
@Transactional
public Long create(NoticeSaveReq req) {
NoticeVO vo = new NoticeVO();
@@ -52,6 +63,7 @@ public class NoticeService {
return vo.getNoticeId();
}
+ /** 공지사항 수정. 존재 검증 후 갱신한다. */
@Transactional
public void update(Long noticeId, NoticeSaveReq req) {
NoticeResp existing = noticeMapper.selectById(noticeId);
@@ -66,6 +78,7 @@ public class NoticeService {
noticeMapper.update(vo);
}
+ /** 공지사항 삭제. 존재 검증 후 삭제한다. */
@Transactional
public void delete(Long noticeId) {
NoticeResp existing = noticeMapper.selectById(noticeId);
@@ -75,21 +88,25 @@ public class NoticeService {
// ── UserNotification ──────────────────────────────────────────────────────
+ /** 사용자 알림 목록 조회(페이징). */
public PageResponse