프로젝트 문서 체계 정비

docs/history.md

@@ -1,82 +1,121 @@
 # 의사결정 이력
 
-## 2026-06-22 / NAS 운영 네이밍 정리 (`uniare-*`)
-- 배경: NAS에 기존 `uniare-web` 컨테이너와 신규 `uadeck-web` 컨테이너가 공존하면서 포트 충돌 및 식별 혼선이 발생했다.
-- 결정:
-- Docker Compose 서비스/컨테이너 명칭을 프로젝트 식별자 기준 `uniare-*`로 통일한다.
-- Nginx 내부 프록시 대상도 서비스명 변경에 맞춰 `uniare-api`로 함께 정렬한다.
-- 이유:
-- 운영 시 `docker ps`, 로그 확인, 재시작 명령에서 컨테이너 목적을 즉시 식별하기 위함.
-- 기존 운영 스택(`uniare`)과 명칭 일관성을 맞춰 재배포 실수를 줄이기 위함.
+## 2026-06-23 v4.0.0 — SQLite 백업은 온라인 백업 API를 사용
 
-## 2026-06-19 / v4.0.0 구현 완료
-- 배경: 설계 확정 후 회원·API·공유 시스템 1차 구현.
-- 반영: `api/` 백엔드, Docker Compose, 인증/덱/관리자 API, 프론트 신규 페이지 및 헤더 프로필 UI.
-- 배포: NAS Docker + Nginx `/api/`, `/d/` 프록시 필요.
+💡 WAL 모드에서 DB 본파일만 복사하면 아직 병합되지 않은 최신 트랜잭션이 누락될 수 있기 때문.
+🔧 운영 중에는 `better-sqlite3`의 `backup()`으로 일관된 백업본을 만든 뒤 컨테이너 밖으로 복사.
 
-## 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-06-23 v4.0.0 — 헤더 로고 규격을 공통 스타일로 관리
 
-## 2026-04-19 / v3.1.0 릴리즈 기준 확정
-- 배경: 저장소의 마지막 명시 릴리즈 기록은 `v3.0.1`인데, 메인 화면은 이미 `v3.1`을 노출하고 있어 실제 릴리즈 이력과 화면 표기가 어긋나 있었다.
-- 결정:
-- 이번 반영분을 `v3.1.0`으로 정의하고, 화면 표기와 문서 표기를 같은 버전으로 통일한다.
-- 이후 버전 증가는 `docs/update.md`에 먼저 기록한 뒤 화면 표기와 함께 반영한다.
-- 이유:
-- 외부 협업자나 후속 Codex 작업자가 "현재 배포 기준이 무엇인지" 즉시 판단할 수 있어야 한다.
-- 자산 중심 정적 프로젝트 특성상 코드보다 데이터/이미지 변경이 잦기 때문에, 명시 릴리즈 기준이 없으면 누락 여부를 추적하기 어렵다.
+💡 페이지마다 로고 크기를 따로 지정하면 화면 이동 시 높이가 달라지고 수정 지점도 늘어나기 때문.
+🔧 `style/brand.css`의 `.app-brand-logo`와 `--brand-logo-height`를 모든 헤더의 단일 기준으로 채택.
 
-## 2026-03-30 / 문서 체계 초기화
-- 배경: 프로젝트 루트에 AI 작업 규칙은 있었지만 `docs/` 실체가 없어 규칙과 실제 운영 상태가 분리되어 있었다.
-- 결정: 규칙 문서가 요구하는 핵심 문서 6종을 먼저 생성하고, 이후 변경 시 이 파일들을 기준 문서로 유지한다.
-- 기대 효과: 작업 내역, 기술 구조, 화면-파일 연결, 향후 할 일을 한곳에서 추적할 수 있다.
+## 2026-06-23 v4.0.0 — 표시 브랜드는 UNIARE, 내부 식별자는 호환 유지
 
