Files

T

king c6fb8ed375 feat(cafe24): 상품 상세페이지 관리 모듈 Phase 1

카페24 관리자에 직접 접속하지 않고 상품 상세페이지(description HTML)를
편집·예약 적용·복원하기 위한 모듈의 기반을 만든다. Phase 1 은 공통
Integration 계층, cafe24_db, OAuth 연결 화면까지다.

카페24 OAuth/API 클라이언트를 상품관리 모듈 안에 두지 않고
app/integrations/cafe24/ 로 분리했다. 향후 추가할 주문관리(주문 조회·송장
일괄등록·취소/반품/교환)가 같은 토큰과 클라이언트를 그대로 재사용해야 하기
때문이다. 라우터에서 httpx 를 직접 부르지 않고 Cafe24Client 만 쓰게 해서
재시도·rate limit·API 로그·토큰 갱신을 한 곳에 모았다.

토큰은 Fernet 으로 암호화해 저장한다(CAFE24_TOKEN_SECRET). DB 덤프가
유출돼도 access/refresh token 이 평문으로 남지 않게 하기 위함이며, API 로그와
연결 상태 화면에는 토큰·시크릿을 일절 기록/표시하지 않는다.

토큰 갱신은 행 잠금(SELECT ... FOR UPDATE) 안에서 한다. 카페24는 refresh
token 을 회전시키므로, 이후 추가될 예약 worker 컨테이너와 web 컨테이너가
동시에 갱신하면 한쪽 토큰이 무효화된다.

기존 파일 변경은 목록에 한 줄씩 추가하는 형태로 44줄뿐이며 기존 라우트·
테이블·인증 로직은 건드리지 않았다. CAFE24_DB_URL 미설정 시 store 가 None
이라 앱은 정상 기동하고 모듈만 "설정 필요" 안내를 표시한다.

가드 헬퍼를 common.py 로 분리한 것은 router.py 가 routes_system.py 를
include 하는 구조에서 순환 import 가 생기기 때문이다.

검증: 신규 테스트 16개 통과(암호화 왕복, 토큰 만료·자동갱신, 상태 노출 시
토큰 미유출, 재시도 예산, 예약 상태 전이). dispatch 기존 테스트 9개 통과.
cafe24_db_init.sql 은 로컬에 Docker 가 없어 미실행 — 서버 적용 시 확인 필요.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-08-14 00:23:02 +09:00

7.5 KiB

Raw Blame History

main-app ERP 프로젝트 작업 기준

이 문서는 Claude Code가 이 저장소에서 작업할 때 가장 먼저 확인하는 기준 문서입니다. 작업 시작 전, 아래 "반드시 먼저 읽을 문서"를 모두 확인한 뒤 작업을 시작합니다.

반드시 먼저 읽을 문서

Claude Code는 이 저장소에서 작업을 시작하기 전에 반드시 아래 문서를 순서대로 읽고 맥락을 확보한 뒤 작업한다.

docs/PROJECT_OVERVIEW.md — 프로젝트 정의, 기능 범위, 연동 대상
docs/SERVER_ARCHITECTURE.md — 서버 구성도와 네트워크 흐름
docs/DATABASES.md — PostgreSQL DB 구성과 명명 규칙
docs/DEPLOYMENT.md — 배포 경로, 서비스 실행 방식, 복구 절차

문서 간 내용이 충돌하면 위의 우선순위(1 → 4)를 따른다.

프로젝트 한 줄 정의

main-app은 DBX ERP 시스템의 메인 프로젝트(허브) 이다.

담당 영역:

