king/dbx-main
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(cafe24): 읽기 지연 보정("마지막 쓰기가 권위") + 상품 정보 패널

Browse Source 
증상: 상세페이지를 적용해도 편집기에 수정 전 소스가 보이고 한참 뒤에야
반영됨. 원인은 우리 캐시가 아니라(전부 no-store) 카페24 관리자 API 가 PUT
뒤 한동안 GET 에서 예전 값을 돌려주는 읽기 지연. 예전 코드는 2.4초만
기다린 뒤 GET 값을 그대로 믿어 예전 소스 표시·지문 충돌 오판·예전 값
백업이 생겼다.

- 상세설명: 쓰기 성공 시 MANUAL/SCHEDULED revision 을 기준으로, 카페24 값이
  유예시간 안의 revision 중 하나와 같으면 지연(pending)으로 보고 마지막
  쓰기를 표시·지문 기준으로 쓴다. 모르는 값이면 외부 변경(external).
  store.resolve_description / db.revision_digests(md5) / 배너 2종.
- 적용(apply)은 유효 현재값으로 BACKUP·지문 대조·변경없음 판정. 재조회
  확인 결과는 감사로그에만 남긴다.
- 스칼라(상품명·가격·이미지·진열/판매): PUT 응답을 cafe24_products.
  last_write_snapshot(JSONB, 마이그레이션 004)에 남기고 GET 의 updated_date
  가 그보다 이전이면 스냅샷으로 덮어씀. 옵션/품목도 섹션별 스냅샷.
- 3분할 화면: 목록 | 편집기 | 상품 정보 패널(_side.html, /pane 이 두 조각을
  한 응답으로). routes_product_info.py JSON API — 상품명/판매가/공급가/
  소비자가, 대표이미지 업로드(POST /admin/products/images → PUT detail_image
  + image_upload_type=A), 옵션 생성/이름·썸네일·표시방식 수정/삭제, 품목
  자체코드·추가금액·진열·판매 일괄 수정. 화면은 PUT 응답으로 그린다.
- client.delete/timeout, products.upload_images·options·variants 래퍼.
- 유닛테스트 21건 추가(88 통과), 문서(CAFE24_MODULE 3-3/3-4, DATABASES,
  .env.example CAFE24_READ_LAG_GRACE_MIN) 갱신.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
