# バッチ設計書 15-Released Package Test

## 概要

本ドキュメントは、GitHub Actions ワークフロー「Released Package Test」の設計を定義するものである。リリース後のCLIパッケージ（@liam-hq/cli）の動作検証を自動化し、npmパッケージとしての品質を保証するバッチ処理について記載する。

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

**業務上の目的・背景**：npmパッケージのリリース後、実際にユーザーがインストール・使用できる状態であることを検証する必要がある。本バッチは、npxコマンドを使用してリリースされたバージョンのCLIパッケージを実行し、複数のスキーマフォーマット（postgres、schemarb、prisma）に対するERD生成機能をテストする。テスト結果はSlackに通知され、リリース品質の可視化を実現する。

**バッチの実行タイミング**：手動実行（workflow_dispatch）のみ。リリース後にバージョンを指定して実行する。

**主要な処理内容**：
1. 指定された遅延時間（delay_seconds）の待機
2. バージョン文字列の検証（セマンティックバージョニング形式）
3. `--version`オプションによるバージョン確認テスト
4. postgres形式でのERD生成テスト（Supabase schemaを使用）
5. schemarb形式でのERD生成テスト（Mastodon schema.rbを使用）
6. prisma形式でのERD生成テスト（Langfuse schema.prismaを使用）
7. テスト結果のSlack通知（成功/失敗）

**前後の処理との関連**：Release（No.5）ワークフロー後に手動でトリガーされることを想定。パッケージ公開から反映までの遅延を考慮し、delay_secondsパラメータを提供。

**影響範囲**：npmパッケージ（@liam-hq/cli）、Slackチャンネル

## バッチ種別

パッケージテスト / リリース後検証

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 手動実行（随時） |
| 実行時刻 | - |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | workflow_dispatch（手動） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| バージョン公開 | 指定バージョンがnpmに公開済みであること |
| シークレット | SLACK_CLI_CI_WEBHOOK_URLが設定されていること |
| 権限 | contents: read が付与されていること |

### 実行可否判定

workflow_dispatchで手動トリガーされた場合に実行。バージョン文字列が正規表現 `^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$` に一致しない場合はエラー終了。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| delay_seconds | 数値 | No | 0 | 実行前の遅延秒数 |
| version | 文字列 | Yes | - | テスト対象のバージョン（例：1.0.0） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| @liam-hq/cli | npm パッケージ | テスト対象のCLI |
| Supabase schema.sql | SQL | postgres形式テスト用スキーマ |
| Mastodon schema.rb | Ruby | schemarb形式テスト用スキーマ |
| Langfuse schema.prisma | Prisma | prisma形式テスト用スキーマ |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| Slack通知 | Attachments | テスト結果（成功/失敗、バージョン） |
| GitHub Checks | Status | CI実行結果（成功/失敗） |

### 出力ファイル仕様

ファイル出力は行わない。結果はSlackおよびGitHub ActionsのUI上に出力される。

## 処理フロー

### 処理シーケンス

```
1. 遅延待機
   └─ delay_seconds秒スリープ（npm反映待ち）

2. バージョン確認テスト
   └─ npx @liam-hq/cli@{version} --version
   └─ バージョン形式の検証

3. postgres形式テスト
   └─ erd build --format postgres
   └─ 入力：Supabase schema.sql

4. schemarb形式テスト
   └─ erd build --format schemarb
   └─ 入力：Mastodon schema.rb

5. prisma形式テスト
   └─ erd build --format prisma
   └─ 入力：Langfuse schema.prisma

6. 結果通知
   └─ 成功時：Slack（緑色）
   └─ 失敗時：Slack（赤色）
```

### フローチャート

```mermaid
flowchart TD
    A[workflow_dispatch トリガー] --> B[delay_seconds 待機]
    B --> C{バージョン形式検証}
    C -->|無効| D[エラー終了]
    C -->|有効| E[--version テスト]
    E --> F[postgres形式テスト]
    F --> G[schemarb形式テスト]
    G --> H[prisma形式テスト]
    H --> I{全テスト成功?}
    I -->|はい| J[Slack通知: 成功]
    I -->|いいえ| K[Slack通知: 失敗]
    D --> L[バッチ終了]
    J --> L
    K --> L
```

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

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

データベース操作は行わない。

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| VERSION_EMPTY | 入力エラー | バージョン未指定 | バージョンを指定して再実行 |
| VERSION_INVALID | 検証エラー | バージョン形式不正 | 正しい形式（x.y.z）で指定 |
| NPM_NOT_FOUND | パッケージエラー | 指定バージョンがnpm未公開 | 遅延を増やして再実行、または公開確認 |
| CLI_ERROR | 実行エラー | CLIコマンド失敗 | CLIのバグ調査、修正後に再リリース |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（自動リトライなし） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

1. GitHub Actions実行ログで失敗したステップを特定
2. npmパッケージの公開状態を確認（`npm view @liam-hq/cli@{version}`）
3. CLI機能のバグの場合：修正後に新バージョンをリリース
4. 一時的な問題（npm反映遅延等）の場合：delay_secondsを増やして再実行

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 4テストケース |
| 目標処理時間 | 15分以内（timeout-minutes: 15） |
| メモリ使用量上限 | GitHubランナー標準（7GB） |

## 排他制御

同一refに対する同時実行は許可されない。concurrency設定により、同一ワークフロー・同一refの実行が重複した場合、先行する実行がキャンセルされる（cancel-in-progress: true）。

```yaml
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true
```

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | 遅延開始時 | delay_seconds値 |
| 進捗ログ | 各テスト実行時 | テストケース名、実行コマンド |
| 終了ログ | ワークフロー終了時 | 全テスト結果 |
| エラーログ | エラー発生時 | 失敗したテストケース、エラー詳細 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| テスト失敗 | 1回 | Slack（SLACK_CLI_CI_WEBHOOK_URL） |
| テスト成功 | - | Slack（SLACK_CLI_CI_WEBHOOK_URL） |
| タイムアウト | 15分 | GitHub Checks UI |

## 備考

- tokorom/action-slack-incoming-webhook v1.3.0を使用
- Slack Webhook URL: https://api.slack.com/apps/A08CVT65VAT/general
- テスト対象スキーマ:
  - postgres: liam-hq/liam/frontend/internal-packages/db/supabase/schemas/schema.sql
  - schemarb: mastodon/mastodon/db/schema.rb
  - prisma: langfuse/langfuse/packages/shared/prisma/schema.prisma
- npx --yesオプションでプロンプトなしで実行
