근로계약서 스펙

근로계약서 스펙은 Simple HR 프로젝트 내 직원 등록, 계약 관리, 승인 흐름에서 발생한 다양한 문제를 해결하기 위해 정의된 기능 명세입니다. 핵심 변경 사항은 계약서 작성 시 직원 유형의 정확한 반영, 날인 및 승인 프로세스의 명확화, 계약연장 시작일·종료일의 자동 동기화, 그리고 관리자 승인 상태에 따른 출근 가능 여부 제어입니다.

회사 직인 미등록 시 서명/제출 불가

회사 직인이 우선으로 등록되어 있어야만 근로계약서 서명과 제출이 가능합니다. 직인 등록 전에는 서명 버튼이 비활성화되어야 합니다. [fix-task-0623 (26년 06월 23일 수정사항)]

계약서 보기 시 잘못된 서류 노출

근로계약서 날인 후 보기/다운로드를 클릭하면 탄력근로제 서면 합의서가 표시되는 오류가 발생했습니다. 원인은 나의 정보 화면에서 가장 최근에 발송된 서류를 표시하는 로직이 있어, 최근에 발송된 탄력근로제 서면 합의서가 근로계약서 이름으로 노출되는 버그였습니다. 완료 상태: 최근 날짜의 근로계약서만 필터링되도록 수정 완료. [fix-task-0623 (26년 06월 23일 수정사항)] [fix-task-0624 (26년 06월 24일 수정사항)]

직인 이미지 대신 경로 텍스트 표시

근로계약서 미리보기/출력에서 직인이 이미지가 아닌 URL 경로 텍스트로 표시되는 버그가 발생했습니다. 완료 상태: 직인 이미지 정상 표시로 수정 완료. [fix-task-0623 (26년 06월 23일 수정사항)]

관리자 페이지에서 서명 이미지 미노출

서명 받은 계약서를 관리자 페이지에서 보면 서명된 이미지가 표시되지 않는 문제가 발생했습니다. 완료 상태: 서명 이미지 정상 노출로 수정 완료. [fix-task-0623 (26년 06월 23일 수정사항)]

최고관리자 등록 실패

관리자 관리 > 관리자 등록에서 최고관리자를 선택하여 등록할 때 등록이 되지 않는 문제가 발생했습니다.

원인: Bootstrap 시점에 admin_role_id만 최고관리자로 설정되고 admin_level은 3(부서장)으로 방치되어 레벨 불일치로 권한 체크 실패.

수정 사항:

• _get_actor_admin_level() 함수에서 is_system=True이면 1 반환 처리
• Bootstrap 데이터 동기화
• 에러 코드별 토스트 메시지 추가 [fix-task-0623 (26년 06월 23일 수정사항)]

배포 전 조치: 프로드 DB 데이터 보정 필요 (is_system=True 역할인데 admin_level!=1인 직원 2건)

계약직 신규 생성 시 서식 오류

이상기로 가입된 계정이 근로계약서 작성 후 날인, 출퇴근이 안 되는 문제와 새로 생성된 계약서가 계약직으로 생성했지만 정규직 근로계약서 양식이 나오는 문제가 발생했습니다. [fix-task-0623 (26년 06월 23일 수정사항)] [fix-task-0624 (26년 06월 24일 수정사항)]

완료 상태: contract_type 기반 양식 자동 매핑(_resolve_form_id_by_contract_type) 추가, 관리자 미리보기에서도 contract_type에 맞는 양식으로 폴백, per_employee 서브쿼리에 CONTRACT 카테고리 필터 적용(REQUIRED 계약이 max를 점유해 CONTRACT 계약 누락되던 버그 수정). [fix-task-0624 (26년 06월 24일 수정사항)]

관련 수정: 계약형태별 양식 자동 선택 참고

과거 입사자의 Hard 근로계약 강제

계약시작일과 입사일만 비교하여 Hard 판정하여 과거 입사자도 Hard로 출퇴근이 차단되는 문제가 발생했습니다.

원인: 계약 시작 시점 확인 로직 부재로 과거 계약도 즉시 적용 처리.

수정 사항: Hard 판정 시 contract_start >= today 조건 추가. 과거 입사/계약자는 soft(안내만)로 처리 변경. [fix-task-0623 (26년 06월 23일 수정사항)]

계약 차수 구분 불명확

직원에게 발송된 근로계약서 1, 2, 3차 중 어떤 것이 신규이고 어떤 것이 연장 또는 수정인지 구분할 수 없었으며, 계약서들 간 관계(동일 계약의 상이한 버전인지 여부)가 명확하지 않았습니다.

