dbx-main/docs/CAFE24_MODULE.md

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

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

---

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

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

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

app/modules/cafe24/             ← 상품관리 모듈
├─ router.py           루트 라우터(prefix=/cafe24) + 서브 라우터 결합
├─ routes_products.py  상품 목록/검색 · 상세설명 조회 (읽기 전용)
├─ 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 · product.html ·
                       schedules.html · system.html
```

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

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

---

## 2. 화면 / 경로

| 경로 | 화면 | 권한 |
| --- | --- | --- |
| `GET /cafe24/` | 상품 목록·검색 (`q`, `page`) | `cafe24` |
| `GET /cafe24/products/{product_no}` | 상품 1건 + 상세설명 HTML 편집기 + 버전 이력 | `cafe24` |
| `POST /cafe24/products/{product_no}/apply` | 편집한 HTML 을 카페24에 즉시 적용 | `cafe24` |
| `GET /cafe24/schedules` | 예약관리 (Phase 5 안내) | `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/health` | 포털 카드 상태 점 | 없음 |

---

## 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`)

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

1. **카페24에서 현재 HTML 을 다시 읽는다.** 로컬 DB 의 마지막 버전을 "지금
   올라간 값"으로 가정하지 않는다(카페24 관리자에서 직접 고쳤을 수 있다).
2. 그 값으로 **BACKUP revision** 을 남긴다. 유일한 복구 수단이다.
3. **지문 대조** — 편집 화면을 열 때의 `fingerprint`(sha256 앞 32자)와 지금
   카페24 값의 지문이 다르면 적용을 거부한다. 편집 중 남이 바꾼 내용을 조용히
   덮어쓰는 것을 막는 낙관적 잠금이다.
4. 내용이 같으면 호출하지 않는다(불필요한 쓰기·API 호출 방지).
5. PUT 적용 → **MANUAL revision** + 감사로그(`apply_description`).

추가 규칙:

- 빈 내용은 거부한다(상세페이지 전체를 날리는 실수 방지).
- **PC/모바일 미분리(`separated_mobile_description='F'`) 상품은 모바일 필드도
  같은 HTML 로 함께 쓴다.** PC 만 바꾸면 모바일이 어긋난다.
  분리(`'T'`) 상품은 모바일을 건드리지 않고, 화면에 "모바일은 따로 반영" 을 알린다.
- 실패해도 BACKUP 은 이미 남아 있으므로 오류 메시지에 버전 번호를 알려준다.

---

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

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

```bash
cd /opt/www/main && docker compose up -d --build web
```

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

---

## 6. 테스트

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

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

---

## 7. 진행 상태

| Phase | 내용 | 상태 |
| --- | --- | --- |
| 1 | 공통 Integration · cafe24_db · OAuth 연결 화면 | ✅ 완료 |
| 2 | 상품 목록·검색·현재 HTML 조회 | ✅ 완료 |
| 3 | 편집기 · 미리보기 · Diff · 초안 | ◐ 편집기(textarea)만 완료. 미리보기·Diff·초안 예정 |
| 4 | 즉시 적용 · BACKUP · Revision · 감사로그 | ✅ 완료 |
| 5 | 예약 DB · Worker(compose 서비스) · 예약관리 화면 | 예정 |
| 6 | 자동 종료/복원 · 롤백 | 예정 |
| 7 | 일괄 수정 · 일괄 예약 · Rate limit 제어 | 예정 |

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` 으로 돌린다.