HBHR202_직원 추가
(Hereby) HR 급여 관리 > 시트 워크스페이스 > 급여대장 시트 > 행 추가
| 앱 | HR 급여 관리 (hr-system, 포트 4000) |
| 대상 사용자 | 조건1 [HR_ADMIN] / 조건2 [SUPER_ADMIN] |
| 프로토타입 | TBU |
| 관련 정책 | [[POL_급여정본경계]] |
| Status | review |
| Owner | 카나 |
| 부모 | [[HBHR200_급여대장 시트]] |
개요
- 급여대장 시트 툴바의 ➕ 직원 추가(진입 버튼명 유지)를 클릭하면 "행 추가" 모달이 열린다. 모달 제목은 "행 추가", 안내 문구는 "한 명을 골라 추가하거나, 팀 단위(하위 팀 포함)·조건으로 여러 명을 한 번에 추가합니다."(#906 변경).
- 시트 행은 새로운 직원 마스터를 생성하는 것이 아니라, 기존 employee를 참조하는 행(
sheet_rows.employeeIdFK → employees)을 만든다. - 모달은 조건 필터 탭(전체 직원 / 부서·팀 / 이번 달 생일자 / 입사 기념일 / 입사 100일)으로 후보를 좁히고, "{n}명 후보" 카운트와 "전체 선택 · 전체 해제", 직원 리스트(사번 / 이름 / 소속)를 제공한다. 한 명 또는 여러 명을 선택해 한 번에 추가한다.
- 직원 마스터의 SoT는 Admin(직원 마스터)이며, 급여대장 시트는 그 employee를 참조해 급여 작업 행을 얹는 구조다. 시스템 컬럼(#/사번/성명/팀/직급)은 이 참조로 read-only 채워진다. 추가된 행은
sheet_rows.source가 manual(기본값)이 되며, 확정 전까지는 작업공간 행이다 ([[POL_급여정본경계]]).
문서 히스토리
| 날짜 | 작성자 | 팀 | 변경 내용 |
|---|---|---|---|
| 2026-07-06 | 카나 | PM | 최초 작성 |
| 2026-07-10 | 카나 | PM | 라이브 기능 검토 반영 (행 추가 모달 개편) |
| 2026-07-13 | 카나 | PM | 버튼 행동 명세 보강 |
| 2026-07-21 | 카나 | PM | GC700 깊이 재작성 |
| 2026-07-21 | 카나 | PM | 가독성 패스 + 액션 표기 (GUIDE §7·§8) |
| 2026-07-21 | 카나 | PM | 셀 스타일 확정판 적용 (콸 승인) |
| 2026-10-01 | 카나 | PM | 「부서 · 팀」 탭 팀 트리(깊이 들여쓰기)·「하위 팀 포함」(기본 켬)·요약 줄·팀 선택 시 추가 가능 직원 자동 선택(b1efbb85, #906) + 팀 이름 검색·「대상」 필터(재직/휴직/퇴직·급여 미지급 대상 포함, 기본 재직만)·후보 상태 라벨(f5004c9c, #958) + 검색어 변경 시 선택 유지·「(검색 밖 N명 포함)」(3b3aa15d, #963) 반영, 신규 입사자 시트 자동 추가(#903/#908) 교차 참조 — 커밋 근거, 라이브 실사 이월(TBU) |
| 2026-10-02 | 카나 | PM | 행 추가 시 아래쪽 빈 행부터 채움·푸터 안내 「아래쪽 빈 행 N개부터 채워요」(5521c70b, #975) · 설정 중에도 「직원 추가」 노출(7170d1a6, #978) — 커밋 근거, #978 라이브 실사 확인(10/2), #975 라이브 실사 이월(TBU) |
Data I/O
Client → Server
| 액션 | 전달 값 | tRPC procedure | 권한 토큰 |
|---|---|---|---|
| 직원(행) 추가 | sheetViewId, employeeId[] | sdk.payrollSheet.addRows() (추정) — 팀 탭도 기존 batchCreate로 삽입(부분 성공 규칙 동일) | payroll:write (추정) |
| 팀 후보 조회 | teamId, 하위 팀 포함 여부, statuses(기본 재직), includePayrollExcluded(기본 false) | sdk.sheetRow.teamMemberCandidates() — 활성 소속 전부(겸직 1회) · 이미 행 있음 · 입사일 가드 표시 | TBU |
Server side 효과 (행 생성)
| 대상 | 효과 | 비고 |
|---|---|---|
sheet_rows.sheetViewId (FK) | 대상 급여대장 시트에 행 추가 | |
sheet_rows.employeeId (FK → employees) | 선택 직원 마스터 참조 | 시트 행 = employee 참조 |
sheet_rows.source | manual (기본값) | 수동 추가 행 |
sheet_rows.sortOrder | 행 순번 부여 |
화면 플로우 (행 추가 동선)
직원 마스터 생성이 아니라 참조. 급여 계산/확정은 [[HBHR200_급여대장 시트]]/[[HBHR201_전체 확정 (commit)]]에서.
행 추가 모달 사양표
| 번호 | 항목/기능명 | 타입 | 사양 및 기능 설명 | 연관/영향 범위 | 비고 |
|---|---|---|---|---|---|
| 00 | 노출 조건 | - | • 급여대장 시트 툴바 "➕ 직원 추가" 클릭 → "행 추가" 모달 노출 (진입 버튼명 유지) • 시트가 설정 중이어도 「직원 추가」 버튼 노출·동작 (설정 중 툴바엔 안내 "설정 중엔 급여반영이 불가합니다." + 「설정 완료」가 함께 보임 — 반영 버튼만 숨김) - 행 추가는 구조 변경이 아니라 서버 구조 게이트(assertSheetStructureEditable) 대상 아님 | [[HBHR200_급여대장 시트]] · HBHR100 ㄴ64C(같은 #978 — 툴바 쪽 정본) | 진입 버튼명 "직원 추가" · 설정 중 노출 (코드 반영: 7170d1a6, #978, MED-843 · 라이브 실사 확인(10/2)) · 이전엔 설정 중 버튼 숨김 |
| 01 | 초기 상태 | - | 기본 탭 "전체 직원" 활성, 후보 리스트 전 직원. 미선택 상태 = 추가 버튼 disabled(추정) | ||
| 10 | 타이틀 | Text | "행 추가" (원문) | ||
| 11 | 안내 문구 | Text | "한 명을 골라 추가하거나, 조건으로 여러 명을 한 번에 추가합니다." (원문) | ||
| 15 | 대상 필터 | Checkbox | • 모든 탭 공통으로 후보를 재직 상태·급여 대상 여부로 거름. 라벨 "대상": "재직" / "휴직" / "퇴직" 체크 + "급여 미지급 대상 포함" 체크 • 기본: 재직만 · 급여 미지급 제외 (모달을 열 때마다 기본으로 복귀) - CASE01 [마지막 남은 상태 체크]: 끌 수 없음 - 퇴직 = TERMINATED·INACTIVE 모두 포함 | 20 조건 필터 · 50 직원 리스트 | 신설 (코드 반영: f5004c9c, #958, MED-833) · 이전엔 퇴직·휴직 직원도 후보에 섞임 |
| 20 | 조건 필터 탭 | Tab | • 탭 조건으로 후보를 좁히는 기능. 탭: "전체 직원" / "부서 · 팀" / "이번 달 생일자" / "입사 기념일" / "입사 100일" • 클릭 시: 해당 조건으로 후보 필터 - CASE01 [탭 전환]: 후보 리스트·카운트 재산출 | Admin 직원 마스터 (employees) · 30 후보 카운트 | 조건별 후보 산출 |
| ㄴ21 | 부서 · 팀 — 팀 트리 | Tree | • 전체 팀을 트리(깊이 들여쓰기, 최상위 = 조직 아이콘)로 표시. 부모가 비활성이면 최상위로. 겸직 직원은 어느 팀에서도 후보로 나옴 • 팀 클릭 → 서버 후보 조회 → 추가 가능한 직원 전부 자동 선택 - "하위 팀 포함" 체크(기본 켬): 하위 팀 직원까지 후보 - 요약 줄: "{N}명 중 추가 가능 {n}명 · 이미 있음 {n} · 입사 전 {n}" (조회 중 "불러오는 중…") - 이미 시트에 있는 직원·그 달 이후 입사자는 목록에서 빼고 요약 건수로만 표시 | sdk.sheetRow.teamMemberCandidates() · team_members.isActive · teams.parentTeamId | 신설 (코드 반영: b1efbb85, #906) · 이전엔 대표 팀 하나로만 거른 평면 목록 · 팀 목록 조회 실패 시 종전 대표 팀 목록으로 폴백 |
| ㄴ21-E | 팀 트리 Empty | Text | • 팀 0건: "등록된 팀이 없습니다." • 팀 미선택: "위 목록에서 팀을 고르면 그 팀 직원이 모두 선택돼요." • 팀 직원이 전부 이미 있음/입사 전: "이 팀 직원은 모두 시트에 있거나 입사 전이에요." | 코드 반영: b1efbb85, #906 | |
| ㄴ22 | 팀 이름 검색 | Input | • 팀 트리 위 검색칸(placeholder "팀 이름으로 검색") • 입력 → 이름 부분 일치 팀 + 그 상위 팀만 남김(들여쓰기 유지) - -E [일치 없음]: "검색어와 맞는 팀이 없어요." | ㄴ21 팀 트리 | 신설 (코드 반영: f5004c9c, #958) |
| 30 | 후보 카운트 | Text | • 선택 조건 기준 후보 수를 "{n}명 후보"로 표기하는 기능. 조건 결과 0명 시 "0명 후보" | 20 조건 필터 | |
| 40 | 전체 선택 · 전체 해제 | Button | • 후보 리스트를 일괄 선택/해제하는 기능 ("전체 선택 · 전체 해제") • 클릭 시: 지금 보이는 목록(검색 적용)만 선택 또는 해제 — 검색 밖 선택은 그대로 유지 - 필터 탭·팀 변경 시 선택 비움(종전 동작) | 50 직원 리스트 | 보이는 목록 한정 (코드 반영: 3b3aa15d, #963) |
| 50 | 직원 리스트 | List | • 후보 직원을 골라 선택하는 기능. 항목 = 사번 / 이름 / 소속. 시트 행 = employee 참조 • 클릭 시: 해당 직원 선택/해제 (한 명 또는 여러 명) | Admin 직원 마스터 (employees) | 마스터 생성 아님 |
| ㄴ51 | 후보 상태 라벨 | Label | • 성명 옆 라벨: "휴직"(노랑) / "퇴직"(회색) / "급여 미지급"(빨강) — 대상 필터(15)로 포함한 경우 | 15 대상 필터 | 신설 (코드 반영: f5004c9c, #958) |
| ㄴ52 | 검색 중 선택 유지 | Rule | • 이름·사번 검색은 보이는 목록만 거름. 검색어를 바꿔 가며 고른 직원도 모두 추가됨(제출 = 후보 풀 ∩ 선택) • 대상 필터로 풀에서 빠진 직원은 선택 표에 남아도 세지 않고 추가하지 않음 | 60 행 추가 · 61 선택 카운트 | 수정 (코드 반영: 3b3aa15d, #963, MED-836) · 이전엔 마지막 검색 결과에 남은 직원만 추가돼 「N명 선택됨」과 실제 추가 인원 불일치 |
| 50-E | Empty (후보 0) | Text | • 조건 결과 0명 시 "일치하는 직원이 없습니다." (팀 탭은 ㄴ21-E 문구) | 원문 (b1efbb85 diff 확인) | |
| 60 | 행 추가 | Button | • 선택 직원(들)로 sheet_rows 행을 생성하는 기능 (source=manual) • 클릭 시: 즉시 실행 → 시트 맨 아래에서부터 이어지는 빈 행(아래쪽 빈 행)이 있으면 그 행부터 위에서 순서대로 선택 직원으로 채우고, 빈 행이 모자랄 때만 남은 직원을 맨 끝 새 행으로 생성 - 빈 행 = 직원 미연결 수동 행 중 보호·병합·메모 없고 모든 입력 열 값이 빈 행 (「수정 › 아래쪽 빈 행 삭제」와 같은 판정). 표 가운데 끼인 빈 행은 건드리지 않음 - 서버가 DB로 빈 행 여부를 다시 확인 — 이미 직원·값이 있으면 채우지 않고 새 행 생성 - CASE01 [미선택]: 무반응/비활성(추정) - CASE02 [아래쪽 빈 행 없음]: 종전처럼 맨 끝에 새 행 | sheet_rows.employeeId FK · sheetRow.batchCreate(fillRowIds → 결과 created/filled/skipped) | payroll:write (추정) · 빈 행 우선 채움 (코드 반영: 5521c70b, #975, MED-841) · 이전엔 빈 행을 그대로 두고 그 아래 맨 끝에 붙음 |
| 61 | 선택 카운트 | Text | • 하단 "{N}명 선택됨" + 버튼 "행 추가 ({N}명)"(2명 이상). N = 선택 ∩ 후보 풀 - CASE01 [검색에 가려진 선택 있음]: "(검색 밖 {n}명 포함)" 추가 표시(0명이면 숨김) - CASE02 [N=0]: "행 추가" 비활성 - CASE03 [선택 1명 이상 + 아래쪽 빈 행 있음]: "· 아래쪽 빈 행 {k}개부터 채워요" 추가 표시 (k = min(아래쪽 빈 행 수, 선택 수)). 저장 전 화면 전용 빈 자리 행은 세지 않음 | 60 행 추가 | 코드 반영: 3b3aa15d, #963 · CASE03 (코드 반영: 5521c70b, #975) |
| 70 | 시스템 컬럼 채움 | Output | • 추가 직후 #/사번/성명/팀/직급이 employee 참조로 read-only 자동 채움 | employees | |
| 80 | 값 없음 처리 | - | • 추가 직후 급여 항목 컬럼은 빈 셀/미계산 (추정) | TBU: 급여 항목 컬럼 초기값/필드 상세 |
관계: 시트 행 ↔ Admin 직원 마스터
| 계층 | 역할 | 정본성 |
|---|---|---|
| Admin 직원 마스터 (employees) | 직원 기본 정보 SoT (사번/성명/팀/직급) | 직원 마스터 정본 |
| 급여대장 시트 행 (sheet_rows) | employee를 참조하는 급여 작업 행 | 작업공간 (참조) |
시트에서 직원을 추가/제거해도 employee 마스터 자체는 변하지 않는다(참조 관계). 시스템 컬럼은 마스터가 SoT이므로 시트에서 read-only.
권한·상태 분기 요약
| 시나리오 | 트리거 | 결과 | 비고 |
|---|---|---|---|
CASE01 [직원 추가] | ➕ → 직원 선택 → 행 추가 | sheet_rows 행 생성 (employeeId 참조) | payroll:write (추정) |
CASE02 [시스템 컬럼] | 추가 직후 | 사번/성명/팀/직급 read-only 채움 | employee가 SoT |
CASE03 [후보 0명] | 조건 필터 결과 없음 | 빈 리스트, 추가 불가 | |
CASE04 [신규 입사자 자동 추가] | 조직 설정 「신규 입사자 시트 자동 추가」 켬 + 직원 등록 | 직원 기준 수동 시트(이번 달 이후·상시, 잠김·작업 완료·자동 채움 규칙 시트 제외)에 manual 행 자동 삽입(이미 있으면 건너뜀, 입사일 가드 동일) | [[HBAD270_설정 (조직 설정·내 정보)]] ㄴ33 · [[HBAD201_직원 추가·수정 모달]] ㄴ90-1·2 (#903/#908) |
Open Question
- 추가 시 급여 항목 컬럼 초기값/필드 상세 = TBU
- 미등록 직원(마스터 부재) 추가 가능 여부 및 마스터 생성 동선 = TBU
- 확정 후 행 제거 제약 (정본 record와의 관계) = TBU
미선택 상태 추가 버튼 disabled 여부 및 후보 0명 Empty 문구→ 해소(커밋 근거: 선택 0이면 비활성, 문구 50-E·ㄴ21-E) — 라이브 확인 대기- 대상 필터(15)가 급여대장 외 직원 기준 시트 전체 공통인지 = 코드상 공통 모달(bulk-add) — 라이브 확인 대기