v3.0.0: 저장소 재시작 및 전체 자산 반영

docs/convention.md

@@ -0,0 +1,43 @@
+# 코딩 컨벤션
+
+## 기본 원칙
+- 모든 문서와 커뮤니케이션은 한국어 기준으로 유지한다.
+- 코드 주석은 필요 시 `JSDoc` 형식을 우선한다.
+- 기존 정적 사이트 구조를 존중하고, 대규모 구조 변경 시에는 먼저 `docs/history.md`에 의사결정을 기록한다.
+
+## 파일 및 폴더 규칙
+- 시리즈 데이터 파일은 `datas/uaXX.js`, `datas/uapr.js`처럼 시리즈 키와 일치하게 관리한다.
+- 이미지 폴더는 `images/<seriesKey>/` 규칙을 유지한다.
+- 새 문서는 `docs/` 하위에서 목적별 단일 파일에 누적 관리한다.
+
+## JavaScript 규칙
+- 기존 코드 스타일에 맞춰 기본 들여쓰기는 4칸을 사용한다.
+- 상수는 `const`, 재할당 변수는 `let`을 사용한다.
+- DOM 참조가 반복될 경우 `getEl()`처럼 묶어서 관리하는 패턴을 우선 고려한다.
+- URL 파라미터, `localStorage`, 동적 import는 예외 처리와 함께 사용한다.
+- 카드 데이터 객체의 필드명은 기존 호환성을 위해 현재 형태(`imgSrc`, `Number`, `count`, `key`)를 유지한다.
+
+## HTML 규칙
+- 정적 페이지는 의미 단위별로 `header`, `main`, `aside` 등을 우선 사용한다.
+- 페이지별 스크립트가 길어질 경우 신규 기능은 별도 JS 파일 분리 여부를 먼저 검토한다.
+- 인라인 이벤트(`onclick`)는 기존 파일에 이미 존재하므로 즉시 제거 대상은 아니지만, 신규 대형 기능은 `addEventListener` 방식 우선 검토한다.
+
+## CSS 규칙
+- 공통 UI는 가능한 한 Tailwind 유틸리티 클래스를 우선 사용한다.
+- 페이지 특화 보정 스타일만 인라인 `<style>` 또는 전용 CSS 파일에 둔다.
+- 캡처 안정성처럼 이유가 분명한 예외 스타일은 주석으로 목적을 남긴다.
+
+## 데이터 관리 규칙
+- 카드 데이터 추가 시 최소 필드는 `imgSrc`, `Number`, `count`, `key`, `color`, `parallel`, `rarity`, `trigger`를 맞춘다.
+- 동일 카드의 패러렐 판본은 동일 `Number`를 유지하고 `parallel` 값으로 구분한다.
+- 파일명 변경 시 `datas/*.js`와 `images/<seriesKey>/`가 함께 일치하는지 확인한다.
+
+## Git 규칙
+- 커밋 메시지는 한국어로 작성한다.
+- 버전 상승 작업은 `docs/update.md` 반영 후 태그명과 맞춘다.
+- 민감 정보, 로컬 경로, 개인 식별 정보가 커밋되지 않도록 확인한다.
+
+## 이미지 자산 규칙
+- `images/**`는 `Git LFS`로 관리한다.
+- 이미지 파일을 새로 추가하거나 교체할 때는 일반 Git 객체로 들어가지 않도록 `.gitattributes` 설정을 유지한다.
+- 대량 이미지 추가 전에는 원격 저장소의 LFS 정책과 비용 한도를 확인한다.

docs/history.md

