HERA-V4 엑셀 업로드 가이드¶

package kr.co.dandisoft.hera.domain.sys.excel.sys0101;

import jakarta.annotation.Resource;
import kr.co.dandisoft.hera.domain.sys.CommonCodeClient;
import kr.co.dandisoft.hera.domain.sys.code.common.CommonCodeVO;
import kr.co.dandisoft.hera.domain.sys.excel.upload.FieldExistsRequest;
import kr.co.dandisoft.hera.excel.upload.AbstractExcelUploadMenuAdapter;
import kr.co.dandisoft.hera.excel.upload.ExcelUploadSaveResult;
import kr.co.dandisoft.minu.utils.map.MapContext;
import lombok.extern.slf4j.Slf4j;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Component;

import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.Set;

@Slf4j
@Component   // Spring이 자동으로 인스턴스를 만들고 관리
public class CommonCodeExcelAdapter extends AbstractExcelUploadMenuAdapter<CommonCodeVO> {

    @Resource
    private CommonCodeClient commonCodeClient;   // bootstrap-system 모듈로 호출하는 Feign client

    // === 메뉴 식별 ===

    @Override
    public String getDomainCode() { return "SYS_0101"; }   // 임시 파일 경로 prefix

    @Override
    public String getMenuId() { return "sys0101"; }   // Coordinator가 이 ID로 Adapter 매핑

    // === 도메인 콜백 (부모 클래스가 호출) ===

    /** chunk 단위 저장 — 부모의 saveInChunks()가 자동 호출한다. */
    @Override
    protected ResponseEntity<?> doSaveChunk(List<CommonCodeVO> chunk) {
        return commonCodeClient.saveBatch(chunk);   // 엑셀 전용 batch INSERT (UPDATE 우회)
    }

    /** 검증룰 unique:Y 필드 자동 DB 체크 시 호출된다. */
    @Override
    protected List<String> doFindExistingValues(
            String dbFieldName, List<String> values, Map<String, Object> scopeContext) {
        return commonCodeClient.findExistingValues(new FieldExistsRequest(dbFieldName, values, scopeContext));
    }

    // === 라이프사이클 ===

    /** Coordinator가 검증 통과 행을 넘겨주면 호출된다. */
    @Override
    public ExcelUploadSaveResult save(List<Map<String, Object>> validRows, MapContext context) {
        return saveInChunks(toVoList(validRows, context));   // Map → VO 변환 후 부모의 chunk 저장 호출
    }

    /** 엑셀 row(Map) → 도메인 VO 변환. 도메인마다 필드가 다르므로 메뉴별로 작성한다. */
    private List<CommonCodeVO> toVoList(List<Map<String, Object>> rows, MapContext context) {
        List<CommonCodeVO> list = new ArrayList<>(rows.size());
        for (Map<String, Object> row : rows) {
            CommonCodeVO vo = new CommonCodeVO();
            vo.setCategoryCode(str(row, "categoryCode"));   // str()는 부모가 제공하는 헬퍼 (null 안전 + trim)
            vo.setGroupCode(str(row, "groupCode"));
            vo.setCode(str(row, "code"));
            vo.setName(str(row, "name"));
            list.add(vo);
        }
        return list;
    }
}

@Data
@EqualsAndHashCode(callSuper = true)
public class CommonCodeVO extends AuditVO {
    private String categoryCode;
    private String categoryName;
    private String groupCode;
    private String groupName;
    private String code;
    private String name;
    private String useYn;
    private Integer orderNo;
    // ... attribute01~05, refId 등
}

@Mapper
public interface CommonCodeMapper extends BaseMapper<CommonCode> {

    List<String> findExistingValuesByField(
        @Param("columnName") String columnName,
        @Param("categoryCode") String categoryCode,
        @Param("groupCode") String groupCode,
        @Param("refId") String refId,
        @Param("refIdBlank") boolean refIdBlank,
        @Param("values") String[] values
    );

    Set<String> findTableColumns(@Param("tableName") String tableName);
}

