- 옵션/품목 팝업 저장 시 기본몰(1)에 반영된 행의 진열·판매만 CAFE24_SHOP_NOS(예 1,2,3)의 다른 쇼핑몰에도 같은 값으로 PUT - 추가금액(통화 다름)·자체코드·순서는 기본몰만 - 다른 쇼핑몰 실패는 응답 shop_failed·감사 기록·화면 경고(기본몰 반영 유지) - 쇼핑몰 목록 API 는 mall.read_store 권한이 필요해 번호를 환경변수로 받음 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
5.6 KiB
[카페24] 카페24 상품관리 모듈 — app/modules/cafe24/, cafe24_db
이 모듈만 고칠 때 읽는 요약. 상세는
docs/CAFE24_MODULE.md(큰 문서 —grep -n '^#'로 목차 보고 필요한 절만 읽기). 정적 파일:app/static/cafe24.css,cafe24-options.js. 템플릿:templates/. 테스트:tests/. 공통 API 계층:app/integrations/cafe24/— 실적 모듈 카페24 어댑터도 같은 토큰을 씀, 바꾸면 실적 영향 확인. 배포 시 이 모듈 변경이면 worker 도 같이 재빌드 — compose 서비스명cafe24-worker(컨테이너명dbx-cafe24-worker아님):docker compose up -d --build --no-deps web cafe24-worker.
기능
- 카페24 관리자에 들어가지 않고 상품 상세페이지(description HTML) 조회·편집·즉시적용·예약적용·버전 이력.
- 3분할 화면(목록 | HTML 편집기 | 상품 정보 패널). 목록에 64x64 대표 이미지(
tiny_image, 없으면detail_image). - HTML 편집기에서
<img>태그에 마우스를 올리면 태그를 오렌지색으로 칠하고 화면 오른쪽에 폭 500px·창 높이로 파일명과 미리보기(상대 경로는CAFE24_SHOP_URL루트 기준, 색칠 한도HL_LIMIT초과 소스는 미동작). - HTML 편집기에서 커서가
<img>태그 안 어디에 있든 Ctrl+↑/↓ 로src파일명(.jpg/.gif/.png) 번호 변경. 없음 →_2→_3…, 이미_숫자면 다음 숫자부터. 내릴 때는 원래 번호(없었으면 원래 이름) 아래로 안 감 — 다른 편집이 끼거나 다른 이미지로 옮기면 그때 번호가 새 원래 번호. - 정보 패널(
routes_product_info.py,_side.html)에서 상품명·판매가·공급가·소비자가, 대표이미지, 옵션(생성/이름·썸네일·표시방식 수정/삭제)·품목(자체코드·추가금액·진열·판매) 수정. 품목 진열·판매는CAFE24_SHOP_NOS(예 1,2,3)의 모든 멀티쇼핑몰에 같은 값으로 보냄(추가금액 등은 기본몰만).- 대표이미지는
POST /admin/products/{no}/images에 base64 data URI +image_upload_type=A. NNEditor 업로드 경로를 PUTdetail_image에 넣는 방식은 적용 안 됨. - 옵션/품목 팝업 「판매 가격」 열: 기본 정보 판매가 + 추가금액을 보여주고, 입력하면 추가금액을 역산(
cafe24-options.jsbindSalePrice). 저장되는 값은 추가금액뿐. - 옵션/품목 팝업 옵션값 이름·자체 품목코드·추가금액·판매 가격 칸: Enter·↓ 아래 행, ↑ 위 행 같은 열로 이동(한글 조합 중에는 이동 안 함).
- 옵션/품목 팝업(단일 옵션 화면) 「모바일 스와이프 복사(코드)」:
// 상품명+"품목코드": "/web/…썸네일 경로",줄들을 클립보드로 (cafe24-options.jsswipeCode— 행에 지금 보이는 썸네일 기준, 도메인/CDN 은 떼고/web/부터). 「모바일 스와이프 복사(이름)」은 키가 품목코드 대신 옵션값 이름(swipeCode(tbody, true), 품목코드 있는 행만).
- 대표이미지는
- 예약(편집기 아래 「예약 적용」): 대표 이미지(썸네일) · 상세페이지 · 진열 · 판매를 지정 시각에. 대표 이미지 파일은
cafe24_schedule_images(마이그레이션 006)에 보관, worker 가 이미지 먼저 교체. - 권한키
cafe24(연결/해제는 admin 전용).
규칙
-
카페24 PUT options 는 옵션값 추가를 오류 없이 무시한다 — 기존 옵션에 행 추가는 「옵션 재생성」(DELETE → POST, 품목코드 새로 부여)으로만. 저장 버튼이 새 행을 보면 재생성 확인창으로 넘긴다.
-
카페24 OAuth/API 클라이언트는 향후 주문관리와 공유하기 위해 공통 계층
app/integrations/cafe24/에 둔다 — 라우터에서httpx/requests직접 호출 금지. -
토큰은 Fernet 암호화 저장(
CAFE24_TOKEN_SECRET), 로그/화면에 토큰·시크릿 절대 미출력. -
쓰기 직전 항상 카페24 현재 HTML 을 다시 읽어
BACKUPrevision 생성(로컬 값을 현재값으로 가정 금지). -
디자인 FTP(스와이프·상품상세) 쓰기는 임시 파일 → 검증 → rename. 카페24 FTP 는 허용 확장자만 받으므로 임시 이름도 원래 확장자로 끝나야 함(
x_cf24tmp_<tag>.js,design_ftp.temp_names).x.js.cf24tmp-…는550 Operation not permitted. -
예약은 DB 저장 + 별도 worker(
worker.py, compose 서비스cafe24-worker, 컨테이너dbx-cafe24-worker)가 처리 — 웹 프로세스에서 대기하지 않는다.
읽기 지연 ("마지막 쓰기가 권위")
- 카페24 관리자 API 는 PUT 뒤 한동안 GET 에서 예전 값을 돌려준다(읽기 지연) — 우리 캐시 문제가 아니다.
- 상세설명: 카페24 값이 최근 revision 중 하나와 같으면 지연으로 보고 마지막 MANUAL/SCHEDULED 를 표시·지문 기준으로 씀(
store.resolve_description). - 스칼라(상품명·가격·이미지·진열/판매): PUT 응답 스냅샷(
cafe24_products.last_write_snapshot, 마이그레이션 004)과 GET 의updated_date를 비교해 덮어씌움(store.overlay_recent_write).- 진열/판매만 바꾼 PUT 은
updated_date가 안 오를 수 있음 → 같은 시각 + 값 다름 = 지연. - 단건 GET 뿐 아니라 목록·예약 미리보기도 보정 필수(
store.overlay_product_rows). 빠뜨리면 "진열/중지 바꿔도 반영 안 됨"으로 보임.
- 진열/판매만 바꾼 PUT 은
- 유예시간
CAFE24_READ_LAG_GRACE_MIN(기본 360분). - 쓰기 후 화면은 PUT 응답으로 그리고 다시 GET 하지 않는다.
- API 문서 예제는 apidocs.cafe24.com 청크 JS 에서 추출(예전
/docs/codeJSON 은 404).