tk-factory-services/.cowork/sprints/sprint-004/PLAN.md

Sprint 004: 월간 근무 비교·확인·정산

작성: Cowork | 초안: 2026-03-30 | 갱신: 2026-03-31 (출근부 양식 반영)

목표

1. 작업보고서 vs 근태관리 비교 페이지: 그룹장이 입력한 작업보고서와 근태관리 데이터를 일별로 비교하여 불일치를 시각화
2. 월말 확인 프로세스: 작업자가 자신의 월간 근무 내역을 확인(승인/반려)하는 워크플로우
3. 출근부 엑셀 다운로드: 전원 확인 완료 시, 업로드된 양식에 맞는 출근부 엑셀 내보내기
4. 연차 잔액 연동: sp_vacation_balances 기반 신규/사용/잔여 데이터 엑셀 포함

현재 구현 상태 (2026-03-31)

항목	파일	상태	비고
DB 마이그레이션	api/db/migrations/20260330_create_monthly_work_confirmations.sql	✅ 완료
모델	api/models/monthlyComparisonModel.js (232줄)	✅ 완료	getExportData 추가됨
컨트롤러	api/controllers/monthlyComparisonController.js (560줄)	✅ 완료	exportExcel 출근부 양식 재작성
라우트	api/routes/monthlyComparisonRoutes.js (33줄)	✅ 완료
라우트 등록	api/routes.js 157줄	✅ 완료
프론트엔드 HTML	web/pages/attendance/monthly-comparison.html	✅ 완료
프론트엔드 JS	web/js/monthly-comparison.js (558줄)	✅ 완료
프론트엔드 CSS	web/css/monthly-comparison.css	✅ 완료
대시보드 연동	web/js/production-dashboard.js	✅ 완료	PAGE_ICONS 추가

모든 파일이 존재하고 라우트가 등록되어 있으나, 실 서버 배포 및 통합 테스트 미완료.

배경

• monthly.html에서 그룹장이 등록한 근태정보를 각 작업자가 개별 확인·승인
• 전원 confirmed 완료 시 지원팀이 출근부 엑셀 다운로드 가능
• 출근부 양식: 업로드된 출근부_2026.02_TK 생산팀.xlsx 기준
• attendanceService.js에서 연차 자동 차감/복원이 이미 구현되어 있으므로 sp_vacation_balances가 소스 오브 트루스

아키텍처

┌──────────────────────────────────────────────────────┐
│  monthly.html (그룹장 → 근태 입력)                    │
│       ↓                                              │
│  daily_attendance_records 저장                        │
│  attendanceService.js → sp_vacation_balances 자동 반영 │
└─────────────────┬────────────────────────────────────┘
                  ↓
┌──────────────────────────────────────────────────────┐
│  monthly-comparison.html                              │
│                                                      │
│  [작업자 뷰]                        [관리자 뷰]       │
│   ├ 작업보고서 vs 근태 일별 비교     ├ 전체 확인 현황   │
│   ├ 요약 카드 (근무일/시간/연장/휴가) ├ 개별 작업자 상세 │
│   └ 확인(승인) / 반려(사유 입력)     └ 엑셀 다운로드   │
│        ↓ (반려 시)                                   │
│  notifications → 지원팀에 알림                        │
│        ↓ (전원 확인 완료 시)                           │
│  출근부 엑셀 다운로드                                 │
│  (출근부_YYYY.MM_부서명.xlsx)                          │
└──────────────────────────────────────────────────────┘

출근부 엑셀 양식 (신규)

기존 2-시트 구조(월간 근무 현황 + 일별 상세)를 출근부 단일 시트로 변경.

시트명: {YY}.{M}월 출근부

Row 2: 부서명 | [부서명 (병합)]
Row 3: 근로기간 | [YYYY년 M월 (병합)]
Row 4: [이름] [담당]  1  2  3 ... 31  [총시간]  [M월(병합)]  [비고(병합)]
Row 5:              일 월 화 ...       [      ]  신규 사용 잔여
Row 6+: 김두수  1   0  0  0 ... 휴무  =SUM()   15  2  =AF-AG