-## 2026-03-30 / 이미지 관리 방식 1차 판단
-- 배경: `images/` 디렉터리 용량이 약 `1.7G`, 파일 수가 `9,370개` 수준으로 증가했다.
-- 관찰:
-- 개별 파일이 아주 크지 않아도 Git 일반 객체로 누적되면 clone 및 fetch 비용이 계속 증가한다.
-- 이미지 추가가 잦은 프로젝트 특성상 저장소 히스토리 비대화가 반복될 가능성이 높다.
-- 결정:
-- 신규 이미지 유입 관리 목적이라면 `Git LFS` 도입을 권장한다.
-- 단, 이미 커진 저장소를 즉시 가볍게 만드는 해결책으로 `Git LFS`만 기대해서는 안 된다.
-- 히스토리 크기까지 줄여야 하면 `git lfs migrate` 또는 자산 저장소 분리/CDN 이전을 별도 의사결정으로 다룬다.
-- 보류 사유:
-- 원격 저장소의 LFS 지원 여부, 무료 용량, 대역폭 정책을 아직 확인하지 않았다.
-- 기존 협업자들의 개발 환경에 `git lfs` 설치를 요구하게 되므로 도입 공지가 필요하다.
+💡 사용자에게 보이는 제품명은 통일하되 기존 API 클라이언트와 저장 데이터의 호환성은 깨지 않기 위함.
+🔧 화면·문서·다운로드 파일명은 `UNIARE`로 변경하고 `uadeck_token`, `uadeck.db`, `UaDeckApi`, `/api/v1`은 유지.
 
-## 2026-03-30 / 이미지 히스토리 전체 LFS 마이그레이션 결정
-- 배경: 목적이 "앞으로 예방"이 아니라 "기존 저장소 용량 절감"으로 명확해졌다.
-- 확인:
-- 로컬 환경에 `git lfs`가 설치되어 있다.
-- 원격 저장소에 LFS 엔드포인트가 설정되어 있다.
-- 결정:
-- `images/**` 전체 히스토리를 `Git LFS`로 마이그레이션한다.
-- 현재 작업 중인 `ua27` 데이터 및 이미지 추가분도 함께 반영한다.
-- 영향:
-- 기존 커밋 해시가 모두 재작성된다.
-- 원격 반영 시 강제 푸시가 필요하다.
-- 협업 중인 다른 클론은 재동기화 절차가 필요하다.
+## 2026-06-23 v4.0.0 — 주요 화면 너비를 1280px로 통일
 
