Files
dbx-main/docs/PROJECT_OVERVIEW.md
T
king f54f19fa45 feat(라이브커머스): 라이브 커머스 모듈 추가
말레이시아 라이브 방송의 호스트 정보와 방송 스케줄을 관리하는 새 모듈.
호스트 설정(이름·연락처·주소·계좌·틱톡)은 ERP 관리자만 다루고,
스케줄표에서 등록된 호스트를 골라 날짜·시간·장소·판매금액(RM)·결과
이미지를 저장한다. 권한키 live, DB live_db(LIVE_DB_URL), 미설정이면
설정 필요 안내만 표시한다.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 16:41:37 +09:00

8.9 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/inout/, inout_db) — 발주 담당·입고 담당·공장은 모듈 옵션에서 지정, 제품은 itemcode_db 단품 읽기 전용. docs/INOUT_MODULE.md
긴급 공지 수퍼관리자가 정한 시각에 전체/고른 사람의 ERP 화면 정가운데에 띄우는 공지(app/modules/notice/, project_db 024) — [확인] 전까지 다시 뜸, 확인 현황. docs/NOTICE_MODULE.md
안내문 발송 리스트(이메일·인스타 주소 + 이름)에 {이름}을 넣은 안내문 — 메일 일괄 발송(보내는 사람 본인 Gmail)·인스타 DM 반자동(문구 복사 + DM 창) (app/modules/outreach/, outreach_db)
라이브 커머스 말레이시아 라이브 방송의 호스트 정보(설정)와 스케줄표(호스트·날짜·시간·판매금액·장소·결과 이미지) (app/modules/live/, live_db)
실적 쇼핑몰 통합 매출 (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 접근 자산관리 조회·등록·수정·배정·반납·보고서
outreach 접근 안내문 발송 — 리스트·메일 발송·DM·설정
live 접근 라이브 커머스 스케줄표 보기·고치기(호스트 정보 설정은 ERP 관리자만)
inout 접근 입출고 관리 조회. 발주·입고 입력은 모듈 옵션의 발주 담당·입고 담당(ERP 관리자는 둘 다 + 옵션)
vacation_approver 결재 휴가 승인/반려 (모듈 미개발)

CORM은 별도 서비스로 실행하되 로그인·로그아웃·사용자·접근 권한은 ERP가 관리한다. CORM은 브라우저의 ERP 세션 쿠키를 GET /api/auth/check?module=corm으로 전달하고 ERP의 현재 사용자/권한을 매 요청 확인한다. CORM은 세션을 발급·갱신하지 않는다. 권한 해제·사용자 삭제는 다음 요청부터 반영되며, ERP 확인 실패 시 503으로 차단한다. API는 order 권한 확인도 지원하지만 Order 서비스 연동은 별도 작업이다. 설정과 배포 순서는 CORM 중앙 인증을 따른다.

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/<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 폴백 없음)
outreach_db 안내문 발송 — 리스트·보낸 기록·제목/본문 설정·사진 (OUTREACH_DB_URL 필수, JSON 폴백 없음)
live_db 라이브 커머스 — 호스트 정보·방송 스케줄·결과 이미지 (LIVE_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에서 검사한다.

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


작업 우선순위 / 원칙

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