결재 관리 스펙

결재 관리는 Simple HR 프로젝트의 기업 관리자 영역 중 하나로, 경로 /admin/approvals에서 제공된다. 직원이 제출한 각종 신청서(근태, 휴가, 기안서 등)를 승인·반려하는 워크플로우를 담당한다. 근태 관리 스펙 및 휴가 관리 스펙과 밀접하게 연결된다. [fix-task-0604.md]

✅ 완료된 버그 수정

[fix-task-0604.md]

기업 사용자 신청결재 UI 개선

• 경로: /user/approval
• 개선 필요: 신청 결재 결재하기 사용자 인터페이스 개선 필요

[fix-task-0610.md]

GPS 기반 출근 승인 기능

[fix-task-0616.md]에 따르면, GPS 범위 검사 기능(checkGpsRadius)이 순수 함수로 추출되고 FE/BE 단위 테스트가 완료되었다. 다음 단계로 GPS 실패 시 출근 요청 → 관리자 승인 기능이 계획되어 있으며, 현재 계획은 완료되었으나 구현은 대기 중이다.

[fix-task-0616.md]

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

[fix-task-0624 (26년 06월 24일 수정사항)]에 따르면, 필수서류가 기존 EmployeeContract 방식에서 Document 결재 시스템으로 전환되었다:

• REQUIRED 양식 제출 시 Document 생성 → 결재선 승인 → 결재 관리에서 처리
• 승인 시 EmployeeDocument 자동 생성 side-effect 추가
• 관리자 발송(EmployeeContract) 경로에서 REQUIRED 카테고리 제외 (CONTRACT 포함 시 허용)
• 필수서류 목록에 Document 결재 상태 반영
• 서류 보관함에 doc_content/form_content 필드 추가 및 내용 보기 모달 제공
• 기존 데이터 영향: 이미 EmployeeContract로 생성된 REQUIRED 건은 기존 방식으로 승인 처리 후, 이후 건부터 Document로 전환

기안서 양식 목록 필터링 버그 수정

• 탄력근로제서면합의서(REQUIRED)가 기안서 목록에 노출되던 문제: 기안서 페이지에서 form_category: "OPTIONAL" 필터 적용으로 REQUIRED/CONTRACT 양식 분리 완료
• 서류신청 페이지도 form_category: "APPLICATION" 필터 적용

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

기안서 UI 개선

• 기안서 목록에서 CONTRACT 문서종류가 영문으로 노출되던 문제: DOC_TYPE_CONFIG에 CONTRACT 라벨 매핑 추가 ("계약")
• 양식 분류 OPTIONAL 라벨을 "양식"에서 "기안서"로 변경: 신청서(APPLICATION)와 구분 명확화

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

모바일 결재 페이지 개선

• 결재 상세 시트에서 v2 양식 JSON 대신 TemplatePreview 렌더링 지원
• 전체 문서 fetch(approvalApi.get) → form_id 기반 양식 스키마 로드 → TemplatePreview 렌더링
• 빈 values 양식(PASTE_UPLOAD 등)은 "입력된 내용이 없습니다." 안내 표시 (PC 동일)
• 카드 미리보기에서 JSON 대신 텍스트 값 추출 표시
• REQUIRED/CONTRACT 배지 한글화 ("필수서류"/"계약")
• 상세 시트 로딩 시 JSON 깜빡임 수정 (templateLoading 초기값 개선)

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

회사 양식 관리: 붙여넣기+첨부파일 동시 제출 방식 추가

• PASTE_UPLOAD 제출방식 추가: 붙여넣기 시 엑셀 자료 그대로 붙여지도록 수정
• 제출방식 전환 시 양식 내용 초기화 확인 팝업 추가

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

기안서 기준 재정립 (결재 유형 이원화)

[fix-task-0630 (26년 06월 30일 수정사항)]에 따라 결재 유형이 두 가지 기반으로 명확히 분리되었다:

• CHECKIN(출퇴근 요청): Document 기반이지만 사용자 근태 탭에 표시, 승인은 관리자 전용
• 공용 컴포넌트 approval-shared.tsx로 분리; 서류 관련 kind(application/required/draft)는 근태결재관리에서 제거

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

사용자 결재 페이지 근태/서류 탭 분리

