dbx-main/docs/CAFE24_MODULE.md

# 카페24 상품 상세페이지 관리 모듈 (cafe24)

> 카페24 관리자 페이지에 직접 들어가지 않고 상품 상세페이지를 조회·편집·예약
> 적용하고, 언제든 이전 상태로 되돌리기 위한 운영용 모듈.
> main-app ERP 에 편입된 **모듈**이다(별도 앱/포트 아님). 인증은 기존 Google
> OAuth + 권한키 `cafe24` 를 재사용한다.

---

## 1. 구조 — 왜 두 곳으로 나눴나

향후 **카페24 주문관리**(주문 조회·송장 일괄등록·취소/반품/교환)를 같은
프로젝트에 추가할 예정이다. 그래서 카페24 인증/전송은 상품관리에 종속시키지
않고 공통 계층으로 분리했다.

```
app/integrations/cafe24/        ← 공통 (상품관리 + 향후 주문관리 공유)
├─ config.py    환경변수 → Cafe24Config / Cafe24FtpConfig (하드코딩 금지)
├─ crypto.py    토큰 Fernet 암복호화
├─ oauth.py     인증 URL / code→token / refresh
├─ tokens.py    TokenService — 저장·만료판정·자동갱신(행 잠금)
├─ client.py    Cafe24Client — 전송·재시도·401/429/5xx·호출간격·API 로그
├─ products.py  상품 엔드포인트 래퍼   (향후 orders.py 를 형제로 추가)
├─ design_ftp.py 디자인 보관함 FTP 읽기/쓰기 (product-swiper.js·detail.html 등 스킨 파일)
└─ errors.py    공통 예외

app/modules/cafe24/             ← 상품관리 모듈
├─ router.py           루트 라우터(prefix=/cafe24) + 서브 라우터 결합
├─ routes_products.py  3분할 화면 · 편집기+정보패널 조각 · 적용(쓰기) · 읽기 지연 보정
├─ routes_product_info.py 오른쪽 정보 패널 JSON API — 상품명/가격 · 대표이미지 ·
│                      옵션(생성/수정/삭제) · 품목(자체코드/추가금액/진열/판매)
├─ routes_schedules.py 예약 등록·목록·취소
├─ routes_design_files.py 디자인 보관함 파일 편집·적용(FTP) — 모바일 스와이프·
│                      PC/모바일 상품상세 템플릿(file_key 로 하나의 라우트 공유)
├─ worker.py           예약 실행기 (compose 서비스 dbx-cafe24-worker)
├─ routes_system.py    연결(OAuth)·상태·API 로그·작업 로그
├─ common.py           가드/컨텍스트 헬퍼 (순환 import 방지로 분리)
├─ db.py               Cafe24Store (cafe24_db, psycopg3 raw SQL)
├─ store.py            순수 로직 — 상수·상태전이·재시도 규칙·검증
├─ tests/              DB/네트워크 없는 유닛테스트
└─ templates/cafe24/   _nav.html · products.html(3분할 + 모든 JS) ·
                       _editor.html(가운데 조각) · _side.html(오른쪽 정보 패널 조각) ·
                       _panes.html(두 조각 묶음 — /pane 응답) · design_editor.html ·
                       schedules.html · system.html
```

**규칙: 라우터에서 `httpx`/`requests` 를 직접 부르지 않는다.** 반드시
`app.integrations.cafe24` 의 `Cafe24Client` 를 통한다(재시도·로그·토큰 갱신이
한 곳에 모여 있어야 하기 때문).

핸들러는 `async def` 가 아니라 **`def`(동기)** 로 선언한다. 카페24 API·DB 호출이
블로킹이므로 FastAPI 스레드풀에서 돌게 두는 편이 이벤트 루프를 막지 않는다.

---

## 2. 화면 / 경로

