feat(cafe24): 예약관리 — 지정 시각에 상세페이지·진열/판매 자동 적용 (Phase 5)

되돌리기(자동 복원)는 요청대로 만들지 않았다. 예약은 "그 시각에 이 내용을 적용"
하나뿐이며, 한 예약에서 상세페이지 HTML·진열·판매를 각각 고를 수 있다. 셋 다
"변경 없음"인 예약은 DB CHECK 로 막는다.

등록은 편집기 아래 「예약 적용」에서 한다. HTML 을 적용하는 예약이면 그 시점의 편집기
내용을 DRAFT revision 으로 저장해 고정한다 — 이후 편집기를 더 고쳐도 예약된 내용이
바뀌지 않아야 한다. 단건 적용과 같은 다듬기(URL 인코딩 → 소스 정리)를 거치므로 화면에서
본 값이 그대로 저장된다. 예약 폼은 적용 폼과 형제로 두고(폼 중첩 불가) 편집기 내용을
JS 가 hidden 에 복사한다.

실행은 web 이 아니라 worker 다(app/modules/cafe24/worker.py, compose 서비스
dbx-cafe24-worker, --loop 60). 웹 요청 안에서 기다리면 프록시 타임아웃·재기동에
무너지고, 브라우저를 닫으면 실행되지 않는다.

worker 는 claim_due_schedule 로 한 건씩 FOR UPDATE SKIP LOCKED 로 잠그고 PROCESSING
으로 바꾼 뒤 잠금을 푼다. worker 가 둘 떠도 같은 예약을 두 번 적용하지 않고, 긴 API
호출 동안 DB 잠금을 쥐지 않는다. 적용 순서는 화면 편집과 같다(현재값 재조회 → BACKUP
→ PUT → 감사로그). HTML 없이 진열/판매만 바꾸는 예약은 상세설명을 읽지도 백업하지도
않는다. 실패는 1분→5분→15분 재시도 후 FAILED 확정이며, 한 건의 오류로 worker 가
죽지 않는다.

진열/판매를 한 번의 PUT 으로 함께 보내려고 products.update_product 를 추가했다
(update_descriptions 는 이 함수로 위임). None 인 필드는 payload 에서 빼므로 "건드리지
않음"이 그대로 표현된다.

DB: scripts/sql/cafe24_db_002_schedule_flags.sql (멱등) — set_display/set_selling
BOOLEAN NULL 추가 + 아무것도 하지 않는 예약 금지 제약. 되돌리기용 end_* 컬럼은 쓰지
않지만 삭제하지 않는다(파괴적).

시각은 KST 로 해석한다(datetime-local 은 타임존이 없다). 과거는 거부하되 폼을 채우는
동안 시간이 흐른 경우를 위해 1분 여유를 뒀다.

검증: 유닛테스트 66개 통과(신규 15개 — 3-상태 파싱, KST 해석·과거 거부·1분 여유,
요약 문구, payload 의 T/F 와 None 생략, 바꿀 것 없으면 미호출, worker 의 성공 경로
(백업+PC/모바일 동시+진열만 전송)·상태만 변경 시 백업 생략·재시도 후 최종 실패·
버전 누락 시 크래시 대신 실패·처리할 것 없을 때 종료). 예약 목록/편집기 예약 폼 렌더 확인.
라우트 16개. 실제 예약 실행은 서버 배포 후 확인 필요.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

app/integrations/cafe24/products.py

@@ -149,27 +149,72 @@ def fetch_descriptions(client: Cafe24Client, product_no: int) -> Descriptions:
     return descriptions_from_product(get_product(client, product_no))
 
 
