공유 덱 카드 복원 기준을 imgSrc로 전환

동일 번호 카드가 많은 시리즈에서도 선택한 카드가 정확히 복원되도록 저장·검증·복원 흐름을 imgSrc 중심으로 정리하고, 이미지 누락 시 공통 뒷면 폴백을 적용한다.

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/changelog.md

@@ -1,5 +1,15 @@
 # 변경사항
 
+## v4.0.17
+
+### 공유 덱 카드 복원 정확도 개선
+
+공유 링크로 덱을 불러올 때 카드 복원 기준을 `imgSrc`로 통일해, 같은 카드 번호를 가진 일반·패러렐 카드가 섞여 있어도 선택한 카드가 정확히 다시 표시됩니다.
+
+### 누락 이미지 표시 방식 개선
+
+카드 목록과 덱 프리뷰에서 이미지 경로가 잘못되었거나 파일이 없는 경우 깨진 이미지 대신 카드 뒷면 이미지를 표시하도록 개선했습니다.
+
 ## v4.0.16
 
 ### 회원 탈퇴

docs/history.md

@@ -1,5 +1,10 @@
 # 의사결정 이력
 
+## 2026-06-25 v4.0.17 — 공유 덱 카드는 imgSrc를 기준으로 복원
+
+💡 동일 `Number`의 일반·패러렐·프로모가 공존해 번호만으로는 원본 카드를 안정적으로 식별할 수 없기 때문.
+🔧 덱 저장 payload에 `imgSrc`를 필수 포함하고 서버 복원은 `imgSrc` 우선, 레거시 데이터만 `number`로 보조 복원.
+
 ## 2026-06-25 v4.0.16 — 탈퇴 계정의 덱은 익명 콘텐츠로 보존
 
 💡 공개 덱을 참고하거나 즐겨찾기한 다른 사용자의 이용 흐름을 탈퇴로 끊지 않기 위함.

docs/spec.md

@@ -3,7 +3,7 @@
 ## 프로젝트 개요
 
 - 서비스명: `UNIARE - Union Arena Deck Builder`
-- 현재 버전: `v4.0.16`
+- 현재 버전: `v4.0.17`
 - 프론트: 정적 HTML, CSS, JavaScript
 - 백엔드: Express, SQLite(`better-sqlite3`)
 - 운영: Docker Compose 기반 Nginx + API
@@ -69,6 +69,7 @@
 - 폴백 이미지: `/images/uapr/comingsoon.png`
 - 브랜드 자산: `images/assets/`
 - `images/**`는 Git LFS로 관리한다.
+- 카드 목록·덱 결과 화면에서 카드 이미지 로드 실패 시 폴백 이미지를 표시한다.
 - 아바타와 덱 미리보기는 API 데이터 디렉터리에 저장하며 Git에 포함하지 않는다.
 - 덱 저장 미리보기는 1200px 기준 PNG로 정규화한다.
 - 덱 삭제 시 해당 공유 코드의 미리보기 PNG도 함께 삭제한다.
@@ -122,8 +123,9 @@
 - 덱 저장과 공개 링크 생성은 로그인한 회원만 사용할 수 있다.
 - 비회원은 덱 구성과 PNG 이미지 다운로드만 사용할 수 있다.
 - 기존 비회원 공유 덱은 호환을 위해 원래 만료일까지 조회할 수 있다.
-- DB의 `cards_json`에는 `{number, count, key}`만 저장한다.
+- DB의 `cards_json`에는 `{imgSrc, number, count, key}`를 저장한다.
 - API 응답 시 `datas/<series>.js`에서 이미지·색상·희귀도·트리거 정보를 합성한다.
+- 같은 `Number`에 여러 판본이 있을 경우 API는 저장된 `imgSrc`를 기준으로 카드 메타를 복원한다.
 - 공개 덱 목록은 `share_type='user'`, `is_public=1`, 미만료 조건을 사용한다.
 - `preset` 타입과 관리자 프리셋 API는 레거시 호환용으로 코드에 남아 있으며 현재 공개 덱 화면에서는 사용하지 않는다.
 

docs/update.md

@@ -1,5 +1,13 @@
 # 업데이트 이력
 
+## 2026-06-25 / v4.0.17 — 누락 이미지 폴백·공유 덱 매핑 보정
+
+### 수행 작업
+- 덱 저장 카드 payload를 `imgSrc` 필수로 확장하고 API 검증에서 `imgSrc` 누락 요청을 차단
+- 덱 복원은 `imgSrc` 기준으로 정확 매핑하고, 기존 구데이터 호환을 위해서만 `number`를 보조 fallback으로 유지
+- `cardList.html`, `result.html` 카드 렌더링에서 이미지 로드 실패 시 공통 폴백(`/images/uapr/comingsoon.png`)을 사용
+- 카드 목록 확대 미리보기(오버레이)도 동일 폴백을 적용해 이미지 누락 시 깨짐 대신 뒷면 노출
+
 ## 2026-06-25 / v4.0.16 — 회원 탈퇴·관리자 덱 일괄 삭제
 
 ### 수행 작업