| 경로 | 화면 | 권한 |
| --- | --- | --- |
| `GET /cafe24/` | 3분할 화면 (`q`, `display`, `selling`, `selected`) | `cafe24` |
| `GET /cafe24/products/{product_no}/pane` | 편집기 + 정보 패널 조각 묶음 (JS 가 가져가 `[data-pane]` 별로 끼움) | `cafe24` |
| `GET /cafe24/products/{product_no}` | → `/cafe24/?selected=` 로 리다이렉트(옛 주소) | `cafe24` |
| `POST /cafe24/products/{product_no}/apply` | 편집한 HTML 을 카페24에 즉시 적용 | `cafe24` |
| `POST /cafe24/products/{product_no}/status` | 진열/판매 토글 (JSON: `{field, value}` → 적용 후 상태) | `cafe24` |
| `POST /cafe24/products/{product_no}/name` | 상품명 변경 (JSON: `{name}` → 적용된 이름). 이전 이름은 감사로그 `rename_product` | `cafe24` |
| `POST /cafe24/products/{product_no}/basic` | 상품명·판매가·공급가·소비자가 (JSON, 바뀐 것만 PUT). 감사로그 `update_basic` | `cafe24` |
| `POST /cafe24/products/{product_no}/image` | 대표 이미지 교체 (multipart `file`) — 업로드 후 PUT `detail_image` + `image_upload_type=A`. 감사로그 `set_main_image` | `cafe24` |
| `GET /cafe24/products/{product_no}/options` | 옵션 + 품목 조회 (JSON, 읽기 지연 보정 포함) | `cafe24` |
| `POST /cafe24/products/{product_no}/options` | 옵션 생성 (`{option_name, values, display_type}`) — 조합형, 품목 자동 생성 | `cafe24` |
| `PUT /cafe24/products/{product_no}/options` | 옵션명·옵션값 이름/썸네일/표시방식 수정 (`{options:[...], option_list_type}`) | `cafe24` |
| `DELETE /cafe24/products/{product_no}/options` | 옵션 삭제 — **품목도 함께 삭제**(화면 확인창) | `cafe24` |
| `POST /cafe24/products/{product_no}/options/image` | 옵션값 썸네일 업로드만 (multipart → `{path}`) | `cafe24` |
| `PUT /cafe24/products/{product_no}/variants` | 품목 자체코드·추가금액·진열·판매 일괄 수정 (`{rows:[...]}`, 바뀐 행만) | `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** |
| `POST /cafe24/system/oauth/disconnect` | 저장된 토큰 삭제 | **admin** |
| `GET /cafe24/design/{file_key}` | 디자인 보관함 파일 편집 화면(`swiper`\|`mobile_detail`\|`pc_detail`) | `cafe24` |
| `POST /cafe24/design/{file_key}/apply` | 편집한 내용을 디자인 보관함(FTP)에 즉시 적용 | `cafe24` |
| `GET /cafe24/health` | 포털 카드 상태 점 | 없음 |

---

### 2-0. 디자인 보관함 파일 편집 — 상품 API 와 완전히 다른 경로

세 파일이 이 방식이다 — 상품이 아니라 카페24 **"디자인 보관함"** 에 올라간
스킨 파일이라서다.

| `file_key` | 상단 탭 | 기본 경로 |
| --- | --- | --- |
| `swiper` | 모바일 스와이프 | `/sde_design/mobile11/product-swiper/product-swiper.js` |
| `mobile_detail` | 모바일 상품상세 | `/sde_design/mobile11/product/detail.html` |
| `pc_detail` | PC 상품상세 | `/sde_design/skin11/product/detail.html` |

`mobile_detail`/`pc_detail` 은 **스킨 템플릿**이다 — 상품마다 다른
`description`(상세페이지 API, 2-3 절)과 달리 전 상품이 공유하는 레이아웃이므로
잘못 고치면 모든 상품 페이지에 영향을 준다.

Admin API(OAuth)로는 스킨 파일을 읽거나 쓸 방법이 없다(`config.py` 상단 주석의
확인 내용 — themes/themes-pages 어디에도 파일 내용이 없다). 카페24가 스킨
파일에 제공하는 유일한 프로그램적 접근은 **디자인 보관함 FTP 계정**이며, OAuth
와는 완전히 별개의 인증(호스트/포트/아이디/비밀번호)이다.

- 실물 확인(카페24 관리자 → 디자인 → 웹FTP 화면): 호스트 `{mall_id}.ftp.cafe24.com`,
  포트 21, **SSL/TLS 미사용(평문 FTP)**. `app/integrations/cafe24/design_ftp.py`
  가 표준 라이브러리 `ftplib` 로 직접 붙는다(Cafe24Client/httpx 경로가 아니다).
- 세 파일 모두 화면·로직이 완전히 같아 `routes_design_files.py` 하나가
  `/cafe24/design/{file_key}` 로 공유한다(경로만 `file_key` 로 갈라짐).
  화면(`design_editor.html`)은 상세페이지 편집기(`_editor.html`)와 **완전히
  같은** 문법강조·색상·단축키 JS 를 그대로 복사해 쓴다(요청사항). 다만
  목록·진열/판매·예약처럼 "상품" 전용 UI는 없다 — 편집·적용·버전 이력만 있다.
- 적용 순서도 상세페이지와 같은 원칙: FTP 에서 현재 내용을 다시 읽는다(로컬 값을
  현재값으로 가정하지 않는다) → **BACKUP** 버전 저장 → 지문 대조(편집 중 다른
  경로로 파일이 바뀌었으면 거부) → FTP 로 쓴다 → **MANUAL** 버전 + 감사로그
  (`apply_design:{file_key}`, `product_no` 는 NULL).
- 버전 이력은 `cafe24_swiper_revisions` 전용 테이블에 `file_key` 로 구분해 쌓인다
  (`cafe24_product_revisions.product_no` 가 NOT NULL 이라 재사용 불가 —
  `scripts/sql/cafe24_db_003_swiper_revisions.sql`. 테이블 이름은 처음 만들 때
  기준인 스와이프에서 왔지만 `file_key` 컬럼으로 세 파일을 함께 담게 설계했다).
- 브라우저 `<textarea>` 는 줄바꿈을 CRLF 로 보낸다 — 적용 직전 LF 로 정규화한다
  (안 하면 실수정 없이도 매번 파일 전체 줄바꿈이 바뀌어 지문 비교·"변경 없음"
  판정이 어긋난다).
- env: `CAFE24_FTP_HOST`(미설정 시 `{mall_id}.ftp.cafe24.com`), `CAFE24_FTP_PORT`
  (기본 21), `CAFE24_FTP_USER`, `CAFE24_FTP_PASSWORD` — 세 파일이 계정을 공유한다.
  경로는 파일별로 `CAFE24_SWIPER_FTP_PATH` / `CAFE24_MOBILE_DETAIL_FTP_PATH` /
  `CAFE24_PC_DETAIL_FTP_PATH` (각각 위 표의 기본값을 쓴다).

---

### 2-1. 상품관리 화면 구성 (3분할)

```
┌─ 320~460px ──────────┬──────── 남은 폭 전부 ────────┬─ 380px ─────────────┐
│ 상품명 검색(한 줄)    │ [반영 대기 배너 — 지연 시]     │ 기본 정보            │
│ ☑진열중 ☑판매중       │ 상품 이름 · 번호 · 진열/판매   │  상품명/판매가/공급가 │
│ ── 목록(전체) ──      │ 상세설명 HTML 편집기           │  /소비자가 [저장]     │
│ 번호 상품명 진열 판매 │  (PC/모바일 공통 · 문법 강조)  │ 대표 이미지          │
│ (제목행 클릭 = 정렬)  │ [메모][복사][다시 읽기][적용]  │  큰 그림 + 목록/축소  │
│                       │ ▸ 예약 적용                    │  [파일 선택][교체]    │
│                       │ ▸ 버전 이력                    │ ▸ 옵션 / 품목 (지연 로드) │
└───────────────────────┴───────────────────────────────┴──────────────────────┘
```

- 오른쪽 **상품 정보 패널**(`_side.html`)은 "소스 수정 외 기능"을 모아둔 별도 공간이다.
  상품 클릭 시 `/products/{no}/pane` 이 편집기 조각과 패널 조각을 **한 응답**(`_panes.html`,
  `[data-pane=editor]`/`[data-pane=side]`)으로 돌려주고 JS 가 각각 끼운다 — 카페24 상품
  조회는 1회. 옵션/품목은 `<details>` 를 펼칠 때 JSON 으로 따로 불러온다(호출 2회 절약).
- 1360px 이하에서는 패널이 편집기 아래로 내려가고(높이 38vh, 안에서 스크롤), 1100px 이하는
  한 열이다.
- 패널의 모든 쓰기는 JSON API(`routes_product_info.py`)이며 화면은 **응답값**으로 다시
  그린다. 저장 뒤 카페24를 다시 GET 하지 않는다(아래 3-3 읽기 지연 참고).

- 검색 입력란은 **한 줄 높이로 고정**한다(`height: 32px`). `.cf24-filters` 가 세로
  flex 이므로 `flex-basis` 를 주면 그 값이 **높이**로 적용돼 입력란이 거대해진다.
  실제로 그 사고가 있었다 — flex 방향을 항상 확인할 것.

- **왼쪽은 전체 목록**(페이지 없음). `list_all_products` 로 페이지를 넘겨가며 전부
  받는다(1회 100개, 상한 1000개). 필터를 한 페이지에만 적용하면 다음 페이지의
  해당 상품이 빠지기 때문이다.
- **필터**는 `진열중`/`판매중` 체크박스이며 **중복 선택 시 AND** 다. 문서에 없는 API
  파라미터에 기대지 않고 받아온 뒤 파이썬에서 걸러낸다.
  **기본값은 둘 다 체크**다. 체크박스는 해제 상태면 아무 값도 보내지 않으므로,
  폼에 표식(`f=1`)을 함께 넣어 "첫 방문"과 "사용자가 일부러 해제함"을 구분한다.
  표식이 없으면 기본값(둘 다 체크)으로 보고, 있으면 실제 체크 상태를 따른다.
  이 표식은 `_list_query` 가 링크·리다이렉트에도 이어 붙여 해제 상태가 유지된다.
- **정렬**은 제목행 클릭(오름↔내림 토글). 브라우저에서 처리하므로 전체를 받아둔
  덕분에 목록 전체가 대상이 된다.
- **상품 클릭 시 편집기·정보 패널만 교체**한다(`/pane` 조각 묶음을 fetch → 삽입). 목록을
  다시 받지 않으므로 카페24 호출이 1회로 끝난다. JS 실패 시 각 행의 링크로 정상 동작한다.
- 편집기 상단에 **상품 다이렉트 주소**(고객이 보는 상세페이지 URL)와 「주소 복사」·
  「쇼핑몰에서 열기」를 둔다. 주소는 `CAFE24_SHOP_URL` 기준으로 만들고, 미설정 시
  카페24 기본 도메인(`https://<mall_id>.cafe24.com`)으로 대체한다 — 커스텀 도메인은
  `mall_id` 로 알 수 없으므로 환경변수가 필요하다.