• 근태 결재 탭: RequestApprovalStep 기반 휴가·연장근로 + CHECKIN Document 병합 표시
• 서류 결재 탭: CHECKIN 제외한 기안서·신청서·필수서류 표시
• 사용자용 근태 결재 API 신규 구현: GET /v2/approval-requests, PUT approve/reject (request_approval_service.py, 통합 테스트 3건)
• 출퇴근 요청 결재는 관리자 페이지 전용 — 사용자 페이지에서는 "관리자 페이지에서 처리" 안내 표시
• 탭 명칭 변경: 근태 → 근태 결재, 서류 → 서류 결재 (데스크톱 + 모바일(모바일 앱 스펙) 동일 적용)
• 뱃지 UI: 인라인 스타일 → Badge 컴포넌트 통일 (관리자 결재관리 페이지와 동일 색상 체계)
• 테이블 레이아웃: table-fixed + colgroup 비율 고정, 제목 외 컬럼 중앙 정렬

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

근태결재관리 출퇴근 요청 신청자 "-" 표시 버그 수정

• 원인: emp.get("name") 키 오류 → emp.get("employee_name")으로 수정

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

결재 시스템 확장 계획 (추후)

결재 승인 후 대기중 상태 잔존

• 승인 처리 후에도 결재 상태가 "대기중"으로 남아있는 경우가 보고됨.
• 재현 조건: 연장근로 신청 / 이상재 관리자의 사용자 페이지 / 유유정 직원의 신청 건.
• 원인 및 수정 방법 확인 필요. [fix-task-0713 (26년 07월 13일 수정사항)]

최고관리자 결재선 변경 미적용

• 최고관리자가 결재선을 변경했음에도 조직관리자에게 결재가 라우팅되는 문제. 변경이 저장되지 않거나 세션 캐시 미갱신 등 원인 조사 필요. [fix-task-0713 (26년 07월 13일 수정사항)]

[E2E 테스트 시나리오 - Part 3. 관리자↔사용자 연계 시나리오]에서 정의한 핵심 결재 연계 시나리오를 요약한다.

기안서/서류 결재 흐름 (시나리오 6)

기안서 반려 및 재제출

기안서 회수

보완 요청

사직서 결재 흐름 (시나리오 8)

사직서 결재 흐름은 사직서 처리 워크플로 스펙에서 상세 명세되며, 아래는 결재 처리 관점의 요약이다.

• 퇴사 처리 완료 시: Employee.employment_status = EMP_RETIRED, User.status = RESIGNED, 모든 세션 무효화
• 미래 퇴사일의 경우 스케줄러가 처리

[E2E 테스트 시나리오 - Part 3. 관리자↔사용자 연계 시나리오]

• 인사발령/사직처리 결재선 추가 (미완료): Document(DocumentApprovalStep) 기반으로 구현 예정
• 관리자: 등록 시 결재선 선택 가능 → 결재선 있으면 승인 후 반영, 없으면 즉시 처리
• 사용자 사직서(사직서 처리 워크플로 스펙): 결재선 있으면 따르고, 없으면 자동 승인
• 상세 설계: docs/fix_tasks/0630/approval-workflow-plan.md
• 결재 시스템 통합 (장기): RequestApprovalStep → DocumentApprovalStep 일원화
• 현재 이원화 상태(근태/서류)에서 통합 시 변경 범위 큼 (attendance_service, request_approval_service, 프론트 전체)

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

출퇴근 결재 라인 자동 생성 및 삭제 보호

[fix-task-0622.md]에서 다음 사항이 확인되었다:

• 기본 출퇴근 결재선 자동 생성: 서버 시작 시 checkin_approval_line_id가 NULL인 테넌트에 대해 기본 출퇴근 결재선이 자동으로 생성된다.
• 삭제 차단: 기본 출퇴근 결재선 삭제 시도 시 "기본 출퇴근 결재선은 삭제할 수 없습니다" 토스트 알림이 표시된다.

GPS 출근 요청 시 즉시 처리

GPS 이슈를 사유로 작성하여 출근하기를 누른 후 처리 흐름이 개선되었다:

• 이전 동작: 출퇴근 요청이 1차 결제자(팀장) 이상재에게 결재 라인으로 넘어갔다.
• 개선 사항: 출퇴근 요청 시 즉시 출근/퇴근 처리로 변경
• 대시보드가 "근무중"으로 즉시 전환
• 관리자 반려 시 GPS_REQUEST 기록 자동 취소

[fix-task-0622.md]

퇴근 시 GPS 위치 확인

[fix-task-0622.md]에 따르면, 퇴근 버튼 클릭 시 다음과 같이 처리된다:

