# バッチ設計書 6-Generate Sponsors README

## 概要

本ドキュメントは、Decap CMSプロジェクトにおけるGenerate Sponsors READMEワークフローのバッチ設計書である。GitHub Actionsで定義されたスケジュール実行パイプラインのうち、GitHub Sponsors情報を取得してREADME.mdにスポンサーアバターを自動更新する処理について記述する。

### 本バッチの処理概要

本バッチは、GitHub Sponsorsの情報を定期的に取得し、README.mdにスポンサーのアバター画像を自動更新するバッチである。毎週日曜日のUTC 0時にスケジュール実行されるほか、手動トリガーにも対応している。

**業務上の目的・背景**：オープンソースプロジェクトであるDecap CMSにとって、スポンサーへの謝意表明は重要な活動である。README.mdにスポンサーのアバターを掲載することで、プロジェクトを支援してくれるスポンサーの可視化と、新規スポンサー獲得の促進を図る。手動での更新は手間がかかるため、週次の自動更新により最新のスポンサー情報を維持する。

**バッチの実行タイミング**：毎週日曜日のUTC 0時（cron: 0 0 * * 0）にスケジュール実行される。また、workflow_dispatchによる手動トリガーも可能である。

**主要な処理内容**：
1. リポジトリのチェックアウト
2. GitHub Sponsors APIからスポンサー情報の取得（組織スポンサー含む、非アクティブスポンサー含む）
3. スポンサーアバターのHTMLテンプレート生成とREADME.mdへの挿入
4. 更新されたREADME.mdをreadme-sponsorsブランチにデプロイ

**前後の処理との関連**：本バッチは独立して動作する。readme-sponsorsブランチへのデプロイ後、メインブランチへのマージは手動またはPR経由で行われる可能性がある。

**影響範囲**：README.mdのスポンサーセクションが更新される。readme-sponsorsブランチが更新される。

## バッチ種別

データ連携（外部API連携 - スポンサー情報取得・ドキュメント更新）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 週次 |
| 実行時刻 | 00:00 UTC |
| 実行曜日 | 日曜日 |
| 実行日 | 該当なし |
| トリガー | cron（0 0 * * 0）/ 手動（workflow_dispatch） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| GITHUB_TOKENシークレット | GitHub Sponsors APIおよびリポジトリ書き込みに必要なトークンが利用可能であること |
| README.mdの存在 | リポジトリルートにREADME.mdが存在すること |
| contents: write権限 | ワークフローがリポジトリのコンテンツを書き込み可能であること |

### 実行可否判定

スケジュール（cron）に基づいて毎週日曜日UTC 0時に自動実行される。workflow_dispatchにより手動でも実行可能である。特別な実行可否判定ロジックは存在しない。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| GITHUB_TOKEN | シークレット | Yes | secrets.GITHUB_TOKEN | GitHub API認証トークン |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| GitHub Sponsors API | JSON | スポンサーのログイン名・アバター情報 |
| README.md | Markdown | スポンサーセクションを含むREADMEファイル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| readme-sponsorsブランチ | Git | 更新されたREADME.mdを含むブランチ |
| GitHub Actionsログ | テキスト | スポンサー情報取得・デプロイの実行ログ |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | README.md |
| 出力先 | readme-sponsorsブランチ |
| 文字コード | UTF-8 |
| 区切り文字 | 該当なし（Markdownファイル） |

## 処理フロー

### 処理シーケンス

```
1. ワークフロートリガー
   └─ cron（毎週日曜日UTC 0時）またはworkflow_dispatch
2. リポジトリチェックアウト
   └─ actions/checkout@v2
3. スポンサー情報生成
   └─ JamesIves/github-sponsors-readme-action@v1
       ├─ GitHub Sponsors APIからスポンサー情報取得
       ├─ organization: true（組織スポンサーを含む）
       ├─ active-only: false（非アクティブスポンサーも含む）
       └─ HTMLテンプレートに基づくアバター画像リンクの生成
4. README.mdデプロイ
   └─ JamesIves/github-pages-deploy-action@v4
       ├─ branch: readme-sponsors
       └─ folder: '.'（カレントディレクトリ全体をデプロイ）
```