@@ -0,0 +1,44 @@
+# 의사결정 이력
+
+## 2026-03-30 / 문서 체계 초기화
+- 배경: 프로젝트 루트에 AI 작업 규칙은 있었지만 `docs/` 실체가 없어 규칙과 실제 운영 상태가 분리되어 있었다.
+- 결정: 규칙 문서가 요구하는 핵심 문서 6종을 먼저 생성하고, 이후 변경 시 이 파일들을 기준 문서로 유지한다.
+- 기대 효과: 작업 내역, 기술 구조, 화면-파일 연결, 향후 할 일을 한곳에서 추적할 수 있다.
+
+## 2026-03-30 / 이미지 관리 방식 1차 판단
+- 배경: `images/` 디렉터리 용량이 약 `1.7G`, 파일 수가 `9,370개` 수준으로 증가했다.
+- 관찰:
+- 개별 파일이 아주 크지 않아도 Git 일반 객체로 누적되면 clone 및 fetch 비용이 계속 증가한다.
+- 이미지 추가가 잦은 프로젝트 특성상 저장소 히스토리 비대화가 반복될 가능성이 높다.
+- 결정:
+- 신규 이미지 유입 관리 목적이라면 `Git LFS` 도입을 권장한다.
+- 단, 이미 커진 저장소를 즉시 가볍게 만드는 해결책으로 `Git LFS`만 기대해서는 안 된다.
+- 히스토리 크기까지 줄여야 하면 `git lfs migrate` 또는 자산 저장소 분리/CDN 이전을 별도 의사결정으로 다룬다.
+- 보류 사유:
+- 원격 저장소의 LFS 지원 여부, 무료 용량, 대역폭 정책을 아직 확인하지 않았다.
+- 기존 협업자들의 개발 환경에 `git lfs` 설치를 요구하게 되므로 도입 공지가 필요하다.
+
+## 2026-03-30 / 이미지 히스토리 전체 LFS 마이그레이션 결정
+- 배경: 목적이 "앞으로 예방"이 아니라 "기존 저장소 용량 절감"으로 명확해졌다.
+- 확인:
+- 로컬 환경에 `git lfs`가 설치되어 있다.
+- 원격 저장소에 LFS 엔드포인트가 설정되어 있다.
+- 결정:
+- `images/**` 전체 히스토리를 `Git LFS`로 마이그레이션한다.
+- 현재 작업 중인 `ua27` 데이터 및 이미지 추가분도 함께 반영한다.
+- 영향:
+- 기존 커밋 해시가 모두 재작성된다.
+- 원격 반영 시 강제 푸시가 필요하다.
+- 협업 중인 다른 클론은 재동기화 절차가 필요하다.
+
+## 2026-03-30 / 새 루트 커밋 기준 저장소 재시작 결정
+- 배경: `images/**`는 LFS 포인터로 전환됐지만, 저장소 자체는 과거 Git 객체 영향으로 여전히 비대했다.
+- 결정:
+- 현재 로컬 작업본을 단일 기준 스냅샷으로 보고 새 루트 커밋을 만든다.
+- 원격 `main`은 새 루트 커밋으로 교체한다.
+- 기존 히스토리는 로컬 백업 브랜치에서만 보존한다.
+- 새 버전 체계는 `v3.0.0`부터 다시 시작한다.
+- 이미지 자산은 새 시작 이후에도 `Git LFS` 정책을 유지한다.
+- 이유:
+- 가장 확실하게 Git 일반 히스토리 용량을 줄일 수 있다.
+- 추가적인 서버 GC 상태나 숨은 과거 객체를 더 추적하지 않고도 정리 목적을 달성할 수 있다.

docs/map.md