• CheckInLocationSheet 다이얼로그 표시: 퇴근 시에도 GPS 확인
• 반경 판정:
• 반경 안이면 직접 퇴근 처리
• 밖이면 출퇴근 요청 폴백
• 동적 텍스트 표시: 다이얼로그 내부 "출근" 텍스트를 출근/퇴근 상황에 맞게 표시

[fix-task-0622.md]

수정 전 문제점: 항목 클릭 시 본문에 JSON이 그대로 노출되었으며, 신규 작성 시 토스트 알림이 표시되지 않고, 발급/승인 시 작성 모달이 흐릿하게 표시되었다. [fix-task-0604.md]

[fix-task-0622.md]

기업 사용자 측 신청결재 기능에서도 연관 수정이 이루어졌다.

• 기안서 신규 작성 시, 양식 선택 시 제목 자동 업데이트 적용
• 단, 사용자가 직접 입력한 제목은 유지 (자동 업데이트로 덮어쓰지 않음)

[fix-task-0604.md]

• 경로: 기업 사용자 근무관리 > 연장근로 현황
• 버그 수정: 연장근로 신청 후 신청 목록이 갱신되지 않는 문제 해결 (완료)

[fix-task-0604.md]

관리자(허빈)↔직원(김소민) 간 결재 연계 흐름의 E2E 시나리오는 E2E 테스트 시나리오 명세에서 확인할 수 있다. [E2E 테스트 시나리오 - Part 3. 관리자↔사용자 연계 시나리오]

• 근태 관리 스펙 — 결재 관리와 연계되는 근태 승인 흐름
• 휴가 관리 스펙 — 휴가 신청 결재 연동
• 근무 정책 스펙 — 연장근로 정책 설정
• 근로계약서 스펙 — 계약서 관련 발급/승인 연동
• 모바일 UI/UX 개선 작업 (기업 사용자) — 모바일 결재 관련 개선
• 액션 아이템 — 전체 수정 작업 목록
• 의사결정 로그 — 관련 의사결정 기록
• GPS 출퇴근 스펙 — GPS 기반 승인 기능
• 양식 편집기(폼 빌더) 스펙 — PASTE_UPLOAD 등 제출방식 및 양식 분류 관련
• 모바일 앱 스펙 — 모바일 결재 상세 시트 TemplatePreview 렌더링
• 근로계약서 스펙 — 필수서류 Document 결재 전환 연동
• fix-task-0630 (26년 06월 30일 수정사항) — 결재 유형 이원화, 사용자 탭 분리, 버그 수정 상세
• 사직서 처리 워크플로 스펙 — 사직서 결재선 연동 계획
• fix-task-0702 (26년 07월 02일 수정사항) — 서류 작성 명칭 변경, 결재선 초기화 버그 수정, 사직서 프로세스 확정
• fix-taskNew-0702 (26년 07월 02일 우선수정사항) — 근태결재 배지·목록 불일치, 신청결재 탭 명칭, 관리자 출퇴근 승인 기본값, 모바일 첨부파일, 문서 종류 선택 제거
• fix-taskNew-0706 (26년 07월 06일 우선수정사항) — 근태결재 결재선 선택 UI, 근태결재 배지 오류 수정, 드로어 본문 통일, 경조사 사유 선택, 제목 형식 통일, 위임 버튼 제거
• fix-task-0709 (26년 07월 09일 수정사항) — 기안서·서류 신청 탭 통합, 사직서 처리 Document 전환, 모바일 결재 한글화, EWP 단일 소스 전환
• E2E 테스트 시나리오 명세 — 결재 관리 전체 흐름의 통합 테스트 시나리오 명세- fix-task-0713 (26년 07월 13일 수정사항) — 결재 승인 후 대기중 상태 잔존, 최고관리자 결재선 변경 미적용 이슈
• fix-task-0715 수정사항 — 연장근로 직위 표시 버그, 근로정책 적용시점/이력 수정, 결재선 자동 적용 안내 추가, 계약서 불일치 수정, 교대근로·연차촉진·일정관리 미구현 이슈

✅ 연장근로 신청 직위 '-' 표시 버그 수정

관리자 결재 목록(/admin/approvals)에서 연장근로 신청의 직위가 "-"로 표시되는 문제가 수정되었다. OvertimeRequestInfo 스키마에 position_name 필드가 누락된 것이 원인으로, 백엔드 서비스는 정상 반환하지만 Pydantic response_model 직렬화 시 스키마에 없는 필드가 제거되었다. LeaveRequestInfo에는 해당 필드가 있으나 OvertimeRequestInfo에만 누락되어 있었으며, 필드 추가로 수정 완료. [fix-task-0715 수정사항]

