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>

docs/CAFE24_MODULE.md

@@ -27,6 +27,8 @@ app/modules/cafe24/             ← 상품관리 모듈
 ├─ router.py           루트 라우터(prefix=/cafe24) + 서브 라우터 결합
 ├─ routes_products.py  2분할 화면 · 편집기 조각 · 적용(쓰기)
 ├─ routes_bulk.py      일괄수정 (검사 → 선택 적용)
+├─ routes_schedules.py 예약 등록·목록·취소
+├─ worker.py           예약 실행기 (compose 서비스 dbx-cafe24-worker)
 ├─ routes_system.py    연결(OAuth)·상태·API 로그·작업 로그
 ├─ common.py           가드/컨텍스트 헬퍼 (순환 import 방지로 분리)
 ├─ db.py               Cafe24Store (cafe24_db, psycopg3 raw SQL)
@@ -57,7 +59,10 @@ app/modules/cafe24/             ← 상품관리 모듈
 | `GET /cafe24/bulk` | 일괄수정 화면 (`<style>` 통일) | `cafe24` |
 | `GET /cafe24/bulk/scan/{product_no}` | 상품 1건 검사 (JSON, 읽기 전용) | `cafe24` |
 | `POST /cafe24/bulk/apply/{product_no}` | 상품 1건 적용 (JSON) | `cafe24` |
-| `GET /cafe24/schedules` | 예약관리 (Phase 5 안내) | `cafe24` |
+| `GET /cafe24/schedules` | 예약 목록 · 취소 | `cafe24` |
+| `POST /cafe24/schedules` | 예약 등록 (편집기에서) | `cafe24` |
+| `POST /cafe24/schedules/{id}/cancel` | 대기 중 예약 취소 | `cafe24` |
+| `GET /cafe24/schedules/preview/{product_no}` | 현재 진열/판매 상태 (JSON) | `cafe24` |
 | `GET /cafe24/system` | 연결 상태 · API 로그 · 작업 로그 | `cafe24` |
 | `GET /cafe24/system/oauth/start` | 카페24 인증 시작 | **admin** |
 | `GET /cafe24/oauth/callback` | 카페24 콜백 (code→토큰) | **admin** |
@@ -170,6 +175,40 @@ app/modules/cafe24/             ← 상품관리 모듈
 
 ---
 
+### 2-4. 예약관리 (지정 시각 자동 적용)
+
+**되돌리기(자동 복원)는 쓰지 않는다.** 예약은 "그 시각에 이 내용을 적용" 하나뿐이다.
+한 예약에서 세 가지를 각각 고를 수 있고, 하나 이상은 반드시 골라야 한다(DB CHECK 제약).
+
+| 항목 | 값 |
+| --- | --- |
+| 상세페이지 HTML | 편집기 내용을 적용 / 적용 안 함 |
+| 진열 | 진열 · 미진열 · 변경 없음 |
+| 판매 | 판매 · 중지 · 변경 없음 |
+
+- **등록**은 편집기 아래 「예약 적용」에서 한다. HTML 을 적용하는 예약이면 그 시점의
+  편집기 내용을 **DRAFT revision 으로 저장해 고정**한다 — 이후 편집기를 더 고쳐도
+  예약된 내용은 바뀌지 않는다(예약해둔 것이 조용히 달라지면 안 된다).
+  단건 적용과 같은 다듬기(URL 인코딩 → 소스 정리)를 거치므로 화면에서 본 값이 저장된다.
+- 예약 폼은 적용 폼과 **형제**로 둔다(HTML 은 폼 중첩을 허용하지 않는다). 편집기 내용은
+  JS 가 hidden 에 복사해 함께 보낸다.
+- **시각은 KST 로 해석**한다(`datetime-local` 은 타임존이 없다). 과거 시각은 거부하되
+  폼을 채우는 동안 시간이 흐른 경우를 위해 1분 여유를 둔다.
+- **실행은 `app/modules/cafe24/worker.py`** — compose 서비스 `dbx-cafe24-worker` 가
+  `--loop 60` 으로 돈다. 웹 요청 안에서 기다리는 방식은 프록시 타임아웃·재기동에
+  무너지므로 별도 프로세스여야 한다.
+- worker 는 `claim_due_schedule` 로 **한 건씩 `FOR UPDATE SKIP LOCKED`** 로 잠그고
+  PROCESSING 으로 바꾼 뒤 잠금을 푼다. worker 가 둘 떠 있어도 같은 예약을 두 번
+  적용하지 않고, 긴 API 호출 동안 DB 잠금을 쥐고 있지도 않는다.
+- 적용 순서는 화면 편집과 같다: **현재값 재조회 → BACKUP revision → PUT → SUCCESS +
+  감사로그**(`actor=SCHEDULER`, `action=schedule_apply`). HTML 없이 진열/판매만 바꾸는
+  예약은 상세설명을 읽지도, 백업하지도 않는다.
+- 실패는 `store.MAX_RETRY`(3) 안에서 1분 → 5분 → 15분 간격으로 재시도하고, 소진되면
+  `FAILED` 로 확정한다. 한 건의 오류가 worker 를 죽이지 않는다.
+- **대기(PENDING) 상태만 취소**할 수 있다. 실행 중/완료된 예약은 건드리지 않는다.
+
+---
+
 ## 3. OAuth 흐름
 
 ```
@@ -311,7 +350,19 @@ CAFE24_TOKEN_SECRET=<openssl rand -hex 32>
 ### 5-4. 재기동 + 권한 부여
 
 ```bash
-cd /opt/www/main && docker compose up -d --build web
+cd /opt/www/main && docker compose up -d --build web cafe24-worker
+```
+
+예약 기능을 쓰려면 마이그레이션 002 를 먼저 적용해야 한다(진열/판매 예약 컬럼).
+
+```bash
+docker exec -i postgres-db psql -U postgres -d cafe24_db < scripts/sql/cafe24_db_002_schedule_flags.sql
+```
+
+worker 가 도는지 확인:
+
+```bash
+cd /opt/www/main && docker compose logs --tail=20 cafe24-worker
 ```
 
 관리자 페이지(`/admin`)에서 직원에게 **카페24 상품관리** 권한을 부여한다.
@@ -337,8 +388,8 @@ DB·네트워크 없이 암호화 왕복, 토큰 만료/자동갱신, 상태 노
 | 2 | 상품 목록·검색·현재 HTML 조회 | ✅ 완료 |
 | 3 | 편집기 · 미리보기 · Diff · 초안 | ◐ 문법 강조 편집기 + 소스 정리 완료. 미리보기·Diff·초안 예정 |
 | 4 | 즉시 적용 · BACKUP · Revision · 감사로그 | ✅ 완료 |
-| 5 | 예약 DB · Worker(compose 서비스) · 예약관리 화면 | 예정 |
-| 6 | 자동 종료/복원 · 롤백 | 예정 |
+| 5 | 예약 DB · Worker(compose 서비스) · 예약관리 화면 | ✅ 완료 |
+| 6 | 자동 종료/복원 · 롤백 | ✖ 되돌리기는 쓰지 않기로 결정. 버전 선택 복원만 남음 |
 | 7 | 일괄 수정 · 일괄 예약 · Rate limit 제어 | ◐ `<style>` 통일 일괄수정 완료. 일괄 예약 예정 |
 
 Phase 5 의 worker 는 `app/modules/cafe24/worker.py` 에 둔다 — `Dockerfile` 이