uniare.sori.studio/docs/history.md

의사결정 이력

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