✅ 근로정책 work_days OFF 요일 출근 차단 미구현 수정

_resolve_scheduled_for_day()에 work_days OFF 체크 추가 및 get_user_dashboard()에 주휴일 판정 추가로 출근 버튼 비활성화. OT_HOLIDAY 승인 시 출근 허용 흐름은 동일하게 유지. (커밋 0e9ac95) [fix-task-0715 수정사항]

✅ 근로정책 적용시점 반영 및 이력 덮어쓰기 수정

근무 정책 스펙 변경 시 기존 EWP 레코드를 UPDATE(reuse)하여 과거 이력이 소실되고, is_primary 즉시 플립으로 미래 예약 후 동기화 불일치가 발생하던 문제를 수정하였다.

• 이력 덮어쓰기 방지: 항상 신규 EWP INSERT, 기존 EWP는 effective_to 설정으로 종료
• 날짜 기반 활성 판정: is_primary 플립 대신 effective_from/to 날짜 범위 + ORDER BY effective_from DESC로 활성 정책 결정
• 미래 예약 시 기존 EWP 미수정: 적용일 도래 시 Read 쿼리가 자연 전환, 스케줄러(close_superseded_ewps)가 이전 EWP의 effective_to 자동 채움
• 적용시점 표시: EmployeeDetail 응답에 work_policy_effective_from, scheduled_work_policy_name, scheduled_work_policy_date 추가, 드로어에 표시
• 이력 모달: GET /employees/{id}/work-policy-history API + 프론트 변경이력 모달 (적용중/예약중/취소 배지)
• 배포 체크리스트: docs/fix_tasks/0715/report/deploy-checklist.md

[fix-task-0715 수정사항]

✅ 최고관리자 결재선 변경 미적용 (확인 완료)

결재선 미선택 시 조직도 기반 자동 결재선(본사 조직장=조직관리자)이 적용됨이 원인으로 확인되었다. 결재선 템플릿 수정과 자동 결재선은 별개 시스템이다. 결재선 드롭다운에 amber 색상 안내 텍스트를 추가하여 미선택 시 자동 결재선이 적용됨을 명시하도록 수정. [fix-task-0715 수정사항]

✅ 근로계약서 auto_renew / renewal_method 불일치 수정

근로계약서 스펙 관련: 계약 유형 옆 "자동연장" 텍스트가 auto_renew(boolean)를 기준으로 표시되어, renewal_method=MANUAL_RENEW인데 auto_renew=true인 데이터에서 잘못 표시되는 문제를 수정. 프론트엔드에서 c.auto_renew → c.renewal_method === "AUTO_RENEW" 조건으로 변경 (frontend/src/app/admin/employees/contracts/page.tsx). 운영 데이터 불일치 1건(박준혁, 도급직 시드)의 renewal_method를 AUTO_RENEW로 보정 완료. [fix-task-0715 수정사항]

✅ 도급직 계약 생성 시 auto_renew 기본값 수정

모든 계약 유형에서 auto_renew=False 기본값으로 통일. 관리자가 명시적으로 선택한 경우에만 자동연장 적용. backend/app/services/contract_service.py:627-629 — 도급직 자동연장 기본값 로직 제거. [fix-task-0715 수정사항]

✅ 관리자 등급 변경 미반영 (정상 동작 확인)

관리자 상세 드로어에서 등급 변경 후 저장 시 DB에 반영되고 목록에도 즉시 갱신됨을 확인. [fix-task-0715 수정사항]

✅ 계약형태 변경 (계약직↔정규직 전환)

계약직에서 정규직으로, 정규직에서 계약직으로 계약형태 변경이 가능하도록 수정. [fix-task-0715 수정사항]

⬜ 교대/변형근로 수동 배정 시 최소 연속 휴식 시간 검증 미구현

교대(변형)근로 관리 스펙 관련: 정책에 min_consecutive_rest_hours 값 저장·로드는 정상이며, 변형근무 자동배정(auto_assign_variant_shifts)에서는 rest_hours 검증이 구현되어 있다. 그러나 수동 셀 클릭 배정(assign_shift_roster, bulkCreate) 시 전일 퇴근~당일 출근 간격 검증이 없다.

