Files
dbx-main/app/modules/cafe24/CLAUDE.md
T
king 1efc59ffcf fix(cafe24): 진열/판매 변경 후 예전 상태로 보이는 읽기 지연 보정
- overlay_recent_write: updated_date 가 같아도 값이 다르면 지연으로 판정
  (진열/판매만 바꾼 PUT 은 updated_date 를 올리지 않을 수 있음)
- 상품 목록에도 최근 쓰기 스냅샷 보정 적용(overlay_product_rows) —
  목록·필터가 예전 값으로 보이고 캐시가 예전 값으로 덮이던 문제
- 예약 폼 현재 상태 미리보기도 load_product 로 보정
- PUT 응답에 product_no 가 없어도 스냅샷 저장
- 회귀 테스트 추가

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 03:50:48 +09:00

3.0 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 어댑터도 같은 토큰을 씀, 바꾸면 실적 영향 확인. 배포 시 이 모듈 변경이면 dbx-cafe24-worker 도 같이 재빌드.

기능

  • 카페24 관리자에 들어가지 않고 상품 상세페이지(description HTML) 조회·편집·즉시적용·예약적용·버전 이력.
  • 3분할 화면(목록 | HTML 편집기 | 상품 정보 패널).
  • 정보 패널(routes_product_info.py, _side.html)에서 상품명·판매가·공급가·소비자가, 대표이미지, 옵션(생성/이름·썸네일·표시방식 수정/삭제)·품목(자체코드·추가금액·진열·판매) 수정.
    • 대표이미지는 POST /admin/products/{no}/images 에 base64 data URI + image_upload_type=A. NNEditor 업로드 경로를 PUT detail_image 에 넣는 방식은 적용 안 됨.
  • 권한키 cafe24(연결/해제는 admin 전용).

규칙

  • 카페24 OAuth/API 클라이언트는 향후 주문관리와 공유하기 위해 공통 계층 app/integrations/cafe24/ 에 둔다 — 라우터에서 httpx/requests 직접 호출 금지.
  • 토큰은 Fernet 암호화 저장(CAFE24_TOKEN_SECRET), 로그/화면에 토큰·시크릿 절대 미출력.
  • 쓰기 직전 항상 카페24 현재 HTML 을 다시 읽어 BACKUP revision 생성(로컬 값을 현재값으로 가정 금지).
  • 예약은 DB 저장 + 별도 worker(worker.py, compose 서비스 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). 빠뜨리면 "진열/중지 바꿔도 반영 안 됨"으로 보임.
  • 유예시간 CAFE24_READ_LAG_GRACE_MIN(기본 360분).
  • 쓰기 후 화면은 PUT 응답으로 그리고 다시 GET 하지 않는다.
  • API 문서 예제는 apidocs.cafe24.com 청크 JS 에서 추출(예전 /docs/code JSON 은 404).