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_system.py  연결(OAuth)·상태·API 로그·작업 로그
├─ common.py         가드/컨텍스트 헬퍼 (순환 import 방지로 분리)
├─ db.py             Cafe24Store (cafe24_db, psycopg3 raw SQL)
├─ store.py          순수 로직 — 상수·상태전이·재시도 규칙·검증
├─ tests/            DB/네트워크 없는 유닛테스트
└─ templates/cafe24/ _nav.html · index.html · system.html
```

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

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

---

## 2. 화면 / 경로

| 경로 | 화면 | 권한 |
| --- | --- | --- |
| `GET /cafe24/` | 상품 목록 (Phase 2) | `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 이 만료되면 자동 복구가 불가능하므로 화면에 "재연결 필요"를
  표시한다.

---

## 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 | Monaco 편집 · 미리보기 · 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` 으로 돌린다.