# Project Overview ## 한 줄 정의 `main-app`은 DBX ERP 시스템의 **메인 프로젝트(허브)** 이다. 주문 수집부터 상품코드 매칭, 재고, CS, 반품, 외부 쇼핑몰 API 연동까지 ERP 운영 전체를 담당한다. --- ## 기능 범위 | 모듈 | 설명 | | --- | --- | | 주문관리 | 다채널 주문 수집·통합, 상태 추적, 분석 | | 상품코드 매칭 | 채널별 상품코드 ↔ 사내 표준 상품코드 매핑, 단품/세트 구성 | | 재고관리 | 입고/출고/재고 조정, 채널별 재고 동기화 | | CS관리 | 문의/응대 이력, 발주 업무 트리거 | | 반품관리 | 반품/교환 접수, 처리, 환불 연계 | | 외부 연동 | 쇼핑몰·통합관리·택배사·문자 API 연동 | | 개인경비 | 법인카드/개인지출 등록·증빙·정산 신청 (`app/modules/expense/`) — 결재 워크플로 / 첨부(영수증·기타) / 월별 집계 / 엑셀 내보내기 | | 쿠팡 밀크런 | 쿠팡 출고 일정 관리 (`app/modules/cupang/`) — 월간 달력 / 출고 묶음(헤더+라인) / 상자 입수량 자동계산 / 로켓 매출 관리 / 엑셀 내보내기. 상품은 `itemcode_db` 읽기 전용 참조 | | 휴가 (준비중) | 연차/반차/특별휴가 신청·잔여일수 관리 | | 말레이시아 재고 | 말레이시아 창고 재고관리 (`app/modules/malaysia/`) — 낱개 입출고/조정, 세트 BOM, 일일 재고조사(세트 분해 자동 반영), 현재고 현황. 상품명은 `itemcode_db` 읽기 전용 참조 | | 입출고 관리 | 본사 → 공장 제품 제작 발주, 물류 입고(여러 번 나눠), 발주 대비 미입고·초과 입고 관리 (`app/modules/inout/`, `inout_db`) — 발주 담당·입고 담당·공장은 모듈 옵션에서 지정, 제품은 `itemcode_db` 단품 읽기 전용. `docs/INOUT_MODULE.md` | | 긴급 공지 | 수퍼관리자가 정한 시각에 전체/고른 사람의 ERP 화면 정가운데에 띄우는 공지(`app/modules/notice/`, project_db 024) — [확인] 전까지 다시 뜸, 확인 현황. `docs/NOTICE_MODULE.md` | | 실적 | 쇼핑몰 통합 매출 (`app/modules/performance/`) — 쇼핑몰별 어댑터로 수집 → `performance_db` 저장 → 일자×쇼핑몰 표·KPI·월/연 누적·그래프. 수수료율 이력, API 인증정보는 설정 화면 입력 + AES-256-GCM 암호화 저장. 1단계는 모의 데이터·구조까지(실제 API 는 쇼핑몰별로 순차 연동). `docs/PERFORMANCE_MODULE.md` | ### 권한 키 (`MODULE_KEYS`) 자산관리: `app/modules/asset/`, `/asset/`, `asset_db` — 사무집기·전산장비 개별 등록, 배정/반납/상태·구매/보증·활동 이력, HWiNFO XML 사양/보고서 보존. 상세 `docs/ASSET_MODULE.md`. 사진 갤러리, 보고서 모니터 자산 개요·등록·연결, 수퍼 관리자 삭제(이력/원본 보존)를 제공한다. | 키 | 종류 | 설명 | | --- | --- | --- | | `corm` / `order` | 접근 | 외부 모듈 진입 | | `expense` / `vacation` / `cupang` / `malaysia` / `performance` | 접근 | 내부 모듈 진입 (`performance` 설정 화면·API 는 추가로 `admin` 필요) | | `expense_approver` | 결재 | 개인경비 승인/반려/정산 | | `asset` | 접근 | 자산관리 조회·등록·수정·배정·반납·보고서 | | `inout` | 접근 | 입출고 관리 조회. 발주·입고 입력은 모듈 옵션의 발주 담당·입고 담당(ERP 관리자는 둘 다 + 옵션) | | `vacation_approver` | 결재 | 휴가 승인/반려 (모듈 미개발) | CORM은 별도 서비스로 실행하되 로그인·로그아웃·사용자·접근 권한은 ERP가 관리한다. CORM은 브라우저의 ERP 세션 쿠키를 `GET /api/auth/check?module=corm`으로 전달하고 ERP의 현재 사용자/권한을 매 요청 확인한다. CORM은 세션을 발급·갱신하지 않는다. 권한 해제·사용자 삭제는 다음 요청부터 반영되며, ERP 확인 실패 시 503으로 차단한다. API는 `order` 권한 확인도 지원하지만 Order 서비스 연동은 별도 작업이다. 설정과 배포 순서는 [CORM 중앙 인증](CORM_AUTH.md)을 따른다. `admin` 역할은 모든 권한 자동 부여. 신규 사용자는 관리자 페이지(`/admin`)에서 이메일만으로 등록 가능. 관리자 등급(2026-10-12): **수퍼관리자**(`SUPER_ADMIN_EMAIL` 한 명 고정 — 변경·삭제·추가 불가) > **Admin**(`role=admin`) > **Pro user**(`role=pro`) > **User**(`role=user`). Pro user 는 Project 모듈(프로젝트·목표·주간 회의록)에서만 권한이 늘고 (`app/modules/project/access.py`, 표는 `docs/PROJECT_MODULE.md` 6-14), 다른 모듈·관리자 페이지에서는 User 와 같다. --- ## 모듈 디렉토리 규약 신규 업무 모듈은 **별도 디렉토리 한 곳**에 라우터·저장소·템플릿을 모은다. ``` app/modules// ├─ __init__.py # router export ├─ router.py # FastAPI APIRouter (prefix=/) ├─ store.py # 데이터 저장소 (JSON → 향후 _db) └─ templates// # Jinja 템플릿 (ChoiceLoader 로 검색) ``` 신규 모듈 등록 시 `app/main.py` 의: 1. `_MODULE_TEMPLATE_DIRS` 에 템플릿 경로 추가 2. `app.include_router(_router)` 추가 3. `app.state._store = ...` 등 상태 등록 4. `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 | 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 폴백 없음) | | `malaysia_stock_db` | 말레이시아 창고 재고/세트BOM/재고조사 (`MALAYSIA_STOCK_DB_URL` 필수, JSON 폴백 없음) | | `performance_db` | 실적 — 쇼핑몰 설정/수수료 이력/인증정보(암호문)/매출 사건 (`PERFORMANCE_DB_URL` 필수, JSON 폴백 없음) | > 신규 DB 생성은 서버 실행 명령을 제공하고 사용자가 직접 진행한다 (사용자 지시: 2026-10-06). 대상·상태·백업 확인 명령을 제공하고 이름은 `_db`로 끝낸다. 기존 DB 삭제·덮어쓰기는 별도 승인 대상이다. 상세는 `DATABASES.md`. 자산관리는 전용 `asset_db`를 사용한다. `ASSET_DB_URL` 미설정 시 저장 비활성, XML 분석 미리보기 가능. --- ## 접속/도메인 | 환경 | 주소 | | --- | --- | | 운영 | `https://dbx.no1king.freeddns.org` | | 로컬 | `http://localhost:8080` | | Git 저장소 | `https://gitea.no1king.freeddns.org/king/dbx-main.git` | --- ## 허용 사용자 (서버 측 화이트리스트) `app/main.py`의 `ALLOWED_EMAILS`에서 검사한다. - king@dbxcorp.co.kr - julie@dbxcorp.co.kr - ellen@dbxcorp.co.kr - bj@dbxcorp.co.kr Google `hd=dbxcorp.co.kr` 힌트는 클라이언트 편의용이며, **실제 권한 검사는 항상 서버 측**에서 수행한다. --- ## 작업 우선순위 / 원칙 1. 운영 데이터 안전이 최우선. 위험 명령은 사용자 승인 후 실행. 2. 신규 기능보다 기존 데이터 일관성 유지 우선. 3. 외부 API 연동은 실패 재시도와 로깅을 기본으로 한다. 4. 비밀값은 `.env`로만 관리하고 Git에 절대 올리지 않는다.