@@ -0,0 +1,50 @@
+# 파일-화면 매핑 가이드
+
+## `/`
+- 진입 파일: `index.html`
+- 화면 역할: 시리즈 선택 홈 화면
+- 사용자 행동:
+- 언어 선택
+- 시리즈 카드 클릭
+- 연결 파일:
+- `i18n/translations.<lang>.json`: 제목, 설명, 시리즈명
+- `script/navigation.js`: 공통 네비게이션 오버레이
+- `style/output.css`: 공통 스타일
+
+## `/cardList.html?series=<seriesKey>`
+- 진입 파일: `cardList.html`
+- 화면 역할: 카드 검색, 필터링, 수량 선택, 키 카드 지정
+- 사용자 행동:
+- 검색어 입력
+- 색상/타입/트리거 필터
+- 카드 수량 조절
+- 키 카드 지정
+- 덱 결과 페이지 이동
+- 연결 파일:
+- `datas/<seriesKey>.js`: 현재 시리즈 카드 원본 데이터
+- `images/<seriesKey>/`: 카드 이미지 원본
+- `i18n/translations.<lang>.json`: 버튼/문구 번역
+- `script/navigation.js`: 공통 네비게이션
+
+## `/result.html`
+- 진입 파일: `result.html`
+- 화면 역할: 선택한 덱 미리보기 및 이미지 저장
+- 사용자 행동:
+- 덱 이름 입력
+- 출력 스타일 선택
+- 고화질 저장 토글
+- PNG 다운로드
+- 연결 파일:
+- `localStorage.selectedCards` 또는 `cards` 쿼리스트링: 덱 데이터 소스
+- `images/<seriesKey>/`: 결과 이미지 렌더링 대상
+- `i18n/translations.<lang>.json`: 결과 화면 번역
+
+## 공통 보조 파일
+- `script/navigation.js`: 오버레이 메뉴 생성 및 이동 처리
+- `i18n/i18n.js`: `data-i18n` 기반 공통 번역 적용
+- `style/style.css`, `style/navigation.css`, `style/output.css`: 공통/페이지 스타일
+
+## 초보자용 이해 포인트
+- 이 프로젝트는 프레임워크 앱이 아니라 HTML 파일 3개가 직접 화면 역할을 나눠 갖는 구조다.
+- 카드 정보는 `datas/`에, 실제 카드 이미지는 `images/`에 따로 있다.
+- 화면에서 보이는 한 장의 카드는 "데이터 파일의 객체 1개 + 이미지 폴더의 파일 1개" 조합으로 만들어진다.

docs/spec.md