• 예: 야간(18:00~06:00) 다음날 바로 주간(06:00~18:00) 수동 배정 시 휴식 0시간이지만 경고/차단 없음
• 수정 대상: backend/app/services/policy_service.py — assign_shift_roster() + 프론트 셀 배정(bulkCreate) 시 전일 퇴근~당일 출근 간격 검증 추가

[fix-task-0715 수정사항]

⬜ 교대근로 순환 패턴(cycle_pattern) 기반 자동 배정 미구현

cycle_pattern과 rotation_cycle_days 저장·로드는 정상이지만, 교대근무(SHIFT) 모드에서 패턴 기반 자동 순환 배정 로직이 없다. 현재 자동배정은 변형근무(VARIANT) 모드 전용이며, SHIFT 모드는 관리자가 수동으로 셀 배정해야 한다. 프론트에서 패턴 기반 법정한도 체크(주간시간 검증)는 구현됨. 백엔드 저장 시 패턴 유효성 재검증은 없음. [fix-task-0715 수정사항]

⬜ 연차촉진 threshold_days 변경 시 기존 대상자 미정리

연차촉진 스펙 관련: sync_promotion_targets()에서 threshold 미달 대상자 삭제 조건이 first_status == "PENDING" AND second_status == "PENDING"인 경우만 해당. 1차 알림 발송 완료(first_status = "NOTIFIED")된 대상자는 threshold를 올려도 목록에서 제거되지 않음.

• 수정 대상: backend/app/services/policy_service.py — sync_promotion_targets() 정리 조건에서 threshold 미달 시 알림 발송 여부와 무관하게 제거하거나, 최소한 목록 조회 시 현재 threshold 기준으로 필터링

[fix-task-0715 수정사항]

⬜ 연차촉진 설정값 미적용 (알림 채널/자동 실행/촉진 시기/응답 기한)

AnnualPromotionSetting의 first_notify_months_before, second_notify_months_before, first_notify_deadline_days, auto_schedule, use_email/use_push/use_kakao 값이 DB에 저장만 되고 실제 로직에 반영되지 않음. 현재 알림 발송은 인앱 알림(create_notification)만 생성하며, 채널 분기/자동 스케줄러/시기 판단/기한 초과 처리 없음. [fix-task-0715 수정사항]

⬜ 일정관리 반복 일정 미구현

recurrence_type(DAILY/WEEKLY/MONTHLY/YEARLY) 값은 DB에 저장되지만 반복 일정 확장(expand) 로직이 없어 부모 1건만 표시됨.

• 수정 대상: backend/app/services/calendar_service.py — list_events()에 반복 확장 로직 추가, create_event()에서 자식 이벤트 생성, update_event()에 scope 파라미터 추가

[fix-task-0715 수정사항]

⬜ 일정관리 알림 발송 미구현

reminder(10MIN/30MIN/1HOUR/1DAY) 값은 DB에 저장되지만 실제 알림 발송 로직이 없음. 백그라운드 스케줄러로 일정 시작 전 알림 시간에 push/브라우저/이메일 알림 발송 구현 필요. [fix-task-0715 수정사항]

⬜ 급여기초 간이세액 비율 선택 UI 미구현

급여관리 스펙 관련: 백엔드에 tax_rate_pct 컬럼(기본값 100)과 소득세 계산 시 비율 적용 로직은 구현되어 있으나, 프론트엔드 급여기초 페이지(/admin/payroll/base)의 "간이세액 (부양가족)" 영역에 80/100/120% 선택 UI가 없어 항상 100%로만 동작.

• 수정 대상: frontend/src/app/admin/payroll/base/page.tsx — 80/100/120% 선택 드롭다운 또는 라디오 추가, 저장 시 tax_rate_pct 값 전송

[fix-task-0715 수정사항]

⬜ 관리자 설정에서 별도 권한(인사, 급여) 항목 제거

관리자 등급 및 권한 관리 스펙 관련: 관리자 설정에서 별도 권한(인사, 급여) 항목 제거 예정. [fix-task-0715 수정사항]

시스템 확인: 회사 이미지 등록 깨짐 현상

이미지 업로드/저장 기능은 정상 구현됨. 깨짐 원인으로 서명 URL 만료(1시간) 가능성이 있음 — 페이지를 오래 띄워놓으면 이미지 URL이 만료되어 깨질 수 있음. 실제 재현 확인 필요. [fix-task-0715 수정사항]