feat(cafe24): 상품 목록·검색 + 현재 상세페이지 HTML 조회 (Phase 2)

상세설명 API 경로가 틀려 있던 것을 실물 확인으로 바로잡았다.
`/admin/products/{no}/description` 은 존재하지 않는다(운영몰 호출 결과
`No API found.`). 상세설명은 상품 리소스의 필드이므로 GET/PUT 을
`/admin/products/{no}` 로 옮겼고, PUT body 는 {"request": {...}} 다.

PC/모바일 상세설명이 별도 필드라는 것도 확인됐다. `separated_mobile_description`
('T'/'F') 이 분리 사용 여부이며, 미분리 상품을 수정할 때 description 만 바꾸면
모바일이 어긋난다. Descriptions 데이터클래스에 이 플래그와 불일치 여부를 담아
화면에서 경고로 노출한다.

목록 응답에는 description 이 없어(확인됨) 상세설명은 상품 1건씩 조회한다.
그래서 목록 화면에 미리보기를 뿌리지 않는다 — 상품 87개면 87호출이라 호출
제한에 걸린다.

화면은 읽기 전용이다(편집·적용은 Phase 3~4). 목록은 카페24를 매번 조회해
현재값을 보여주고, 결과를 cafe24_products 에 UPSERT 해둔다(예약·로그 화면에서
API 없이 상품명을 쓰기 위함).

상단 탭의 예약관리가 404 였으므로 Phase 5 안내 화면을 붙였다.

토큰 만료 시각이 화면에 +00:00 로 보이던 것도 고쳤다. 컬럼이 timestamptz 라
psycopg 가 UTC 로 돌려주는 값을 그대로 출력하고 있었다(시각 자체는 정확했다).

검증: 유닛테스트 23개 통과(신규 7개 — 상세설명 경로가 /description 으로
되돌아가지 않는지, PUT payload 모양, 미분리 플래그 파싱, 페이징 clamp).
라우트 8개 등록 확인. 실제 화면은 서버 배포 후 확인 필요.

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

docs/CAFE24_MODULE.md

@@ -24,13 +24,15 @@ app/integrations/cafe24/        ← 공통 (상품관리 + 향후 주문관리
 └─ 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
+├─ 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` 를 직접 부르지 않는다.** 반드시
@@ -46,7 +48,9 @@ app/modules/cafe24/             ← 상품관리 모듈
 
 | 경로 | 화면 | 권한 |
 | --- | --- | --- |
-| `GET /cafe24/` | 상품 목록 (Phase 2) | `cafe24` |
+| `GET /cafe24/` | 상품 목록·검색 (`q`, `page`) | `cafe24` |
+| `GET /cafe24/products/{product_no}` | 상품 1건 + 현재 상세설명 HTML (읽기 전용) | `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** |
@@ -82,6 +86,34 @@ cafe24_oauth_tokens 저장
 
 ---
 
+## 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`(멀티쇼핑몰).
+
+---
+
 ## 4. 보안 규칙 (반드시 지킬 것)
 
 - `client_secret`·토큰을 코드에 하드코딩하지 않는다. 전부 `.env`.
@@ -151,7 +183,7 @@ DB·네트워크 없이 암호화 왕복, 토큰 만료/자동갱신, 상태 노
 | Phase | 내용 | 상태 |
 | --- | --- | --- |
 | 1 | 공통 Integration · cafe24_db · OAuth 연결 화면 | ✅ 완료 |
-| 2 | 상품 목록·검색·현재 HTML 조회 | 예정 |
+| 2 | 상품 목록·검색·현재 HTML 조회 | ✅ 완료 |
 | 3 | Monaco 편집 · 미리보기 · Diff · 초안 | 예정 |
 | 4 | 즉시 적용 · BACKUP · Revision · 감사로그 | 예정 |
 | 5 | 예약 DB · Worker(compose 서비스) · 예약관리 화면 | 예정 |