# 갤산기

홀로라이브 드림즈의 카드와 멤버 성장 상태를 관리하고, 악곡별 최적 배치와 카드 조합을 분석하는 비공식 도구입니다.

[온라인 서비스 이용](https://doricalc-holo.live/) · 한국어 전용 · PC 환경 권장

![갤산기 홈 화면](docs/images/home.png)

## 주요 기능

- 5성 카드의 타입, 주스탯, 기수와 스킬 정보 조회
- 보유 카드와 개화 단계, 메모리, 멤버 강화 수치 저장
- 멤버별 보드 노드와 연결 카드 설정
- 현재 편성에서 초록 노드의 자원 대비 효율 분석
- 특정 악곡과 5인 편성의 최적 배치 및 빈도 감소 조합 분석
- 고정 멤버를 기준으로 남은 자리에 들어갈 카드 조합 탐색
- 액티브·스페셜 발동 구간과 노트 분포 시각화
- 사용자 데이터 백업과 복원

## 서비스 이용

[갤산기 온라인 서비스](https://doricalc-holo.live/)에 접속해 사용합니다. 별도의 설치나 다운로드는 필요하지 않습니다.

Chrome 또는 Edge의 최신 버전을 권장합니다.

## 처음 사용하는 순서

### 1. 사용자 데이터를 설정합니다

상단 메뉴에서 **사용자 데이터 → 카드**로 이동해 보유 카드와 개화 단계를 입력합니다.

- 5성 카드는 `0~5` 개화 단계를 설정합니다.
- 4성 카드는 보유 여부와 5개화 여부를 설정합니다.
- 보유하지 않은 카드는 개화 단계를 변경할 수 없습니다.
- 행을 누르면 보유 여부를 빠르게 전환할 수 있습니다.

![카드 보유 및 개화 설정](docs/images/user-cards.png)

**사용자 데이터 → 일반**에서는 메모리 보유 수와 멤버 강화 수치를 설정하고, 전체 사용자 데이터를 백업하거나 복원할 수 있습니다.

### 2. 멤버 보드를 설정합니다

**사용자 데이터 → 보드**에서 멤버를 선택한 뒤 실제 게임에서 활성화한 노드를 같은 형태로 입력합니다.

- 빈 공간을 드래그해 보드를 이동합니다.
- 마우스 휠로 확대하거나 축소합니다.
- 인접하지 않은 노드를 누르면 중심에서 이어지는 최단 경로가 함께 활성화됩니다.
- 보드 슬롯에는 보유 카드를 한 장씩 배치할 수 있습니다.
- `모든 멤버 초록 3칸 활성화`와 `중앙 연결 노드 자동 배치`로 일반적인 설정을 빠르게 적용할 수 있습니다.

![멤버 보드 설정](docs/images/member-board.png)

같은 페이지의 **초록 노드 효율 분석**에서는 현재 편성을 기준으로 다음 항목을 비교할 수 있습니다.

- 아직 활성화하지 않은 노드 중 우선 활성화할 노드
- 이미 활성화한 노드 중 초기화를 검토할 노드
- 종합력 변화, 필요한 연결 노드 수, 자원 소모량과 그린 큐브 효율

목록의 항목을 누르면 해당 멤버와 노드로 바로 이동합니다.

### 3. 카드 정보를 확인합니다

**카드 목록**에서는 타입, 주스탯, 기수, 액티브 확률, 조건부 스킬과 이격 여부로 카드를 필터링할 수 있습니다. 카드 행을 누르면 패시브·액티브·스페셜·의상 효과가 펼쳐집니다.

![카드 목록과 상세 스킬](docs/images/cards.png)

### 4. 5인 편성의 최적 배치를 분석합니다

**배치 분석**은 선택한 악곡과 5인 조합을 유지하면서 가장 높은 점수를 내는 멤버 순서와 빈도 감소 조합을 찾습니다.

1. 악곡과 난이도를 선택합니다.
2. 5장의 카드와 개화 단계를 설정합니다.
3. 필요한 경우 카드별 빈도 감소를 특정 값으로 고정합니다.
4. 리더와 리더 의상을 선택합니다.
5. `최적 배치 분석`을 누릅니다.

![배치 분석 조건 설정](docs/images/analysis.png)

분석 결과에서는 최고·평균 점수, 최적 순서, 카드별 빈도 감소율과 함께 다음 시각화 자료를 확인할 수 있습니다.

- 초당 노트 분포
- 멤버별 액티브 발동 구간
- 중첩을 반영한 최종 액티브 적용 구간
- 멤버별 스페셜 발동 구간

분석 조건과 마지막 결과는 브라우저에 저장되며, 같은 악곡과 난이도의 조합 탐색에서 **기준 조합**으로 사용할 수 있습니다.

### 5. 더 좋은 카드 조합을 탐색합니다

**조합 탐색**은 악곡, 리더, 리더 의상과 최대 4명의 고정 카드를 기준으로 남은 자리에 들어갈 후보를 비교합니다.

- 고정하지 않은 자리에는 전체 5성 카드가 후보로 들어갑니다.
- 자동 후보의 개화 단계와 기수 보너스 덮어쓰기 값을 지정할 수 있습니다.
- 보유 카드의 실제 개화가 자동 후보 개화보다 높으면 실제 보유 개화를 우선 적용합니다.
- 고정 멤버별 개화, 빈도 감소, 파란 노드 전체 적용 여부와 기수 보너스를 따로 설정할 수 있습니다.
- 한 편성에는 같은 인물의 일반 카드와 이격 카드가 동시에 들어가지 않습니다.
- 결과는 최고 점수 기준으로 정렬되며 상위 조합의 상세 분석을 펼쳐볼 수 있습니다.

![조합 탐색 조건과 기준 조합](docs/images/combination.png)

`최대 컴퓨팅 자원 활용`을 켜면 탐색 속도가 빨라질 수 있지만, 분석 중 브라우저와 다른 프로그램의 반응이 느려질 수 있습니다.

## 데이터 저장과 백업

사용자 데이터와 분석 조건은 서버로 전송하지 않고 현재 브라우저의 `localStorage`에 자동 저장합니다.

- 브라우저나 사용자 프로필이 달라지면 별도의 데이터로 취급될 수 있습니다.
- 브라우저 데이터 삭제 시 저장 내용도 사라질 수 있습니다.
- 새 버전으로 이동하기 전 **사용자 데이터 → 일반 → 백업 내보내기**를 권장합니다.
- 백업 JSON은 다른 브라우저나 PC의 **백업 가져오기**에서 복원할 수 있습니다.

## 업데이트

검증이 끝난 업데이트는 온라인 서비스에 배포됩니다. 중요한 변경 전에는 사용자 데이터 백업을 권장합니다.

## 참고

- 이 프로젝트는 홀로라이브 드림즈의 비공식 팬 제작 도구입니다.
- 게임 업데이트와 확보된 데이터 범위에 따라 실제 게임 결과와 차이가 날 수 있습니다.
- 분석 결과는 입력한 카드·개화·보드·메모리·멤버 강화 데이터가 정확하다는 전제에서 계산됩니다.
- 카드와 악곡의 원본 게임 데이터는 프로젝트가 직접 소유하거나 공식 제공하는 데이터가 아닙니다.

<details>
<summary><strong>개발 환경과 실행 방법</strong></summary>

### 기술 구성

- SvelteKit + TypeScript + `@sveltejs/adapter-node`
- SQLite + Drizzle ORM
- Web Worker 기반 클라이언트 계산
- Docker / Docker Compose

계산 엔진은 UI와 분리하며 `UI → Engine → Models` 의존성 방향을 유지합니다.

### Docker 개발 실행

```bash
docker compose up --build
```

- 웹: <http://localhost:5173>
- 상태 확인: <http://localhost:5173/api/health>

개발 컨테이너는 시작할 때 패키지 설정·잠금 파일과 Node.js 버전을 확인하고, 변경되었으면 의존성 볼륨에 `npm ci`를 실행합니다. 실행 중 의존성이 변경되면 `docker compose restart app`으로 동기화할 수 있습니다. Dockerfile 변경 후에는 `docker compose up --build -d`로 컨테이너를 다시 생성하세요.

종료할 때 `docker compose down`은 SQLite 볼륨을 보존합니다. `docker compose down --volumes`는 저장된 볼륨까지 제거하므로 주의하세요.

### 호스트에서 실행

Node.js 22.12 이상이 필요합니다.

```powershell
Copy-Item .env.example .env
npm ci
npm run dev
```

### 검증과 빌드

```bash
npm run check
npm run build
npm run build:pages
```

### Production 실행

```bash
docker compose -f compose.prod.yaml up --build -d
```

- 웹: <http://localhost:3000>
- 상태 확인: <http://localhost:3000/api/health>

</details>

<details>
<summary><strong>게임 데이터 갱신과 카드 표시명 수정</strong></summary>

게임에서 직접 확보한 DB 스냅샷을 마스터 데이터 원본으로 사용합니다. HolodoriDB 원격 저장소를 가져오지 않습니다.

```bash
npm run data:sync
# 전체 변경을 읽고 보고한 뒤
npm run data:apply
```

검토 결과는 `data/game-db/review/latest.json`과 `latest.md`에 저장합니다. 원본은 `data/game-db/snapshots/`, 계산기용 중간 결과는 `data/game-db/derived/`에 보관합니다. 해시가 다른 스냅샷이나 누락된 테이블을 외부 자료로 대체하지 않습니다.

채보 본문은 별도 게임 SUS 파일입니다. 신규 이벤트 일정·배율은 검증한 게임 API 응답에서 생성하며, 과거 수동 이벤트 기록은 기존 출처를 유지합니다. DB 등록과 채보 갱신 방법 및 남은 예외는 [데이터 원본 안내](docs/game-data-source.md)를 참고하세요.

특별 버전명이나 번역 이름은 `data/card-overrides.csv`에서 관리합니다.

```csv
cardId,versionName,displayName
card-06002-5-uniq-0066-00,수영복,
```

- `cardId`: 수정할 카드의 고유 ID
- `versionName`: 이름 옆에 표시할 짧은 버전명
- `displayName`: 기본 멤버 이름을 완전히 바꿀 때만 입력

수정 후 `npm run data:sync`로 전체 변경을 검토·보고한 다음 `npm run data:apply`를 실행하면 반영됩니다. 이 파일은 원본 데이터를 다시 수집해도 덮어쓰지 않습니다.

</details>