- 편집 중 다른 상품을 클릭하거나 페이지를 벗어나면 **저장 안 됨 경고**가 뜬다.
- **캐시 금지.** 화면·조각 응답에 `Cache-Control: no-store` 를 붙이고 조각 fetch 에도
  `cache: "no-store"` 를 건다. 캐시된 조각이 다시 그려지면 카페24 관리자에서 값을 바꾼
  뒤에도 예전 소스가 보이고, 그것을 그대로 편집하면 남의 수정을 덮어쓴다.
  편집기의 **[다시 읽기]** 버튼으로 언제든 현재값을 강제로 다시 받을 수 있다.
- `.erp-page` 의 `max-width` 를 이 화면에서만 풀어 편집 영역을 넓게 쓴다. 이때
  `box-sizing: border-box` 를 함께 줘야 한다(안 주면 padding 이 폭에 더해져 문서에
  가로 스크롤이 생긴다).

---

### 2-2. 편집기 (문법 강조 · 소스 정리)

**문법 강조** — 색칠된 `<pre>` 위에 **투명한 `<textarea>`** 를 정확히 겹쳐 놓는
방식이다. 외부 라이브러리를 쓰지 않는다(자체 호스팅 원칙).

- 두 층의 **폰트·글자크기·줄높이·padding·`white-space`·`tab-size` 가 완전히 같아야**
  글자가 어긋나지 않는다. 줄 번호 칸(`.cf24-gutter`)도 같은 글꼴 지표를 써야 줄이
  맞는다. `cafe24.css` 의 세 선택자를 항상 함께 수정할 것.
