Files
dbx-corm/README.md
T
king d2fdec5c43 feat: v9.1 업그레이드 — CS 기록 메뉴 + 반품 목록 검색 + 구글 연동 안정화
원본(CS 통합 프로그램 v9.1, 2026.09.03)을 서버판에 병합. 서버용 개조는 유지:
SSO(AuthGuard·SessionMiddleware), /corm 서브경로(root_path·APP_BASE_PATH),
X-Service-Token, /health/db, 환경변수 DB 설정, cafe24/naver 키 환경변수.

- CS 기록 메뉴(routers/cs_records.py, cs_records.js/css): 달력별 기록·완료·복사·
  다음 업무일 이월, 상시 메모(폴더·색), 일정, 엑셀 내려받기/업로드.
  표는 itemcode_db 에 자동 생성(CREATE TABLE IF NOT EXISTS). DB 설정은 원본의
  하드코딩 대신 CS_RECORD_DB_* → POSTGRES_*/ITEMCODE_DB 환경변수.
- New CS 누락·파손·불량·오배송 발주 → CS 기록 자동 저장.
- 반품 신청/입고 목록: 최근 3개월 기본, 전체 보기, 원송장번호 전체 검색.
- google_runtime.py: 구글 호출 시간 제한·전용 작업 슬롯, 설정 시트 스냅샷 캐시
  (예전 10분 인메모리 캐시와 /api/config/refresh 대체), 설정 저장 한 번에 원자적으로.
- 밀크런: 탭을 열 때만 구글 시트 조회.
- 자동발주 메뉴는 원본처럼 막지 않고 그대로 둠, 엑셀 내려받기 링크도 /corm 경로.
- requirements: holidays 추가. tests/test_google_resilience.py(서비스 토큰으로 SSO 통과).

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

154 lines
3.6 KiB
Markdown

# DBX CORM (CS Web Program)
CS / 발주 / 반품 통합 관리 웹 애플리케이션.
FastAPI + PostgreSQL 기반, Docker로 실행.
---
## 기술 스택
- **Backend**: Python 3.10, FastAPI, Uvicorn
- **DB**: PostgreSQL (외부 Docker 컨테이너 연결)
- **외부 연동**: 네이버 커머스 API, 카페24 API, Google Sheets
- **Frontend**: Jinja2 템플릿 + Vanilla JS
---
## 사용 DB
| DB 이름 | 용도 |
|---|---|
| `itemcode_db` | 품목코드 마스터 + CS 기록(v9.1: `cs_records`·`cs_memo_folders`·`cs_permanent_memos`·`cs_schedules`, 앱이 처음 쓸 때 `CREATE TABLE IF NOT EXISTS` 로 자동 생성) |
| `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`)
### 1. 코드 받기
```bash
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. 환경변수 설정
```bash
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 컨테이너 이름 확인:
```bash
docker ps --filter "ancestor=postgres" --format "{{.Names}}"
```
### 3. PostgreSQL 네트워크 확인 / 수정
```bash
docker network ls | grep postgres
```
`docker-compose.yml`의 `networks.postgres-net.name` 값을 실제 네트워크 이름으로 수정.
### 4. 민감 파일 업로드 (Git에 없음)
로컬 PC에서 서버로 직접 복사:
```bash
# 로컬 PC에서 실행
scp cafe24_tokens.json king@<서버>:/opt/dbx-corm/
scp manual-ordering.json king@<서버>:/opt/dbx-corm/
```
### 5. 빌드 및 실행
```bash
cd /opt/dbx-corm
docker compose up -d --build
```
### 6. 상태 확인
```bash
docker compose ps
docker compose logs -f
```
---
## 업데이트 (Git pull 후 재배포)
```bash
cd /opt/dbx-corm
git pull
docker compose up -d --build
```
---
## 접속
- 컨테이너 포트: `8002`
- 호스트 포트: `8002`
- 헬스체크: `http://<서버>:8002/`
Nginx Proxy Manager 등을 사용한다면 `<서버>:8002`로 프록시 설정.
---
## 로컬 개발 (Windows)
```cmd
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env
:: .env 편집
python main.py
```
---
## Gitea 푸시 (Windows)
리포지토리에 변경사항을 올릴 때:
```cmd
push_to_gitea.bat
```
스크립트가 변경사항 확인 → 커밋 메시지 입력 → push 자동 수행.
---
## 주의사항
- `.env`, `cafe24_tokens.json`, `manual-ordering.json` 등 **민감 파일은 절대 Git에 올리지 마세요**.
- `.gitignore`에 자동 제외 설정되어 있습니다.
- DB 이름은 반드시 `orderlist_db`를 사용 (예전 이름 `orderlist_app` 사용 금지).