셀 값 규칙:
  정상출근 → 근무시간(숫자, 0.00)
  주말(근무없음) → '휴무'
  연차(ANNUAL) → '연차'
  반차(HALF_ANNUAL) → '반차'
  반반차(ANNUAL_QUARTER) → '반반차'
  조퇴(EARLY_LEAVE) → '조퇴'
  병가(SICK) → '병가'
  경조사(SPECIAL) → '경조사'

스타일:
  폰트: 맑은 고딕 12pt, 가운데 정렬
  주말 헤더: 빨간 폰트 (FFFF0000)
  테두리: thin 전체
  헤더 행 높이: 40, 데이터 행 높이: 60
  수식: 총시간=SUM(날짜열), 잔여=신규-사용

API 엔드포인트

Method	Path	접근권한	설명
GET	/api/monthly-comparison/my-records	인증된 사용자	내 일별 비교 데이터
GET	/api/monthly-comparison/records	support_team+ 또는 본인	특정 작업자 비교 조회
POST	/api/monthly-comparison/confirm	인증된 사용자 (본인)	승인/반려
GET	/api/monthly-comparison/all-status	support_team+	전체 확인 현황
GET	/api/monthly-comparison/export	support_team+	출근부 엑셀 다운로드

데이터 소스

데이터	테이블	비고
작업보고서	daily_work_reports	report_date, work_hours, project_id
근태 기록	daily_attendance_records	record_date, total_work_hours, vacation_type_id
확인 상태	monthly_work_confirmations	신규 테이블 (Sprint 004)
연차 잔액	sp_vacation_balances	year별 SUM(total_days, used_days)
휴가 유형	vacation_types	type_code → 출근부 텍스트 매핑
작업자 정보	workers + departments	worker_id 순 정렬

작업 분할

섹션	핵심 작업	규모
A (Backend)	모델·컨트롤러 검증 + 출근부 엑셀 엣지케이스 + 배포	파일 4개, 검증 위주
B (Frontend)	UI 최종 검증 + 모바일 반응형 + 캐시 버스팅 + 배포	파일 4개, 검증 위주

기존 코드가 모두 구현되어 있으므로 검증·배포 중심으로 진행.

섹션 간 의존성

A ──(API 제공)──→ B

  GET  /api/monthly-comparison/my-records
  POST /api/monthly-comparison/confirm
  GET  /api/monthly-comparison/all-status
  GET  /api/monthly-comparison/records
  GET  /api/monthly-comparison/export

Section A 배포 완료 후 Section B 프론트엔드가 정상 동작 가능.

완료 조건

• 마이그레이션 파일 생성 (20260330_create_monthly_work_confirmations.sql)
• 모든 Backend 파일 생성 (model, controller, routes)
• routes.js에 라우트 등록
• 프론트엔드 페이지 생성 (HTML, JS, CSS)
• 대시보드 아이콘 매핑 추가
• 출근부 양식 엑셀 재작성 (getExportData + exportExcel)
• 실 서버 마이그레이션 실행
• Docker 빌드·배포
• 통합 테스트 (작업자 확인 → 지원팀 엑셀 다운로드 전체 플로우)
• 모바일 반응형 확인
• 엣지케이스 확인 (데이터 없는 월, 중도 입사자 등)

주요 변경 이력

날짜	변경 내용
2026-03-30	초안 작성 + Section A/B 코드 구현
2026-03-31	출근부 양식 반영: getExcelData→getExportData, exportExcel 전면 재작성
2026-03-31	버그 수정: export 조건에 rejected 추가, admin detail 모드 버튼 숨김
2026-04-01	워크플로우 확장: pending→review_sent→confirmed/change_request/rejected 상태 추가
2026-04-01	정책 변경: 확인요청 발송 전 전원 admin_checked 필수 (선택적→필수)