-## 2026-03-30 / 새 루트 커밋 기준 저장소 재시작 결정
-- 배경: `images/**`는 LFS 포인터로 전환됐지만, 저장소 자체는 과거 Git 객체 영향으로 여전히 비대했다.
-- 결정:
-- 현재 로컬 작업본을 단일 기준 스냅샷으로 보고 새 루트 커밋을 만든다.
-- 원격 `main`은 새 루트 커밋으로 교체한다.
-- 기존 히스토리는 로컬 백업 브랜치에서만 보존한다.
-- 새 버전 체계는 `v3.0.0`부터 다시 시작한다.
-- 이미지 자산은 새 시작 이후에도 `Git LFS` 정책을 유지한다.
-- 이유:
-- 가장 확실하게 Git 일반 히스토리 용량을 줄일 수 있다.
-- 추가적인 서버 GC 상태나 숨은 과거 객체를 더 추적하지 않고도 정리 목적을 달성할 수 있다.
+💡 페이지 이동 때 헤더와 본문 폭이 달라지는 시각적 흔들림을 줄이고 광고 레일을 안정적으로 배치하기 위함.
+🔧 홈·편집·결과·프로필·덱 목록의 공통 최대 너비를 `80rem` 기준으로 정렬.
+
+## 2026-06-22 v4.0.0 — Docker 서비스 이름을 `uniare-*`로 통일
+
+💡 NAS에서 구·신규 컨테이너가 혼재할 때 포트 충돌과 운영 명령 실수를 줄이기 위함.
+🔧 Compose 서비스·컨테이너·볼륨과 Nginx 프록시 대상을 `uniare-web`, `uniare-api`, `uniare-data`로 정렬.
+
+## 2026-06-22 v4.0.0 — 운영 웹 컨테이너는 허용 자산만 읽기 전용 공개
+
+💡 프로젝트 루트 전체를 웹 루트로 노출하면 `.env`, `.git`, `docs`, API 소스가 외부에 노출될 수 있기 때문.
+🔧 HTML과 `script`, `style`, `i18n`, `datas`, `images`만 Nginx에 read-only 볼륨으로 연결.
+
+## 2026-06-22 v4.0.0 — 공개 덱은 사용자 공개 설정을 기준으로 구성
+
+💡 관리자 전용 프리셋보다 사용자가 직접 공개한 덱을 탐색하는 방식이 서비스 흐름에 더 자연스럽기 때문.
+🔧 `/preset.html`과 `GET /api/v1/decks/presets`는 만료되지 않은 공개 사용자 덱을 최신순으로 제공.
+
+## 2026-06-22 v4.0.0 — 덱 미리보기는 1200px PNG로 정규화
+
+💡 브라우저와 옵션에 따라 저장 썸네일 크기가 달라지고 큰 base64 요청이 413 오류를 일으켰기 때문.
+🔧 저장 이미지는 1200px 기준 PNG로 만들고 Nginx 요청 한도 25MB, Express JSON 한도 20MB를 적용.
+
+## 2026-06-22 v4.0.0 — 즐겨찾기는 브라우저 로컬 상태로 우선 제공
+
+💡 서버 스키마를 늘리지 않고도 공개 덱과 내 덱 탐색 편의를 빠르게 제공하기 위함.
+🔧 공유 코드를 키로 `localStorage`에 저장하며 계정 간 동기화는 후속 과제로 남김.
+
+## 2026-06-22 v4.0.0 — 정적 프론트를 유지하며 회원·덱 API를 추가
+
+💡 기존 카드 데이터와 화면을 전면 재작성하지 않고 로그인, 소유권, 공유 기능을 확장하기 위함.
+🔧 정적 HTML/JavaScript는 유지하고 Express·SQLite API와 Docker Compose 운영 구성을 추가.
+
+## 2026-06-22 v4.0.0 — 덱 공유는 공유 코드와 REST API를 사용
+
+💡 `?cards=<JSON>` 방식의 긴 URL과 중복 데이터를 없애고 공개 범위·작성자·수정 권한을 관리하기 위함.
+🔧 DB에는 `{number,count,key}`만 저장하고 `GET /api/v1/decks/:shareCode` 응답에서 카드 메타를 합성.
+
+## 2026-06-22 v4.0.0 — 회원 덱과 비회원 공유의 보존 기간을 분리
+
+💡 계정 소유 덱은 영구 관리하고 익명 공유 데이터는 무기한 누적되지 않게 하기 위함.
+🔧 회원 덱은 만료 없이 저장하고 비회원 덱은 공개 상태로 30일 뒤 만료되도록 구성.
+
+## 2026-06-22 v4.0.0 — 프로필 이미지는 클라이언트에서 PNG로 정규화
+
+💡 JPEG 등 원본 바이트를 `.png` 확장자로 저장해 브라우저 표시가 실패하는 문제를 막기 위함.
+🔧 업로드 전에 Canvas로 PNG 변환·리사이즈하고 `updatedAt` 쿼리로 캐시를 갱신.
+
+## 2026-06-17 v3.1.2 — 유니티켓은 기존 시리즈 데이터에 병합
+
+💡 별도 시리즈를 만들기보다 동일 작품의 카드 번호 체계와 필터 흐름을 유지하는 편이 검색과 덱 구성이 일관되기 때문.
+🔧 `ua03`, `ua06`, `ua10` 데이터와 이미지에 헌터×헌터·테일즈 오브 어라이즈·히로아카 유니티켓을 추가.
+
+## 2026-06-15 v3.1.2 — 후속 부스터도 기존 시리즈 키를 재사용
+
+💡 작품 단위 진입 구조를 유지하면서 신규 부스터와 기존 카드를 한 화면에서 다루기 위함.
+🔧 마크로스 2nd는 `ua36`에 병합하고 무직전생 1st는 신규 `ua54` 데이터·이미지·번역 세트로 추가.
+
+## 2026-05-26 v3.1.2 — 신규 시리즈 반영은 데이터·이미지·번역을 한 세트로 관리
+
+💡 세 축 중 하나라도 빠지면 홈 노출, 카드 로딩, 이미지 표시 중 일부가 즉시 깨지기 때문.
+🔧 `ua50`, `ua53` 추가와 `ua52` 병렬 이미지 보강을 같은 릴리즈 단위로 반영.
+
+## 2026-05-16 v3.1.1 — 신규 시리즈와 기존 누락 자산을 함께 보강
+
+💡 새 시리즈 배포 시 인접 시리즈의 확인된 누락 이미지도 함께 정리해 데이터 신뢰도를 유지하기 위함.
+🔧 `ua52` 데이터·이미지·3개 언어명을 추가하고 `ua51` 병렬 이미지 누락분을 보강.
+
+## 2026-04-19 v3.1.0 — 릴리즈 기준과 작업 인계 문서를 명시
+
+💡 화면 버전과 실제 변경 이력이 어긋나 후속 작업자가 현재 배포 기준을 판단하기 어려웠기 때문.
+🔧 `ua51` 릴리즈를 `v3.1.0`으로 정의하고 데이터·이미지·번역 검증 절차를 문서화.
+
+## 2026-04-08 v3.0.1 — 카드 목록 상호작용은 기존 동작을 우선 보존
+
+💡 구조 개선 과정에서 수량 조절과 카드 선택 UX가 달라져 기존 사용 흐름이 훼손되었기 때문.
+🔧 변경된 목록 상호작용을 되돌리고 이후 UI 수정은 기존 동작 검증을 선행하도록 기준화.
+
+## 2026-04-08 v3.0.1 — 카드 번호와 덱 집계는 동일 식별자를 기준으로 처리
+
+💡 잘못된 카드 번호 하나가 패러렐 묶음과 덱 수량 계산까지 연쇄적으로 어긋나게 하기 때문.
+🔧 `ua27` 카드 번호를 정정하고 동일 `Number` 그룹의 수량 표시를 다시 동기화.
+
+## 2026-03-30 v3.0.1 — 데이터 경로는 실제 이미지 파일명을 기준으로 정합성 유지
+
+💡 데이터의 `imgSrc`와 저장 파일명이 다르면 카드가 존재해도 화면에서는 누락으로 보이기 때문.
+🔧 오기입 경로를 수정하고 누락 이미지 추가와 사용하지 않는 주석 데이터 제거를 함께 수행.
+
+## 2026-03-30 v3.0.0 — 저장소를 현재 스냅샷 기준 새 루트로 재시작
+
+💡 과거 대용량 이미지 객체로 비대해진 Git 이력을 가장 확실하게 줄이기 위함.
+🔧 현재 작업본을 새 루트 커밋으로 삼고 버전은 `v3.0.0`부터 재시작하며 기존 이력은 로컬 백업 브랜치에 보존.
+
+## 2026-03-30 v3.0.0 — 이미지 자산은 Git LFS로 관리
+
+💡 수천 개 카드 이미지가 일반 Git 객체로 누적되는 비용을 줄이고 코드 이력과 대용량 자산 관리를 분리하기 위함.
+🔧 `.gitattributes`에서 `images/**`를 LFS 대상으로 지정하고 신규 이미지도 같은 정책을 적용.
+
+## 2026-03-30 v3.0.0 — 문서를 목적별 기준 파일로 분리
+
+💡 구현 상태, 작업 로그, 결정 이유, 할 일을 한 문서에 섞지 않고 후속 작업자가 빠르게 맥락을 찾게 하기 위함.
+🔧 `spec`, `update`, `history`, `todo`, `deploy`, `map`, `convention`을 역할별 기준 문서로 운영.