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

증상: 상세페이지를 적용해도 편집기에 수정 전 소스가 보이고 한참 뒤에야
반영됨. 원인은 우리 캐시가 아니라(전부 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:
2026-09-18 18:07:42 +09:00
parent 8ea0db9245
commit 40766d805d
21 changed files with 2782 additions and 99 deletions
@@ -0,0 +1,96 @@
{# 오른쪽 상품 정보 패널 조각.
기본 정보(상품명·판매가·공급가·소비자가) · 대표 이미지 · 옵션/품목.
전체 페이지(products.html)가 include 하고, 상품을 바꾸면 JS 가 /products/{no}/pane
에서 같은 조각을 다시 받아 끼워 넣는다. 그래서 <script> 를 두지 않는다 — JS 는
products.html 의 cf24BindSide() 에 있다. 쓰기는 전부 routes_product_info.py 의
JSON API 로 하고, 화면은 **응답값**으로 다시 그린다(요청값을 낙관 반영하지 않는다). #}
{% if desc %}
<div class="cf24-side" id="cf24-side" data-product-no="{{ product_no }}">
{# ── 기본 정보 ── #}
<section class="cf24-side-sec">
<h4 class="cf24-side-title">기본 정보</h4>
{% if scalar_stale %}
<p class="cf24-side-note cf24-side-note-warn">
카페24 관리자 API 가 아직 이전 값을 돌려주고 있어 마지막으로 적용한 값을 표시합니다.
</p>
{% endif %}
<form class="cf24-side-form" id="cf24-basic-form" autocomplete="off">
<label class="cf24-side-field">
<span>상품명</span>
<input type="text" name="product_name" maxlength="250" value="{{ info.product_name }}" />
</label>
<div class="cf24-side-grid3">
<label class="cf24-side-field">
<span>판매가</span>
<input type="text" name="price" inputmode="numeric" value="{{ info.price_plain }}" placeholder="원" />
</label>
<label class="cf24-side-field">
<span>공급가</span>
<input type="text" name="supply_price" inputmode="numeric" value="{{ info.supply_price_plain }}" placeholder="원" />
</label>
<label class="cf24-side-field">
<span>소비자가</span>
<input type="text" name="retail_price" inputmode="numeric" value="{{ info.retail_price_plain }}" placeholder="원" />
</label>
</div>
<div class="cf24-side-actions">
<span class="cf24-muted" id="cf24-basic-msg"></span>
<button class="erp-btn erp-btn-primary" type="submit" id="cf24-basic-save">카페24에 저장</button>
</div>
</form>
</section>
{# ── 대표 이미지 ── #}
<section class="cf24-side-sec">
<h4 class="cf24-side-title">대표 이미지</h4>
<div class="cf24-image-box" id="cf24-image-box">
{% if info.detail_image %}
<a href="{{ info.detail_image }}" target="_blank" rel="noopener noreferrer" id="cf24-image-link">
<img class="cf24-image-main" id="cf24-image-main" src="{{ info.detail_image }}" alt="대표 이미지" />
</a>
{% else %}
<a href="#" target="_blank" rel="noopener noreferrer" id="cf24-image-link" class="is-hidden">
<img class="cf24-image-main" id="cf24-image-main" src="" alt="대표 이미지" />
</a>
<div class="cf24-image-empty" id="cf24-image-empty">등록된 대표 이미지가 없습니다.</div>
{% endif %}
</div>
<div class="cf24-image-thumbs" id="cf24-image-thumbs">
{# 이미지가 없는 종류는 칸째로 숨긴다(빈 칸에 이름만 남으면 어색하다).
업로드 뒤 응답에 경로가 오면 JS 가 칸을 다시 보인다. #}
{% for key, label in (("list_image", "목록"), ("tiny_image", "작은목록"), ("small_image", "축소")) %}
<figure class="cf24-image-thumb{% if not info[key] %} is-hidden{% endif %}" data-image-figure="{{ key }}">
<img src="{{ info[key] }}" alt="{{ label }}" data-image-key="{{ key }}" />
<figcaption>{{ label }}</figcaption>
</figure>
{% endfor %}
</div>
<form class="cf24-side-form" id="cf24-image-form">
<label class="cf24-file-pick">
<input type="file" name="file" id="cf24-image-file" accept="image/jpeg,image/png,image/gif,image/webp" />
<span class="erp-btn erp-btn-outline">파일 선택</span>
<span class="cf24-file-name" id="cf24-image-filename">선택된 파일 없음</span>
</label>
<div class="cf24-side-actions">
<span class="cf24-muted" id="cf24-image-msg">JPG·PNG·GIF·WEBP, 10MB 이하. 목록/축소 이미지는 카페24가 자동 생성합니다.</span>
<button class="erp-btn erp-btn-primary" type="submit" id="cf24-image-save" disabled>업로드하여 교체</button>
</div>
</form>
</section>
{# ── 옵션 / 품목 — 펼칠 때 JSON 으로 불러온다(카페24 호출 2회) ── #}
<details class="cf24-side-sec cf24-side-details" id="cf24-options-details">
<summary class="cf24-side-title">옵션 / 품목 <span class="cf24-muted" id="cf24-options-count"></span></summary>
<div class="cf24-options-body" id="cf24-options-body">
<p class="cf24-muted">불러오는 중…</p>
</div>
</details>
</div>
{% else %}
<div class="cf24-side cf24-side-empty">
<p class="cf24-muted">카페24 조회에 실패해 상품 정보를 표시할 수 없습니다.</p>
</div>
{% endif %}