refactor(api): MapStruct 적용 + AgentOrgHistoryResp 적용 + PaymentService/UploadTemplateService 신설 (리뷰 5b)

코드 품질 자동 체인 마지막 단계. ga-api에 5a 산출물 적용 + 잔여 Controller
Mapper 직접 주입 제거.

MapStruct 적용 (수동 매핑 제거):
- ContractService.create/update — ContractMapStruct.toVO/updateVO
- LedgerService — ExceptionLedgerMapStruct.toVO
- UserService.create/update — UserMapStruct.toVO/updateVO

AgentOrgHistoryResp 적용:
- AgentService.history() 반환 List<AgentOrgHistoryVO> → List<AgentOrgHistoryResp>
- AgentMapper.selectHistoryResp(agentId) 사용
- AgentController history 시그니처 동반 변경 — 감사 필드 누설 + FK ID 노출 문제 해소

잔여 Controller Mapper 직접 주입 제거:
- AgentController/LedgerController — AgentService.exportCursor /
  LedgerService.exportRecruitCursor/exportMaintainCursor 위임
- PaymentService 신설 — PaymentController에서 Mapper/TransferFileService
  직접 주입 제거, PageHelper.startPage Service로 이전
- UploadTemplateService 신설 — 3개 Mapper(template/column/history) Service로 이전

PageHelper 위치 통일:
- grep -rn "startPage" controller/ → 결과 없음 (모두 Service로 이전)

남은 예외:
- BatchTriggerController.BatchJobLogMapper — 배치 트리거 특수 패턴이라 보류
- PaymentStatus Enum — 도메인 단계에서 처리 예정

ga-api/src/main/java/com/ga/api/controller/ledger/LedgerController.java

@@ -6,8 +6,6 @@ import com.ga.common.annotation.RequirePermission;
 import com.ga.common.excel.ExcelService;
 import com.ga.common.model.ApiResponse;
 import com.ga.common.model.PageResponse;
-import com.ga.core.mapper.ledger.MaintainLedgerMapper;
-import com.ga.core.mapper.ledger.RecruitLedgerMapper;
 import com.ga.core.vo.ledger.*;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.servlet.http.HttpServletResponse;
