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

6.6 KiB

Raw Blame History

카페24 상품 상세페이지 관리 모듈 (cafe24)

카페24 관리자 페이지에 직접 들어가지 않고 상품 상세페이지를 조회·편집·예약 적용하고, 언제든 이전 상태로 되돌리기 위한 운영용 모듈. main-app ERP 에 편입된 모듈이다(별도 앱/포트 아님). 인증은 기존 Google OAuth + 권한키 cafe24 를 재사용한다.

1. 구조 — 왜 두 곳으로 나눴나

향후 카페24 주문관리(주문 조회·송장 일괄등록·취소/반품/교환)를 같은 프로젝트에 추가할 예정이다. 그래서 카페24 인증/전송은 상품관리에 종속시키지 않고 공통 계층으로 분리했다.

app/integrations/cafe24/        ← 공통 (상품관리 + 향후 주문관리 공유)
├─ config.py    환경변수 → Cafe24Config (하드코딩 금지)
├─ crypto.py    토큰 Fernet 암복호화
├─ oauth.py     인증 URL / code→token / refresh
├─ tokens.py    TokenService — 저장·만료판정·자동갱신(행 잠금)
├─ client.py    Cafe24Client — 전송·재시도·401/429/5xx·호출간격·API 로그
├─ products.py  상품 엔드포인트 래퍼   (향후 orders.py 를 형제로 추가)
└─ errors.py    공통 예외

app/modules/cafe24/             ← 상품관리 모듈
├─ router.py         루트 라우터(prefix=/cafe24) + 서브 라우터 결합
├─ routes_system.py  연결(OAuth)·상태·API 로그·작업 로그
├─ common.py         가드/컨텍스트 헬퍼 (순환 import 방지로 분리)
├─ db.py             Cafe24Store (cafe24_db, psycopg3 raw SQL)
├─ store.py          순수 로직 — 상수·상태전이·재시도 규칙·검증
├─ tests/            DB/네트워크 없는 유닛테스트
└─ templates/cafe24/ _nav.html · index.html · system.html

규칙: 라우터에서 httpx/requests 를 직접 부르지 않는다. 반드시 app.integrations.cafe24 의 Cafe24Client 를 통한다(재시도·로그·토큰 갱신이 한 곳에 모여 있어야 하기 때문).

핸들러는 async def 가 아니라 def(동기) 로 선언한다. 카페24 API·DB 호출이 블로킹이므로 FastAPI 스레드풀에서 돌게 두는 편이 이벤트 루프를 막지 않는다.

2. 화면 / 경로

경로	화면	권한
`GET /cafe24/`	상품 목록 (Phase 2)	`cafe24`
`GET /cafe24/system`	연결 상태 · API 로그 · 작업 로그	`cafe24`
`GET /cafe24/system/oauth/start`	카페24 인증 시작	admin
`GET /cafe24/oauth/callback`	카페24 콜백 (code→토큰)	admin
`POST /cafe24/system/oauth/disconnect`	저장된 토큰 삭제	admin
`GET /cafe24/health`	포털 카드 상태 점	없음

3. OAuth 흐름

관리자 [카페24 연결]
   ↓  state 생성 → 세션 저장
GET /cafe24/system/oauth/start  → 302 카페24 인증 페이지
   ↓  사용자 승인
GET /cafe24/oauth/callback?code=&state=
   ↓  세션 state 와 대조 (불일치 시 토큰 교환 거부 — CSRF 방어)
code → access/refresh token 교환
   ↓  Fernet 암호화
cafe24_oauth_tokens 저장

scope 는 app/integrations/cafe24/config.py 의 PRODUCT_SCOPES = mall.read_product, mall.write_product. 주문관리 추가 시 ORDER_SCOPES 를 합쳐 넘기고, 카페24 개발자센터 앱에서도 권한을 추가한 뒤 재인증하면 된다.
access token 은 만료 2분 전부터 자동 갱신된다. 갱신은 토큰 행을 SELECT ... FOR UPDATE 로 잠근 채 수행 — web 컨테이너와 worker 컨테이너가 동시에 refresh 해서 한쪽 토큰이 무효화되는 것을 막는다(카페24는 refresh token 을 회전시킨다).
refresh token 이 만료되면 자동 복구가 불가능하므로 화면에 "재연결 필요"를 표시한다.

4. 보안 규칙 (반드시 지킬 것)

client_secret·토큰을 코드에 하드코딩하지 않는다. 전부 .env.
로그·예외 메시지·템플릿에 토큰/시크릿을 절대 출력하지 않는다. cafe24_api_logs 에도 Authorization 헤더를 기록하지 않는다.
토큰은 DB 에 Fernet 암호문으로만 저장한다(CAFE24_TOKEN_SECRET).
카페24 연결/해제는 is_admin 전용.
OAuth 콜백은 세션 state 대조 후에만 code 를 교환한다.
SQL 은 %s 플레이스홀더만 사용한다(문자열 조립 금지).

5. 설치 / 실행

5-1. 카페24 개발자센터 앱 등록 (사람이 해야 하는 일)

https://developers.cafe24.com 로그인 → 앱 생성
Redirect URI 를 .env 의 CAFE24_REDIRECT_URI 와 정확히 동일하게 등록 (운영: https://dbx.no1king.freeddns.org/cafe24/oauth/callback)
권한(Scope)에 mall.read_product, mall.write_product 체크
발급된 Client ID / Client Secret 을 .env 에 기입

5-2. DB 초기화 (superuser 로 1회)

read -s -p "cafe24_app password: " APP_PWD; echo
docker exec -i postgres-db psql -U postgres \
    -v app_password="$APP_PWD" \
    < scripts/sql/cafe24_db_init.sql

5-3. .env

CAFE24_DB_URL=postgresql://cafe24_app:<APP_PWD>@postgres-db:5432/cafe24_db
CAFE24_MALL_ID=miraskitchen
CAFE24_CLIENT_ID=...
CAFE24_CLIENT_SECRET=...
CAFE24_REDIRECT_URI=https://dbx.no1king.freeddns.org/cafe24/oauth/callback
CAFE24_API_VERSION=2026-03-01
CAFE24_TOKEN_SECRET=<openssl rand -hex 32>

5-4. 재기동 + 권한 부여

cd /opt/www/main && docker compose up -d --build web

관리자 페이지(/admin)에서 직원에게 카페24 상품관리 권한을 부여한다.

6. 테스트

python -m app.modules.cafe24.tests.test_cafe24

DB·네트워크 없이 암호화 왕복, 토큰 만료/자동갱신, 상태 노출(토큰 미유출), 재시도 예산, 예약 상태 전이를 검증한다.

7. 진행 상태

Phase	내용	상태
1	공통 Integration · cafe24_db · OAuth 연결 화면	✅ 완료
2	상품 목록·검색·현재 HTML 조회	예정
3	Monaco 편집 · 미리보기 · Diff · 초안	예정
4	즉시 적용 · BACKUP · Revision · 감사로그	예정
5	예약 DB · Worker(compose 서비스) · 예약관리 화면	예정
6	자동 종료/복원 · 롤백	예정
7	일괄 수정 · 일괄 예약 · Rate limit 제어	예정

Phase 5 의 worker 는 app/modules/cafe24/worker.py 에 둔다 — Dockerfile 이 COPY app/ ./app/ 만 하므로 scripts/ 에 두면 이미지에 포함되지 않는다. docker-compose.yml 에 같은 이미지로 dbx-cafe24-worker 서비스를 추가해 python -m app.modules.cafe24.worker --loop 60 으로 돌린다.

6.6 KiB Raw Blame History