+def _flag_value(flag: bool) -> str:
+    """카페24는 boolean 을 'T'/'F' 문자열로 받는다."""
+    return "T" if flag else "F"
+
+
 def build_update_payload(
     *,
-    description: str,
+    description: str | None = None,
     mobile_description: str | None = None,
+    display: bool | None = None,
+    selling: bool | None = None,
     shop_no: int | None = None,
 ) -> dict[str, Any]:
     """상품 수정 PUT body. 준 필드만 바뀌고 나머지는 유지된다(부분 수정).
 
-    `mobile_description=None` 이면 모바일 필드를 건드리지 않는다. PC/모바일
-    미분리(separated_mobile=False) 상품은 호출부가 같은 HTML 을 두 번 넘겨
-    두 필드를 함께 맞춘다.
+    `None` 인 항목은 payload 에 넣지 않는다 = 그 필드를 건드리지 않는다.
+    예약에서 "진열만 켜기"처럼 상세설명 없이 상태만 바꾸는 경우가 있으므로
+    description 도 생략할 수 있다.
     """
-    request: dict[str, Any] = {"description": description}
+    request: dict[str, Any] = {}
+    if description is not None:
+        request["description"] = description
     if mobile_description is not None:
         request["mobile_description"] = mobile_description
+    if display is not None:
+        request["display"] = _flag_value(display)
+    if selling is not None:
+        request["selling"] = _flag_value(selling)
     payload: dict[str, Any] = {"request": request}
     if shop_no:
         payload["shop_no"] = int(shop_no)
     return payload
 
 
+def update_product(
+    client: Cafe24Client,
+    product_no: int,
+    *,
+    description: str | None = None,
+    mobile_description: str | None = None,
+    display: bool | None = None,
+    selling: bool | None = None,
+    shop_no: int | None = None,
+) -> dict[str, Any]:
+    """상품 부분 수정. 상세설명·진열·판매를 한 번의 호출로 바꿀 수 있다.
+
+    바꿀 것이 하나도 없으면 호출하지 않고 빈 dict 를 돌려준다.
+
+    ⚠️ 상세설명을 바꿀 때는 쓰기 직전 카페24 현재 HTML 을 다시 읽어 BACKUP
+       revision 을 남길 것(`docs/CAFE24_MODULE.md` 규칙). 이 함수는 백업하지 않는다.
+    """
+    payload = build_update_payload(
+        description=description,
+        mobile_description=mobile_description,
+        display=display,
+        selling=selling,
+        shop_no=shop_no,
+    )
+    if not payload["request"]:
+        return {}
+    no = int(product_no)
+    response = client.put(f"/admin/products/{no}", json=payload, product_no=no)
+    product = response.get("product")
+    return product if isinstance(product, dict) else response
+
+
 def update_descriptions(
     client: Cafe24Client,
     product_no: int,
@@ -178,26 +223,14 @@ def update_descriptions(
     mobile_description: str | None = None,
     shop_no: int | None = None,
 ) -> dict[str, Any]:
-    """상세설명 교체. 성공하면 카페24가 돌려준 상품 dict.
-
-    실패는 Cafe24ApiError/Cafe24AuthError 로 올라오므로 호출부는 예외가 없을
-    때만 성공으로 처리하면 된다.
-
-    ⚠️ 쓰기 직전 항상 카페24 현재 HTML 을 다시 읽어 BACKUP revision 을 남길
-       것(`docs/CAFE24_MODULE.md` 보안 규칙). 이 함수는 백업을 하지 않는다.
-    """
-    no = int(product_no)
-    payload = client.put(
-        f"/admin/products/{no}",
-        json=build_update_payload(
-            description=description,
-            mobile_description=mobile_description,
-            shop_no=shop_no,
-        ),
-        product_no=no,
+    """상세설명만 교체하는 지름길. 실제 전송은 `update_product` 가 한다."""
+    return update_product(
+        client,
+        product_no,
+        description=description,
+        mobile_description=mobile_description,
+        shop_no=shop_no,
     )
-    product = payload.get("product")
-    return product if isinstance(product, dict) else payload
 
 
 def normalize_product(raw: dict[str, Any]) -> dict[str, Any]: