Files
dbx-main/app/modules/vacation/CLAUDE.md
T

74 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# [휴가] 휴가 관리 모듈 — `app/modules/vacation/`, `vacation_db`
> 이 모듈만 고칠 때 읽는 요약. 별도 상세 문서 없음 — 코드가 기준.
> 정적 파일: `app/static/vacation.css`, `app/static/vacation.js`. 템플릿: `templates/`.
- 월간 달력(구글식 bar) / 연차·반차 신청 / 승인 워크플로 / 옵션(승인자·통보자·잔여 연차).
- **설정 화면 없음**(2026-10-27 삭제 — [설정] 버튼·공휴일 추가/삭제 기능 포함). `GET /vacation/settings` 는 옵션으로 넘김, 공휴일 저장 주소 없음.
- 권한키 `vacation`(사용)·`vacation_approver`(승인).
- **신청 화면**(2026-11-02, `form.html`) = 위 휴가 종류 라디오(고르면 검은 배경·흰 굵은 글씨) · 왼쪽 붙박이 달력(공용 `ErpDatePop.mountRange` — 팝업과 같은 `.pj-dp-*` 서식,
첫 클릭 시작일·둘째 클릭 종료일·셋째 새로, 하루 = 동그라미, 기간 = 둥근 막대, 반차 = 클릭마다 하루) · 오른쪽 시작일·종료일(읽기 전용, 달력이 채움)·구분·예상 일수·사유 · 아래 결재 라인.
하루짜리는 종료 구분을 숨기고 보내지 않는다(서버 compute_days 도 시작 구분만 씀). 시작일·종료일 숨긴 칸은 브라우저 필수 검사가 안 돼 `vacation.js` 가 제출 전 확인.
공휴일 = 국경일·대체공휴일(`router._red_holidays` → `db.holiday_map`, 작년~내년, `#vac-holidays`) — 달력 빨강·이름(10.5px, 달력 폭 380px 라야 "석가탄신일"이 안 잘림) + 예상 일수에서도 뺀다(서버 compute_days 와 같은 표).
옵션의 입사일 버튼은 그대로 `ErpDatePop.enhance`(팝업). 테스트 `tests/js/vacation_datepop.browser.test.js`(`render_vacation.py`).
## 협의자 결재 (2026-11-02, 마이그레이션 `vacation_db_003_consults.sql`)
- 흐름: 작성중 → (협의자 있으면) **협의중** → 모두 승인 → **제출**(결재자 승인 대기) → 승인. 협의자 한 명이 반려하면 신청도 반려(`approver_email` = 그 협의자). 수정·재제출하면 협의가 처음부터(`db.submit`).
협의중에는 결재자가 승인·반려 못 함(`approve`·`reject` 가 status='제출' 만). 일수·연차 차감은 그대로 승인 때만. 마지막 두 명 동시 처리는 `decide_consult` 가 신청 줄을 잠가 막음.
- 표 `vacation_consults`(신청 삭제 시 CASCADE) — 이메일·이름·협의 내용·상태 대기|승인|반려·반려 사유·처리 시각. 003 전이면 `consults_ready()` False → 협의자 칸 잠김, 예전처럼 제출.
- 신청 화면: [구성원 선택] = **ERP 등록 구성원 전체**(`router._people`, 휴가 권한 무관, 본인 제외) 아이콘 + 이름, 복수. 고른 사람마다 협의 내용 칸(`consult_email`·`consult_message` 같은 순서 — 빈 내용도 자리 유지).
[협의자 없음] 체크 = 칸 잠김·전송 안 함. 제출인데 둘 다 없으면 400(작성중 저장은 통과). 통보자·결재자 = 옵션 값, 아이콘 + 이름 표시만.
- 메일(`notify.py`): 제출 = 협의자마다 따로 한 통(자기 내용만, `consult_request`) + 결재자·통보자(전체 협의자·내용). 모두 승인 = `consulted`(결재자·통보자·신청자). 협의 반려 = `rejected`. 한 명 승인만으로는 메일 없음.
- 화면: 달력 위 [내 신청 내역] `/vacation/mine`(협의자별 상태 → 결재 상태), [협의 대기 N] → `/vacation/pending#consults`(이 화면은 이제 누구나, 승인 대기 표는 결재자만, 표에 협의 내용).
상세 = 결재 진행·협의자별 내용·협의 승인/반려. **보기 권한**: 신청자·결재자·통보자 = 전체, 협의자 = 자기 줄만(서버가 거름, 메일 기록도 안 보임).
- **휴가 권한 없는 협의자**: 사이드바에 휴가 메뉴가 없어 메일 링크로 상세(`_guard(consult_of=…)`)에 들어와 처리한다. 달력·내역·대기 화면은 권한이 있어야 함.
- 테스트 `tests/test_vacation_options_mail.py`(메일 내용·폼·권한), `tests/test_vacation_db.py`(실제 PG 흐름).
## 공휴일 · 연차 (2026-10-27)
- **쉬는 날 = 대한민국 국경일·대체공휴일 표만**(`db.holiday_map` 한 곳 — 달력·날짜 팝업·일수 계산 `red_holiday_set` 모두).
표는 프로젝트 모듈 `app/modules/project/store.py` `KR_HOLIDAYS`(2026~2030, **새 연도는 그 표에 추가**). 공휴일 설정 화면은 없앴고
`vacation_holidays` 표(예전 seed·직접 넣은 줄)는 남아 있지만 읽지 않는다. 예전엔 그 표만 써서 seed 가 없는 해·제헌절은 근무일로 셌다.
이미 저장된 신청의 일수는 그대로(새로 저장·수정할 때 다시 계산).
- 메인 달력: 공휴일 이름이 **날짜 숫자 아래**(`.vac-hol-name`), 그 주는 `.vac-week.has-hol`(휴가 막대 top 38 → 54px).
- **연차 = 입사일 기준, 12/31 소멸 없음**(2026-10-27 — 그 전 판의 "그해 1/1~12/31, 12/31 소멸"은 근로기준법보다 짧아 없앴다).
`store.leave_grants`(연차마다 생긴 날·쓸 수 있는 마지막 날) · `leave_period`(입사일/기념일 ~ 다음 기념일 전날) · `leave_status` 한 곳:
· 입사 1년 미만 = 입사일 + 1~11개월마다 1일, **입사일부터 1년(첫 기념일 전날)까지** 사용(제60조 ②·⑦ 단서)
· 근속 n년이 되는 날 = `min(25, 15 + (n−1)//2)`일, **그날부터 1년(다음 기념일 전날)까지**(제60조 ①④⑦). 출근율은 모두 채운 것으로 본다.
· 쓴 연차 = 승인된 `DEDUCT_TYPES`(연차·오전반차·오후반차)만(`db.usage_events` → 날짜별 1·0.5, `store.usage_units` = compute_days 규칙,
병가·경조·대체휴무·기타·제출·작성중은 안 뺌, 앞날짜 승인도 차감). 쓴 날마다 그날 쓸 수 있는 연차 중 **먼저 소멸하는 것부터** 빼고,
생기기 전에 쓰면 다음 연차를 당겨 씀(지금 잔여가 음수).
· 화면 = 지금 연차 기간·이번 기간에 생기는 연차(오늘까지 +앞으로)·이번 기간 쓴 날·**오늘 쓸 수 있는 잔여**·먼저 소멸할 잔여(날짜·일수).
달력 위 내 연차 줄도 같은 값(`db.balance_summary(as_of=오늘)`, 보고 있는 달력의 해와 무관). `db.used_days(연도)` 는 참고용 합계만.
- **잔여 연차 등록 = 옵션**(옵션 수정 권한자만 보기·저장) — 참여자(휴가 모듈 사용자) 전원을 아이콘·이름·이메일과 함께 미리 보여 주는 표
(예전에 등록됐지만 권한이 없는 사람도 아래에), 오늘 기준 하나(해 이동 없음). `POST /vacation/options/balances` 한꺼번에(`db.save_balances`).
## 입사일 · 직접 입력 · 시스템 전 사용 (2026-10-27, 마이그레이션 `vacation_db_002_hire_prior.sql`)
- 옵션 잔여 연차 표 **이름 옆 입사일** = 날짜 버튼(`ErpDatePop.enhance`, « » 1년씩·직접 입력 2020-03-02 Enter, 지우기) → `vacation_employees`(사람마다 하나).
입사일을 고르면 화면(vacation.js)이 같은 규칙으로 근속·연차 기간·생기는 연차를 바로 다시 보여 주고, 사용·잔여·소멸은 "저장 후"(서버가 휴가를 연차마다 나눠 계산).
- **직접 입력** = 그 사람의 **지금 연차 기간** 연차를 법정 대신 그 값으로(비우면 법정) — `vacation_balances` 의 **그 기간이 시작한 해** 줄
`total_days`(`db.override_year`, 저장 때 바꾼 입사일로 서버가 계산). 입사일 없이 직접 입력만 있으면 그해 연차로 셈(소멸일 없음 — 입사일을 넣어야 계산).
- **시스템 전 사용**(`prior_used`) — 이 시스템을 쓰기 전(2026)에 이미 쓴 연차, `SYSTEM_START_YEAR`(2026) 줄에. 도입일 `SYSTEM_START_DATE`(2026-10-27)에 쓴 것으로
쳐서 그날 쓸 수 있는 연차에서 뺀다. 표 칸은 도입 다음 해까지(또는 값이 남아 있으면).
- 저장 줄마다 email·hire·total·prior·memo(칸 수가 다르면 400, 한 줄이라도 틀리면 전부 안 함). 002 전이면 입사일·시스템 전 사용은 무시(입사일 칸은 숨김 칸, 안내 문구).
## 휴가 옵션 · 휴가 메일 (2026-10-27, 마이그레이션 `vacation_db_001_options_mail.sql`)
- **옵션** `/vacation/options`(달력 위 [옵션], 누구나 보기): 휴가 승인자(여러 명) · 휴가 승인 통보자 · 잔여 연차.
**수정 = ERP 관리자(수퍼관리자 포함) + 지금 승인자(옵션 지정, 없으면 휴가 승인 권한자) + 승인 통보자**(`router._can_edit_options` 한 곳, 2026-10-27 — 예전엔 관리자만).
`vacation_options` 키 `approval` = `{"approvers": [...], "notifiers": [...]}`(`db.get_options`·`save_options`, 휴가 모듈 사용자만 고를 수 있음).
- **승인·반려 권한**(`router._is_approver`) = ERP 관리자 + 옵션 승인자(지정했으면 그 사람만), 승인자를 비우면 예전처럼 `vacation_approver` 권한자.
승인 대기 버튼·상세 조회·`_require_approver` 모두 이 한 곳.
- **메일**(`notify.py`, 응답 뒤 BackgroundTasks — 실패해도 휴가 처리는 그대로): 제출 = 승인자 + 통보자, 승인·반려 = 승인자 + 통보자 + 신청자
(승인자 미지정이면 `vacation_approver` 칩을 켠 사람 — 관리자는 자동으로 안 넣음, 중복 한 번). 제목 `[휴가 승인] 이름 · 종류 기간 (N일)`,
본문 표 + [휴가 신청 보기] 링크(`PUBLIC_BASE_URL`). 사유·반려 사유는 escape.
- **보내는 사람 = 그 일을 한 사람 본인 Gmail**(제출 = 신청자, 승인·반려 = 처리한 승인자) — **입출고와 같은 Gmail 연결**(inout_db `inout_gmail_tokens`,
gmail.send 만, 한 사람 = 연결 하나). 옵션 화면 [Gmail 연결] → `/vacation/gmail/connect`(세션 `_gmail_origin=vacation`) → 구글 →
**입출고 콜백 `/inout/gmail/callback` 이 휴가 권한으로 처리**(`inout.router._gmail_callback_vacation` — 구글 클라우드 리디렉션 주소 추가 없음) → 옵션으로.
연결이 없거나 끊김·Gmail 실패면 회사 SMTP(`app/mail.py`, 보낸 사람 이름 = "이름 (DBX ERP)"·Reply-To = 그 사람). 끊긴 토큰은 지움.
- **기록** `vacation_mail_log`(이벤트·보낸 사람·gmail|smtp·받는 사람·제목·성공·오류, 본문·토큰은 안 남김) → 상세 화면 "메일" 줄.
- 001 미적용이면 옵션 없음(예전 권한 규칙)·저장 503·기록 없음, 메일은 그대로 나감. 화면 `.erp-page:has(> .vac)` border-box(셸 오른쪽 48px 넘침).
- 테스트 `tests/test_vacation_options_mail.py`(규칙·내용·Gmail→SMTP·실제 앱 권한·콜백 분기), `tests/test_vacation_db.py`(실제 PG, `VACATION_TEST_DB_URL`).