<select id="findExistingValuesByField" resultType="string">
    SELECT cc.${columnName}
      FROM sys_common_code cc
     WHERE cc.category_code = #{categoryCode}
       AND cc.group_code = #{groupCode}
       AND (#{refIdBlank} = true OR cc.ref_id = #{refId})
       AND cc.${columnName} = ANY(
             #{values, jdbcType=ARRAY,
               typeHandler=kr.co.dandisoft.hera.mapper.handler.type.StringArrayTypeHandler}::varchar[]
           )
</select>

<select id="findTableColumns" resultType="string">
    SELECT column_name FROM information_schema.columns
     WHERE table_schema = current_schema()
       AND table_name = #{tableName}
</select>

@Service
public class CommonCodeServiceImpl extends AuditServiceImpl<CommonCode, CommonCodeMapper>
        implements CommonCodeService {

    @Resource
    private CommonCodeMapper commonCodeMapper;

    @Resource
    private DbColumnGuard dbColumnGuard;

    @Override
    public List<String> findExistingValues(
            String dbFieldName, List<String> values, Map<String, Object> scopeContext) {
        // SQL Injection 3중 방어 (정규식 + information_schema 캐시)
        dbColumnGuard.validate(dbFieldName, "sys_common_code", commonCodeMapper::findTableColumns);

        if (values == null || values.isEmpty()) return List.of();

        Map<String, Object> scope = scopeContext != null ? scopeContext : Map.of();
        String categoryCode = (String) scope.get("categoryCode");
        String groupCode = (String) scope.get("groupCode");
        String refId = (String) scope.get("refId");
        boolean refIdBlank = (refId == null || refId.isEmpty());

        List<String> distinctValues = values.stream()
                .filter(v -> v != null && !v.isBlank())
                .distinct()
                .toList();
        if (distinctValues.isEmpty()) return List.of();

        return Lists.partition(distinctValues, BULK_UNIQUE_LOOKUP_CHUNK_SIZE).stream()
                .flatMap(chunk -> commonCodeMapper.findExistingValuesByField(
                        dbFieldName, categoryCode, groupCode, refId, refIdBlank, chunk.toArray(new String[0])
                ).stream())
                .distinct()
                .toList();
    }
}

@PostMapping("/common-codes/exists-by-field")
public List<String> findExistingValues(@RequestBody FieldExistsRequest request) {
    return commonCodeService.findExistingValues(
        request.getDbFieldName(),
        request.getValues(),
        request.getScopeContext()
    );
}

/**
 * 엑셀 업로드 전용 batch INSERT.
 * 화면 단건 저장의 부가 로직(예: revision UPDATE) 을 우회하고 multi-row INSERT 만 수행한다.
 */
@PostMapping("/common-codes/batch")
public ResponseEntity<?> saveBatch(@RequestBody List<CommonCodeVO> commonCodeVOList) {
    commonCodeService.saveCodeListBatch(commonCodeVOList);
    return ok();
}

@PostMapping("/common-codes/exists-by-field")
List<String> findExistingValues(@RequestBody FieldExistsRequest request);

/** 엑셀 업로드 전용 batch INSERT. 화면 단건 저장의 부가 로직 우회. */
@PostMapping("/common-codes/batch")
ResponseEntity<?> saveBatch(@RequestBody List<CommonCodeVO> codeVOList);

// scope 분기가 필요한 경우 (예: categoryCode + groupCode 조합 안에서만 unique)
@Override
protected Map<String, Object> buildScope(MapContext context) {
    Map<String, Object> scope = super.buildScope(context);
    scope.putIfAbsent("categoryCode", context.get("categoryCode"));
    scope.putIfAbsent("groupCode", context.get("groupCode"));
    return scope;
}

// 어댑터에서 별도 복합키를 직접 검증하는 경우에만 (자동 DB unique 체크 제외)
// → §4.5 "자주 쓰는 적용 패턴" 참조. CommonCodeExcelAdapter는 override 안 함.
// @Override
// protected Set<String> adapterHandledFields() {
//     return Set.of("code");
// }

