# バッチ設計書 39-release-artifact

## 概要

本ドキュメントは、clojure-lspプロジェクトにおけるrelease-artifactバッチの設計仕様を定義するものです。release-artifactは、GitHubリリースにアーティファクトをアップロードするタスクです。

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

release-artifactバッチは、ビルド成果物（JARファイル、ネイティブバイナリなど）をGitHubリリースにアップロードするリリースタスクです。本番リリースと開発ビルドの両方に対応しています。

**業務上の目的・背景**：ビルド成果物をGitHubリリースから直接ダウンロード可能にするため、自動アップロード機能が必要です。CI/CDパイプラインからの自動実行により、リリースプロセスを効率化し、手動アップロードの手間とミスを削減します。

**バッチの実行タイミング**：CI/CDパイプライン（GitHub Actions等）から自動実行されます。releaseタスク実行後のビルド完了時、またはdev-buildsリポジトリへの定期的なビルドアップロード時に実行されます。

**主要な処理内容**：
1. GITHUB_TOKEN環境変数の確認
2. 現在のブランチがmain/masterか確認
3. 本番リリースタグの有無を確認
4. 本番タグがある場合はclojure-lspリポジトリにアップロード
5. 本番タグがない場合はclojure-lsp-dev-buildsリポジトリにアップロード
6. SHA256チェックサムを同時にアップロード

**前後の処理との関連**：releaseタスクでタグが作成された後、ビルドタスク（native-cli、cli-prod-jar等）が完了した後に実行されます。borkdude/gh-release-artifactライブラリを使用してGitHub APIと連携します。

**影響範囲**：GitHubリリースにファイルがアップロードされます。本番リリースはclojure-lsp/clojure-lspリポジトリに、開発ビルドはclojure-lsp/clojure-lsp-dev-buildsリポジトリにアップロードされます。

## バッチ種別

リリース処理 / アーティファクト配布

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | ビルド完了時 |
| 実行時刻 | - |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | CI/CDパイプライン |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Babashka | Babashka (bb) がインストールされていること |
| GITHUB_TOKEN | 有効なGitHubトークンが環境変数に設定されていること |
| リリースブランチ | main/masterブランチで実行されること |
| アーティファクト | アップロードするファイルが存在すること |

### 実行可否判定

1. GITHUB_TOKENが設定されていない場合はスキップ
2. main/masterブランチ以外で実行された場合はスキップ
3. 本番タグも開発タグもない場合はスキップ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| file | String | Yes | なし | アップロードするファイルのパス |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| アップロードファイル | 任意 | JAR、ネイティブバイナリ等 |
| lib/resources/CLOJURE_LSP_VERSION | テキスト | バージョン番号（本番リリース時） |
| git tag | - | 本番リリースタグの確認 |
| GITHUB_TOKEN | 環境変数 | GitHubアクセストークン |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| GitHub Release | バイナリ | アップロードされたアーティファクト |
| GitHub Release | テキスト | SHA256チェックサム |
| 標準出力 | テキスト | 処理結果メッセージ |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| アップロード先（本番） | clojure-lsp/clojure-lsp リポジトリのリリース |
| アップロード先（開発） | clojure-lsp/clojure-lsp-dev-builds リポジトリのリリース |
| チェックサム | SHA256形式で同時アップロード |

## 処理フロー

### 処理シーケンス

```
1. Babashkaタスク起動
   └─ bb release-artifact <file> コマンドを実行
2. clojure-lsp.release-artifact/release関数呼び出し
   └─ release_artifact.clj内のrelease関数を実行
3. 環境確認
   └─ GITHUB_TOKEN、ブランチ、タグの確認
4. 条件分岐
   ├─ GITHUB_TOKENなし → スキップ
   ├─ リリースブランチ外 → スキップ
   ├─ 本番タグあり → 本番リリースにアップロード
   ├─ 開発タグあり → 開発リリースにアップロード
   └─ タグなし → スキップ
5. アップロード実行
   └─ ghr/overwrite-assetでGitHubにアップロード
6. 完了
   └─ アップロード成功を確認
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[bb release-artifact file 実行]
    B --> C[release関数呼び出し]
    C --> D{GITHUB_TOKEN存在?}
    D -->|なし| E[スキップ: no GITHUB_TOKEN]
    D -->|あり| F{リリースブランチ?}
    F -->|いいえ| G[スキップ: not on release branch]
    F -->|はい| H{本番タグ存在?}
    H -->|はい| I[本番リリースにアップロード]
    H -->|いいえ| J{開発タグ存在?}
    J -->|はい| K[開発リリースにアップロード]
    J -->|いいえ| L[スキップ: No prod or dev tags]
    I --> M[ghr/overwrite-asset実行]
    K --> M
    M --> N{アップロード成功?}
    N -->|成功| O[正常終了]
    N -->|失敗| P[エラー終了]
    E --> Q[終了]
    G --> Q
    L --> Q
    O --> Q
    P --> Q
```

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

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

本バッチはデータベース操作を行いません。GitHub APIを通じてリリースアセットを操作します。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 非0 | ファイル未指定 | fileパラメータが指定されていない場合 | ファイルパスを引数に指定 |
| 非0 | ファイル不存在 | 指定されたファイルが存在しない場合 | ファイルの存在を確認 |
| 非0 | 認証エラー | GITHUB_TOKENが無効な場合 | トークンを再生成 |
| 非0 | アップロードエラー | GitHubへのアップロードが失敗した場合 | ネットワーク確認、再試行 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし、CI/CDでジョブ再実行） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

1. エラーメッセージを確認し、問題の原因を特定
2. GITHUB_TOKENの有効性を確認
3. ファイルの存在と読み取り権限を確認
4. ネットワーク接続を確認
5. CI/CDジョブを再実行

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 単一アップロード |
| コミットタイミング | アップロード完了時 |
| ロールバック条件 | アップロード失敗時は自動ロールバック |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1ファイル |
| 目標処理時間 | ファイルサイズに依存（数分以内） |
| メモリ使用量上限 | ファイルサイズに依存 |

## 排他制御

同じファイルの同時アップロードは推奨されません。:overwrite falseの設定により、同名ファイルの上書きは行われません。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| スキップログ | 条件不一致時 | スキップ理由 |
| 進捗ログ | アップロード時 | アップロード先タグ |
| 結果ログ | 処理完了時 | 成功/失敗メッセージ |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 終了コード | 非0 | CI/CDシステム通知 |
| アップロード時間 | 10分以上 | 開発チーム |

## 備考

- borkdude/gh-release-artifactライブラリを使用
- 本番リリースはCLOJURE_LSP_VERSIONファイルからタグを取得
- 開発リリースはclojure-lsp-dev-buildsリポジトリの最新タグを使用
- SHA256チェックサムは自動的に生成されアップロードされる
- :overwrite falseにより、既存ファイルの上書きは行われない
- 複数のCI環境（AppVeyor、CircleCI、GitHub Actions、Cirrus）のブランチ検出に対応
