DBX CORM (CS Web Program)

CS / 발주 / 반품 통합 관리 웹 애플리케이션. FastAPI + PostgreSQL 기반, Docker로 실행.

로그인·로그아웃·사용자·CORM 접근 권한은 ERP(main-app)가 관리한다. erp_auth.py가 매 사용자 요청마다 ERP의 GET /api/auth/check?module=corm에 세션 쿠키를 전달해 현재 권한을 확인한다. ERP에서 권한을 끄거나 사용자를 삭제하면 다음 요청부터 차단된다. ERP 연결 실패/타임아웃은 503으로 차단하며, CORM은 ERP 세션을 발급·갱신하지 않는다. 사용자 확인은 CORM의 세션 서명 키 없이 동작한다. SESSION_COOKIE_NAME은 ERP와 같아야 한다.

ERP_AUTH_URL 기본값은 http://dbx-main:8000/api/auth/check이다(공용 postgres_default 네트워크). 운영은 동일 도메인의 /corm/ 프록시를 유지하고, ERP 인증 API를 먼저 배포한 다음 CORM을 배포한다. 새 CORM만 배포하면 기존 ERP의 404 응답으로 사용자 접근이 503이 된다. 실제 배포 전 양쪽 git status --short, docker compose ps, 공통 Docker 네트워크와 설정 백업 위치를 확인한다. 기존 INTERNAL_SERVICE_TOKEN 시스템 호출과 NPM의 외부 X-Service-Token 헤더 제거 설정은 유지한다.

검증: python -m unittest discover -s tests -v. 권한이 있는 직원으로 접속 후 ERP에서 corm 권한을 끄고, 같은 탭 새로고침 시 403인지 확인한다. 공개 헬스 체크 성공만으로 사용자 인증 성공을 판단하지 않는다.


기술 스택

  • Backend: Python 3.10, FastAPI, Uvicorn
  • DB: PostgreSQL (외부 Docker 컨테이너 연결)
  • 외부 연동: 네이버 커머스 API, 카페24 API, Google Sheets
  • Frontend: Jinja2 템플릿 + Vanilla JS

사용 DB

구글 시트의 업무 설정을 같은 PostgreSQL 서버의 전용 corm_db로 이전하려면 설정 DB 이전 절차를 따른다. SETTINGS_BACKEND=postgres로 전환한 뒤에는 설정 화면의 조회·저장이 DB를 사용한다. DB 접속 정보와 API 비밀키는 기존 .env/환경변수에 유지한다. 문자내역과 수동발주내역도 같은 corm_db로 옮기려면 내역 DB 이전 절차를 따르고 HISTORY_BACKEND=postgres로 전환한다. 실제 수동발주 시트를 셀 편집·자동 저장 표로 바꾸려면 수동발주 표 전환을 따른다. 운영자 실행: cd /opt/dbx-corm && git pull --ff-only && bash deploy-manual-orders.sh.

DB 이름 용도
itemcode_db 품목코드 마스터 + CS 기록(v9.1: cs_records·cs_memo_folders·cs_permanent_memos·cs_schedules, 앱이 처음 쓸 때 CREATE TABLE IF NOT EXISTS 로 자동 생성)
corm_db CORM 업무 설정·문자내역·수동발주내역·실제 수동발주 표 (SETTINGS_DB, 각각 별도 테이블 사용)
orderlist_db 주문 정보 조회
return_db 반품 데이터 저장

모두 DB 계정은 king 통일.

버전

  • 현재 v9.1 (2026.09.03) — CS 기록 메뉴(달력·상시 메모·일정, 엑셀 내려받기/업로드), New CS 누락·파손·불량·오배송 발주 → CS 기록 자동 저장, 반품 신청/입고 목록 최근 3개월 + 원송장번호 전체 검색, 구글 연동 시간 제한·설정 스냅샷(google_runtime.py).
  • 원본은 로컬 CS 통합 프로그램 폴더. 서버판은 원본 위에 SSO(AuthGuard)·/corm 서브경로·환경변수 DB 설정·/health/db 를 유지한다. 원본을 다시 가져올 때 이 부분과 cafe24_api.py·naver_api.py(원본은 키가 코드에 박혀 있음 — 서버판은 환경변수)는 덮어쓰지 않는다.

