프로젝트 문서 체계 정비

docs/codex-handoff.md

@@ -1,61 +1,71 @@
-# Codex Handoff Guide
+# 작업 인계 가이드
 
-## 목적
-- 이 문서는 다른 작업 환경이나 다른 Codex 세션에서 프로젝트를 이어받더라도 같은 품질 기준으로 작업하기 위한 운영 기준서다.
-- 특히 이 저장소는 정적 HTML/JS 프로젝트이면서 카드 데이터와 이미지 자산 비중이 크기 때문에, "코드 수정"보다 "데이터-번역-이미지 일치"가 더 중요하다.
+## Handoff(핸드오프)란?
+다른 개발자나 운영 담당자가 지금 작업을 이어받을 때 빠르게 상황을 이해하도록 정리한 문서입니다. 비개발자에게는 '작업 인수인계 노트'라고 생각하면 됩니다.
 
-## 현재 기준 릴리즈
-- 현재 작업 기준 버전: `v4.0.0`
-- 이번 릴리즈 핵심 반영:
-- 회원·인증·덱 API (`api/`, Docker)
-- 공유 코드 기반 덱 공유 (`/d/:code`, `GET /api/v1/decks/:shareCode`)
-- 관리자 화면 (`admin.html`)
-- `?cards=` URL 방식 폐기
+## 우선 확인
 
-## 다음 작업자에게 반드시 전달할 것
-- 이 프로젝트는 빌드 시스템 중심 앱이 아니라 `index.html`, `cardList.html`, `result.html` 3개 페이지가 직접 동작하는 정적 사이트다.
-- 신규 시리즈를 추가할 때는 항상 아래 3가지를 한 세트로 본다.
-- `datas/<series>.js`
-- `images/<series>/`
-- `i18n/translations.ko.json`, `i18n/translations.ja.json`, `i18n/translations.en.json`
-- 이미지 자산은 `images/**` 전체가 `Git LFS` 대상이다. 대용량 이미지가 일반 Git 객체로 들어가지 않게 주의한다.
-- `cardList.html`은 `?series=<seriesKey>` 값을 기준으로 `./datas/${seriesKey}.js`를 동적 import 한다. 즉, 시리즈 키 불일치가 있으면 화면에서 바로 깨진다.
-- 카드 이미지 렌더링은 최종적으로 `images/${seriesKey}/${fileName}` 규칙을 사용하므로, `imgSrc`에는 파일명 기준 일관성이 중요하다.
-- 릴리즈 버전이 바뀌면 최소한 아래 두 곳은 함께 맞춘다.
-- `index.html`의 `<title>` 및 상단 배지
-- `docs/spec.md`, `docs/update.md`, 필요 시 `docs/history.md`
+1. 프로젝트 루트 `AGENTS.md`
+2. `docs/spec.md`
+3. `docs/todo.md`
+4. `docs/history.md`
+5. `docs/convention.md`
+6. `docs/map.md`
+7. `docs/deploy.md`
 
-## 품질 기준
-- 신규 시리즈 반영 시 데이터 파일만 추가하고 번역 키를 빼먹지 않는다.
-- 카드 번호(`Number`) 그룹과 실제 파일명 규칙이 시리즈 키와 일치해야 한다.
-- 병렬 카드(`parallel: true`)는 일반 카드와 같은 카드 번호를 공유하되 이미지 파일만 다르게 유지한다.
-- `trigger`는 `null`, `COLOR`, `FINAL`, `SPECIAL`만 사용한다.
-- AP 카드의 `color`는 `AP`를 사용한다.
-- 릴리즈 전에 `git diff --stat`으로 변경 범위를 보고, 데이터/번역/이미지 중 빠진 축이 없는지 확인한다.
+현재 버전은 루트 `VERSION`을 기준으로 확인한다.
 
