# バッチ設計書 27-promote-lite.ts

## 概要

本ドキュメントは、Liteプランの制限設定を別ステージへ同期するスクリプトの設計を記載したバッチ設計書です。

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

promote-lite.tsは、SST secretsに保存されているLiteプラン（ライトサブスクリプション）の制限設定を取得・検証し、指定されたステージ（例：staging、production）に同期する管理スクリプトです。Blackプランよりも低価格なLiteプランの設定を環境間で一貫して管理するために使用されます。

**業務上の目的・背景**：ZEN APIにはLiteプランと呼ばれる低価格サブスクリプションが存在し、週次の利用制限（fixedLimit）やローリングウィンドウ制限（rollingLimit）が設定されています。Blackプランとは異なり単一プランのみ存在します。ステージング環境でのテスト後に本番環境へ反映する必要があり、本スクリプトにより安全にプラン設定を同期できます。

**バッチの実行タイミング**：管理者による手動実行。Liteプランの制限設定変更後、他のステージへ反映する際に使用されます。

**主要な処理内容**：
1. コマンドライン引数からステージ名を取得
2. `bun sst secret list`でデフォルトステージのシークレット一覧を取得
3. ZEN_LITE_LIMITSシークレットを抽出
4. LiteData.validateでスキーマ検証
5. 指定ステージにシークレットを設定

**前後の処理との関連**：管理コンソールまたは直接設定でLiteプラン制限が更新された後に実行されます。同期後はZEN APIで新しい制限値が適用されます。

**影響範囲**：Liteプランユーザーの利用制限に影響し、週次制限・ローリング制限の適用に関わります。

## バッチ種別

設定管理 / 環境同期

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（手動） |
| 実行時刻 | - |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | 管理者による手動実行 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| bunランタイム | Bunがインストールされていること |
| SST CLI | SSTがセットアップされていること |
| AWS認証 | SST secretsへのアクセス権限があること |
| ZEN_LITE_LIMITS設定 | デフォルトステージにZEN_LITE_LIMITSが設定されていること |

### 実行可否判定

- コマンドライン引数でステージが指定されていること
- ZEN_LITE_LIMITSシークレットが存在すること
- シークレット値がLiteDataスキーマに準拠すること

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| stage | string | Yes | - | 同期先ステージ名（例：production, staging） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| SST secrets | Key=Value | ZEN_LITE_LIMITSシークレット |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| SST secrets（指定ステージ） | Key=Value | 同期されたLiteプラン設定 |

### 出力ファイル仕様

ファイル出力なし

| 項目 | 内容 |
|-----|------|
| ファイル名 | - |
| 出力先 | - |
| 文字コード | - |
| 区切り文字 | - |

## 処理フロー

### 処理シーケンス

```
1. 引数検証
   └─ process.argv[2]からステージ名取得
   └─ ステージ未指定の場合エラー
2. ルートディレクトリ計算
   └─ process.cwdから3階層上を計算
3. シークレット一覧取得
   └─ bun sst secret list（デフォルトステージ）
4. シークレット値抽出
   └─ ZEN_LITE_LIMITSを検索
   └─ 見つからない場合エラー
5. スキーマ検証
   └─ LiteData.validate(JSON.parse(value))
6. シークレット設定
   └─ bun sst secret set ZEN_LITE_LIMITS {value} --stage {stage}
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B{ステージ指定あり?}
    B -->|No| C[Error: Stage is required]
    B -->|Yes| D[ルートパス計算]
    D --> E[sst secret list実行]
    E --> F[ZEN_LITE_LIMITS抽出]
    F --> G{シークレット存在?}
    G -->|No| H[Error: ZEN_LITE_LIMITS not found]
    G -->|Yes| I[LiteData.validate]
    I --> J{検証OK?}
    J -->|No| K[バリデーションエラー]
    J -->|Yes| L[sst secret set実行]
    L --> M[バッチ終了]
    C --> N[異常終了]
    H --> N
    K --> N
```

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

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

本バッチはデータベースを操作しません。

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

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

データベース操作なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 引数エラー | ステージ未指定 | コマンドライン引数を確認 |
| - | シークレット欠落 | ZEN_LITE_LIMITSが見つからない | デフォルトステージの設定を確認 |
| - | バリデーションエラー | JSONスキーマ不一致 | Liteプラン設定の形式を確認 |

### リトライ仕様

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

### 障害時対応

- エラー発生時はthrowで即時終了
- シークレットは更新されないため、ロールバック不要

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 全体 |
| コミットタイミング | sst secret set成功時 |
| ロールバック条件 | バリデーション失敗時は設定されない |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1回/実行 |
| 目標処理時間 | 数秒 |
| メモリ使用量上限 | 制限なし |

## 排他制御

- 同時実行は推奨しない
- sst secret setは上書き動作

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | - | - |
| 進捗ログ | - | - |
| 終了ログ | - | - |
| エラーログ | エラー発生時 | throw Error メッセージ |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| - | - | - |

## 備考

- Liteプランは単一プランのみ（Blackの20/100/200とは異なる）
- スキーマにはfixedLimit（週次制限）、rollingLimit（ローリング制限）、rollingWindow（制限ウィンドウ時間）が含まれる
- promote-black.tsと同様の構造を持つが、対象シークレット名とバリデーションモジュールが異なる