@Override
public ExcelUploadSaveResult validateBeforeSave(List<Map<String, Object>> validRows, MapContext context) {
    ExcelUploadSaveResult result = ExcelUploadSaveResult.success();
    // 검증룰 unique:Y 자동 DB 체크 (sys0402 매핑 + buildScope 기반)
    if (!Boolean.TRUE.equals(context.get("skipDbUniqueCheck"))) {
        applyAutoDbUniqueCheck(validRows, context, result);
    }
    return result;
}

<th:block layout:insert="~{fragments/modal/modal-excel-upload :: content(${@apiUrl}+'/sys0101/excel-upload', 'sys0101')}"/>

[
  {"fieldName":"카테고리코드"},
  {"fieldName":"그룹코드"},
  {"fieldName":"코드(필수)"},
  {"fieldName":"이름(필수)"}
]

{
  "0": [
    {"fieldName":"카테고리코드","dataType":"STRING","dbfieldName":"category_code","uniqueField":false},
    {"fieldName":"그룹코드","dataType":"STRING","dbfieldName":"group_code","uniqueField":false},
    {"fieldName":"코드(필수)","dataType":"STRING","dbfieldName":"code","uniqueField":true},
    {"fieldName":"이름(필수)","dataType":"STRING","dbfieldName":"name","uniqueField":true}
  ]
}

{
  "0": {
    "fieldName":"code",
    "validationRule":{"notNull":"Y","textSize":"50","unique":"Y"}
  },
  "1": {
    "fieldName":"name",
    "validationRule":{"notNull":"Y","textSize":"100"}
  }
}

{
  "0": {
    "fieldName":"code",
    "conversionRule":{"trim":"Y","upperCase":"Y"}
  }
}

{ "excelUpload": "Y" }

// 예: 도메인이 (categoryCode + groupCode + code) 3컬럼 복합키를 별도 검증하는 경우
@Override
protected Set<String> adapterHandledFields() {
    return Set.of("code");   // 'code'는 자동 체크에서 제외
}

1. ValidationRuleEngine 이 검증룰에서 unique:Y 필드 발견
        ↓
2. AbstractExcelUploadMenuAdapter.applyAutoDbUniqueCheck 진입
        ↓
3. 어댑터의 buildScope(context) 호출 → Map<String, Object> scope 획득
        ↓
4. doFindExistingValues(dbFieldName, values, scope) 호출
        ↓
5. 도메인 Feign Client → 서버 API → Service → Mapper
        ↓
6. Mapper 가 scope 의 키를 WHERE 절에 적용:
   SELECT code FROM sys_common_code
    WHERE code IN (?, ?, ...)
      AND category_code = #{scope.categoryCode}    ← scope 키 활용
      AND group_code    = #{scope.groupCode}        ← scope 키 활용

@SuppressWarnings("unchecked")
protected Map<String, Object> buildScope(MapContext context) {
    Map<String, Object> raw = (Map<String, Object>) context.get("scopeContext");
    return raw != null ? new LinkedHashMap<>(raw) : new LinkedHashMap<>();
}

@Override
protected Map<String, Object> buildScope(MapContext context) {
    Map<String, Object> scope = super.buildScope(context);              // 1) 기본 scope 가져오기
    scope.putIfAbsent("categoryCode", context.get("categoryCode"));     // 2) 카테고리 추가
    scope.putIfAbsent("groupCode", context.get("groupCode"));           // 3) 그룹 추가
    return scope;
}

1. 화면 JS (sys0101.js) → 업로드 모달에서 categoryCode/groupCode 선택
        ↓
2. POST /api/excel-upload-runtime/{menuId}/excel/upload/post-action
   요청 본문에 { uploadId, categoryCode, groupCode, ... } 포함
        ↓
3. ExcelUploadRuntimeApiController 가 받아 MapContext 에 모든 키 주입
        ↓
4. ExcelUploadCoordinator.process 호출 → context 에 scopeContext 등 자동 채움
   (Coordinator 가 일부 도메인 키를 scopeContext 로 옮기기도 함)
        ↓
5. ValidationRuleEngine 이 unique:Y 필드 발견
        ↓
