[cowtree28]

개요

엑셀 일괄 등록에서 인적사항이 없는 대상자의 행을 실패시키던 것을, humans를 만들어 연결하도록 바꾼다.

Closes #81

왜 필요했나

#35부터 행마다 (성명, 생년월일)으로 humans를 찾는데 없으면 실패였다. 그래서 개별 등록으로 사람을 한 명씩 먼저 만들어 두지 않은 엑셀은 통째로 올라가지 않았다. 300행을 올리면 300행이 다 실패한다 — 일괄 등록의 목적과 정반대다.

#35의 판단 자체는 맞다("연결 없이 저장하면 조회·발급·수정에서 어디에도 안 보인다"). 빠진 건 연결할 humans를 만들어 주는 것이었다.

가능했던 이유

엑셀 필수 매핑 필드가 humans의 NOT NULL 컬럼과 정확히 일치한다.

REQUIRED_TARGET_FIELDS	HumanEntity NOT NULL
name	name
birthDate	birthDate
gender	gender

추가 입력 없이 만들 수 있다. birthDate가 필수인 이유도 주석에 이미 "humans 매칭 키"로 적혀 있었다.

변경 내용

1. 없으면 만든다. 파일 안에서 (성명, 생년월일)당 한 번만 조회·생성하고 같은 사람의 다른 행은 캐시를 재사용한다. 한 사람의 전보 이력이 여러 행에 걸치는 게 정상이라 이게 중요하다.

2. address를 선택 매핑 필드로 추가. humans.address는 증명서 서식의 주소 칸에 인쇄된다. 매핑이 없으면 자동 생성된 사람의 주소가 비어 공란으로 찍힌다. 열이 있으면 쓸 수 있게 열어 뒀다.

3. 응답에 createdHumanCount 추가.

{ "saved": true, "insertedCount": 300, "createdHumanCount": 42, "failedRows": [] }

정한 기준

이미 있는 인적사항은 엑셀 값으로 덮어쓰지 않는다. 엑셀 성별이 humans와 달라도 humans를 따른다 — 검수된 데이터가 우선이고, 개별 등록(CertificateService.create)과 같은 기준이다. 테스트로 고정했다.

humans.department는 채우지 않는다. 사람당 한 개라 기간별 부서를 표현할 수 없고, 재직 이력의 부서는 certificate.department가 따로 갖는다 (§1-2).

주소가 없으면 null로 둔다. 틀린 주소를 공문서에 인쇄하는 것보다 공란이 낫다.

⚠️ 남는 한계 — 리뷰어가 봐야 할 지점

1. 성명 오타 한 글자가 별개 인물을 만든다. 식별 키가 (성명, 생년월일)뿐이다. "홍길동"을 "홍길돈"으로 치면 새 사람이 생긴다. 되돌리려면 수동 삭제인데 #64에서 연결 데이터가 있으면 삭제를 막아 뒀으니 번거롭다. createdHumanCount를 내려주는 이유가 이것이다 — 담당자가 "42명이 새로 생겼다"를 보고 이상하면 확인할 수 있게.

2. 동명이인이 같은 생년월일이면 한 사람으로 합쳐진다. uk_humans_name_birth_date에서 오는 기존 한계이고 이번 변경으로 생기지도 없어지지도 않는다. 다만 자동 생성은 검수를 거치지 않으므로 노출이 커진다. 한 사람의 경력이 남의 증명서에 찍히는 결과라 가볍지 않다. 근본 해결은 식별자(주민번호 뒷자리 등) 도입이고 별도 논의가 필요하다.

3. 동시 확정 경합. 같은 사람이 든 엑셀을 두 담당자가 동시에 확정하면 유니크 제약 위반으로 트랜잭션이 깨진다. 창구 운영에서는 발생하지 않는다고 보고 재시도를 넣지 않았다 — ponytail: 태그로 남겼다.

선택지였던 것

업로드마다 "없는 사람 만들기" 스위치를 요청에 받는 방법도 있다. 담당자가 끌 수 있어 안전하지만 FE에 체크박스가 하나 늘고, 요청은 "그냥 다 저장되게"였으므로 무조건 생성으로 갔다. 필요하면 플래그로 바꾸기 쉽다.

테스트

MappingConfirmServiceTest에 5개 추가/교체. 전체 129개 통과.

• 없는 대상자는 만들어 연결한다 (기존 "실패로 돌려준다" 테스트를 새 동작으로 교체)
• 같은 사람이 여러 행에 있어도 한 번만 만든다 (조회·저장 각 1회 검증)
• 이미 있는 인적사항은 덮어쓰지 않는다
• 주소 열을 매핑하면 주소가 들어간다
• 주소 열이 없으면 null로 둔다

FE 변경

• MappingConfirmResponse에 createdHumanCount 추가 (additive)
• 매핑 화면 대상 필드 목록에 address(주소) 노출 — 주소는 증명서에 인쇄되므로 열이 있으면 매핑을 권해야 한다
• "인적사항이 등록되지 않은 대상자입니다" 실패 사유가 더 이상 발생하지 않는다

Summary by CodeRabbit

• New Features
  • Excel imports now create and link a person record when a valid row has no matching record, instead of marking the row as failed. Repeated rows for the same name and birth date reuse the created record.
  • The import response reports how many person records were created.
  • Address can be mapped from the spreadsheet for newly created records. If no address is mapped, it remains blank. Existing person details are not overwritten by spreadsheet values.

[coderabbitai]

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 6baa4c22-2c66-4929-a0d1-dffa046276bf

📥 Commits

Reviewing files that changed from the base of the PR and between b10649f and 16cb060.

📒 Files selected for processing (5)

• docs/certificate-domain.md
• src/main/java/commonly/commonlybe/file/controller/dto/MappingConfirmResponse.java
• src/main/java/commonly/commonlybe/file/excel/ColumnMappingTable.java
• src/main/java/commonly/commonlybe/file/service/MappingConfirmService.java
• src/test/java/commonly/commonlybe/file/service/MappingConfirmServiceTest.java

 _____________________________
< Here comes the bug bouncer. >
 -----------------------------
  \
   \   (\__/)
       (•ㅅ•)
       / 　 づ

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}