- **스크롤 주체는 `textarea` 다.** 색칠 층과 줄 번호를 `transform` 으로 같은 양만큼
  이동시켜 맞춘다(`scroll` 이벤트에서 `translate(-scrollLeft, -scrollTop)`).
  크기를 계산해 맞추는 방식은 두 번 실패했다 — ① textarea 의 `scrollHeight` 는
  브라우저가 한두 줄 더 잡는다(실측 830 vs 792), ② flex 자식에서 `width: max-content`
  가 기대대로 적용되지 않아 긴 줄이 있으면 textarea 만 내부 스크롤되고 색칠 층은
  제자리에 남는다(실측 706 vs 686). 그 상태에서는 **커서를 둔 곳과 다른 위치에 글자가
  입력된다.** 스크롤 동기화는 크기 계산이 없어 어긋날 여지가 없다.
- **줄바꿈하지 않고 가로로 스크롤한다**(`white-space: pre` + `wrap="off"`).
  줄바꿈을 허용하면 한 논리 줄이 여러 행이 되어 줄 번호가 맞지 않는다.
- 줄 번호 칸은 코드 영역 왼쪽의 **독립 박스**다(가로 스크롤과 무관하며 세로만 따라간다).
- 코드 칸 높이는 `56vh` **고정**이다(`flex: 0 0 auto`). 아래 「예약 적용」·「버전 이력」을
  펼쳐도 편집기가 눌리지 않고 내용이 아래로 밀리며 오른쪽 칸이 스크롤된다. `flex: 1 1 auto`
  였을 때는 펼칠 때마다 편집기가 작아져 작업 위치를 잃었다. 56vh 는 접힌 상태에서 두
  요약줄까지 스크롤 없이 들어오는 값이다(실측: 62vh 는 51px 넘침, 56vh 는 0).
- 20만 자를 넘으면 강조를 끄고 평문으로 보여준다(타이핑마다 재색칠하면 느려짐).
- 색: 태그 초록 / 속성이름 갈색 / 속성값 남색 / 주석 회색 기울임 / 기호 회색.

**소스 정리** — `store.format_html()`. 화면에 보여줄 때와 저장할 때 **같은 함수**를
쓰므로, 화면에서 본 소스가 그대로 카페24에 저장된다.

- 줄을 나누는 것은 **블록 요소 경계에서만** 한다. HTML 에서 공백은 의미가 있어서
  인라인 요소 사이에 줄바꿈을 넣으면 화면에 공백이 생긴다(이미지 사이가 벌어지는
  고전적인 사고). `img`·`br`·`span`·`a` 는 블록 목록에서 **의도적으로 제외**했다.
- **원문에 이미 있던 줄바꿈은 살리고, 각 줄을 현재 깊이로 들여쓴다.** 상세페이지는
  `<img>` 를 한 줄에 하나씩 적어두는 경우가 많고 그 모양이 저자의 의도다. 줄 앞
  공백은 렌더링에 영향이 없으므로 들여쓰기는 안전하다.
- 주석은 줄을 강제로 나누지 않는다. `<!-- 대파_타임랩스 --><img ...>` 처럼 바로 뒤
  요소를 설명하는 주석이 많아, 나누면 라벨과 대상이 떨어져 오히려 읽기 나빠진다.
- 구획용 **빈 줄은 한 줄까지 유지**한다(여러 줄은 하나로 줄인다).
- `<style>`·`<script>`·`<pre>`·`<textarea>` 안쪽은 한 글자도 건드리지 않는다.
- 내용이 한 줄뿐인 짧은 블록은 다시 한 줄로 합친다(`<td>1</td>`).
- **멱등**이다 — 편집하지 않고 다시 적용해도 저장값이 계속 바뀌지 않는다(테스트로 고정).
- 닫는 태그가 빠진 HTML 이 흔하므로 들여쓰기 깊이에 상한(12)을 둔다. 어떤 이유로든
  실패하면 **원본을 그대로** 돌려준다(정리보다 안 깨지는 게 중요).

---

### 2-3. 예약관리 (지정 시각 자동 적용)

**되돌리기(자동 복원)는 쓰지 않는다.** 예약은 "그 시각에 이 내용을 적용" 하나뿐이다.
한 예약에서 세 가지를 각각 고를 수 있고, 하나 이상은 반드시 골라야 한다(DB CHECK 제약).

| 항목 | 값 |
| --- | --- |
| 상세페이지 HTML | 편집기 내용을 적용 / 적용 안 함 |
| 진열 | 진열 · 미진열 · 변경 없음 |
| 판매 | 판매 · 중지 · 변경 없음 |

- **등록**은 편집기 아래 「예약 적용」에서 한다. HTML 을 적용하는 예약이면 그 시점의
  편집기 내용을 **DRAFT revision 으로 저장해 고정**한다 — 이후 편집기를 더 고쳐도
  예약된 내용은 바뀌지 않는다(예약해둔 것이 조용히 달라지면 안 된다).
  단건 적용과 같은 다듬기(URL 인코딩 → 소스 정리)를 거치므로 화면에서 본 값이 저장된다.
- 예약 폼은 적용 폼과 **형제**로 둔다(HTML 은 폼 중첩을 허용하지 않는다). 편집기 내용은
  JS 가 hidden 에 복사해 함께 보낸다.
- **입력은 날짜/시간 별도 input** 이다(`type=date` + `type=time`). `datetime-local`
  단일 입력은 한국어 로캘에서 표시 폭이 브라우저마다 달라 잘리는 사고가 있었다(실제
  발생 — "2026. 08. 14. 오후 07:00" 형태).