@@ -24,8 +22,6 @@ import java.util.Map;
 public class LedgerController {
 
     private final LedgerService service;
-    private final RecruitLedgerMapper recruitMapper;
-    private final MaintainLedgerMapper maintainMapper;
     private final ExcelService excelService;
 
     // ===== 모집 =====
@@ -45,7 +41,7 @@ public class LedgerController {
     @RequirePermission(menu = "LEDGER_RECRUIT", perm = "EXPORT")
     public void exportRecruit(@ModelAttribute LedgerSearchParam param, HttpServletResponse res) {
         excelService.exportLargeExcel("모집수수료원장", LedgerExcelVO.class,
-                () -> recruitMapper.selectCursorForExcel(param), res);
+                () -> service.exportRecruitCursor(param), res);
     }
 
     // ===== 유지 =====
@@ -65,7 +61,7 @@ public class LedgerController {
     @RequirePermission(menu = "LEDGER_MAINTAIN", perm = "EXPORT")
     public void exportMaintain(@ModelAttribute LedgerSearchParam param, HttpServletResponse res) {
         excelService.exportLargeExcel("유지수수료원장", LedgerExcelVO.class,
-                () -> maintainMapper.selectCursorForExcel(param), res);
+                () -> service.exportMaintainCursor(param), res);
     }
 
     // ===== 예외 =====

ga-api/src/main/java/com/ga/api/controller/org/AgentController.java

@@ -6,7 +6,6 @@ import com.ga.common.annotation.RequirePermission;
 import com.ga.common.excel.ExcelService;
 import com.ga.common.model.ApiResponse;
 import com.ga.common.model.PageResponse;
-import com.ga.core.mapper.org.AgentMapper;
 import com.ga.core.vo.org.*;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.servlet.http.HttpServletResponse;
@@ -24,7 +23,6 @@ import java.util.Map;
 public class AgentController {
 
     private final AgentService agentService;
-    private final AgentMapper agentMapper;
     private final ExcelService excelService;
 
     @GetMapping
@@ -64,7 +62,7 @@ public class AgentController {
 
     @GetMapping("/{agentId}/history")
     @RequirePermission(menu = "ORG_AGENT", perm = "READ")
-    public ApiResponse<List<AgentOrgHistoryVO>> history(@PathVariable Long agentId) {
+    public ApiResponse<List<AgentOrgHistoryResp>> history(@PathVariable Long agentId) {
         return ApiResponse.ok(agentService.history(agentId));
     }
 
@@ -72,6 +70,6 @@ public class AgentController {
     @RequirePermission(menu = "ORG_AGENT", perm = "EXPORT")
     public void export(@ModelAttribute AgentSearchParam param, HttpServletResponse response) {
         excelService.exportLargeExcel("설계사목록", AgentExcelVO.class,
-                () -> agentMapper.selectCursorForExcel(param), response);
+                () -> agentService.exportCursor(param), response);
     }
 }

ga-api/src/main/java/com/ga/api/controller/settle/PaymentController.java

@@ -1,11 +1,10 @@
 package com.ga.api.controller.settle;
 
-import com.ga.api.service.transfer.TransferFileService;
+import com.ga.api.service.settle.PaymentService;
 import com.ga.common.annotation.DataChangeLog;
 import com.ga.common.annotation.RequirePermission;
 import com.ga.common.model.ApiResponse;
 import com.ga.common.model.PageResponse;
-import com.ga.core.mapper.settle.PaymentMapper;
 import com.ga.core.vo.settle.PaymentResp;
 import com.ga.core.vo.settle.SettleSearchParam;
 import com.ga.core.vo.settle.TransferFileResp;
@@ -24,21 +23,19 @@ import org.springframework.web.bind.annotation.*;
 @RequiredArgsConstructor
 public class PaymentController {
 
-    private final PaymentMapper mapper;
+    private final PaymentService paymentService;
-    private final TransferFileService transferFileService;
 
     @GetMapping
     @RequirePermission(menu = "PAYMENT", perm = "READ")
     public ApiResponse<PageResponse<PaymentResp>> list(@ModelAttribute SettleSearchParam param) {
-        param.startPage();
+        return ApiResponse.ok(paymentService.list(param));
-        return ApiResponse.ok(PageResponse.of(mapper.selectList(param)));
     }
 
     @PutMapping("/{paymentId}/status")
     @RequirePermission(menu = "PAYMENT", perm = "UPDATE")
     @DataChangeLog(menu = "PAYMENT", table = "payment")
     public ApiResponse<Void> updateStatus(@PathVariable Long paymentId, @Valid @RequestBody PaymentStatusUpdateReq req) {
-        mapper.updateStatus(paymentId, req.getStatus(), req.getFailReason());
+        paymentService.updateStatus(paymentId, req.getStatus(), req.getFailReason());
         return ApiResponse.ok();
     }
 
@@ -49,6 +46,6 @@ public class PaymentController {
     public ApiResponse<TransferFileResp> generateTransferFile(
             @Pattern(regexp = "\\d{6}", message = "settleMonth는 YYYYMM 형식이어야 합니다") @RequestParam String settleMonth,
             @RequestParam String bankCode) {
-        return ApiResponse.ok(transferFileService.generate(settleMonth, bankCode));
+        return ApiResponse.ok(paymentService.generateTransferFile(settleMonth, bankCode));
     }
 }

ga-api/src/main/java/com/ga/api/controller/upload/UploadTemplateController.java

@@ -1,21 +1,15 @@
 package com.ga.api.controller.upload;
 
+import com.ga.api.service.upload.UploadTemplateService;
 import com.ga.common.annotation.DataChangeLog;
 import com.ga.common.annotation.RequirePermission;
-import com.ga.common.exception.BizException;
-import com.ga.common.exception.ErrorCode;
 import com.ga.common.model.ApiResponse;
 import com.ga.common.model.PageResponse;
-import com.ga.common.util.SecurityUtil;
-import com.ga.core.mapper.upload.UploadColumnMapper;
-import com.ga.core.mapper.upload.UploadHistoryMapper;
-import com.ga.core.mapper.upload.UploadTemplateMapper;
 import com.ga.core.vo.upload.*;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
 import lombok.RequiredArgsConstructor;
-import org.springframework.transaction.annotation.Transactional;
 import org.springframework.web.bind.annotation.*;
 
 import java.util.List;
@@ -26,68 +20,37 @@ import java.util.List;
 @RequiredArgsConstructor
 public class UploadTemplateController {
 
-    private final UploadTemplateMapper templateMapper;
+    private final UploadTemplateService templateService;
-    private final UploadColumnMapper   columnMapper;
-    private final UploadHistoryMapper  historyMapper;
 
     @Operation(summary = "템플릿 목록 조회")
     @GetMapping
     @RequirePermission(menu = "SYSTEM_UPLOAD_TEMPLATE", perm = "READ")
     public ApiResponse<PageResponse<UploadTemplateResp>> list(@ModelAttribute UploadTemplateSearchParam param) {
-        param.startPage();
+        return ApiResponse.ok(templateService.list(param));
-        return ApiResponse.ok(PageResponse.of(templateMapper.selectList(param)));
     }
 
     @Operation(summary = "템플릿 상세 조회 (컬럼 포함)")
     @GetMapping("/{templateId}")
     @RequirePermission(menu = "SYSTEM_UPLOAD_TEMPLATE", perm = "READ")
     public ApiResponse<UploadTemplateResp> detail(@PathVariable Long templateId) {
-        UploadTemplateResp resp = templateMapper.selectById(templateId);
+        return ApiResponse.ok(templateService.detail(templateId));
-        if (resp == null) throw new BizException(ErrorCode.NOT_FOUND);
-        resp.setColumns(columnMapper.selectByTemplateId(templateId));
-        return ApiResponse.ok(resp);
     }
 
     @Operation(summary = "템플릿 등록")
     @PostMapping
     @RequirePermission(menu = "SYSTEM_UPLOAD_TEMPLATE", perm = "CREATE")
     @DataChangeLog(menu = "SYSTEM_UPLOAD_TEMPLATE", table = "upload_template")
-    @Transactional
     public ApiResponse<Long> create(@Valid @RequestBody UploadTemplateSaveReq req) {
-        if (templateMapper.existsByCode(req.getTemplateCode()) > 0) {
+        return ApiResponse.ok(templateService.create(req));
-            throw new BizException(ErrorCode.DUPLICATE_DATA, "이미 존재하는 템플릿 코드입니다: " + req.getTemplateCode());
-        }
-        UploadTemplateVO vo = req.toVO();
-        vo.setCreatedBy(SecurityUtil.getCurrentUserId());
-        templateMapper.insert(vo);
-
-        if (req.getColumns() != null && !req.getColumns().isEmpty()) {
-            columnMapper.insertBatch(vo.getTemplateId(), req.getColumns());
-        }
-        return ApiResponse.ok(vo.getTemplateId());
     }
 
     @Operation(summary = "템플릿 수정")
     @PutMapping("/{templateId}")
     @RequirePermission(menu = "SYSTEM_UPLOAD_TEMPLATE", perm = "UPDATE")
     @DataChangeLog(menu = "SYSTEM_UPLOAD_TEMPLATE", table = "upload_template")
-    @Transactional
     public ApiResponse<Void> update(@PathVariable Long templateId,
                                     @Valid @RequestBody UploadTemplateSaveReq req) {
-        if (templateMapper.selectById(templateId) == null) {
+        templateService.update(templateId, req);
-            throw new BizException(ErrorCode.NOT_FOUND);
-        }
-        UploadTemplateVO vo = req.toVO();
-        vo.setTemplateId(templateId);
-        vo.setUpdatedBy(SecurityUtil.getCurrentUserId());
-        templateMapper.update(vo);
-
-        if (req.getColumns() != null) {
-            columnMapper.deleteByTemplateId(templateId);
-            if (!req.getColumns().isEmpty()) {
-                columnMapper.insertBatch(templateId, req.getColumns());
-            }
-        }
         return ApiResponse.ok();
     }
 
@@ -95,13 +58,8 @@ public class UploadTemplateController {
     @DeleteMapping("/{templateId}")
     @RequirePermission(menu = "SYSTEM_UPLOAD_TEMPLATE", perm = "DELETE")
     @DataChangeLog(menu = "SYSTEM_UPLOAD_TEMPLATE", table = "upload_template")
-    @Transactional
     public ApiResponse<Void> delete(@PathVariable Long templateId) {
-        if (templateMapper.selectById(templateId) == null) {
+        templateService.delete(templateId);
-            throw new BizException(ErrorCode.NOT_FOUND);
-        }
-        columnMapper.deleteByTemplateId(templateId);
-        templateMapper.delete(templateId);
         return ApiResponse.ok();
     }
 
@@ -109,23 +67,16 @@ public class UploadTemplateController {
     @GetMapping("/{templateId}/columns")
     @RequirePermission(menu = "SYSTEM_UPLOAD_TEMPLATE", perm = "READ")
     public ApiResponse<List<UploadTemplateColumnVO>> columns(@PathVariable Long templateId) {
-        return ApiResponse.ok(columnMapper.selectByTemplateId(templateId));
+        return ApiResponse.ok(templateService.columns(templateId));
     }
 
     @Operation(summary = "템플릿 컬럼 전체 갱신 (기존 삭제 후 재등록)")
     @PutMapping("/{templateId}/columns")
     @RequirePermission(menu = "SYSTEM_UPLOAD_TEMPLATE", perm = "UPDATE")
     @DataChangeLog(menu = "SYSTEM_UPLOAD_TEMPLATE", table = "upload_template_column")
-    @Transactional
     public ApiResponse<Void> updateColumns(@PathVariable Long templateId,
                                            @RequestBody List<UploadTemplateColumnVO> columns) {
-        if (templateMapper.selectById(templateId) == null) {
+        templateService.updateColumns(templateId, columns);
-            throw new BizException(ErrorCode.NOT_FOUND);
-        }
-        columnMapper.deleteByTemplateId(templateId);
-        if (columns != null && !columns.isEmpty()) {
-            columnMapper.insertBatch(templateId, columns);
-        }
         return ApiResponse.ok();
     }
 
@@ -134,7 +85,6 @@ public class UploadTemplateController {
     @RequirePermission(menu = "SYSTEM_UPLOAD_TEMPLATE", perm = "READ")
     public ApiResponse<PageResponse<UploadHistoryResp>> history(@PathVariable Long templateId,
                                                                  @ModelAttribute UploadTemplateSearchParam param) {
-        param.startPage();
+        return ApiResponse.ok(templateService.history(templateId, param));
-        return ApiResponse.ok(PageResponse.of(historyMapper.selectByTemplate(templateId, param)));
     }
 }

ga-api/src/main/java/com/ga/api/service/ledger/LedgerService.java

@@ -7,9 +7,11 @@ import com.ga.common.util.SecurityUtil;
 import com.ga.core.mapper.ledger.ExceptionLedgerMapper;
 import com.ga.core.mapper.ledger.MaintainLedgerMapper;
 import com.ga.core.mapper.ledger.RecruitLedgerMapper;
+import com.ga.core.mapstruct.ExceptionLedgerMapStruct;
 import com.ga.core.vo.ledger.*;
 import com.ga.core.vo.ledger.ApproveStatus;
 import com.ga.core.vo.ledger.ExceptionLedgerStatus;
+import org.apache.ibatis.cursor.Cursor;
 import lombok.RequiredArgsConstructor;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
@@ -21,6 +23,7 @@ public class LedgerService {
     private final RecruitLedgerMapper recruitMapper;
     private final MaintainLedgerMapper maintainMapper;
     private final ExceptionLedgerMapper exceptionMapper;
+    private final ExceptionLedgerMapStruct exceptionLedgerMapStruct;
 
     @Transactional(readOnly = true)
     public PageResponse<LedgerResp> listRecruit(LedgerSearchParam param) {
@@ -63,17 +66,7 @@ public class LedgerService {
 
     @Transactional
     public Long createException(ExceptionLedgerSaveReq req) {
-        ExceptionLedgerVO vo = new ExceptionLedgerVO();
+        ExceptionLedgerVO vo = exceptionLedgerMapStruct.toVO(req);
-        vo.setAgentId(req.getAgentId());
-        vo.setExceptionCode(req.getExceptionCode());
-        vo.setSettleMonth(req.getSettleMonth());
-        vo.setAmount(req.getAmount());
-        vo.setPolicyNo(req.getPolicyNo());
-        vo.setCompanyCode(req.getCompanyCode());
-        vo.setInsuranceType(req.getInsuranceType());
-        vo.setDescription(req.getDescription());
-        vo.setRecurringYn(req.getRecurringYn());
-        vo.setRecurringMonths(req.getRecurringMonths());
         vo.setRecurringLeft(req.getRecurringMonths());
         vo.setApproveStatus(ApproveStatus.PENDING.name());
         vo.setStatus(ExceptionLedgerStatus.NEW.name());
@@ -81,6 +74,14 @@ public class LedgerService {
         return vo.getLedgerId();
     }
 
+    public Cursor<LedgerExcelVO> exportRecruitCursor(LedgerSearchParam param) {
+        return recruitMapper.selectCursorForExcel(param);
+    }
+
+    public Cursor<LedgerExcelVO> exportMaintainCursor(LedgerSearchParam param) {
+        return maintainMapper.selectCursorForExcel(param);
+    }
+
     @Transactional
     public void approveException(Long ledgerId, String status) {
         if (!ApproveStatus.APPROVED.name().equals(status) && !ApproveStatus.REJECTED.name().equals(status)) {

ga-api/src/main/java/com/ga/api/service/org/AgentService.java

@@ -8,6 +8,7 @@ import com.ga.core.mapper.org.AgentMapper;
 import com.ga.core.vo.org.*;
 import com.ga.core.vo.org.AgentStatus;
 import lombok.RequiredArgsConstructor;
+import org.apache.ibatis.cursor.Cursor;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 
@@ -80,8 +81,12 @@ public class AgentService {
     }
 
     @Transactional(readOnly = true)
-    public java.util.List<AgentOrgHistoryVO> history(Long agentId) {
+    public java.util.List<AgentOrgHistoryResp> history(Long agentId) {
-        return mapper.selectHistory(agentId);
+        return mapper.selectHistoryResp(agentId);
+    }
+
+    public Cursor<AgentExcelVO> exportCursor(AgentSearchParam param) {
+        return mapper.selectCursorForExcel(param);
     }
 
     private AgentVO toVO(AgentSaveReq req, Long agentId) {

ga-api/src/main/java/com/ga/api/service/product/ContractService.java

@@ -4,6 +4,7 @@ import com.ga.common.exception.BizException;
 import com.ga.common.exception.ErrorCode;
 import com.ga.common.model.PageResponse;
 import com.ga.core.mapper.product.ContractMapper;
+import com.ga.core.mapstruct.ContractMapStruct;
 import com.ga.core.vo.product.ContractResp;
 import com.ga.core.vo.product.ContractSaveReq;
 import com.ga.core.vo.product.ContractSearchParam;
@@ -18,6 +19,7 @@ import org.springframework.transaction.annotation.Transactional;
 public class ContractService {
 
     private final ContractMapper mapper;
+    private final ContractMapStruct contractMapStruct;
 
     @Transactional(readOnly = true)
     public PageResponse<ContractResp> list(ContractSearchParam param) {
@@ -37,19 +39,8 @@ public class ContractService {
         if (mapper.existsByPolicyNo(req.getPolicyNo()) > 0) {
             throw new BizException(ErrorCode.DUPLICATE_DATA, "이미 등록된 증권번호입니다");
         }
-        ContractVO vo = new ContractVO();
+        ContractVO vo = contractMapStruct.toVO(req);
-        vo.setAgentId(req.getAgentId());
-        vo.setProductId(req.getProductId());
-        vo.setPolicyNo(req.getPolicyNo());
-        vo.setContractorName(req.getContractorName());
-        vo.setInsuredName(req.getInsuredName());
-        vo.setPremium(req.getPremium());
-        vo.setPayCycle(req.getPayCycle());
-        vo.setPayPeriod(req.getPayPeriod());
-        vo.setCoveragePeriod(req.getCoveragePeriod());
         vo.setStatus(ContractStatus.ACTIVE.name());
-        vo.setContractDate(req.getContractDate());
-        vo.setEffectiveDate(req.getEffectiveDate());
         mapper.insert(vo);
         return vo.getContractId();
     }
@@ -58,15 +49,7 @@ public class ContractService {
     public void update(Long contractId, ContractSaveReq req) {
         ContractVO vo = mapper.selectById(contractId);
         if (vo == null) throw new BizException(ErrorCode.NOT_FOUND);
-        vo.setAgentId(req.getAgentId());
+        contractMapStruct.updateVO(req, vo);
-        vo.setProductId(req.getProductId());
-        vo.setContractorName(req.getContractorName());
-        vo.setInsuredName(req.getInsuredName());
-        vo.setPremium(req.getPremium());
-        vo.setPayCycle(req.getPayCycle());
-        vo.setPayPeriod(req.getPayPeriod());
-        vo.setCoveragePeriod(req.getCoveragePeriod());
-        vo.setEffectiveDate(req.getEffectiveDate());
         mapper.update(vo);
     }
 

ga-api/src/main/java/com/ga/api/service/settle/PaymentService.java

@@ -0,0 +1,34 @@
+package com.ga.api.service.settle;
+
+import com.ga.api.service.transfer.TransferFileService;
+import com.ga.common.model.PageResponse;
+import com.ga.core.mapper.settle.PaymentMapper;
+import com.ga.core.vo.settle.PaymentResp;
+import com.ga.core.vo.settle.SettleSearchParam;
+import com.ga.core.vo.settle.TransferFileResp;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+@Service
+@RequiredArgsConstructor
+public class PaymentService {
+
+    private final PaymentMapper mapper;
+    private final TransferFileService transferFileService;
+
+    @Transactional(readOnly = true)
+    public PageResponse<PaymentResp> list(SettleSearchParam param) {
+        param.startPage();
+        return PageResponse.of(mapper.selectList(param));
+    }
+
+    @Transactional
+    public void updateStatus(Long paymentId, String status, String failReason) {
+        mapper.updateStatus(paymentId, status, failReason);
+    }
+
+    public TransferFileResp generateTransferFile(String settleMonth, String bankCode) {
+        return transferFileService.generate(settleMonth, bankCode);
+    }
+}

ga-api/src/main/java/com/ga/api/service/system/UserService.java

@@ -5,6 +5,7 @@ import com.ga.common.exception.ErrorCode;
 import com.ga.common.model.PageResponse;
 import com.ga.common.system.SystemConfigService;
 import com.ga.core.mapper.user.UserMapper;
+import com.ga.core.mapstruct.UserMapStruct;
 import com.ga.core.vo.user.UserResp;
 import com.ga.core.vo.user.UserSaveReq;
 import com.ga.core.vo.user.UserSearchParam;
@@ -24,6 +25,7 @@ public class UserService {
     private final UserMapper mapper;
     private final PasswordEncoder passwordEncoder;
     private final SystemConfigService configService;
+    private final UserMapStruct userMapStruct;
 
     @Transactional(readOnly = true)
     public PageResponse<UserResp> list(UserSearchParam param) {
@@ -48,13 +50,8 @@ public class UserService {
         if (initialPwd == null || initialPwd.isBlank()) {
             initialPwd = "init1234!";  // 임시 — 로그인 후 변경 강제
         }
-        UserVO vo = new UserVO();
+        UserVO vo = userMapStruct.toVO(req);
-        vo.setLoginId(req.getLoginId());
         vo.setPassword(passwordEncoder.encode(initialPwd));
-        vo.setUserName(req.getUserName());
-        vo.setEmail(req.getEmail());
-        vo.setPhone(req.getPhone());
-        vo.setAgentId(req.getAgentId());
         vo.setStatus(req.getStatus() != null ? req.getStatus() : UserStatus.ACTIVE.name());
         mapper.insert(vo);
 
@@ -66,15 +63,10 @@ public class UserService {
 
     @Transactional
     public void update(Long userId, UserSaveReq req) {
-        UserVO old = mapper.selectById(userId);
+        UserVO vo = mapper.selectById(userId);
-        if (old == null) throw new BizException(ErrorCode.NOT_FOUND);
+        if (vo == null) throw new BizException(ErrorCode.NOT_FOUND);
-        UserVO vo = new UserVO();
+        userMapStruct.updateVO(req, vo);
         vo.setUserId(userId);
-        vo.setUserName(req.getUserName());
-        vo.setEmail(req.getEmail());
-        vo.setPhone(req.getPhone());
-        vo.setAgentId(req.getAgentId());
-        vo.setStatus(req.getStatus());
         mapper.update(vo);
 
         if (req.getRoleIds() != null) {

ga-api/src/main/java/com/ga/api/service/upload/UploadTemplateService.java

@@ -0,0 +1,100 @@
+package com.ga.api.service.upload;
+
+import com.ga.common.exception.BizException;
+import com.ga.common.exception.ErrorCode;
+import com.ga.common.model.PageResponse;
+import com.ga.common.util.SecurityUtil;
+import com.ga.core.mapper.upload.UploadColumnMapper;
+import com.ga.core.mapper.upload.UploadHistoryMapper;
+import com.ga.core.mapper.upload.UploadTemplateMapper;
+import com.ga.core.vo.upload.*;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.List;
+
+@Service
+@RequiredArgsConstructor
+public class UploadTemplateService {
+
+    private final UploadTemplateMapper templateMapper;
+    private final UploadColumnMapper columnMapper;
+    private final UploadHistoryMapper historyMapper;
+
+    @Transactional(readOnly = true)
+    public PageResponse<UploadTemplateResp> list(UploadTemplateSearchParam param) {
+        param.startPage();
+        return PageResponse.of(templateMapper.selectList(param));
+    }
+
+    @Transactional(readOnly = true)
+    public UploadTemplateResp detail(Long templateId) {
+        UploadTemplateResp resp = templateMapper.selectById(templateId);
+        if (resp == null) throw new BizException(ErrorCode.NOT_FOUND);
+        resp.setColumns(columnMapper.selectByTemplateId(templateId));
+        return resp;
+    }
+
+    @Transactional
+    public Long create(UploadTemplateSaveReq req) {
+        if (templateMapper.existsByCode(req.getTemplateCode()) > 0) {
+            throw new BizException(ErrorCode.DUPLICATE_DATA, "이미 존재하는 템플릿 코드입니다: " + req.getTemplateCode());
+        }
+        UploadTemplateVO vo = req.toVO();
+        vo.setCreatedBy(SecurityUtil.getCurrentUserId());
+        templateMapper.insert(vo);
+        if (req.getColumns() != null && !req.getColumns().isEmpty()) {
+            columnMapper.insertBatch(vo.getTemplateId(), req.getColumns());
+        }
+        return vo.getTemplateId();
+    }
+
+    @Transactional
+    public void update(Long templateId, UploadTemplateSaveReq req) {
+        if (templateMapper.selectById(templateId) == null) {
+            throw new BizException(ErrorCode.NOT_FOUND);
+        }
+        UploadTemplateVO vo = req.toVO();
+        vo.setTemplateId(templateId);
+        vo.setUpdatedBy(SecurityUtil.getCurrentUserId());
+        templateMapper.update(vo);
+        if (req.getColumns() != null) {
+            columnMapper.deleteByTemplateId(templateId);
+            if (!req.getColumns().isEmpty()) {
+                columnMapper.insertBatch(templateId, req.getColumns());
+            }
+        }
+    }
+
+    @Transactional
+    public void delete(Long templateId) {
+        if (templateMapper.selectById(templateId) == null) {
+            throw new BizException(ErrorCode.NOT_FOUND);
+        }
+        columnMapper.deleteByTemplateId(templateId);
+        templateMapper.delete(templateId);
+    }
+
+    @Transactional(readOnly = true)
+    public List<UploadTemplateColumnVO> columns(Long templateId) {
+        return columnMapper.selectByTemplateId(templateId);
+    }
+
+    @Transactional
+    public void updateColumns(Long templateId, List<UploadTemplateColumnVO> columns) {
+        if (templateMapper.selectById(templateId) == null) {
+            throw new BizException(ErrorCode.NOT_FOUND);
+        }
+        columnMapper.deleteByTemplateId(templateId);
+        if (columns != null && !columns.isEmpty()) {
+            columnMapper.insertBatch(templateId, columns);
+        }
+    }
+
+    @Transactional(readOnly = true)
+    public PageResponse<UploadHistoryResp> history(Long templateId, UploadTemplateSearchParam param) {
+        param.startPage();
+        return PageResponse.of(historyMapper.selectByTemplate(templateId, param));
+    }
+}