6. AbstractExcelUploadMenuAdapter.applyAutoDbUniqueCheck 진입
        ↓
7. adapter.buildScope(context) 호출:
   - default: context.scopeContext 그대로
   - CommonCodeExcelAdapter (override): context.categoryCode + groupCode 추가
        ↓
8. adapter.doFindExistingValues(dbField, values, scope) 호출
        ↓
9. commonCodeClient.findExistingValues(new FieldExistsRequest(dbField, values, scope))
   → FieldExistsRequest 의 scopeContext 필드에 scope 가 그대로 들어감
        ↓
10. CommonCodeApiController.findExistingValues 가 받아
    CommonCodeServiceImpl.findExistingValues(dbField, values, scope) 호출
        ↓
11. Service 가 scope 에서 키 추출:
    String categoryCode = (String) scope.get("categoryCode");
    String groupCode    = (String) scope.get("groupCode");
    String refId        = (String) scope.get("refId");
        ↓
12. Mapper 호출:
    mapper.findExistingValuesByField(dbField, categoryCode, groupCode, refId, refIdBlank, values)
        ↓
13. MyBatis XML 의 SQL 발행:
    SELECT cc.${columnName}
      FROM sys_common_code cc
     WHERE cc.category_code = #{categoryCode}    ← 9단계의 scope 값
       AND cc.group_code    = #{groupCode}       ← 9단계의 scope 값
       AND cc.${columnName} = ANY(#{values}::varchar[])
        ↓
14. 결과 ← 해당 (category, group) 안에서 이미 존재하는 값 목록
        ↓
15. AbstractExcelUploadMenuAdapter 가 결과를 result.addError(rowIdx, fieldName, msg) 로 마킹

@Override
protected Map<String, Object> buildScope(MapContext context) {
    Map<String, Object> scope = super.buildScope(context);
    scope.put("whereClause", "category_code = 'SYS_USER'");   // ❌ SQL 조각 직접 주입
    return scope;
}

scope.put("CategoryCode", ...);   // ❌ 어댑터마다 다른 케이스 사용
scope.put("category_code", ...);  // ❌ Mapper 가 categoryCode 기대하는데 snake_case 로 넣음

scope.put("categoryCode", context.get("categoryCode").toString().toUpperCase());   // ❌ 가공

@Override
protected Map<String, Object> buildScope(MapContext context) {
    Map<String, Object> scope = super.buildScope(context);
    scope.putIfAbsent("도메인_scope_키1", context.get("도메인_scope_키1"));
    scope.putIfAbsent("도메인_scope_키2", context.get("도메인_scope_키2"));
    // 필요한 만큼 추가
    return scope;
}

@Override
public ExcelUploadSaveResult save(List<Map<String, Object>> validRows, MapContext context) {
    // 1) 컨텍스트 가드 (필수 키 확인)
    String uploadId = (String) context.get("uploadId");
    if (!StringUtils.hasText(uploadId)) {
        return ExcelUploadSaveResult.ofError(0, primaryFieldName(), "업로드 처리 정보가 누락되었습니다.");
    }

    // 2) 도메인 Support 호출 → 저장 대상 분리
    //    (예: parseCustomerRows 가 saveList + resultList 를 분리)
    CustomerUploadResult parsed = ldb0103Support.parseCustomerRows(validRows, context);

    ExcelUploadSaveResult result = ExcelUploadSaveResult.success();

    // 3) 첫 번째 테이블 저장 (chunk 단위)
    if (!parsed.saveList().isEmpty()) {
        result = saveInChunks(parsed.saveList());   // ← cell 단위 마킹 자동
        if (result.hasErrors()) {
            return result;   // 1차 저장 실패 시 2차 저장 시도 안 함
        }
    }

    // 4) 두 번째 테이블 저장 (도메인 Service 의 별도 메서드)
    if (!parsed.resultList().isEmpty()) {
        try {
            ResponseEntity<?> res = ldbFileRsltClient.saveBatch(parsed.resultList());
            if (!res.getStatusCode().is2xxSuccessful()) {
                return ExcelUploadSaveResult.ofError(0, VIRTUAL_ROW_FIELD,
                        "업로드 결과 저장에 실패했습니다. (HTTP " + res.getStatusCode() + ")");
            }
        } catch (Exception e) {
            log.error("{}-save :: 결과 저장 실패", getClass().getSimpleName(), e);
            return ExcelUploadSaveResult.ofError(0, VIRTUAL_ROW_FIELD,
                    isSystemUnavailable(e) ? systemUnavailableMessage() : extractErrorMessage(e));
        }
    }

    // 5) 결과 캐시 보관 등 부가 작업
    resultByUploadId.put(uploadId, parsed);

    return result;
}

@Override
public ExcelUploadSaveResult save(List<Map<String, Object>> validRows, MapContext context) {
    List<HrmEmpeVO> voList = toVoList(validRows);
    return saveInChunks(voList);
}

@Override
protected ResponseEntity<?> doSaveChunk(List<HrmEmpeVO> chunk) {
    // 도메인 Service 의 upsertBatch 가 사번 기준 INSERT/UPDATE 분기 처리
    return hrmEmpeClient.upsertBatch(chunk);
}

@Transactional
public void upsertBatch(List<HrmEmpeVO> list) {
    // 1) 기존 사번 일괄 조회
    List<String> empNos = list.stream().map(HrmEmpeVO::getEmpNo).distinct().toList();
    Set<String> existing = new HashSet<>(mapper.findExistingEmpNos(empNos));

    // 2) 분리
    List<HrmEmpeVO> inserts = list.stream().filter(vo -> !existing.contains(vo.getEmpNo())).toList();
    List<HrmEmpeVO> updates = list.stream().filter(vo -> existing.contains(vo.getEmpNo())).toList();

    // 3) batch INSERT + batch UPDATE
    if (!inserts.isEmpty()) super.saveVO(inserts, 1000);
    if (!updates.isEmpty()) mapper.updateBatch(updates);
}

@Override
protected ResponseEntity<?> doSaveChunk(List<HrmEmpeVO> chunk) {
    return hrmEmpeClient.updateBatch(chunk);   // 도메인 Service 의 batch UPDATE
}

@Override
protected Map<String, String> extractFieldErrors(Exception e, CommonCodeVO row) {
    if (e == null || e.getMessage() == null) {
        return super.extractFieldErrors(e, row);   // 기본: _row 가상 컬럼
    }
    String msg = e.getMessage();
    if (msg.contains("duplicate key") && msg.contains("code")) {
        return Map.of("code", "이미 존재하는 코드입니다.");
    }
    if (msg.contains("null value in column \"name\"")) {
        return Map.of("name", "이름은 필수입니다.");
    }
    return super.extractFieldErrors(e, row);   // 매칭 실패 시 default
}

@Override
protected ResponseEntity<?> doSaveSingle(CommonCodeVO row) {
    return commonCodeClient.save(row);   // 단건 전용 endpoint
}

@Override
public ExcelUploadSaveResult save(List<Map<String, Object>> rows, MapContext context) {
    EasyExcel.read(filePath).sheet(0).doRead();   // ❌ Coordinator가 이미 파싱했다
}

@Transactional   // ❌
public ExcelUploadSaveResult save(...) { }

for (CommonCodeVO vo : list) {
    commonCodeClient.save(List.of(vo));   // ❌ N번 호출, 성능 저하
}

@Override
protected ResponseEntity<?> doSaveChunk(List<CommonCodeVO> chunk) {
    return commonCodeClient.save(chunk);   // ❌ 화면 저장용 (UPDATE/revision 등 부가 로직 포함)
}

@Override
protected ResponseEntity<?> doSaveChunk(List<CommonCodeVO> chunk) {
    return commonCodeClient.saveBatch(chunk);   // ✅ 엑셀 전용 batch INSERT
}

context.put("uploadId", "수정된값");   // ❌

private static final Set<String> ALLOWED_FIELDS = Set.of("code", "name", "use_yn");   // ❌