- **보이는 글자는 우리가 직접 그린다** — 네이티브 date/time input 은 표시 형식을
  CSS 로 바꿀 수 없어서(브라우저·로캘가 강제), 코드 편집기(`.cf24-code-input` 위
  `.cf24-code-hl`)와 같은 원리로 투명한(`opacity:0`) 네이티브 input 을 형식화한
  텍스트(`.cf24-dt-display`, `"2026년 08월 20일 (목)"` / `"오후 07시 30분"`) 위에
  완전히 겹친다. `input`/`change` 이벤트마다 JS(`paintDate`/`paintTime`)가 다시
  그린다. 날짜에는 요일도 붙인다(`new Date(y, mo-1, d).getDay()` — 문자열을 그대로
  `new Date("YYYY-MM-DD")` 로 파싱하면 UTC 로 해석돼 하루 밀릴 수 있어 연/월/일을
  분해해 로컬 시간대로 만든다).
- **클릭은 칸 전체 어디서든 반응한다.** 네이티브 date/time input 은 기본적으로
  자신의 달력 아이콘(우측 끝 작은 영역)을 클릭해야만 팝업이 뜨고, 칸 전체를
  덮도록 늘려도 그 작은 아이콘 영역만 반응한다(실제 겪은 문제 — "오른쪽 부분을
  선택해야 나온다"). `showPicker()` 를 클릭 핸들러에서 직접 호출해 칸 어디를
  클릭해도 팝업이 뜨게 했다. 미지원 브라우저에서는 조용히 무시되고 기존처럼
  포커스만 이동한다(기능 저하 없이 안전하게 대체).
- 글자크기 12px, 날짜 칸은 시간 칸보다 넓게(`flex: 1.7` vs `1`) 잡는다 — 날짜 칸에
  요일까지 들어가 더 길기 때문이다. 값은 실측으로 잘리지 않는 조합을 골랐다.
- 제출 직전 JS 가 두 input 의 `value`(형식과 무관하게 항상 `YYYY-MM-DD` / `HH:MM`)를
  `"YYYY-MM-DD" + "T" + "HH:MM"` 로 합쳐 hidden `scheduled_at` 에 넣는다 —
  서버(`store.parse_schedule_at`)는 예전과 같은 형식을 받으므로 백엔드는 그대로다.
- **시각은 KST 로 해석**한다. 과거 시각은 거부하되
  폼을 채우는 동안 시간이 흐른 경우를 위해 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 흐름

```
관리자 [카페24 연결]
   ↓  state 생성 → 세션 저장
GET /cafe24/system/oauth/start  → 302 카페24 인증 페이지
   ↓  사용자 승인
GET /cafe24/oauth/callback?code=&state=
   ↓  세션 state 와 대조 (불일치 시 토큰 교환 거부 — CSRF 방어)
code → access/refresh token 교환
   ↓  Fernet 암호화
cafe24_oauth_tokens 저장
```

- scope 는 `app/integrations/cafe24/config.py` 의 `PRODUCT_SCOPES` =
  `mall.read_product`, `mall.write_product`.
  주문관리 추가 시 `ORDER_SCOPES` 를 합쳐 넘기고, 카페24 개발자센터 앱에서도
  권한을 추가한 뒤 **재인증**하면 된다.
- access token 은 만료 2분 전부터 자동 갱신된다. 갱신은 토큰 행을
  `SELECT ... FOR UPDATE` 로 잠근 채 수행 — web 컨테이너와 worker 컨테이너가
  동시에 refresh 해서 한쪽 토큰이 무효화되는 것을 막는다(카페24는 refresh
  token 을 회전시킨다).
- refresh token 이 만료되면 자동 복구가 불가능하므로 화면에 "재연결 필요"를
  표시한다.

---

## 3-1. 상세설명 API 사실 (실물 확인 결과 — 추측 금지)

운영 쇼핑몰(`miraskitchen`)에서 직접 확인한 내용이다. 문서에 없는 경로를
추측해서 쓰지 말 것.

- **`/admin/products/{no}/description` 서브리소스는 존재하지 않는다.**
  호출하면 `No API found.` 가 온다. 상세설명은 **상품 리소스의 필드**다.

  ```
  GET  /admin/products/{no}   → description · mobile_description ·
                                separated_mobile_description
  PUT  /admin/products/{no}   → {"request": {"description": "..."}}
  ```

- **목록 API(`GET /admin/products`) 응답에는 `description` 이 없다.**
  그래서 상세설명은 상품 1건씩 조회해야 하고, 목록 화면에 미리보기를 뿌리지
  않는다(상품 87개 × 1호출 = 호출 제한 위험).

- **PC/모바일 상세설명이 분리되어 있다.** `separated_mobile_description`
  (`'T'`/`'F'`) 이 분리 사용 여부다. `'F'`(미분리) 상품을 수정할 때는
  `description` 과 `mobile_description` 을 같은 HTML 로 함께 맞춘다.
  `'T'` 면 두 값을 따로 관리해야 한다.

- 그 밖에 상세 응답에만 있는 참고 필드: `translated_description`(다국어),
  `summary_description`(요약설명), `simple_description`, `shop_no`(멀티쇼핑몰).

- **이미지 경로의 한글은 퍼센트 인코딩되어 저장된다.**

  ```
  src="/web/product/big/%EC%9A%A9%EA%B8%B0…(%ED%99%A9%ED%86%A0)_12.gif"
  ```

  사람이 읽을 수 없으므로 화면에서는 `store.decode_html_urls` 로 풀어서 보여주고,
  저장할 때 `store.encode_html_urls` 로 되돌린다. 두 함수는 서로의 역이며
  **왕복이 보존된다**(편집하지 않고 적용해도 저장값이 바뀌지 않는다 — 테스트로 고정).
  안전 규칙: 디코딩은 non-ASCII(`%80`~`%FF`)만, 인코딩은 URL 속성값 안만.
  `%20`·`%3C` 를 풀거나 본문 한글을 인코딩하면 페이지가 깨진다.

---

## 3-2. 편집·적용 규칙 (`POST /products/{no}/apply`)

이 순서를 절대 바꾸지 않는다.

0. 제출된 HTML 을 `encode_html_urls` → `format_html` 순으로 다듬는다(화면에서 본
   정리된 소스가 그대로 저장된다).
1. **카페24에서 현재 HTML 을 다시 읽는다.** 로컬 DB 의 마지막 버전을 "지금
   올라간 값"으로 가정하지 않는다(카페24 관리자에서 직접 고쳤을 수 있다).
1-1. **읽기 지연 판정으로 유효 현재값을 정한다**(3-3). 카페24가 아직 예전 값을
   돌려주는 중이면 우리 마지막 쓰기(MANUAL/SCHEDULED)가 현재값이다.
2. 유효 현재값으로 **BACKUP revision** 을 남긴다. 유일한 복구 수단이다.
3. **지문 대조** — 편집 화면을 열 때의 `fingerprint`(sha256 앞 32자)와 지금
   유효 현재값의 지문이 다르면 적용을 거부한다. 편집 중 남이 바꾼 내용을 조용히
   덮어쓰는 것을 막는 낙관적 잠금이다. (카페24의 지연된 예전 값과 비교하면
   방금 적용한 것이 "충돌"로 오판된다 — 그래서 유효 현재값과 비교한다.)
4. 내용이 유효 현재값과 같으면 호출하지 않는다(불필요한 쓰기·API 호출 방지).
5. PUT 적용 → PUT 응답을 **스냅샷**으로 저장 → **MANUAL revision** → 짧은 재조회
   확인(결과는 감사로그에만) → 감사로그(`apply_description`).

추가 규칙:

- 빈 내용은 거부한다(상세페이지 전체를 날리는 실수 방지).
- **PC/모바일을 구분하지 않는다.** 단, PUT 에 `mobile_description` 필드를 직접
  보내지 않는다 — 실물 확인 결과 그 필드를 보내는 순간 카페24가
  `separated_mobile_description` 을 `'T'`(관리자 화면 "직접 등록")로 바꿔버린다.
  대신 `separated_mobile_description: "F"` 만 지정하면 카페24가 모바일 값을 PC 와
  자동으로 맞춰주면서 설정도 **"PC 상세설명과 동일하게 사용"으로 유지**된다
  (`products.update_descriptions`). 편집 화면에도 모바일 소스를 따로 보여주지
  않는다 — 한쪽만 바뀌어 어긋나는 사고가 없어진다.
  분리 사용 상품의 모바일 내용이 PC 와 달랐다면 덮어쓰기 전에 **그 내용도 BACKUP
  revision 으로 남긴다**(백업이 없으면 되찾을 방법이 없다).
- 실패해도 BACKUP 은 이미 남아 있으므로 오류 메시지에 버전 번호를 알려준다.
- 적용 직후 `products.wait_for_description` 으로 0.8초 × 3회 재조회해 보지만, 이것은
  **확인용**일 뿐 화면의 기준이 아니다(3-3). 확인 여부는 감사로그 detail 에 남는다.

---

## 3-3. 카페24 읽기 지연(read-after-write lag) — "마지막 쓰기가 권위"

### 증상과 원인

"소스를 수정해 적용했는데 편집기에는 수정 전 소스가 보이고, 한참 뒤에 다시 들어가면
반영돼 있다." 우리 쪽 캐시가 아니다 — 화면·조각 응답은 전부 `Cache-Control: no-store`
이고 fetch 도 `no-store` 다. **카페24 관리자 API 가 PUT 직후 한동안 `GET
/admin/products/{no}` 에서 이전 값을 돌려준다**(실물 관찰. 몇 초일 때도, 훨씬 길 때도
있다. 쇼핑몰 고객 화면에는 바로 반영된다). 예전 코드는 2.4초만 기다리고 포기한 뒤 GET
값을 그대로 믿었기 때문에

1. 편집기에 예전 소스가 보이고,
2. 그 예전 값으로 지문을 만들어 다음 적용이 "충돌"로 거부되거나,
3. 예전 값이 BACKUP 으로 남고 "변경 없음" 판정이 어긋났다.

### 규칙

쓰기가 성공하면 **우리가 쓴 값을 DB 에 남기고, 유예시간 안에서는 그것을 현재값으로
삼는다.** 유예시간은 `CAFE24_READ_LAG_GRACE_MIN`(기본 360분). 지나면 무조건 카페24 값을
믿는다 — 지연은 영원하지 않고, 영원히 로컬 값을 고집하면 그것이 또 다른 캐시다.

| 대상 | 우리가 남기는 것 | 지연 판정 | 구현 |
| --- | --- | --- | --- |
| 상세설명 HTML | MANUAL/SCHEDULED revision (+ 적용 직전 BACKUP) | 카페24 값이 유예시간 안의 **revision 중 하나와 같으면** 지연(pending) → 마지막 쓰기를 표시하고 그 지문을 쓴다. 마지막 쓰기와 같으면 synced. 우리가 모르는 값이면 external(관리자에서 직접 고침) → 카페24 값 표시 | `store.resolve_description`, `routes_products.resolve_description`, DB `revision_digests`(md5) |
| 상품명·가격·이미지·진열/판매 | PUT 응답을 `cafe24_products.last_write_snapshot.product` 에 저장 | GET 의 `updated_date` 가 스냅샷의 `updated_date` 보다 **이전**이면 지연 → 스냅샷 값으로 덮어씀. 카페24 자신의 시각끼리 비교하므로 서버 시계와 무관 | `store.overlay_recent_write`, `routes_products.load_product` |
| 옵션 | PUT/POST 응답을 `…snapshot.options` 에 저장 | 유예시간 안이면 스냅샷 우선 | `routes_product_info._apply_options_snapshot` |
| 품목 | 보낸 값(+응답)을 `…snapshot.variants` 에 코드별 누적 | 유예시간 안이면 해당 코드의 필드만 덮어씀 | `routes_product_info._apply_variant_snapshot` |

- 편집기 위에 **「카페24 반영 대기 중」 배너**(pending) 또는 **「관리자에서 직접 수정된
  것으로 보임」 배너**(external)를 띄운다. 「다시 확인」은 「다시 읽기」와 같다.
- 적용·기본정보·상태 등 **모든 쓰기는 유효 현재값과 비교**해 바뀐 것만 보낸다. 이걸
  안 하면 "A→B 로 바꾼 직후 B→A" 가 카페24의 지연된 값(A)과 같다고 판단돼 무시된다.
- 쓰기 뒤 화면은 **PUT 응답으로 그린다.** 응답은 쓰기 직후의 실제 값이다(GET 과 달리
  지연이 없다 — 실물 예제 응답에 `updated_date` 가 갱신되어 온다). 다시 GET 하지 않는다.
- 스냅샷은 마이그레이션 `cafe24_db_004_write_snapshot.sql`(멱등)의 두 컬럼
  (`last_write_snapshot` JSONB, `last_written_at`)을 쓴다. 미적용 상태에서는 스냅샷
  저장이 실패해 로그가 남지만 적용 자체는 성공한다 — 반드시 적용할 것.

---

## 3-4. 정보 패널 API 사실 (카페24 문서 실물 예제 기준)

- **이미지 업로드**: `POST /admin/products/images` body `{"requests":[{"image":"<base64>"}]}`
  → `{"images":[{"path":"https://{domain}/web/upload/NNEditor/…"}]}`. 1장 10MB, 1호출 30MB,
  1회 20장. 상품 대표이미지는 그 경로를 `PUT /admin/products/{no}` 의 `detail_image` 에
  넣고 `image_upload_type: "A"`(대표이미지등록 — 목록/작은목록/축소를 카페24가 리사이징).
  `B` 는 네 이미지를 각각 지정, `C` 는 웹FTP.
- **가격**: `price`(판매가) · `supply_price`(공급가, 문서상 "참조 목적") · `retail_price`
  (소비자가). 문자열 `"11000.00"` 형식으로 보낸다(`store.parse_price`). 쇼핑몰 설정의
  "판매가 계산 기준"이 상품가(B)면 `price` 대신 `price_excluding_tax` 를 써야 한다는 문서
  주석이 있다 — 그 경우 카페24 오류 메시지가 그대로 화면에 뜬다.
- **옵션**: `GET/POST/PUT/DELETE /admin/products/{no}/options`, 응답 루트 `option`.
  생성은 조합형(`option_type:"T"`, `option_list_type:"S"`) + 옵션값 목록 → **품목 자동
  생성**. 수정(PUT)은 `original_options`(수정 전)와 `options`(수정 후)를 **같은 순서·개수**로
  짝지어 보낸다 — 옵션명·옵션값 이름·`option_image_file`(옵션 버튼 이미지)·
  `option_link_image`(연결 이미지)·`option_color`·`option_display_type`(S 셀렉트/P 미리보기/
  B 버튼/R 라디오)만 바꿀 수 있고 **옵션값 추가/삭제는 불가**(문서). 연동형(E)은
  `option_code`/`value_no`/`option_preset_code` 를 함께 보낸다. DELETE 는 옵션 사용안함 +
  **품목 전부 삭제**(화면에서 확인창).
- **품목**: `GET /admin/products/{no}/variants` → `variants[]`(`variant_code` 12자,
  `options[{name,value}]`, `custom_variant_code`, `additional_amount`, `display`, `selling`,
  `quantity`, `image`…). `PUT /admin/products/{no}/variants` body `{"shop_no":1,
  "requests":[{variant_code, custom_variant_code, additional_amount, display, selling…}]}`
  1회 100건(초과 시 나눠 보냄). 재고(`quantity`)는 이 화면에서 건드리지 않는다.
- "옵션별 상품 이름" 은 옵션값(`option_text`)이고, "옵션별 썸네일" 은 `option_image_file`
  (+ `option_link_image` 에도 같은 경로) 이며, "옵션별 상품코드/추가금액/진열" 은 품목
  (`custom_variant_code`/`additional_amount`/`display`)이다 — 카페24 모델상 둘은 다른
  리소스라 화면에서도 「옵션 저장」과 「품목 저장」이 따로 있다.

---

## 4. 보안 규칙 (반드시 지킬 것)

- `client_secret`·토큰을 코드에 하드코딩하지 않는다. 전부 `.env`.
- **로그·예외 메시지·템플릿에 토큰/시크릿을 절대 출력하지 않는다.**
  `cafe24_api_logs` 에도 Authorization 헤더를 기록하지 않는다.
- 토큰은 DB 에 Fernet 암호문으로만 저장한다(`CAFE24_TOKEN_SECRET`).
- 카페24 연결/해제는 `is_admin` 전용.
- OAuth 콜백은 세션 `state` 대조 후에만 code 를 교환한다.
- SQL 은 `%s` 플레이스홀더만 사용한다(문자열 조립 금지).

---

## 5. 설치 / 실행

### 5-1. 카페24 개발자센터 앱 등록 (사람이 해야 하는 일)

1. <https://developers.cafe24.com> 로그인 → 앱 생성
2. Redirect URI 를 `.env` 의 `CAFE24_REDIRECT_URI` 와 **정확히 동일하게** 등록
   (운영: `https://dbx.no1king.freeddns.org/cafe24/oauth/callback`)
3. 권한(Scope)에 `mall.read_product`, `mall.write_product` 체크
4. 발급된 Client ID / Client Secret 을 `.env` 에 기입

### 5-2. DB 초기화 (superuser 로 1회)

```bash
read -s -p "cafe24_app password: " APP_PWD; echo
docker exec -i postgres-db psql -U postgres \
    -v app_password="$APP_PWD" \
    < scripts/sql/cafe24_db_init.sql
```

### 5-3. .env

```
CAFE24_DB_URL=postgresql://cafe24_app:<APP_PWD>@postgres-db:5432/cafe24_db
CAFE24_MALL_ID=miraskitchen
CAFE24_CLIENT_ID=...
CAFE24_CLIENT_SECRET=...
CAFE24_REDIRECT_URI=https://dbx.no1king.freeddns.org/cafe24/oauth/callback
CAFE24_API_VERSION=2026-03-01
CAFE24_TOKEN_SECRET=<openssl rand -hex 32>
CAFE24_SHOP_URL=https://www.miras.co.kr      # 선택 — 다이렉트 주소용 커스텀 도메인

# 디자인 보관함 FTP (OAuth 와 별개 계정) — 모바일 스와이프 / PC·모바일 상품상세
CAFE24_FTP_HOST=miraskitchen.ftp.cafe24.com  # 선택 — 미설정 시 {mall_id}.ftp.cafe24.com
CAFE24_FTP_PORT=21
CAFE24_FTP_USER=...
CAFE24_FTP_PASSWORD=...
CAFE24_SWIPER_FTP_PATH=/sde_design/mobile11/product-swiper/product-swiper.js
CAFE24_MOBILE_DETAIL_FTP_PATH=/sde_design/mobile11/product/detail.html
CAFE24_PC_DETAIL_FTP_PATH=/sde_design/skin11/product/detail.html
```

### 5-4. 재기동 + 권한 부여

```bash
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
```

모바일 스와이프(버전 이력) 기능을 쓰려면 마이그레이션 003 도 적용해야 한다.

```bash
docker exec -i postgres-db psql -U postgres -d cafe24_db < scripts/sql/cafe24_db_003_swiper_revisions.sql
```

읽기 지연 보정(3-3)·정보 패널을 쓰려면 마이그레이션 004 를 적용해야 한다(멱등).

```bash
docker exec -i postgres-db psql -U postgres -d cafe24_db < scripts/sql/cafe24_db_004_write_snapshot.sql
```

선택 env: `CAFE24_READ_LAG_GRACE_MIN`(기본 360) — 3-3 의 유예시간(분).

worker 가 도는지 확인:

```bash
cd /opt/www/main && docker compose logs --tail=20 cafe24-worker
```

관리자 페이지(`/admin`)에서 직원에게 **카페24 상품관리** 권한을 부여한다.

---

## 6. 테스트

```bash
python -m app.modules.cafe24.tests.test_cafe24
```

DB·네트워크 없이 암호화 왕복, 토큰 만료/자동갱신, 상태 노출(토큰 미유출),
재시도 예산, 예약 상태 전이를 검증한다.

---

## 7. 진행 상태

| Phase | 내용 | 상태 |
| --- | --- | --- |
| 1 | 공통 Integration · cafe24_db · OAuth 연결 화면 | ✅ 완료 |
| 2 | 상품 목록·검색·현재 HTML 조회 | ✅ 완료 |
| 3 | 편집기 · 미리보기 · Diff · 초안 | ◐ 문법 강조 편집기 + 소스 정리 완료. 미리보기·Diff·초안 예정 |
| 4 | 즉시 적용 · BACKUP · Revision · 감사로그 | ✅ 완료 |
| 5 | 예약 DB · Worker(compose 서비스) · 예약관리 화면 | ✅ 완료 |
| 6 | 자동 종료/복원 · 롤백 | ✖ 되돌리기는 쓰지 않기로 결정. 버전 선택 복원만 남음 |
| 7 | 일괄 수정 · 일괄 예약 · Rate limit 제어 | ✖ 일괄수정은 사용하지 않기로 제거. 필요해지면 다시 논의 |
| 8 | 디자인 보관함 파일 편집(모바일 스와이프 · PC/모바일 상품상세 템플릿) — FTP | ✅ 완료. 예약 적용은 없음(상품 전용 개념이라 범위 밖) |
| 9 | 카페24 읽기 지연 보정("마지막 쓰기가 권위", 3-3) | ✅ 완료 (마이그레이션 004) |
| 10 | 상품 정보 패널 — 상품명/가격 · 대표이미지 · 옵션/품목 (3-4) | ✅ 완료 |

Phase 5 의 worker 는 `app/modules/cafe24/worker.py` 에 둔다 — `Dockerfile` 이
`COPY app/ ./app/` 만 하므로 `scripts/` 에 두면 이미지에 포함되지 않는다.
`docker-compose.yml` 에 같은 이미지로 `dbx-cafe24-worker` 서비스를 추가해
`python -m app.modules.cafe24.worker --loop 60` 으로 돌린다.