서버 배포 절차 (/opt/dbx-corm)

설정·문자내역·수동발주내역 PostgreSQL 전환 (운영자 실행)

다른 앱과 시트에서 편집을 잠시 중단한 뒤 서버에서 아래 한 줄을 실행한다. 이미지 빌드 후 CORM 앱을 잠시 정지하며, 원본·로컬 내역·환경과 이전 이미지 백업 → corm_db 준비 → 전체 데이터 이전·검증 → 환경 전환 → 읽기 API 확인 순서로 진행한다. DB 생성 권한이 없는 계정은 관리자가 먼저 corm_db를 생성해야 한다. 실패하면 기존 이미지/환경으로 앱 재시작을 시도하고 DB와 백업을 보존한다. 기존 DB 데이터를 덮어쓰거나 삭제하지 않는다.

cd /opt/dbx-corm && git pull --ff-only && bash deploy-corm-postgres.sh

백업은 .settings-backups/deploy-<시각>-<프로세스번호>/에 보관된다. 직원 로그인과 실제 화면 동작은 완료 후 별도로 확인한다.

1. 코드 받기

sudo mkdir -p /opt/dbx-corm
sudo chown $USER:$USER /opt/dbx-corm
cd /opt
git clone https://gitea.no1king.freeddns.org/king/dbx-corm.git
cd /opt/dbx-corm

2. 환경변수 설정

cp .env.example .env
nano .env

.env 파일에 다음을 채워주세요:

  • POSTGRES_PASSWORD (DB 비밀번호)
  • POSTGRES_HOST (PostgreSQL 컨테이너 이름. 아래로 확인)
  • NAVER_CLIENT_ID, NAVER_CLIENT_SECRET
  • CAFE24_CLIENT_ID, CAFE24_CLIENT_SECRET, CAFE24_REDIRECT_URI

PostgreSQL 컨테이너 이름 확인:

docker ps --filter "ancestor=postgres" --format "{{.Names}}"

3. PostgreSQL 네트워크 확인 / 수정

docker network ls | grep postgres

docker-compose.yml의 networks.postgres-net.name 값을 실제 네트워크 이름으로 수정.

4. 민감 파일 업로드 (Git에 없음)

로컬 PC에서 서버로 직접 복사:

# 로컬 PC에서 실행
scp cafe24_tokens.json king@<서버>:/opt/dbx-corm/
scp manual-ordering.json king@<서버>:/opt/dbx-corm/

5. 빌드 및 실행

cd /opt/dbx-corm
docker compose up -d --build

6. 상태 확인

docker compose ps
docker compose logs -f

업데이트 (Git pull 후 재배포)

cd /opt/dbx-corm
git pull
docker compose up -d --build

접속

  • 컨테이너 포트: 8002
  • 호스트 포트: 8002
  • 헬스체크: http://<서버>:8002/

Nginx Proxy Manager 등을 사용한다면 <서버>:8002로 프록시 설정.


로컬 개발 (Windows)

python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt

copy .env.example .env
:: .env 편집

python main.py

Gitea 푸시 (Windows)

리포지토리에 변경사항을 올릴 때:

push_to_gitea.bat

스크립트가 변경사항 확인 → 커밋 메시지 입력 → push 자동 수행.


주의사항

  • .env, cafe24_tokens.json, manual-ordering.json 등 민감 파일은 절대 Git에 올리지 마세요.
  • .gitignore에 자동 제외 설정되어 있습니다.
  • DB 이름은 반드시 orderlist_db를 사용 (예전 이름 orderlist_app 사용 금지).
S
Description
CS, 발주, 반품, 상품관리 통합 프로그램
Readme 3.3 MiB
Languages
Python 37.8%
JavaScript 36%
HTML 17.9%
CSS 7.2%
Shell 0.8%
Other 0.2%