@@ -0,0 +1,101 @@
+# 기술 명세
+
+## 1. 프로젝트 개요
+- 프로젝트명: `UADECK V3.1 - Union Arena Deck Builder`
+- 형태: 정적 HTML/CSS/JavaScript 기반 덱 빌더
+- 패키지 의존성: `tailwindcss`, `@tailwindcss/cli`
+- 빌드 산출 스타일: `style/output.css`
+
+## 2. 화면 구조
+
+### `/index.html`
+- 시리즈 선택 랜딩 페이지다.
+- `i18n/translations.<lang>.json`을 직접 fetch하여 시리즈명과 소개 문구를 렌더링한다.
+- 사용자가 시리즈를 선택하면 `cardList.html?series=<key>&seriesName=<name>&lang=<lang>`로 이동한다.
+
+### `/cardList.html`
+- 특정 시리즈의 카드 목록을 보여주고 덱을 편집한다.
+- 쿼리스트링의 `series` 값을 기준으로 `./datas/${seriesKey}.js`를 동적 import 한다.
+- 필터 기능:
+- 검색어
+- 색상(`All`, `Red`, `Blue`, `Green`, `Yellow`, `Purple`)
+- 시리즈 하위 그룹
+- 타입(`Basic`, `AP`, `Parallel`)
+- 트리거(`All`, `Special`, `Color`, `Final`)
+- 카드 수량 증감, 키 카드 지정, 초기화, 상세 오버레이, 결과 페이지 이동을 담당한다.
+
+### `/result.html`
+- 선택한 카드 목록을 미리보기하고 이미지로 저장한다.
+- 스타일 모드:
+- `type1`: 키 카드 강조형
+- `type2`: 클래식 5열형
+- `html-to-image` CDN을 사용해 덱 이미지를 PNG로 저장한다.
+
+## 3. 데이터 구조
+
+### 카드 데이터 파일
+- 위치: `datas/*.js`
+- 파일 수: 현재 `52개`
+- 각 파일은 `export const cardList = [...]` 형태를 사용한다.
+
+### 카드 객체 스키마
+```js
+{
+    imgSrc: '/ua24/UA24BT_SHY-1-001.png',
+    Number: 'UA24BT/SHY-1-001',
+    count: 0,
+    key: false,
+    color: 'Red',
+    parallel: false,
+    rarity: 'C',
+    trigger: null,
+}
+```
+
+### 필드 의미
+- `imgSrc`: 원본 상대 식별자. 실제 렌더링 시 `images/${seriesKey}/${fileName}` 형태로 재구성한다.
+- `Number`: 카드 번호. 동일 카드 판본 묶음과 필터 기준으로 사용한다.
+- `count`: 현재 덱에 담긴 수량.
+- `key`: 키 카드 여부.
+- `color`: 카드 색상 또는 일부 특수 분류 값.
+- `parallel`: 패러렐 여부.
+- `rarity`: 희귀도 표기.
+- `trigger`: `null`, `COLOR`, `FINAL`, `SPECIAL` 등 트리거 정보.
+- `maxCount`: 일부 카드만 선택적으로 사용하며 기본값은 `4`로 동작한다.
+
+## 4. 이미지 규칙
+- 기본 위치: `images/<seriesKey>/`
+- 저장 정책: `images/**`는 `Git LFS` 대상으로 관리한다.
+- 렌더링 규칙:
+- 카드 목록 화면: `images/${seriesKey}/${fileName}`
+- 결과 화면: `/images/${seriesKey}/${fileName}`
+- 폴백 이미지: `/images/uapr/comingsoon.png`
+- 현재 용량 현황:
+- `images/` 약 `1.7G`
+- 이미지 파일 약 `9,370개`
+
+## 5. 다국어
+- 지원 언어: `ko`, `ja`, `en`
+- 번역 파일:
+- `i18n/translations.ko.json`
+- `i18n/translations.ja.json`
+- `i18n/translations.en.json`
+- `index.html`은 번역 JSON을 직접 읽는다.
+- 공통 텍스트 치환은 `i18n/i18n.js`의 `data-i18n` 기반 로직을 사용한다.
+
+## 6. 상태 저장
+- `localStorage.lang`: 현재 언어
+- `localStorage.selectedCards`: 선택 카드 목록(JSON 문자열을 `encodeURIComponent` 처리)
+- `localStorage.selectedSeries`: 일부 흐름에서 사용하는 선택 시리즈 값
+
+## 7. 스타일 및 자산
+- Tailwind 유틸리티 클래스와 페이지별 인라인 스타일을 혼용한다.
+- 공통 스타일 파일:
+- `style/output.css`
+- `style/style.css`
+- `style/navigation.css`
+
+## 8. 알려진 제약
+- `cardList.html`과 `result.html`의 스크립트가 페이지 내부에 크게 포함되어 있어 모듈 분리 전까지는 변경 영향 범위가 넓다.
+- `script/navigation.js`의 일부 이동 대상 페이지는 현재 저장소에 존재하지 않는다.
+- 이미지가 Git 일반 객체로 계속 누적되면 저장소 히스토리 크기가 지속 증가한다.

docs/todo.md

@@ -0,0 +1,19 @@
+# 할 일 및 이슈
+
+## 현재 이슈
+- `images/` 디렉터리가 약 `1.7G`까지 증가해 저장소 clone, fetch, checkout 비용이 커졌다.
+- 이미지 파일 수가 `9,000+` 단위라서 카드 추가 빈도가 올라갈수록 Git 객체 수와 히스토리 부담이 계속 누적될 가능성이 높다.
+- `script/navigation.js`에는 현재 프로젝트에 없는 페이지(`deckHistory.html`, `preset.html`, `myDatabase.html`)로 이동하는 코드가 남아 있다.
+- `cardList.html`과 `result.html` 내부 스크립트 비중이 커서 기능 확장 시 유지보수 난도가 올라갈 수 있다.
+- 데이터 파일 네이밍과 샘플 파일(`datas/ua99 sample.js`, `datas/ua99 sample mini.js`) 처리 기준이 문서상 명확하지 않았다.
+
+## 다음 작업 제안
+- 원격 저장소에서 `Git LFS` 업로드가 정상 완료되었는지 확인한다.
+- 협업자가 있다면 히스토리 재작성 이후 동기화 방법을 공지한다.
+- `Git LFS` 도입 후에도 저장소 운영 비용이 크면 이미지 저장소 분리/CDN 이전을 재검토한다.
+- `cardList.html`의 인라인 스크립트를 별도 JS 모듈로 분리하는 리팩터링을 검토한다.
+- 존재하지 않는 페이지 링크를 정리하거나, 향후 구현 예정이면 문서에 상태를 명확히 표기한다.
+
+## 판단 가이드
+- 신규 이미지 추가 관리가 목적이면 `Git LFS` 추적만으로도 충분하다.
+- 기존 clone 크기까지 줄이는 것이 목적이면 `Git LFS` 히스토리 마이그레이션 또는 자산 저장소 분리가 필요하다.

