# 작업 인계 가이드

## Handoff(핸드오프)란?
다른 개발자나 운영 담당자가 지금 작업을 이어받을 때 빠르게 상황을 이해하도록 정리한 문서입니다. 비개발자에게는 '작업 인수인계 노트'라고 생각하면 됩니다.

## 우선 확인

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`

현재 버전은 루트 `VERSION`을 기준으로 확인한다.

## 프로젝트 핵심

- 정적 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` 등 내부 식별자는 호환을 위해 유지한다.

## 카드 데이터 작업

신규 시리즈 또는 카드는 아래 항목을 한 세트로 확인한다.

```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/` 운영 파일을 커밋하지 않는다.