-## 작업 절차
-1. 변경 요청이 신규 시리즈 추가인지, 기존 시리즈 수정인지 먼저 구분한다.
-2. 관련 `datas/*.js`와 `images/<series>/` 상태를 확인한다.
-3. `i18n/translations.*.json`에 시리즈명 또는 UI 문구 변경이 필요한지 확인한다.
-4. 화면에서 버전 표기를 바꿔야 하는 성격의 변경인지 판단한다.
-5. `docs/update.md`에 이번 반영 내용을 남긴다.
-6. 릴리즈성 변경이면 `docs/history.md` 또는 이 문서에도 기준 변화를 남긴다.
-7. 커밋 전 `git status`, `git diff --stat`, 필요한 경우 간단한 구문 체크를 수행한다.
+## 프로젝트 핵심
 
-## 릴리즈 전 체크리스트
-- `datas/<series>.js`가 실제로 import 가능한 형식인지 확인
-- `images/<series>/` 파일이 데이터의 `imgSrc`와 대응되는지 확인
-- `translations.ko/ja/en`에 시리즈 키가 모두 존재하는지 확인
-- 버전 표기가 문서와 UI에서 일치하는지 확인
-- `images/**`가 계속 LFS로 잡히는지 확인
-- 커밋 메시지에 릴리즈 의도가 드러나는지 확인
+- 정적 HTML·JavaScript 프론트와 Express·SQLite API를 함께 사용한다.
+- 운영은 `docker-compose.prod.yml`의 `uniare-web`, `uniare-api` 구성이 기본이다.
+- 덱 공유는 `/d/<shareCode>`와 `GET /api/v1/decks/:shareCode`를 사용한다.
+- `?cards=<JSON>` 공유 방식은 사용하지 않는다.
+- 표시 브랜드는 UNIARE지만 `UaDeckApi`, `uadeck_token`, `uadeck.db` 등 내부 식별자는 호환을 위해 유지한다.
 
-## 커밋 메시지 가이드
-- 릴리즈 커밋 예시: `v3.1.0: add ua51 series and handoff docs`
-- 수정 커밋 예시: `fix: add missing ua49 parallel images`
-- 되돌림 커밋 예시: `revert: restore original card list interactions`
+## 카드 데이터 작업
 
-## 주의할 점
-- 이 저장소는 이미지 비중이 매우 크다. 원격 업로드 전에 대용량 변경이 의도된 것인지 다시 확인한다.
-- 현재 문서 체계는 `docs/update.md`가 작업 로그, `docs/history.md`가 의사결정, `docs/spec.md`가 구조 명세 역할을 맡는다.
-- 후속 작업자가 빠르게 맥락을 잡게 하려면, "무엇을 바꿨는지"보다 "왜 같이 바꿔야 하는지"를 문서에 남기는 편이 더 중요하다.
+신규 시리즈 또는 카드는 아래 항목을 한 세트로 확인한다.
+
+```text
+datas/<series>.js
+images/<series>/
+i18n/translations.ko.json
+i18n/translations.ja.json
+i18n/translations.en.json
+```
+
+- `imgSrc`와 실제 이미지 파일명이 일치해야 한다.
+- 동일 카드의 패러렐 판본은 같은 `Number`를 사용한다.
+- `images/**`는 Git LFS 대상이다.
+- `datas/` 변경 후 API 카드 캐시를 갱신하려면 `uniare-api`를 재시작한다.
+
+## 변경 후 문서
+
+- 현재 구현 변경: `spec.md`
+- 이번 작업 기록: `update.md`
+- 결정 이유: `history.md`
+- 남은 작업: `todo.md`
+- 사용자 공개 변경: `changelog.md`
+- 파일 역할 변경: `map.md`
+- 배포 절차 변경: `deploy.md`
+
+## 검증
+
+```bash
+git diff --check
+git status --short
+```
+
+변경 성격에 따라 다음도 확인한다.
+
+- HTML·정적 자산: 브라우저 새로고침
+- `datas/`: API 재시작 후 카드 목록과 저장 덱 조회
+- API 코드: Docker 재빌드와 `/api/v1/health`
+- Tailwind 클래스: `npm run build:css`
+
+## 커밋
+
+- 커밋 메시지는 한국어로 작성한다.
+- 커밋하는 완료 작업은 `VERSION`을 증가시킨다.
+- 민감 정보와 `api/data/` 운영 파일을 커밋하지 않는다.