Files
dbx-main/docs/PROJECT_OVERVIEW.md
T
king aa669553db feat(performance): 실적(쇼핑몰 통합 매출) 모듈 1단계 — 대시보드·설정·보안·어댑터 구조
- 네 영역 분리: ① 수집(adapters/ 쇼핑몰 10곳 + sync.py) ② 보안(security/ + credentials.py)
  ③ 계산·저장(calc.py + db.py) ④ 화면(dashboard.py, router.py, templates, performance.css/js)
- 대시보드: 기간(오늘/이번주/이번달/올해/직접선택, 이전·다음), 쇼핑몰 필터, KPI 5개(진행 중 기간은
  직전 기간 같은 경과일 대비), 일자×쇼핑몰 표(주간합계, 총매출/수수료/차감매출 전환), 일별 추이·
  쇼핑몰 비중(SVG), 월 누적(비중)·연간 누적, 금액 클릭 → 주문 상세
- 설정(관리자): 사용/매출 집계, 수수료율 이력(적용 시작일), 쇼핑몰별 API 인증정보 입력·연결 테스트·
  연결 상태, 마스터 키 상태·재암호화, 테스트(모의) 데이터 생성/삭제
- 인증정보: 설정 화면 입력 → AES-256-GCM(키 버전, AAD=쇼핑몰+항목) 암호화 저장, secret 원문은
  화면으로 다시 보내지 않음, 오류·로그·raw 는 비밀값 가린 뒤 저장. 마스터 키는 APP_ENCRYPTION_KEY(.env)
- 매출 기준일: 결제=결제일, 취소·반품=발생일. 금액 원 단위 정수, 수수료 반올림은 calc.commission 한 곳
- 동기화: 같은 쇼핑몰 동시 실행 차단(running 부분 유니크), 쇼핑몰별 실패 격리, 중복 방지 UNIQUE+UPSERT
- 카페24 어댑터는 기존 app/integrations/cafe24 OAuth 토큰 재사용, 나머지는 입력칸만(수집은 다음 단계)
- performance_db 초기화 스크립트, 권한키 performance(설정은 is_admin), 문서·.env.example

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 16:07:46 +09:00

5.6 KiB

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/performance/) — 쇼핑몰별 어댑터로 수집 → performance_db 저장 → 일자×쇼핑몰 표·KPI·월/연 누적·그래프. 수수료율 이력, API 인증정보는 설정 화면 입력 + AES-256-GCM 암호화 저장. 1단계는 모의 데이터·구조까지(실제 API 는 쇼핑몰별로 순차 연동). docs/PERFORMANCE_MODULE.md

권한 키 (MODULE_KEYS)

키 종류 설명
corm / order 접근 외부 모듈 진입
expense / vacation / cupang / malaysia / performance 접근 내부 모듈 진입 (performance 설정 화면·API 는 추가로 admin 필요)
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 의:

  1. _MODULE_TEMPLATE_DIRS 에 템플릿 경로 추가
  2. app.include_router(<name>_router) 추가
  3. app.state.<name>_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가 필요하면 승인 요청 후 생성하며, 이름은 _db로 끝낸다. 상세는 DATABASES.md.


접속/도메인

환경 주소
운영 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 힌트는 클라이언트 편의용이며, 실제 권한 검사는 항상 서버 측에서 수행한다.


작업 우선순위 / 원칙

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