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

概要

ディスコグラフィー機能は 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）でデータが更新されることを確認する。

定期同期の仕組み

手動実行手順

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

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

手順:

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 は固定）

データ確認方法

リリース件数の確認

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

最新リリースの確認

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

特定タイトルの検索

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

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

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

前提条件

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

手順

# イベントテーブルの未取得リリースにカバーアートを一括付与する
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 を持たないため、本スクリプトの対象外。

関連ファイル