---
title: "ディスコグラフィー機能 運用ドキュメント"
---

## 概要

ディスコグラフィー機能は MusicBrainz からリリース情報を取得・正規化し、Vercel Blob に保存する。
毎日 JST 20:30 に自動同期する GitHub Actions ジョブ（`sync-discography.yml`）で運用する（当面の間）。

---

## 初回セットアップ手順

1. **手動実行で Blob URL を取得する**

   GitHub Actions の `Sync Discography` ワークフローを `workflow_dispatch` で手動実行する。
   初回は `RELEASES_BLOB_URL` が未設定のため現在のリリースデータの取得はスキップされる（既存データとのマージなしで同期が実行される）。
   `BLOB_READ_WRITE_TOKEN` が設定されていれば MusicBrainz から取得したリリースがそのまま Blob に書き込まれる。

   > 注意: `BLOB_READ_WRITE_TOKEN` が未設定の場合は Blob への書き込みが行われない（ドライランモード）。事前に Repository secrets に登録しておくこと。

2. **Blob URL を Repository secrets に登録する**

   Blob への書き込みが完了すると、固定 URL `releases.json`（`addRandomSuffix: false`）で保存される。
   Vercel Blob のダッシュボードまたは `@vercel/blob` SDK の `list()` で URL を確認し、
   `RELEASES_BLOB_URL` として Repository secrets に登録する。

3. **定期実行の確認**

   次回の自動実行（毎日 JST 20:30）でデータが更新されることを確認する。

---

## 定期同期の仕組み

| 項目 | 内容 |
| ---- | ---- |
| 実行スケジュール | 毎日 JST 20:30（cron: `30 11 * * *`）（当面の間） |
| スクリプト | `scripts/sync-discography.ts` |
| データソース | MusicBrainz API（アーティスト MBID: `013c8e5b-d72a-4cd3-8dee-6c64d6125823`） |
| 保存先 | Vercel Blob（`releases.json`） |
| フェイルセーフ | 取得0件の場合は既存データを維持して終了 |

---

## 手動実行手順

通常の運用ではスケジュール実行で十分だが、以下の場合は手動実行が必要。

- 初回セットアップ時
- スケジュール実行の失敗後の手動リカバリー
- データの即時更新が必要な場合

**手順:**

1. GitHub の当該リポジトリを開く
2. Actions → `Sync Discography` → `Run workflow` で手動実行する
3. 実行ログで取得件数・正規化後件数・Blob 書き込み完了を確認する

---

## 障害対応

### ケース1: ジョブが失敗した（ステータス: failure）

1. GitHub Actions のログを確認する
2. 以下のいずれかを判断する:

   | エラー | 原因 | 対応 |
   | ------ | ---- | ---- |
   | `BLOB_READ_WRITE_TOKEN` 未設定 | secrets 登録漏れ | Repository secrets を確認・登録後に再実行 |
   | MusicBrainz API エラー（4xx/5xx） | MusicBrainz 側の障害 | MusicBrainz の稼働状況を確認し、復旧後に再実行 |
   | ネットワークエラー | 一時的な接続不安定 | 再実行（最大 2 回まで自動再試行あり） |

### ケース2: 取得が0件で既存データを維持した

ログに「取得したリリースが0件です。既存データを維持します。」が表示された場合:

1. MusicBrainz へのアクセスが可能か確認する（サービス稼働状況を参照）
2. ブラウザで `https://musicbrainz.org/artist/013c8e5b-d72a-4cd3-8dee-6c64d6125823` を開いてリリース一覧が表示されるか確認する
3. 問題なければしばらく待って手動再実行する

> 既存データは Vercel Blob に保持されているため、ユーザーへの影響はない。

### ケース3: Vercel Blob のデータが破損・消失した

1. GitHub Actions の `workflow_dispatch` でスクリプトを再実行する
2. MusicBrainz から再取得・上書き保存される
3. 再実行後に `RELEASES_BLOB_URL` が変わっていないことを確認する（`addRandomSuffix: false` のため URL は固定）

---

## データ確認方法

### リリース件数の確認

```bash
curl -s "$RELEASES_BLOB_URL" | jq '.releases | length'
```

### 最新リリースの確認

```bash
curl -s "$RELEASES_BLOB_URL" | jq '.releases | sort_by(.releaseDate) | last'
```

### 特定タイトルの検索

```bash
curl -s "$RELEASES_BLOB_URL" | jq '.releases[] | select(.title | contains("LOVEマシーン"))'
```

---

## 新シングル発売時のカバーアート取得手順

新しいシングル・アルバムが MusicBrainz に登録されたことを確認してから以下の手順を実施する。

### 前提条件

- MusicBrainz にリリースが登録済みであること
- `sync-discography` → `sync-events` が実行済みで、`events` テーブルに該当レコードが作成されていること
- `.env.local` に `DATABASE_URL` が設定されていること

### 手順

```bash
# イベントテーブルの未取得リリースにカバーアートを一括付与する
LOG_LEVEL=TRACE bun run scripts/patch/fetch-release-images.ts
```

- `[TRACE] 更新: "タイトル" (MBID) → https://...` が出れば取得成功
- `[WARN] カバーアートなし:` が出た場合は CAA に画像が未登録（後日再実行で取得できることがある）

### 仕組み

Cover Art Archive（CAA）の release-group エンドポイントを使用する。
`releases.releaseId` は MusicBrainz のリリースグループ MBID であるため、特定の盤が CAA に未登録でも
同グループ内の他の盤に画像があれば取得できる。

> `manual-` プレフィックスの手動登録リリースは MBID を持たないため、本スクリプトの対象外。

---

## 関連ファイル

| ファイル | 説明 |
| -------- | ---- |
| `scripts/workflow/sync-discography.ts` | 同期スクリプト本体 |
| `.github/workflows/sync-discography.yml` | GitHub Actions ワークフロー |
| `lib/musicbrainz.ts` | MusicBrainz API クライアント |
| `lib/release-normalizer.ts` | 正規化・重複排除ロジック |
| `lib/member-release-linker.ts` | メンバー紐づけロジック |
| Neon `releases` テーブル | `lib/releases.ts` の `fetchReleasesFromDB()` 経由で参照 |
| `scripts/patch/fetch-release-images.ts` | カバーアート一括取得スクリプト |
| `scripts/lib/cover-art.ts` | Cover Art Archive API クライアント |