docs/update.md

@@ -0,0 +1,40 @@
+# 업데이트 이력
+
+## 2026-03-30 / docs-bootstrap-1
+
+### 수행 작업
+- 프로젝트 루트의 `.ai-rules.md`와 `.cursorrules`를 검토하여 문서 운영 규칙을 확인했다.
+- 부재하던 `docs/` 디렉터리를 생성하고 문서 기본 세트(`update.md`, `todo.md`, `spec.md`, `convention.md`, `history.md`, `map.md`)를 초기 구축했다.
+- 정적 사이트 구조를 기준으로 주요 페이지(`index.html`, `cardList.html`, `result.html`)와 보조 스크립트(`script/navigation.js`, `i18n/i18n.js`)의 역할을 문서화했다.
+- 카드 데이터셋 구조(`datas/*.js`)와 이미지 경로 규칙(`images/<seriesKey>/<fileName>`)을 정리했다.
+- 이미지 저장소 현황을 점검했다.
+- 점검 결과: `images/` 디렉터리 약 `1.7G`, 이미지 파일 약 `9,370개`, 데이터 파일 `52개`.
+- 대용량 이미지 자산 관리를 위한 `Git LFS` 도입 검토 사항과 주의점을 문서에 반영했다.
+
+### 메모
+- 현재 저장소에는 `docs/`가 없었기 때문에 이번 작업은 문서 체계 초기 세팅 성격이 강하다.
+- `Git LFS`는 신규 이미지 유입 관리에는 유효하지만, 저장소 자체를 즉시 가볍게 만들지는 않으므로 히스토리 정리 전략을 별도 검토해야 한다.
+
+## 2026-03-30 / lfs-migration-1
+
+### 수행 작업
+- `images/**` 전체를 `Git LFS` 대상으로 관리하기 위해 `.gitattributes`를 추가했다.
+- 기존 저장소 용량 절감을 목표로 `Git LFS` 히스토리 마이그레이션을 수행하는 방향으로 결정했다.
+- 현재 변경분을 포함한 뒤 전체 히스토리를 재작성하고 강제 푸시하는 절차를 진행한다.
+
+### 메모
+- 이번 작업은 단순 추적 설정이 아니라 과거 커밋까지 다시 쓰는 작업이므로 커밋 해시가 변경된다.
+- 원격 반영 시 일반 푸시가 아닌 `force-with-lease`가 필요하다.
+- 마이그레이션 체크아웃 이후 `ua27`의 추가 이미지와 데이터 보완분이 확인되어 최종 반영 대상에 포함했다.
+
+## 2026-03-30 / repo-reset-1
+
+### 수행 작업
+- 저장소 용량을 근본적으로 단순화하기 위해 현재 로컬 작업본을 기준으로 새 루트 커밋 하나만 남기는 방향으로 전환했다.
+- 기존 Git 히스토리는 원격 `main`에서는 제거하고, 로컬 백업 브랜치로만 보존하는 방식으로 진행한다.
+- `images/**`는 계속 `Git LFS` 대상으로 유지한다.
+- 새 시작 버전은 `v3.0.0`으로 정하고, 기존 `1.x`, `2.x` 버전 이력은 새 원격 기준에서 계승하지 않기로 했다.
+
+### 메모
+- 이 작업 후 원격 저장소는 사실상 "현재 스냅샷 기반 새 저장소"처럼 동작한다.
+- 과거 커밋 이력, 기존 태그, 옛 해시는 원격 기준으로 더 이상 사용하지 않게 된다.