현재 사용법 (2026-09-10, 6fbaee7f): 연차사용촉진 · 기능 마스터. 아래는 작성 당시의 변경 설명이며 현재 전체 동작·재측정 결과를 뜻하지 않습니다.

연차 사용촉진 QA 후속 — Sign 미연동 무반응 픽스 · 발송 내역 범위 안내

PR: fix(admin): surface sign errors in leave promotion and mark send history batch-only 원 티켓: 2026-09-03 자동 QA 2건 (발송 내역에 개별 통지 미표시 · Sign 미연동 조직 무반응)

전자서명(hereby Sign)이 연동되지 않은 조직의 관리자가 연차현황에서 「개별 통지」·「일괄 통지」 버튼을 누르면 아무 반응이 없던 것을, 연동이 필요하다는 오류 다이얼로그가 뜨도록 바꿉니다. 또한 「발송 내역」 모달 상단에 이 목록이 일괄 통지 작업 전용이라는 안내 문구를 추가합니다.

배경 — 연차 사용촉진 화면의 지금 동작

연차 사용촉진은 admin의 근태 현황 → 연차 → 연차현황 그리드에서 시작하는 기능입니다. 미사용 연차가 있는 직원에게 촉진 안내를 보내고, hereby Sign(외부 전자서명 서비스)에 서명 요청을 생성합니다. 발송 경로는 두 가지입니다.

• 개별 통지 — 그리드 행의 촉진 액션 버튼입니다. firstNotice 프로시저가 해당 직원 1명의 촉진 레코드와 Sign 서명 요청을 즉시 생성합니다.
• 일괄 통지 — 필터 줄의 버튼입니다. batchCreate 프로시저가 발송 작업 레코드(batch)를 만들고, 배치 잡이 대상 직원들에게 순차 발송하며 성공/실패/중지/제외 건수를 집계합니다.

「발송 내역」 모달은 batchList로 이 batch 목록만 조회하는 화면입니다. 진행 중 작업의 중지·실패 건 재시도 버튼도 batch 단위로 동작합니다. 개별 통지는 batch를 만들지 않으므로 이 목록에 나타나지 않는 것이 설계이며, 개별 건의 진행 상태는 그리드의 "촉진 상태" 열이 정본입니다. 그러나 화면 어디에도 이 구분이 안내되지 않아, 개별 통지를 보낸 뒤 발송 내역을 열면 "발송 내역이 없어요."만 보여 발송이 실패한 것으로 오인할 수 있었습니다.

한편 두 통지 버튼은 모두 통지 모달을 여는 openAnnualLeavePromotion 함수를 지나는데, 이 함수는 모달을 열기 전에 Sign 서식 목록(templates())을 서버에서 가져옵니다. hereby Sign은 조직별 크리덴셜(ExternalIntegrationCredential)로 연동되는 외부 서비스라서, 미연동 조직에서는 이 조회가 서버 오류를 던집니다.

변경 1 — Sign 미연동 오류를 화면에 노출합니다

openAnnualLeavePromotion의 templates() 호출에 try/catch가 없어, 미연동 조직에서 던져진 오류가 Alpine의 클릭 핸들러 표현식 밖으로 빠져나가 콘솔에만 기록되고 화면에는 아무것도 표시되지 않았습니다.

변경 전

변경 후

적용한 변경은 세 갈래입니다.

• apps/admin/src/app.ts의 openAnnualLeavePromotion에서 서식 조회를 try/catch로 감싸 실패 시 showError 다이얼로그를 띄우고 모달을 열지 않습니다. 개별·일괄·다시 발송 세 진입점이 모두 이 함수를 지나므로 한 곳의 수정으로 전부 해결됩니다.
• 다시 발송 경로(reissueAnnualLeavePromotion)는 모달을 연 뒤 재발급 대상 id를 기록하는데, 모달이 열리지 않았으면 기록하지 않도록 가드를 추가합니다.
• 서버 packages/api/src/services/integration-credential.service.ts의 미연동 오류가 영문 메시지("Hereby Open API credential not configured for this organization")를 INTERNAL_SERVER_ERROR로 던지고 있었습니다. 이 저장소에서 TRPCError의 message는 화면에 그대로 노출되는 UI 문구이므로 한글 해요체("전자서명(hereby Sign) 연동이 설정되지 않은 조직이에요. 연동 설정 후 이용할 수 있어요.")로 바꾸고, 서버 장애가 아닌 사전조건 미충족이므로 코드도 PRECONDITION_FAILED로 바꿉니다. 이 헬퍼는 전자서명 메뉴 등 Sign 연동 전 경로가 공유하므로 그 화면들의 오류 문구도 함께 개선됩니다. 메시지·코드에 의존하는 분기와 테스트가 없음을 확인했습니다.

버튼을 사전에 비활성화하고 툴팁으로 안내하는 대안은 연차 탭 진입 시마다 연동 상태 조회를 추가로 요구하므로 이번에는 채택하지 않았습니다. 필요 시 eSign.integrationHealth 프리페치를 얹는 후속 작업으로 가능합니다.

변경 2 — 발송 내역이 일괄 전용임을 안내합니다

개별 통지 건을 발송 내역 드롭다운에 합치는 방안은 채택하지 않았습니다. 이 모달의 집계 요약·중지·실패 건 재시도가 전부 batch 모델에 결합되어 있어, 개별 건을 섞으려면 패널 구조 전체를 바꿔야 하기 때문입니다. 대신 모달 본문 최상단에 정보 안내(notice)를 추가합니다: "일괄 통지 작업의 진행·결과를 보여드려요. 개별 통지 결과는 연차현황의 촉진 상태와 촉진 액션에서 확인할 수 있어요."

변경 3 — 정본 스펙(HBAD251) 동기화

화면 정본 스펙 docs/spec/HBAD/HBAD251.md에 두 변경을 반영합니다. 통지 모달 노출 조건에 미연동 조직의 오류 다이얼로그 CASE를 추가하고, 발송 내역 패널 사양표에 범위 안내 행(01)을 추가해 "개별 통지가 목록에 나타나지 않는 것이 정상"임을 명문화합니다.