# 의사결정 이력

## 2026-06-19 / v4.0.0 구현 완료
- 배경: 설계 확정 후 회원·API·공유 시스템 1차 구현.
- 반영: `api/` 백엔드, Docker Compose, 인증/덱/관리자 API, 프론트 신규 페이지 및 헤더 프로필 UI.
- 배포: NAS Docker + Nginx `/api/`, `/d/` 프록시 필요.

## 2026-06-19 / v4.0.0 덱 공유·API 설계 확정
- 배경: v3는 덱을 `?cards=<JSON>` URL에 실어 공유했으나 URL이 수천 자로 비대해지고, 옆 프로젝트도 개발 중이라 계약을 새로 잡을 수 있는 시점이다.
- 결정:
- URL 쿼리 기반 덱 공유는 **폐기**하고, 공유 코드 + REST API 방식으로 전환한다.
- **개인 덱**(`share_type=user`): 저장할 때마다 nanoid 8자 고유 코드 발급. 같은 카드 구성이라도 저장자마다 URL이 다르다.
- **메타 덱·프리셋**(`share_type=preset`): 카드 구성 해시 기반 고정 코드. 동일 구성이면 항상 같은 URL.
- DB에는 `{number, count, key}`만 저장하고, API 응답 시 `datas/`에서 카드 메타를 lookup하여 합성한다.
- 작성자, 생성일, 수정일, 조회수, 공개 여부 등 메타데이터를 덱 레코드와 함께 관리한다.
- 외부 연동(옆 프로젝트) 공식 계약: `GET /api/v1/decks/:shareCode`
- 프론트는 Vue 전환 없이 정적 HTML + API 호출 + Docker 백엔드로 확장한다.
- 이유:
- URL 길이·중복 데이터 문제 해소.
- 회원 덱 소유권·수정·비공개 설정이 자연스럽다.
- DB 용량은 덱 본문 기준 건당 수 KB 수준으로 경미하다.

## 2026-04-19 / v3.1.0 릴리즈 기준 확정
- 배경: 저장소의 마지막 명시 릴리즈 기록은 `v3.0.1`인데, 메인 화면은 이미 `v3.1`을 노출하고 있어 실제 릴리즈 이력과 화면 표기가 어긋나 있었다.
- 결정:
- 이번 반영분을 `v3.1.0`으로 정의하고, 화면 표기와 문서 표기를 같은 버전으로 통일한다.
- 이후 버전 증가는 `docs/update.md`에 먼저 기록한 뒤 화면 표기와 함께 반영한다.
- 이유:
- 외부 협업자나 후속 Codex 작업자가 "현재 배포 기준이 무엇인지" 즉시 판단할 수 있어야 한다.
- 자산 중심 정적 프로젝트 특성상 코드보다 데이터/이미지 변경이 잦기 때문에, 명시 릴리즈 기준이 없으면 누락 여부를 추적하기 어렵다.

## 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 상태나 숨은 과거 객체를 더 추적하지 않고도 정리 목적을 달성할 수 있다.