계약서 편집 시 자동 생성 버그

근로계약서의 계약정보를 편집 후 저장하면 의도하지 않게 새로운 계약이 생성되는 문제가 발생했습니다.

기존 근무 일정 미복원 문제

휴가 승인 시 기존 ShiftSchedule 행이 삭제되고 VACATION 항목으로 삽입되었으나, 휴가를 취소할 때 원래의 스케줄이 자동으로 복원되지 않았습니다.

부서 정책 배정의 불편성

직원 등록 시 근로정책을 선택한 후, 추후에 부서별 근로 정책을 설정하려면 소속 직원의 근로정책을 부서처럼 맞추기 위해 수동으로 모두 변경해야 하는 불편함이 있었습니다.

직인 표시 불일치

근로계약서 관리자 목록에서 미리보기 시 항상 현재의 직인을 표시하여, 계약 당시와 현재 등록된 직인이 다르면 이전 계약서도 바뀌는 버그가 발생했습니다.

계약서 내 템플릿 변수 미지원

양식 편집기(WysiwygTemplateEditor)에서 표 내 변수를 적용하려 할 때 정상 작동하지 않았습니다.

1. 계약 차수 및 유형 명확화

계약서 목록 차수 컬럼에 신규/연장 여부를 표시합니다:

• 신규 계약: parent_contract_id 없음 — "신규" 또는 차수 없음으로 표시
• 계약 연장: parent_contract_id 있음 — "수동 연장" 표시, 부모 계약과 연결 표시
• 자동 갱신: 계약 만료 시 자동으로 새 계약 생성 — "자동 갱신" 표시

용어 명확화:

• "계약연장" → "수동 연장" (명시적 액션)
• "계약연장방식" → "갱신 방식" (자동/수동 선택)

2. 계약서 편집 드로어 저장 버그 수정

• 편집 저장 시: 새로운 계약이 의도하지 않게 생성되는 현상 제거
• 저장 완료 후: 드로어가 자동으로 닫히지 않고 수정된 데이터로 즉시 갱신 표시
• 사용자가 변경 사항을 확인한 후 수동으로 닫을 수 있음

3. 필수서류 발송 시 EmployeeContract 동시 생성

필수서류(근로계약서 등) 발송 시 자동으로 EmployeeContract 레코드를 생성하여 계약 상태를 추적합니다.

상태 흐름:

• DRAFT → PENDING_SIGN (발송) → PENDING_APPROVAL (직원 서명) → ACTIVE (관리자 승인)

[fix-task-0623 (26년 06월 23일 수정사항)]

4. 계약 승인 시 Override.sent_at 초기화

계약 승인(ACTIVE) 상태 전환 시 Override.sent_at을 초기화하여 재계약 차단을 방지합니다. 배포 후 프로드 DB 데이터 보정이 필요합니다(승인 완료됐는데 Override.sent_at이 남아있는 4건). [fix-task-0623 (26년 06월 23일 수정사항)]

5. 계약형태별 양식 자동 선택

근로계약서 생성 시 직원의 계약 유형에 따라 자동으로 적절한 양식을 선택합니다:

• 계약직 → 계약직 근로계약서
• 파견직 → 파견근로계약서
• 정규직 → 정규직 근로계약서

신규 계약 생성 시 계약 유형을 명시적으로 확인하고 해당 양식을 자동 선택하도록 처리. _resolve_form_id_by_contract_type 함수를 통해 매핑하며, 관리자 미리보기에서도 동일 로직으로 폴백합니다. [fix-task-0623 (26년 06월 23일 수정사항)] [fix-task-0624 (26년 06월 24일 수정사항)]

6. 근로계약서 직인 미리보기 정확화

관리자 계약서 목록의 미리보기에서 다음 우선순위로 직인 표시:

1. 1.context_snapshot.company_seal (관리자 발송 서명 시 저장)
2. 2.context.company_seal (직원 자체 서명 시 저장)
3. 3.previewContext (현재 등록된 직인)

이전에는 항상 previewContext(현재 직인)를 사용하여 직인 교체 시 이전 계약서도 바뀌는 버그 발생 → 수정 완료. [fix-task-0623 (26년 06월 23일 수정사항)]

7. 계약서 내 표 변수 지원

양식 편집기(WysiwygTemplateEditor)에서 표을 포함한 모든 요소에 변수를 적용:

