feat(카페24): 대표 이미지(썸네일) 예약 교체

- 편집기 아래 「예약 적용」 폼에 대표 이미지 파일 칸 — 고르면 그 시각에 교체
  (상세페이지·진열·판매와 한 예약에 같이 걸 수 있음, 이미지만도 가능)
- 마이그레이션 006: 예약 image_type/image_name + cafe24_schedule_images(BYTEA, CASCADE),
  "할 일 없는 예약" CHECK 에 이미지 포함
- worker: 이미지 먼저 set_main_image(즉시 교체와 같은 A 타입) → 스냅샷 → 상세페이지·진열/판매
- 예약 목록 「적용 내용」에 대표이미지 표시 + 미리보기 썸네일(GET /cafe24/schedules/{id}/image)
- 이미지 없는 예약 INSERT 는 006 컬럼을 안 써서 마이그레이션 전에도 기존 예약 등록 유지
- 테스트(경로·검증·worker 순서)·문서 갱신, cafe24.css 캐시 버전 올림

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-09 16:38:05 +09:00
parent 36834c65b2
commit 6822329ff2
17 changed files with 286 additions and 45 deletions
+11 -1
View File
@@ -243,10 +243,20 @@ Admin API(OAuth)로는 스킨 파일을 읽거나 쓸 방법이 없다(`config.p
| 항목 | 값 |
| --- | --- |
| 대표 이미지(썸네일) | 파일을 고르면 그 시각에 교체 / 안 고르면 변경 없음 (마이그레이션 006) |
| 상세페이지 HTML | 편집기 내용을 적용 / 적용 안 함 |
| 진열 | 진열 · 미진열 · 변경 없음 |
| 판매 | 판매 · 중지 · 변경 없음 |
- **대표 이미지 예약**(2026-11-09): 예약 폼의 파일 칸(`name="image"`, 폼은 multipart). 검증은 즉시
교체와 같은 `_read_image`(JPG·PNG·GIF·WEBP, 10MB). 파일은 `cafe24_schedule_images`(BYTEA,
예약 삭제 시 CASCADE)에, 형식·파일명은 `cafe24_product_schedules.image_type/image_name` 에 둔다 —
worker 는 web 과 다른 컨테이너라 로컬 파일을 공유하지 않기 때문. worker 는 **이미지를 먼저**
`products.set_main_image`(즉시 교체와 같은 A 타입) 로 올리고 스냅샷을 남긴 뒤 상세페이지·진열/판매를
쓴다 — 뒤 단계 실패로 재시도되면 같은 이미지를 한 번 더 올릴 뿐이라 안전하다. 예약 목록에
`GET /cafe24/schedules/{id}/image` 미리보기 썸네일. 이미지 없는 예약 INSERT 는 006 컬럼을 쓰지
않아 마이그레이션 전에도 기존 예약 등록은 깨지지 않는다.
- **등록**은 편집기 아래 「예약 적용」에서 한다. HTML 을 적용하는 예약이면 그 시점의
편집기 내용을 **DRAFT revision 으로 저장해 고정**한다 — 이후 편집기를 더 고쳐도
예약된 내용은 바뀌지 않는다(예약해둔 것이 조용히 달라지면 안 된다).
@@ -277,7 +287,7 @@ Admin API(OAuth)로는 스킨 파일을 읽거나 쓸 방법이 없다(`config.p
서버(`store.parse_schedule_at`)는 예전과 같은 형식을 받으므로 백엔드는 그대로다.
- **시각은 KST 로 해석**한다. 과거 시각은 거부하되
폼을 채우는 동안 시간이 흐른 경우를 위해 1분 여유를 둔다.
- **실행은 `app/modules/cafe24/worker.py`** — compose 서비스 `dbx-cafe24-worker` 가
- **실행은 `app/modules/cafe24/worker.py`** — compose 서비스 `cafe24-worker`(컨테이너 `dbx-cafe24-worker`)가
`--loop 60` 으로 돈다. 웹 요청 안에서 기다리는 방식은 프록시 타임아웃·재기동에
무너지므로 별도 프로세스여야 한다.
- worker 는 `claim_due_schedule` 로 **한 건씩 `FOR UPDATE SKIP LOCKED`** 로 잠그고
+3 -2
View File
@@ -361,7 +361,8 @@ DDL: `scripts/sql/cafe24_db_init.sql` (멱등). DB·역할(`cafe24_app`)·테이
| `cafe24_oauth_tokens` | 쇼핑몰별 OAuth 토큰(`mall_id` UNIQUE). access/refresh 는 **Fernet 암호문**으로 저장. 상품관리 + 향후 주문관리가 공유 |
| `cafe24_products` | 상품 캐시(`product_no` UNIQUE). 목록/검색 속도용이며 source of truth 는 언제나 카페24. `last_write_snapshot`(JSONB, 마이그레이션 004) 에 카페24 PUT 응답을 섹션별(`product`/`options`/`variants`)로 남겨 **읽기 지연**(PUT 뒤 GET 이 한동안 예전 값을 돌려줌) 동안 화면 기준으로 쓴다 |
| `cafe24_product_revisions` | 상세페이지 HTML 버전(append-only). `revision_type` SYNC/DRAFT/**BACKUP**/MANUAL/SCHEDULED/ROLLBACK |
| `cafe24_product_schedules` | 예약 작업. `status` PENDING/PROCESSING/SUCCESS/FAILED/CANCELLED, 재시도·자동종료·복원 대상 포함 |
| `cafe24_product_schedules` | 예약 작업. `status` PENDING/PROCESSING/SUCCESS/FAILED/CANCELLED, 재시도·자동종료·복원 대상 포함. `image_type`/`image_name`(006) = 대표 이미지 교체 예약 |
| `cafe24_schedule_images` | 대표 이미지 예약 파일(BYTEA, 10MB 이하, 예약 삭제 시 CASCADE) — 마이그레이션 006 |
| `cafe24_audit_logs` | 누가 무엇을 바꿨나. worker 수행분은 `actor='SCHEDULER'` |
| `cafe24_api_logs` | 카페24 API 호출 기록. **토큰/Authorization/client_secret 미기록** |
@@ -371,7 +372,7 @@ DDL: `scripts/sql/cafe24_db_init.sql` (멱등). DB·역할(`cafe24_app`)·테이
- 예약의 `restore_revision_id` 는 **예약 실행 순간** 만든 BACKUP 을 가리킨다(예약 생성 시점 값이 아님).
- 일괄 예약은 상품 1건당 1행 + 공통 `parent_job_id` — 한 상품 실패가 나머지를 막지 않는다.
- 토큰 암호화 키는 `.env` 의 `CAFE24_TOKEN_SECRET`. **값을 바꾸면 기존 토큰을 복호화할 수 없어 카페24 재연결이 필요하다.**
- 기존 운영 DB 에는 마이그레이션 002·003·004 를 순서대로 적용한다(전부 멱등):
- 기존 운영 DB 에는 마이그레이션 002·003·004·005·006 을 순서대로 적용한다(전부 멱등):
`docker exec -i postgres-db psql -U postgres -d cafe24_db < scripts/sql/cafe24_db_004_write_snapshot.sql`
### 운영 서버 초기화 (1회, 사용자 승인 후)