### フローチャート

```mermaid
flowchart TD
    A[スケジュール/手動トリガー] --> B[リポジトリチェックアウト]
    B --> C[GitHub Sponsors API呼び出し]
    C --> D[スポンサーアバターHTML生成]
    D --> E[README.mdにスポンサー情報を挿入]
    E --> F[readme-sponsorsブランチにデプロイ]
    F --> G{デプロイ成功?}
    G -->|成功| H[ワークフロー成功]
    G -->|失敗| I[ワークフロー失敗]
```

## データベース操作仕様

### 操作別データベース影響一覧

本バッチではデータベース操作は行わない。

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 該当なし | 該当なし | 該当なし | 該当なし |

### テーブル別操作詳細

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | API認証失敗 | GITHUB_TOKENが無効または権限不足の場合 | トークンの権限設定を確認する |
| - | スポンサー情報取得失敗 | GitHub Sponsors APIのレスポンスエラー | GitHub APIの状態を確認して再実行する |
| - | ブランチデプロイ失敗 | readme-sponsorsブランチへの書き込みに失敗した場合 | contents: write権限を確認する |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 自動リトライなし（次回スケジュール実行またはworkflow_dispatchで再実行可能） |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

バッチ（ワークフロー）失敗時は以下の手順で対応する：
1. GitHub Actionsのログでエラー内容を確認する
2. API関連のエラーの場合はGitHub APIの状態を確認する
3. 権限関連のエラーの場合はワークフローのpermissionsとトークンの権限を確認する
4. 緊急性がなければ次回の週次スケジュール実行を待つ
5. 即座に更新が必要な場合はworkflow_dispatchで手動再実行する

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし（Git操作はアトミック） |
| コミットタイミング | readme-sponsorsブランチへのデプロイ時 |
| ロールバック条件 | 該当なし（readme-sponsorsブランチのGit履歴で巻き戻し可能） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | スポンサー数に依存（通常数十件程度） |
| 目標処理時間 | 数分以内 |
| メモリ使用量上限 | 最小（API呼び出しとファイル操作のみ） |

## 排他制御

明示的な排他制御は設定されていない。週次スケジュール実行のため、通常は重複実行の問題は発生しない。workflow_dispatchによる手動実行が同時に行われた場合でも、Gitブランチへのデプロイは最後の実行結果で上書きされるため問題はない。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ジョブ開始時 | GitHub Actionsにより自動的にジョブ開始が記録される |
| スポンサー取得ログ | スポンサー情報生成時 | 取得したスポンサー情報の概要 |
| デプロイログ | ブランチデプロイ時 | readme-sponsorsブランチへのデプロイ結果 |
| 終了ログ | ジョブ終了時 | GitHub Actionsにより自動的にジョブ完了ステータスが記録される |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| ジョブ成功/失敗 | 失敗時 | GitHub Actionsログ |

## 備考

- actions/checkout@v2（v4ではなくv2）を使用している点に注意
- JamesIves/github-pages-deploy-action@v4を使用してreadme-sponsorsブランチにデプロイする
- active-only: falseが設定されているため、過去のスポンサーも含めて表示される
- organization: trueが設定されているため、組織としてのスポンサーも含まれる
- スポンサーアバターのHTMLテンプレートは、48px幅の円形画像としてレンダリングされる
- テンプレート内のMustache記法（{{{ login }}}）はHTMLエスケープされない形式で出力される
- デプロイ先はreadme-sponsorsブランチであり、メインブランチに直接書き込まれるわけではない
- permissions: contents: writeが設定されており、ブランチへの書き込み権限が付与されている