• 표은 HTML 형식(<table>)으로 저장
• 표 내 각 셀에 {{key}} 형식의 변수 칩 삽입 가능
• parseBlocks 및 markdownToHtml 함수에 HTML 표 파싱 로직 추가
• 기존 GFM(|) 형식의 표도 계속 지원

⚠️ 주의: 표을 HTML로 저장하므로, 이전 세션 코드로 롤백 시 표이 텍스트로 깨질 수 있습니다. 다만 parseBlocks와 markdownToHtml이 GFM과 HTML 양쪽을 모두 파싱하므로 기존 GFM 데이터는 정상 표시됩니다.

8. 관리자 양식 편집 통합

모든 양식 편집 화면(admin/settings/forms)에서 동일한 TemplateBuilder 사용:

• PASTE 유형: 관리자가 HTML/텍스트 템플릿 직접 입력
• PASTE_UPLOAD 유형: 붙여넣기(엑셀 자료 포함)와 첨부파일 동시 제출 가능 — 제출방식 추가. [fix-task-0624 (26년 06월 24일 수정사항)]
• 템플릿 유형: 변수와 표 기반 빌더 사용
• 직원이 기안서·서류 신청 시 관리자가 설정한 템플릿이 에디터에 미리 채워져 표시됨
• 제출방식 전환 시 양식 내용 초기화 확인 팝업 추가. [fix-task-0624 (26년 06월 24일 수정사항)]

분기 조건: isPaste = submission_type === "PASTE" && !parseTemplateSchema(form.content)

• v2 JSON 스키마가 없으면 HTML 에디터, 있으면 변수 템플릿으로 처리

9. 필수서류(REQUIRED) Document 결재 시스템 전환

REQUIRED 양식 제출 시 기존 EmployeeContract 생성 방식에서 Document 결재 시스템으로 전환합니다. [fix-task-0624 (26년 06월 24일 수정사항)]

• REQUIRED 양식 제출 → Document 생성 → 결재선 승인 → 결재 관리에서 처리
• 승인 시 EmployeeDocument 자동 생성 side-effect 추가
• 관리자 발송(EmployeeContract) 경로에서 REQUIRED 카테고리 제외 (CONTRACT 포함 시 허용)
• 필수서류 목록에 Document 결재 상태 반영
• 서류 보관함에 doc_content/form_content 필드 추가 + 내용 보기 모달

기존 데이터 영향: 이미 EmployeeContract로 생성된 REQUIRED 건은 기존 방식으로 승인 처리 후, 이후 건부터 Document로 전환.

10. 기안서 양식 목록 필터링

탄력근로제 서면합의서(REQUIRED)가 기안서 목록에 노출되던 문제를 수정합니다. [fix-task-0624 (26년 06월 24일 수정사항)]

• 기안서 페이지: form_category: "OPTIONAL" 필터 적용으로 REQUIRED/CONTRACT 양식 분리
• 서류신청 페이지: form_category: "APPLICATION" 필터 적용
• 기안서 목록 문서종류 CONTRACT 라벨 영문 → "계약" 한글 표시 (DOC_TYPE_CONFIG 매핑 추가)
• 양식 분류 OPTIONAL 라벨 "양식" → "기안서" 변경 (신청서(APPLICATION)와 구분)

배포 전 프로드 DB에서 다음 항목을 확인하고 보정합니다:

• 직원 등록 플로우 — 근로계약서 작성 시점과 활성화 스위치 연계
• 결재 관리 스펙 — 계약서 승인 워크플로우 (필수서류 Document 결재 전환 포함)
• 근태 관리 스펙 — 계약 상태와 출근 가능 여부의 연계
• 직원 재직 상태 변경 워크플로 — 직원 활성화/비활성화 상태 관리
• 근무 정책 스펙 — 계약 기간과 근무 정책의 연계
• 휴가 관리 스펙 — 휴가 승인 시 근무 일정 관리
• 교대(변형)근로 관리 스펙 — 근무 스케줄 및 휴가 처리
• 양식 편집기(폼 빌더) 스펙 — 계약서 템플릿 빌더 (PASTE_UPLOAD 유형 포함)
• 직인(회사 인감) 관리 스펙 — 직인 관리 및 날인 프로세스
• 관리자 등급 및 권한 관리 스펙 — 승인 권한 관리
• 휴일 관리 스펙 — 휴일 지정 시 근로계약 및 급여 반영
• 액션 아이템 — 전체 수정 작업 목록
• fix-task-0624 — 6월 24일 수정사항 원문 소스