Files

T

king 269e779129 feat(vacation): 휴가 관리 모듈 — 월간 달력 bar/연차·반차 신청/승인 워크플로/공휴일·연차 설정

- vacation_db 전용 저장소(VacationDBStore), VACATION_DB_URL 미설정 시 '설정 필요' 안내
- 월간 달력: 구글식 휴가 bar(주 단위 lane 배정), 일/공휴일 빨강·토요일 파랑
- 신청 폼: 종류/기간/시작·종료 구분(종일/오전/오후)/사유 + 예상 일수 미리보기
- 일수 계산은 서버(compute_days)에서 주말+공휴일(is_red) 제외 재계산
- 워크플로: 작성중/반려→제출→승인|반려, 취소 soft delete, 본인만 수정(작성중/반려)
- 권한: vacation(접근)/vacation_approver(승인), admin 통과. 설정은 admin 전용
- 공휴일(vacation_holidays) DB 기반 provider + settings CRUD, 연차잔여(vacation_balances)
- 엑셀 내보내기(openpyxl), scripts/sql/vacation_db_init.sql(멱등, 2026 공휴일 seed)
- main.py 등록, 메뉴 ready 전환, docs/.env.example/CLAUDE.md 갱신

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-05-30 08:20:20 +09:00

4.5 KiB

Raw Permalink Blame History

Project Overview

한 줄 정의

main-app은 DBX ERP 시스템의 메인 프로젝트(허브) 이다. 주문 수집부터 상품코드 매칭, 재고, CS, 반품, 외부 쇼핑몰 API 연동까지 ERP 운영 전체를 담당한다.

기능 범위

모듈	설명
주문관리	다채널 주문 수집·통합, 상태 추적, 분석
상품코드 매칭	채널별 상품코드 ↔ 사내 표준 상품코드 매핑, 단품/세트 구성
재고관리	입고/출고/재고 조정, 채널별 재고 동기화
CS관리	문의/응대 이력, 발주 업무 트리거
반품관리	반품/교환 접수, 처리, 환불 연계
외부 연동	쇼핑몰·통합관리·택배사·문자 API 연동
개인경비	법인카드/개인지출 등록·증빙·정산 신청 (`app/modules/expense/`) — 결재 워크플로 / 첨부(영수증·기타) / 월별 집계 / 엑셀 내보내기
쿠팡 밀크런	쿠팡 출고 일정 관리 (`app/modules/cupang/`) — 월간 달력 / 출고 묶음(헤더+라인) / 박스 입수량 자동계산 / 입고센터 관리 / 엑셀 내보내기. 상품은 `itemcode_db` 읽기 전용 참조
휴가 (준비중)	연차/반차/특별휴가 신청·잔여일수 관리

권한 키 (`MODULE_KEYS`)

키	종류	설명
`corm` / `order`	접근	외부 모듈 진입
`expense` / `vacation` / `cupang`	접근	내부 모듈 진입
`expense_approver`	결재	개인경비 승인/반려/정산
`vacation_approver`	결재	휴가 승인/반려 (모듈 미개발)

admin 역할은 모든 권한 자동 부여. 신규 사용자는 관리자 페이지(/admin)에서 이메일만으로 등록 가능.

모듈 디렉토리 규약

신규 업무 모듈은 별도 디렉토리 한 곳에 라우터·저장소·템플릿을 모은다.

app/modules/<name>/
├─ __init__.py        # router export
├─ router.py          # FastAPI APIRouter (prefix=/<name>)
├─ store.py           # 데이터 저장소 (JSON → 향후 <name>_db)
└─ templates/<name>/  # Jinja 템플릿 (ChoiceLoader 로 검색)

신규 모듈 등록 시 app/main.py 의:

_MODULE_TEMPLATE_DIRS 에 템플릿 경로 추가
app.include_router(<name>_router) 추가
app.state.<name>_store = ... 등 상태 등록
MODULE_KEYS (app/store.py) 와 _menu_items_for() 메뉴 항목 동기화

외부 연동 대상

쇼핑몰: 카페24, 네이버 스마트스토어
통합 관리: 사방넷
물류: CJ대한통운(CJ Logistics) 외 택배사 API
알림: 문자 발송 API
인증: Google OAuth (Google Workspace 계정 기반)

기술 스택

영역	사용 기술
Backend	Python, FastAPI
DB	PostgreSQL (Docker 컨테이너)
컨테이너	Docker, Docker Compose
Reverse Proxy	Nginx Proxy Manager (NPM)
OS	Ubuntu Server (Proxmox VM)
인증	Google OAuth + 화이트리스트
저장소	Gitea (self-hosted)

DB명	용도
`itemcode_db`	상품코드, 단품/세트 구성, 매칭 정보
`orderlist_db`	주문 수집·분석·관리 (구 `orderlist_app`)
`return_db`	반품·교환·CS 데이터
`expense_db`	개인경비 / 법인카드 / 정산 (`EXPENSE_DB_URL` 미설정 시 JSON 폴백)
`cupang_db`	쿠팡 밀크런 출고/입고센터/박스규칙 (`CUPANG_DB_URL` 필수, JSON 폴백 없음)
`vacation_db`	휴가 신청/공휴일/연차잔여 (`VACATION_DB_URL` 필수, JSON 폴백 없음)

접속/도메인

환경	주소
운영	`https://dbx.no1king.freeddns.org`
로컬	`http://localhost:8080`
Git 저장소	`https://gitea.no1king.freeddns.org/king/dbx-main.git`

허용 사용자 (서버 측 화이트리스트)

app/main.py의 ALLOWED_EMAILS에서 검사한다.

Google hd=dbxcorp.co.kr 힌트는 클라이언트 편의용이며, 실제 권한 검사는 항상 서버 측에서 수행한다.

작업 우선순위 / 원칙

운영 데이터 안전이 최우선. 위험 명령은 사용자 승인 후 실행.
신규 기능보다 기존 데이터 일관성 유지 우선.
외부 API 연동은 실패 재시도와 로깅을 기본으로 한다.
비밀값은 .env로만 관리하고 Git에 절대 올리지 않는다.

4.5 KiB Raw Permalink Blame History