king
2026-09-18 18:07:42 +09:00
parent 8ea0db9245
commit 40766d805d
21 changed files with 2782 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/CAFE24_MODULE.md
+129 -27
View File
@@ -26,7 +26,9 @@ app/integrations/cafe24/ ← 공통 (상품관리 + 향후 주문관리
app/modules/cafe24/ ← 상품관리 모듈
├─ router.py 루트 라우터(prefix=/cafe24) + 서브 라우터 결합
├─ routes_products.py 2분할 화면 · 편집기 조각 · 적용(쓰기)
├─ routes_products.py 3분할 화면 · 편집기+정보패널 조각 · 적용(쓰기) · 읽기 지연 보정
├─ routes_product_info.py 오른쪽 정보 패널 JSON API — 상품명/가격 · 대표이미지 ·
│ 옵션(생성/수정/삭제) · 품목(자체코드/추가금액/진열/판매)
├─ routes_schedules.py 예약 등록·목록·취소
├─ routes_design_files.py 디자인 보관함 파일 편집·적용(FTP) — 모바일 스와이프·
│ PC/모바일 상품상세 템플릿(file_key 로 하나의 라우트 공유)
@@ -36,8 +38,9 @@ app/modules/cafe24/ ← 상품관리 모듈
├─ db.py Cafe24Store (cafe24_db, psycopg3 raw SQL)
├─ store.py 순수 로직 — 상수·상태전이·재시도 규칙·검증
├─ tests/ DB/네트워크 없는 유닛테스트
└─ templates/cafe24/ _nav.html · products.html(2분할) ·
_editor.html(오른쪽 조각) · design_editor.html ·
└─ templates/cafe24/ _nav.html · products.html(3분할 + 모든 JS) ·
_editor.html(가운데 조각) · _side.html(오른쪽 정보 패널 조각) ·
_panes.html(두 조각 묶음 — /pane 응답) · design_editor.html ·
schedules.html · system.html
```
@@ -54,12 +57,20 @@ app/modules/cafe24/ ← 상품관리 모듈
| 경로 | 화면 | 권한 |
| --- | --- | --- |
| `GET /cafe24/` | 2분할 화면 (`q`, `display`, `selling`, `selected`) | `cafe24` |
| `GET /cafe24/products/{product_no}/pane` | 오른쪽 편집기 조각 (JS 가 가져감) | `cafe24` |
| `GET /cafe24/` | 3분할 화면 (`q`, `display`, `selling`, `selected`) | `cafe24` |
| `GET /cafe24/products/{product_no}/pane` | 편집기 + 정보 패널 조각 묶음 (JS 가 가져가 `[data-pane]` 별로 끼움) | `cafe24` |
| `GET /cafe24/products/{product_no}` | → `/cafe24/?selected=` 로 리다이렉트(옛 주소) | `cafe24` |
| `POST /cafe24/products/{product_no}/apply` | 편집한 HTML 을 카페24에 즉시 적용 | `cafe24` |
| `POST /cafe24/products/{product_no}/status` | 진열/판매 토글 (JSON: `{field, value}` → 적용 후 상태) | `cafe24` |
| `POST /cafe24/products/{product_no}/name` | 상품명 변경 (JSON: `{name}` → 적용된 이름). 이전 이름은 감사로그 `rename_product` | `cafe24` |
| `POST /cafe24/products/{product_no}/basic` | 상품명·판매가·공급가·소비자가 (JSON, 바뀐 것만 PUT). 감사로그 `update_basic` | `cafe24` |
| `POST /cafe24/products/{product_no}/image` | 대표 이미지 교체 (multipart `file`) — 업로드 후 PUT `detail_image` + `image_upload_type=A`. 감사로그 `set_main_image` | `cafe24` |
| `GET /cafe24/products/{product_no}/options` | 옵션 + 품목 조회 (JSON, 읽기 지연 보정 포함) | `cafe24` |
| `POST /cafe24/products/{product_no}/options` | 옵션 생성 (`{option_name, values, display_type}`) — 조합형, 품목 자동 생성 | `cafe24` |
| `PUT /cafe24/products/{product_no}/options` | 옵션명·옵션값 이름/썸네일/표시방식 수정 (`{options:[...], option_list_type}`) | `cafe24` |
| `DELETE /cafe24/products/{product_no}/options` | 옵션 삭제 — **품목도 함께 삭제**(화면 확인창) | `cafe24` |
| `POST /cafe24/products/{product_no}/options/image` | 옵션값 썸네일 업로드만 (multipart → `{path}`) | `cafe24` |
| `PUT /cafe24/products/{product_no}/variants` | 품목 자체코드·추가금액·진열·판매 일괄 수정 (`{rows:[...]}`, 바뀐 행만) | `cafe24` |
| `GET /cafe24/schedules` | 예약 목록 · 취소 | `cafe24` |
| `POST /cafe24/schedules` | 예약 등록 (편집기에서) | `cafe24` |
| `POST /cafe24/schedules/{id}/cancel` | 대기 중 예약 취소 | `cafe24` |
@@ -120,19 +131,29 @@ Admin API(OAuth)로는 스킨 파일을 읽거나 쓸 방법이 없다(`config.p
---
### 2-1. 상품관리 화면 구성 (2분할)
### 2-1. 상품관리 화면 구성 (3분할)
```
┌─ 550px ───────────────────┬───────── 남은 폭 전부 ─────────┐
│ 상품명 검색(한 줄) │ 상품 이름 · 번호 · 진열/판매 │
│ ☑진열중 ☑판매중 (기본 체크) │ 상세설명 HTML 편집기 │
│ ── 목록(전체, 스크롤) ── │ (PC/모바일 공통 · 문법 강조) │
│ 번호 상품명 진열 판매 수정 │ [메모][복사][다시 읽기][적용] │
│ (제목행 클릭 = 정렬) │ ▸ 버전 이력 │
│ │ │
└───────────────────────────┴─────────────────────────────────┘
┌─ 320~460px ──────────┬──────── 남은 폭 전부 ────────┬─ 380px ─────────────┐
│ 상품명 검색(한 줄) │ [반영 대기 배너 — 지연 시] │ 기본 정보 │
│ ☑진열중 ☑판매중 │ 상품 이름 · 번호 · 진열/판매 │ 상품명/판매가/공급가 │
│ ── 목록(전체) ── │ 상세설명 HTML 편집기 │ /소비자가 [저장] │
│ 번호 상품명 진열 판매 │ (PC/모바일 공통 · 문법 강조) │ 대표 이미지 │
│ (제목행 클릭 = 정렬) │ [메모][복사][다시 읽기][적용] │ 큰 그림 + 목록/축소 │
│ │ ▸ 예약 적용 │ [파일 선택][교체] │
│ │ ▸ 버전 이력 │ ▸ 옵션 / 품목 (지연 로드) │
└───────────────────────┴───────────────────────────────┴──────────────────────┘
```
- 오른쪽 **상품 정보 패널**(`_side.html`)은 "소스 수정 외 기능"을 모아둔 별도 공간이다.
상품 클릭 시 `/products/{no}/pane` 이 편집기 조각과 패널 조각을 **한 응답**(`_panes.html`,
`[data-pane=editor]`/`[data-pane=side]`)으로 돌려주고 JS 가 각각 끼운다 — 카페24 상품
조회는 1회. 옵션/품목은 `<details>` 를 펼칠 때 JSON 으로 따로 불러온다(호출 2회 절약).
- 1360px 이하에서는 패널이 편집기 아래로 내려가고(높이 38vh, 안에서 스크롤), 1100px 이하는
한 열이다.
- 패널의 모든 쓰기는 JSON API(`routes_product_info.py`)이며 화면은 **응답값**으로 다시
그린다. 저장 뒤 카페24를 다시 GET 하지 않는다(아래 3-3 읽기 지연 참고).
- 검색 입력란은 **한 줄 높이로 고정**한다(`height: 32px`). `.cf24-filters` 가 세로
flex 이므로 `flex-basis` 를 주면 그 값이 **높이**로 적용돼 입력란이 거대해진다.
실제로 그 사고가 있었다 — flex 방향을 항상 확인할 것.
@@ -148,8 +169,8 @@ Admin API(OAuth)로는 스킨 파일을 읽거나 쓸 방법이 없다(`config.p
이 표식은 `_list_query` 가 링크·리다이렉트에도 이어 붙여 해제 상태가 유지된다.
- **정렬**은 제목행 클릭(오름↔내림 토글). 브라우저에서 처리하므로 전체를 받아둔
덕분에 목록 전체가 대상이 된다.
- **상품 클릭 시 오른쪽만 교체**한다(`/pane` 조각을 fetch → 삽입). 목록을 다시 받지
않으므로 카페24 호출이 1회로 끝난다. JS 실패 시 각 행의 링크로 정상 동작한다.
- **상품 클릭 시 편집기·정보 패널만 교체**한다(`/pane` 조각 묶음을 fetch → 삽입). 목록을
다시 받지 않으므로 카페24 호출이 1회로 끝난다. JS 실패 시 각 행의 링크로 정상 동작한다.
- 편집기 상단에 **상품 다이렉트 주소**(고객이 보는 상세페이지 URL)와 「주소 복사」·
「쇼핑몰에서 열기」를 둔다. 주소는 `CAFE24_SHOP_URL` 기준으로 만들고, 미설정 시
카페24 기본 도메인(`https://<mall_id>.cafe24.com`)으로 대체한다 — 커스텀 도메인은
@@ -341,12 +362,16 @@ cafe24_oauth_tokens 저장
정리된 소스가 그대로 저장된다).
1. **카페24에서 현재 HTML 을 다시 읽는다.** 로컬 DB 의 마지막 버전을 "지금
올라간 값"으로 가정하지 않는다(카페24 관리자에서 직접 고쳤을 수 있다).
2. 그 값으로 **BACKUP revision** 을 남긴다. 유일한 복구 수단이다.
1-1. **읽기 지연 판정으로 유효 현재값을 정한다**(3-3). 카페24가 아직 예전 값을
돌려주는 중이면 우리 마지막 쓰기(MANUAL/SCHEDULED)가 현재값이다.
2. 유효 현재값으로 **BACKUP revision** 을 남긴다. 유일한 복구 수단이다.
3. **지문 대조** — 편집 화면을 열 때의 `fingerprint`(sha256 앞 32자)와 지금
카페24 값의 지문이 다르면 적용을 거부한다. 편집 중 남이 바꾼 내용을 조용히
덮어쓰는 것을 막는 낙관적 잠금이다.
4. 내용이 같으면 호출하지 않는다(불필요한 쓰기·API 호출 방지).
5. PUT 적용 → **MANUAL revision** + 감사로그(`apply_description`).
유효 현재값의 지문이 다르면 적용을 거부한다. 편집 중 남이 바꾼 내용을 조용히
덮어쓰는 것을 막는 낙관적 잠금이다. (카페24의 지연된 예전 값과 비교하면
방금 적용한 것이 "충돌"로 오판된다 — 그래서 유효 현재값과 비교한다.)
4. 내용이 유효 현재값과 같으면 호출하지 않는다(불필요한 쓰기·API 호출 방지).
5. PUT 적용 → PUT 응답을 **스냅샷**으로 저장 → **MANUAL revision** → 짧은 재조회
확인(결과는 감사로그에만) → 감사로그(`apply_description`).
추가 규칙:
@@ -361,12 +386,79 @@ cafe24_oauth_tokens 저장
분리 사용 상품의 모바일 내용이 PC 와 달랐다면 덮어쓰기 전에 **그 내용도 BACKUP
revision 으로 남긴다**(백업이 없으면 되찾을 방법이 없다).
- 실패해도 BACKUP 은 이미 남아 있으므로 오류 메시지에 버전 번호를 알려준다.
- **적용 직후 짧게 재확인한다(`products.wait_for_description`).** 카페24 관리자
API(`GET /admin/products/{no}`)는 PUT 직후 몇 초간 이전 값을 돌려줄 때가
있다(쇼핑몰 화면에는 바로 반영됨 — 실물 관찰). 그 상태에서 다른 상품을 봤다가
돌아오면 우리 편집기만 "적용 안 된 것"처럼 보인다. 적용/예약 실행 직후
0.8초 간격으로 최대 3회 재조회해 새 값이 확인될 때까지 기다린 뒤 화면으로
돌아간다(실패해도 PUT 자체는 이미 성공했으므로 예외를 던지지 않는다).
- 적용 직후 `products.wait_for_description` 으로 0.8초 × 3회 재조회해 보지만, 이것은
**확인용**일 뿐 화면의 기준이 아니다(3-3). 확인 여부는 감사로그 detail 에 남는다.
---
## 3-3. 카페24 읽기 지연(read-after-write lag) — "마지막 쓰기가 권위"
### 증상과 원인
"소스를 수정해 적용했는데 편집기에는 수정 전 소스가 보이고, 한참 뒤에 다시 들어가면
반영돼 있다." 우리 쪽 캐시가 아니다 — 화면·조각 응답은 전부 `Cache-Control: no-store`
이고 fetch 도 `no-store` 다. **카페24 관리자 API 가 PUT 직후 한동안 `GET
/admin/products/{no}` 에서 이전 값을 돌려준다**(실물 관찰. 몇 초일 때도, 훨씬 길 때도
있다. 쇼핑몰 고객 화면에는 바로 반영된다). 예전 코드는 2.4초만 기다리고 포기한 뒤 GET
값을 그대로 믿었기 때문에
1. 편집기에 예전 소스가 보이고,
2. 그 예전 값으로 지문을 만들어 다음 적용이 "충돌"로 거부되거나,
3. 예전 값이 BACKUP 으로 남고 "변경 없음" 판정이 어긋났다.
### 규칙
쓰기가 성공하면 **우리가 쓴 값을 DB 에 남기고, 유예시간 안에서는 그것을 현재값으로
삼는다.** 유예시간은 `CAFE24_READ_LAG_GRACE_MIN`(기본 360분). 지나면 무조건 카페24 값을
믿는다 — 지연은 영원하지 않고, 영원히 로컬 값을 고집하면 그것이 또 다른 캐시다.
| 대상 | 우리가 남기는 것 | 지연 판정 | 구현 |
| --- | --- | --- | --- |
| 상세설명 HTML | MANUAL/SCHEDULED revision (+ 적용 직전 BACKUP) | 카페24 값이 유예시간 안의 **revision 중 하나와 같으면** 지연(pending) → 마지막 쓰기를 표시하고 그 지문을 쓴다. 마지막 쓰기와 같으면 synced. 우리가 모르는 값이면 external(관리자에서 직접 고침) → 카페24 값 표시 | `store.resolve_description`, `routes_products.resolve_description`, DB `revision_digests`(md5) |
| 상품명·가격·이미지·진열/판매 | PUT 응답을 `cafe24_products.last_write_snapshot.product` 에 저장 | GET 의 `updated_date` 가 스냅샷의 `updated_date` 보다 **이전**이면 지연 → 스냅샷 값으로 덮어씀. 카페24 자신의 시각끼리 비교하므로 서버 시계와 무관 | `store.overlay_recent_write`, `routes_products.load_product` |
| 옵션 | PUT/POST 응답을 `…snapshot.options` 에 저장 | 유예시간 안이면 스냅샷 우선 | `routes_product_info._apply_options_snapshot` |
| 품목 | 보낸 값(+응답)을 `…snapshot.variants` 에 코드별 누적 | 유예시간 안이면 해당 코드의 필드만 덮어씀 | `routes_product_info._apply_variant_snapshot` |
- 편집기 위에 **「카페24 반영 대기 중」 배너**(pending) 또는 **「관리자에서 직접 수정된
것으로 보임」 배너**(external)를 띄운다. 「다시 확인」은 「다시 읽기」와 같다.
- 적용·기본정보·상태 등 **모든 쓰기는 유효 현재값과 비교**해 바뀐 것만 보낸다. 이걸
안 하면 "A→B 로 바꾼 직후 B→A" 가 카페24의 지연된 값(A)과 같다고 판단돼 무시된다.
- 쓰기 뒤 화면은 **PUT 응답으로 그린다.** 응답은 쓰기 직후의 실제 값이다(GET 과 달리
지연이 없다 — 실물 예제 응답에 `updated_date` 가 갱신되어 온다). 다시 GET 하지 않는다.
- 스냅샷은 마이그레이션 `cafe24_db_004_write_snapshot.sql`(멱등)의 두 컬럼
(`last_write_snapshot` JSONB, `last_written_at`)을 쓴다. 미적용 상태에서는 스냅샷
저장이 실패해 로그가 남지만 적용 자체는 성공한다 — 반드시 적용할 것.
---
## 3-4. 정보 패널 API 사실 (카페24 문서 실물 예제 기준)
- **이미지 업로드**: `POST /admin/products/images` body `{"requests":[{"image":"<base64>"}]}`
→ `{"images":[{"path":"https://{domain}/web/upload/NNEditor/…"}]}`. 1장 10MB, 1호출 30MB,
1회 20장. 상품 대표이미지는 그 경로를 `PUT /admin/products/{no}` 의 `detail_image` 에
넣고 `image_upload_type: "A"`(대표이미지등록 — 목록/작은목록/축소를 카페24가 리사이징).
`B` 는 네 이미지를 각각 지정, `C` 는 웹FTP.
- **가격**: `price`(판매가) · `supply_price`(공급가, 문서상 "참조 목적") · `retail_price`
(소비자가). 문자열 `"11000.00"` 형식으로 보낸다(`store.parse_price`). 쇼핑몰 설정의
"판매가 계산 기준"이 상품가(B)면 `price` 대신 `price_excluding_tax` 를 써야 한다는 문서
주석이 있다 — 그 경우 카페24 오류 메시지가 그대로 화면에 뜬다.
- **옵션**: `GET/POST/PUT/DELETE /admin/products/{no}/options`, 응답 루트 `option`.
생성은 조합형(`option_type:"T"`, `option_list_type:"S"`) + 옵션값 목록 → **품목 자동
생성**. 수정(PUT)은 `original_options`(수정 전)와 `options`(수정 후)를 **같은 순서·개수**로
짝지어 보낸다 — 옵션명·옵션값 이름·`option_image_file`(옵션 버튼 이미지)·
`option_link_image`(연결 이미지)·`option_color`·`option_display_type`(S 셀렉트/P 미리보기/
B 버튼/R 라디오)만 바꿀 수 있고 **옵션값 추가/삭제는 불가**(문서). 연동형(E)은
`option_code`/`value_no`/`option_preset_code` 를 함께 보낸다. DELETE 는 옵션 사용안함 +
**품목 전부 삭제**(화면에서 확인창).
- **품목**: `GET /admin/products/{no}/variants` → `variants[]`(`variant_code` 12자,
`options[{name,value}]`, `custom_variant_code`, `additional_amount`, `display`, `selling`,
`quantity`, `image`…). `PUT /admin/products/{no}/variants` body `{"shop_no":1,
"requests":[{variant_code, custom_variant_code, additional_amount, display, selling…}]}`
1회 100건(초과 시 나눠 보냄). 재고(`quantity`)는 이 화면에서 건드리지 않는다.
- "옵션별 상품 이름" 은 옵션값(`option_text`)이고, "옵션별 썸네일" 은 `option_image_file`
(+ `option_link_image` 에도 같은 경로) 이며, "옵션별 상품코드/추가금액/진열" 은 품목
(`custom_variant_code`/`additional_amount`/`display`)이다 — 카페24 모델상 둘은 다른
리소스라 화면에서도 「옵션 저장」과 「품목 저장」이 따로 있다.
---
@@ -441,6 +533,14 @@ docker exec -i postgres-db psql -U postgres -d cafe24_db < scripts/sql/cafe24_db
docker exec -i postgres-db psql -U postgres -d cafe24_db < scripts/sql/cafe24_db_003_swiper_revisions.sql
```
읽기 지연 보정(3-3)·정보 패널을 쓰려면 마이그레이션 004 를 적용해야 한다(멱등).
```bash
docker exec -i postgres-db psql -U postgres -d cafe24_db < scripts/sql/cafe24_db_004_write_snapshot.sql
```
선택 env: `CAFE24_READ_LAG_GRACE_MIN`(기본 360) — 3-3 의 유예시간(분).
worker 가 도는지 확인:
```bash
@@ -474,6 +574,8 @@ DB·네트워크 없이 암호화 왕복, 토큰 만료/자동갱신, 상태 노
| 6 | 자동 종료/복원 · 롤백 | ✖ 되돌리기는 쓰지 않기로 결정. 버전 선택 복원만 남음 |
| 7 | 일괄 수정 · 일괄 예약 · Rate limit 제어 | ✖ 일괄수정은 사용하지 않기로 제거. 필요해지면 다시 논의 |
| 8 | 디자인 보관함 파일 편집(모바일 스와이프 · PC/모바일 상품상세 템플릿) — FTP | ✅ 완료. 예약 적용은 없음(상품 전용 개념이라 범위 밖) |
| 9 | 카페24 읽기 지연 보정("마지막 쓰기가 권위", 3-3) | ✅ 완료 (마이그레이션 004) |
| 10 | 상품 정보 패널 — 상품명/가격 · 대표이미지 · 옵션/품목 (3-4) | ✅ 완료 |
Phase 5 의 worker 는 `app/modules/cafe24/worker.py` 에 둔다 — `Dockerfile` 이
`COPY app/ ./app/` 만 하므로 `scripts/` 에 두면 이미지에 포함되지 않는다.