{{ r.action_label }}
+ {% if r.image_type %}{% endif %}
{% if r.status == 'SUCCESS' %}{{ r.status_label }}
{% elif r.status == 'FAILED' %}{{ r.status_label }}
diff --git a/app/modules/cafe24/templates/cafe24/system.html b/app/modules/cafe24/templates/cafe24/system.html
index ac7db6b..edcebe2 100644
--- a/app/modules/cafe24/templates/cafe24/system.html
+++ b/app/modules/cafe24/templates/cafe24/system.html
@@ -1,7 +1,7 @@
{% extends "erp_base.html" %}
{% block head_extra %}
-
+
{% endblock %}
{% block content %}
diff --git a/app/modules/cafe24/tests/fakes.py b/app/modules/cafe24/tests/fakes.py
index 38590c4..35edc0d 100644
--- a/app/modules/cafe24/tests/fakes.py
+++ b/app/modules/cafe24/tests/fakes.py
@@ -411,6 +411,13 @@ class FakeCafe24:
def post(self, path, *, json=None, **kw):
self.calls.append(("POST", path, json))
+ if path == f"/admin/products/{self.product_no}/images": # 대표이미지 등록(A 타입)
+ self._tick()
+ n = sum(1 for c in self.calls if c[1] == path)
+ image = {k: f"/web/product/{k.split('_')[0]}/{self.product_no}_{n}.png"
+ for k in ("detail_image", "list_image", "tiny_image", "small_image")}
+ self.state.update(image)
+ return {"image": image}
out = self._options_call("POST", path, json)
return copy.deepcopy(out) if out is not None else {}
diff --git a/app/modules/cafe24/tests/test_cafe24.py b/app/modules/cafe24/tests/test_cafe24.py
index f31e49a..00d8593 100644
--- a/app/modules/cafe24/tests/test_cafe24.py
+++ b/app/modules/cafe24/tests/test_cafe24.py
@@ -649,6 +649,9 @@ def test_describe_schedule_action():
assert store.describe_schedule_action(
has_html=False, set_display=None, set_selling=None
) == "없음"
+ assert store.describe_schedule_action(
+ has_html=True, set_display=None, set_selling=None, has_image=True
+ ) == "대표이미지 · 상세페이지"
def test_normalize_schedule_status():
diff --git a/app/modules/cafe24/worker.py b/app/modules/cafe24/worker.py
index 5f078ed..209b0eb 100644
--- a/app/modules/cafe24/worker.py
+++ b/app/modules/cafe24/worker.py
@@ -50,6 +50,7 @@ from app.timezone import now_kst
from . import store, writes
from .common import read_lag_grace_minutes
+from .routes_products import load_product
logger = logging.getLogger("cafe24.worker")
@@ -77,9 +78,28 @@ def _summary(row: dict[str, Any]) -> str:
has_html=bool(row.get("revision_id")),
set_display=row.get("set_display"),
set_selling=row.get("set_selling"),
+ has_image=bool(row.get("image_type")),
)
+def _apply_image(st: Any, api: Any, product_no: int, data: bytes, content_type: str) -> str:
+ """예약 대표 이미지 교체(routes_product_info.product_image 와 같은 순서). 반환: 새 detail_image.
+
+ 상세페이지·진열/판매보다 **먼저** 한다 — 뒤 단계가 실패해 재시도되면 같은 이미지를 한 번 더
+ 올릴 뿐이라 안전하고, 앞 단계(시도 기록)가 SUCCESS 로 복구된 뒤 이미지가 빠지는 일이 없다.
+ """
+ current, _ = load_product(st, api, product_no)
+ if not current:
+ raise Cafe24Error("카페24에서 상품을 찾지 못했습니다.")
+ images = products.set_main_image(api.client, product_no, data, content_type=content_type)
+ if not images.get("detail_image"):
+ raise Cafe24Error("카페24가 등록된 이미지 경로를 돌려주지 않았습니다.")
+ writes.remember_product_write(
+ st, product_no, {**current, **images, "updated_date": now_kst().isoformat(timespec="seconds")}
+ )
+ return str(images["detail_image"])
+
+
def _retry_or_fail(st: Any, row: dict[str, Any], token: str, error: str) -> str:
"""재시도 예산 안이면 PENDING + 대기, 아니면 FAILED. 반환: 결과 상태."""
retry_count = int(row.get("retry_count") or 0)
@@ -113,6 +133,8 @@ def run_one(st: Any, api: Any, row: dict[str, Any]) -> str:
def fence() -> bool:
return bool(st.renew_schedule_lease(schedule_id, token, ttl_seconds=lease))
+ image_type = str(row.get("image_type") or "")
+ new_image = ""
try:
html: str | None = None
if revision_id:
@@ -122,17 +144,26 @@ def run_one(st: Any, api: Any, row: dict[str, Any]) -> str:
html = str(revision.get("html_content") or "")
if not html.strip():
raise Cafe24Error(f"버전 {revision_id} 의 내용이 비어 있습니다.")
+ image = st.get_schedule_image(schedule_id) if image_type else b""
+ if image_type and not image:
+ raise Cafe24Error("예약해 둔 대표 이미지 파일을 찾을 수 없습니다.")
with writes.write_lock(
st, writes.product_lock_key(product_no), actor=ACTOR,
purpose=f"예약 #{schedule_id} 실행", wait_seconds=0,
) as lock:
- outcome = writes.write_product(
- st, api, product_no,
- lock=lock, origin=store.ORIGIN_SCHEDULED, actor=ACTOR, html=html,
- set_display=set_display, set_selling=set_selling,
- schedule_id=schedule_id, target_revision_id=int(revision_id) if revision_id else None,
- memo=f"예약 #{schedule_id} 적용", extra_fence=fence,
- )
+ if image:
+ if not fence():
+ raise writes.WriteBusy("예약 lease 를 잃었습니다 — 다른 worker 가 처리합니다.")
+ new_image = _apply_image(st, api, product_no, image, image_type)
+ outcome = writes.WriteOutcome()
+ if html is not None or set_display is not None or set_selling is not None:
+ outcome = writes.write_product(
+ st, api, product_no,
+ lock=lock, origin=store.ORIGIN_SCHEDULED, actor=ACTOR, html=html,
+ set_display=set_display, set_selling=set_selling,
+ schedule_id=schedule_id, target_revision_id=int(revision_id) if revision_id else None,
+ memo=f"예약 #{schedule_id} 적용", extra_fence=fence,
+ )
except writes.WriteSetupError as exc:
st.finish_schedule(schedule_id, token=token, status=store.STATUS_PENDING, error=str(exc),
next_retry_at=now_kst() + timedelta(seconds=SETUP_RETRY_SECONDS))
@@ -171,6 +202,7 @@ def run_one(st: Any, api: Any, row: dict[str, Any]) -> str:
revision_id=outcome.revision_id or (int(revision_id) if revision_id else None),
schedule_id=schedule_id, result="SUCCESS",
detail=summary + (f" (백업 {outcome.backup_id})" if outcome.backup_id else "")
+ + (f" / 대표이미지 → '{new_image}'" if new_image else "")
+ (f" / {note}" if note else ""),
)
logger.info("예약 #%s 상품 %s 적용 완료 — %s", schedule_id, product_no, summary)
diff --git a/app/static/cafe24.css b/app/static/cafe24.css
index 17ac2ed..dc3be11 100644
--- a/app/static/cafe24.css
+++ b/app/static/cafe24.css
@@ -746,6 +746,27 @@
grid-column: 1 / -1;
}
+/* 예약 대표 이미지 — 칸 제목은 다른 칸과 같게, 파일 고르기는 가로 한 줄 */
+.cf24-schedule-image {
+ display: flex;
+ flex-direction: column;
+ gap: 4px;
+ font-size: var(--text-caption, 12px);
+ color: var(--color-midtone-gray, #737373);
+}
+.cf24-schedule-grid label.cf24-file-pick {
+ flex-direction: row;
+}
+.cf24-sched-img {
+ display: block;
+ width: 48px;
+ height: 48px;
+ margin-top: 4px;
+ object-fit: cover;
+ border: 1px solid var(--color-border, #e5e5e5);
+ border-radius: 4px;
+}
+
/* 날짜/시간을 별도 input 으로 나눈다 — datetime-local 은 한국어 로캘에서
"2026. 08. 14. 오후 07:00" 형태로 길어져 auto-fit minmax(160px, 1fr) 칸에
잘렸다(실측). 지금은 표시 텍스트를 우리가 직접 그리므로(아래 .cf24-dt-*) 폭을
diff --git a/docs/CAFE24_MODULE.md b/docs/CAFE24_MODULE.md
index 1244492..c00d6d8 100644
--- a/docs/CAFE24_MODULE.md
+++ b/docs/CAFE24_MODULE.md
@@ -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`** 로 잠그고
diff --git a/docs/DATABASES.md b/docs/DATABASES.md
index cd1eb06..17beddd 100644
--- a/docs/DATABASES.md
+++ b/docs/DATABASES.md
@@ -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회, 사용자 승인 후)
diff --git a/scripts/sql/cafe24_db_006_schedule_image.sql b/scripts/sql/cafe24_db_006_schedule_image.sql
new file mode 100644
index 0000000..8976eba
--- /dev/null
+++ b/scripts/sql/cafe24_db_006_schedule_image.sql
@@ -0,0 +1,54 @@
+-- =====================================================================
+-- cafe24_db 006 — 예약에 대표 이미지 교체 추가 (2026-11-09)
+-- =====================================================================
+-- 멱등(idempotent): 여러 번 실행해도 안전. DROP TABLE/TRUNCATE 없음.
+--
+-- 실행:
+-- docker exec -i postgres-db psql -v ON_ERROR_STOP=1 -U postgres -d cafe24_db \
+-- < scripts/sql/cafe24_db_006_schedule_image.sql
+--
+-- 배경:
+-- 지정 시각에 상품 대표 이미지(썸네일)를 교체하는 예약. 등록 때 올린 파일을
+-- 그 시각까지 보관해야 하므로 바이트를 DB 에 둔다(worker 는 web 과 다른
+-- 컨테이너라 로컬 파일을 공유하지 않는다). 예약 목록(s.*)이 무거워지지 않게
+-- 바이트는 별도 테이블에 둔다.
+-- cafe24_product_schedules.image_type = '' → 이미지 교체 없음
+-- 'image/png' 등 → 그 시각에 교체
+--
+-- 롤백(이미지 예약을 쓰지 않을 때만):
+-- ALTER TABLE cafe24_product_schedules DROP CONSTRAINT chk_cafe24_schedule_has_action;
+-- ALTER TABLE cafe24_product_schedules ADD CONSTRAINT chk_cafe24_schedule_has_action CHECK (
+-- revision_id IS NOT NULL OR set_display IS NOT NULL OR set_selling IS NOT NULL);
+-- DROP TABLE cafe24_schedule_images;
+-- ALTER TABLE cafe24_product_schedules DROP COLUMN image_type, DROP COLUMN image_name;
+-- =====================================================================
+
+\set ON_ERROR_STOP on
+
+ALTER TABLE cafe24_product_schedules
+ ADD COLUMN IF NOT EXISTS image_type TEXT NOT NULL DEFAULT '',
+ ADD COLUMN IF NOT EXISTS image_name TEXT NOT NULL DEFAULT '';
+
+COMMENT ON COLUMN cafe24_product_schedules.image_type IS
+ '예약 시각에 교체할 대표 이미지의 형식(image/png 등). 빈 값이면 이미지 교체 없음';
+COMMENT ON COLUMN cafe24_product_schedules.image_name IS
+ '등록 때 올린 대표 이미지 파일명(표시용)';
+
+CREATE TABLE IF NOT EXISTS cafe24_schedule_images (
+ schedule_id BIGINT PRIMARY KEY REFERENCES cafe24_product_schedules(id) ON DELETE CASCADE,
+ data BYTEA NOT NULL,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+COMMENT ON TABLE cafe24_schedule_images IS '예약 대표 이미지 파일(10MB 이하)';
+
+-- 아무것도 하지 않는 예약은 만들 수 없게 한다 — 이미지 교체도 "할 일"로 센다.
+ALTER TABLE cafe24_product_schedules
+ DROP CONSTRAINT IF EXISTS chk_cafe24_schedule_has_action;
+ALTER TABLE cafe24_product_schedules
+ ADD CONSTRAINT chk_cafe24_schedule_has_action CHECK (
+ revision_id IS NOT NULL OR set_display IS NOT NULL OR set_selling IS NOT NULL OR image_type <> ''
+ );
+
+GRANT SELECT, INSERT, UPDATE, DELETE ON cafe24_schedule_images TO cafe24_app;
+
+SELECT 'cafe24_db 006 applied' AS status;
diff --git a/tests/test_cafe24_db.py b/tests/test_cafe24_db.py
index 1b4da91..78fffba 100644
--- a/tests/test_cafe24_db.py
+++ b/tests/test_cafe24_db.py
@@ -583,6 +583,50 @@ def test_worker_real_db_success_and_needs_review():
assert q("SELECT status FROM cafe24_write_attempts WHERE schedule_id=%s", sid2)[0]["status"] == "RECORDED"
+def test_schedule_main_image_route_and_worker():
+ """대표 이미지 예약(006): 등록 → 파일 DB 보관 → 그 시각에 worker 가 교체 → 목록 미리보기."""
+ no, cafe = _new_product("
A
")
+ at = (now_kst() + timedelta(days=1)).strftime("%Y-%m-%dT%H:%M")
+ png = b"\x89PNG\r\n\x1a\n" + b"x" * 64
+ form = {"product_no": str(no), "scheduled_at": at, "set_display": "", "set_selling": ""}
+ # 내용 없는 예약(이미지도 안 고름 — 이름 없는 빈 파트) 거부
+ resp = req("POST", "/cafe24/schedules", data=form, files={"image": ("", b"", "application/octet-stream")})
+ assert "하나 이상" in _location(resp).get("err", ""), resp.headers
+ # 이미지 아닌 파일 거부
+ resp = req("POST", "/cafe24/schedules", data=form, files={"image": ("a.txt", b"hi", "text/plain")})
+ assert "이미지만" in _location(resp).get("err", ""), resp.headers
+ resp = req("POST", "/cafe24/schedules", data=form, files={"image": ("가을.png", png, "image/png")})
+ assert "대표이미지" in _location(resp).get("msg", ""), resp.headers
+ sid = q("SELECT id FROM cafe24_product_schedules WHERE product_no=%s", no)[0]["id"]
+ row = ST.get_schedule(sid)
+ assert row["image_type"] == "image/png" and row["image_name"] == "가을.png" and row["revision_id"] is None
+ got = req("GET", f"/cafe24/schedules/{sid}/image")
+ assert got.status_code == 200 and got.content == png and got.headers["content-type"] == "image/png"
+ listed = json.loads(req("GET", "/cafe24/schedules").text.split("\n", 1)[1])["rows"]
+ mine = [r for r in listed if r["id"] == sid][0]
+ assert mine["image_type"] == "image/png" and mine["action_label"] == "대표이미지", mine
+
+ q("UPDATE cafe24_product_schedules SET scheduled_at = now() - interval '3000 days' WHERE id=%s RETURNING id", sid)
+ worker.process_once(ST, fakes.FakeApi(MULTI))
+ row = ST.get_schedule(sid)
+ assert row["status"] == "SUCCESS", row
+ posts = [c for c in cafe.calls if c[0] == "POST" and c[1].endswith("/images")]
+ assert len(posts) == 1 and posts[0][2]["request"]["detail_image"].startswith("data:image/png;base64,")
+ assert cafe.state["detail_image"] == f"/web/product/detail/{no}_1.png"
+ assert [c for c in cafe.calls if c[0] == "PUT"] == [] # 이미지만 — 상세설명·진열 PUT 없음
+ assert ST.get_write_snapshot(no)["product"]["data"]["detail_image"] == cafe.state["detail_image"]
+
+ # 이미지 + 진열을 한 예약에: 이미지 먼저, 그다음 진열 PUT
+ no2, cafe2 = _new_product("
A
")
+ sid2 = ST.create_schedule(product_no=no2, scheduled_at=now_kst() - timedelta(days=3000), revision_id=None,
+ set_display=False, set_selling=None, image=png, image_type="image/png", image_name="b.png")
+ worker.process_once(ST, fakes.FakeApi(MULTI))
+ assert ST.get_schedule(sid2)["status"] == "SUCCESS"
+ kinds = [(c[0], c[1].rsplit("/", 1)[-1]) for c in cafe2.calls if c[0] in ("POST", "PUT")]
+ assert kinds == [("POST", "images"), ("PUT", str(no2))], kinds
+ assert cafe2.state["display"] == "F" and cafe2.state["detail_image"].endswith(f"{no2}_1.png")
+
+
def test_worker_real_db_recovers_crash_after_remote_ok():
no, cafe = _new_product("