feat(cafe24): 상품 상세페이지 관리 모듈 Phase 1

카페24 관리자에 직접 접속하지 않고 상품 상세페이지(description HTML)를
편집·예약 적용·복원하기 위한 모듈의 기반을 만든다. Phase 1 은 공통
Integration 계층, cafe24_db, OAuth 연결 화면까지다.

카페24 OAuth/API 클라이언트를 상품관리 모듈 안에 두지 않고
app/integrations/cafe24/ 로 분리했다. 향후 추가할 주문관리(주문 조회·송장
일괄등록·취소/반품/교환)가 같은 토큰과 클라이언트를 그대로 재사용해야 하기
때문이다. 라우터에서 httpx 를 직접 부르지 않고 Cafe24Client 만 쓰게 해서
재시도·rate limit·API 로그·토큰 갱신을 한 곳에 모았다.

토큰은 Fernet 으로 암호화해 저장한다(CAFE24_TOKEN_SECRET). DB 덤프가
유출돼도 access/refresh token 이 평문으로 남지 않게 하기 위함이며, API 로그와
연결 상태 화면에는 토큰·시크릿을 일절 기록/표시하지 않는다.

토큰 갱신은 행 잠금(SELECT ... FOR UPDATE) 안에서 한다. 카페24는 refresh
token 을 회전시키므로, 이후 추가될 예약 worker 컨테이너와 web 컨테이너가
동시에 갱신하면 한쪽 토큰이 무효화된다.

기존 파일 변경은 목록에 한 줄씩 추가하는 형태로 44줄뿐이며 기존 라우트·
테이블·인증 로직은 건드리지 않았다. CAFE24_DB_URL 미설정 시 store 가 None
이라 앱은 정상 기동하고 모듈만 "설정 필요" 안내를 표시한다.

가드 헬퍼를 common.py 로 분리한 것은 router.py 가 routes_system.py 를
include 하는 구조에서 순환 import 가 생기기 때문이다.

검증: 신규 테스트 16개 통과(암호화 왕복, 토큰 만료·자동갱신, 상태 노출 시
토큰 미유출, 재시도 예산, 예약 상태 전이). dispatch 기존 테스트 9개 통과.
cafe24_db_init.sql 은 로컬에 Docker 가 없어 미실행 — 서버 적용 시 확인 필요.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.env.example

@@ -64,6 +64,28 @@ CUSTOMER_ORDER_LIST_URL=/orderlist/
 # 알림 수신자(쉼표구분). 비워두면 ERP 관리자(admin) 전원에게 발송.
 # PROJECT_NOTIFY_EMAIL=king@dbxcorp.co.kr
 
+# ─── 카페24 상품 상세페이지 관리 모듈 (cafe24_db) ───
+# 설정해야 모듈이 동작한다(미설정 시 "설정 필요" 안내, JSON 폴백 없음).
+# DB/역할/스키마 생성: scripts/sql/cafe24_db_init.sql 참고.
+# 권한키: cafe24(접근). admin 은 항상 통과. 카페24 연결(OAuth)은 admin 전용.
+# CAFE24_DB_URL=postgresql://cafe24_app:replace-me@postgres-db:5432/cafe24_db
+#
+# 카페24 개발자센터(https://developers.cafe24.com)에서 앱을 만들고 발급받은 값.
+#   - Redirect URI 는 아래 CAFE24_REDIRECT_URI 와 반드시 동일하게 앱에 등록.
+#   - Scope 는 상품관리에 mall.read_product, mall.write_product 가 필요하다.
+#     (향후 주문관리 추가 시 mall.read_order, mall.write_order 를 앱에 추가하고
+#      재인증하면 된다 — 코드는 app/integrations/cafe24/config.py 의 SCOPES)
+# 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
+#
+# access/refresh token 을 DB 에 Fernet 암호화해서 저장할 때 쓰는 키.
+# openssl rand -hex 32 로 생성. ⚠️ 값을 바꾸면 기존 토큰을 복호화할 수 없어
+# 카페24 재연결(재인증)이 필요하다.
+# CAFE24_TOKEN_SECRET=
+
 # ─── 상품 검색 (itemcode_db 읽기 전용) ───
 # cupang 설정 화면에서 제품명을 itemcode_db 에서 검색해 등록한다(읽기만).
 # 미설정 시 검색 비활성 → 수동 등록만 가능.