주문관리
상품코드 매칭
재고관리
CS관리
반품관리
외부 쇼핑몰 API 연동 (카페24, 네이버 스마트스토어, 사방넷 등)
개인경비 (app/modules/expense/, expense_db)
쿠팡 밀크런 (app/modules/cupang/, cupang_db) — 출고 달력/박스 입수량 계산/입고센터 관리, 상품은 itemcode_db 읽기 전용
휴가 관리 (app/modules/vacation/, vacation_db) — 월간 달력(구글식 bar)/연차·반차 신청/승인 워크플로/공휴일·연차 설정. 권한키 vacation·vacation_approver
말레이시아 창고 재고관리 (app/modules/malaysia/, malaysia_stock_db) — 낱개(MT/MX/MZ) 입출고·조정, 세트(MY) BOM, 일일 재고조사(세트→낱개 자동 분해), 현재고 현황. 뚜껑(MD-)은 재고 집계 제외 — 단, 창고 랙에는 위치 확인용으로 배치 가능(store.LID_ITEMS). 상품은 itemcode_db 읽기 전용. 권한키 malaysia
말레이시아 배송 (app/modules/dispatch/, dispatch_db) — TikTok·Shopee 출고관리. 플랫폼별 데이터 엑셀 업로드(TikTok=03_TikTok_Order_Export.xlsx, Shopee=Packing List.Doorstep Delivery.xlsx) → 1박스=1카드 출고 작업 리스트·SKU 피킹 요약·Kagayaku 전달표 자동 생성. 1박스 묶음 기준 Package ID > Tracking ID > Order ID, 같은 박스 같은 SKU 합산. 작업 상태 토글(dispatch_logs 기록). 받는 사람 이름/전화/주소는 박스 단위로 저장(작업 카드 표시 + 출고 엑셀 생성용 — 개인정보). 배치 다운로드 zip 에 업로드 원본 + 취합 출고 엑셀(YYYY.MM.DD(Ddd)_tictoc|shopee.xlsx) 포함. 엑셀은 openpyxl 파싱/생성. 권한키 dispatch. 상세는 docs/DISPATCH_MODULE.md
카페24 상품관리 (app/modules/cafe24/, cafe24_db) — 카페24 관리자에 들어가지 않고 상품 상세페이지(description HTML) 조회·편집·즉시적용·예약적용·자동복원·버전 롤백·일괄수정. 카페24 OAuth/API 클라이언트는 향후 주문관리와 공유하기 위해 공통 계층 app/integrations/cafe24/ 에 둔다 — 라우터에서 httpx/requests 직접 호출 금지. 토큰은 Fernet 암호화 저장(CAFE24_TOKEN_SECRET), 로그/화면에 토큰·시크릿 절대 미출력. 쓰기 직전 항상 카페24 현재 HTML 을 다시 읽어 BACKUP revision 생성(로컬 값을 현재값으로 가정 금지). 예약은 DB 저장 + 별도 worker(app/modules/cafe24/worker.py, compose 서비스 dbx-cafe24-worker)가 처리 — 웹 프로세스에서 대기하지 않는다. 권한키 cafe24(연결/해제는 admin 전용). 상세는 docs/CAFE24_MODULE.md
프로젝트 관리 (app/modules/project/, project_db) — 아사나식. 프로젝트/서브프로젝트(self-FK parent_id, CASCADE)·업무(tasks: 담당자·우선순위·시작/마감)·진행단계(project_stages 칸반, 생성시 기본 4단계 seed)·멤버 배정(project_members)·활동이력(project_activity). 메인 뷰 달력(FullCalendar)/타임라인(vis-timeline) 버튼 토글 + 보드(드래그로 단계 이동)/리스트. 진입 권한키 project(관리자 페이지 토글로 직원별 부여, admin 자동). 프로젝트 생성/삭제·사용자 배정은 is_admin 만, 배정 멤버(또는 owner)는 서브프로젝트/업무/단계 CRUD. 멤버 배정 후보는 project 권한 보유 등록 사용자에서 자동 목록(GET /project/api/assignable-users). 업무 배정·완료 시 관리자에게 메일(app/mail.py stdlib smtplib, SMTP_*+PROJECT_NOTIFY_EMAIL env, 미설정 시 조용히 skip, BackgroundTasks 비동기). 상세는 docs/PROJECT_MODULE.md

상세는 docs/PROJECT_OVERVIEW.md.

개발 원칙

기존 코드를 수정하기 전 관련 파일을 먼저 읽고 구조를 파악한다.
위험 명령은 반드시 사용자 확인 후 실행한다 (아래 "위험 명령" 절 참고).
.env, API 키, DB 비밀번호, OAuth Secret, 토큰은 절대 Git에 올리지 않는다.
신규 DB가 필요하면 승인 요청 후 생성하며, DB명은 반드시 _db로 끝낸다 (예: inventory_db).
예전 문서/코드의 orderlist_app은 현재 기준 orderlist_db이다. 발견 시 수정 대상.

위험 명령 (사용자 확인 없이 실행 금지)

아래 명령은 반드시 사용자에게 의도를 설명하고 명시적 승인을 받은 뒤 실행한다.

분류	명령 예시
파일 삭제	`rm -rf`, `Remove-Item -Recurse -Force`
DB 파괴	`DROP DATABASE`, `DROP TABLE`, `DROP SCHEMA`
데이터 삭제	`TRUNCATE`, 조건 없는 대량 `DELETE`, `UPDATE`
Docker 파괴	`docker volume rm`, `docker volume prune`, `docker system prune -a --volumes`
Git 파괴	`git reset --hard`, `git push --force`, `git clean -fd`, `git branch -D`
운영 초기화	운영 DB 덤프 덮어쓰기, 마이그레이션 롤백

원칙:

실행 전 현재 상태 확인 명령을 먼저 보여준다 (예: docker ps, \l, git status).
백업 존재 여부와 위치를 명시한다.
실행 후 결과 확인 절차를 같이 제시한다.

서버 작업 원칙

배포, DB 복구, Docker 작업 전에는 현재 상태 확인 명령을 먼저 제안한다.
PostgreSQL 작업 전에는 DB명, 컨테이너명, 포트, 백업 위치를 확인한다.
운영 서버 경로와 개발 PC 경로를 혼동하지 않는다.
- 개발 PC: G:\내 드라이브\프로젝트\Main-app
- 운영 서버 (main-app): /opt/www/main ← 본 프로젝트 경로
- 참고용 (같은 호스트 내 다른 서비스 경로): /opt/dbx-corm, /opt/dbx-orderlist
- 명령 예시·문서 작성 시 main-app 경로는 반드시 /opt/www/main 사용. 상세는 docs/DEPLOYMENT.md.

환경 변수 / 비밀값

.env, .env.local, .env.production 은 Git에 절대 커밋하지 않는다.
예시 파일(*.example)만 커밋한다.
비밀값 유출이 의심되면 즉시 회전(rotate)을 권고한다.
신규 환경변수 추가 시 *.example 파일과 본 문서(또는 docs/DEPLOYMENT.md)에 변수 설명을 함께 갱신한다.

디렉터리 구조 (요약)

Main-app/
├─ app/                  FastAPI 앱 소스
├─ docs/                 운영/설계 문서 (작업 전 필독)
├─ scripts/              배포·유지보수 스크립트
├─ skills/               Claude Code 규칙/스킬
├─ docker-compose.yml    운영 컴포즈
├─ docker-compose.local.yml  로컬 컴포즈
├─ Dockerfile
├─ requirements.txt
└─ CLAUDE.md             ← 이 문서

7.5 KiB Raw Blame History