# バッチ設計書 23-pull-models.ts

## 概要

本ドキュメントは、SST secretsからZENモデル設定を取得・検証するスクリプトの設計を記載したバッチ設計書です。

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

pull-models.tsは、SST（Serverless Stack）のシークレット管理からZENモデル設定（LLMプロバイダー・モデル定義）を取得し、JSONスキーマで検証した後、環境ファイルとして再保存する管理スクリプトです。ステージ間でのモデル設定同期や、設定の整合性確認に使用されます。

**業務上の目的・背景**：ZEN APIは複数のLLMプロバイダー（Anthropic、OpenAI、Google等）へのプロキシとして機能しており、各モデルの設定（コスト、レート制限、プロバイダーマッピング等）を一元管理する必要があります。この設定は大規模なJSONデータであるため、20個のシークレットパーツに分割して保存されています。pull-models.tsはこれらの分割データを結合・検証し、別ステージへの反映準備を行います。

**バッチの実行タイミング**：管理者による手動実行。モデル設定の確認、ステージ間同期、設定バリデーション時に使用されます。

**主要な処理内容**：
1. コマンドライン引数からステージ名を取得
2. `bun sst secret list --stage {stage}`でシークレット一覧を取得
3. ZEN_MODELS1〜ZEN_MODELS20の20個のシークレットを抽出
4. 20個のパーツを結合してJSONを復元
5. ZenData.validateでスキーマ検証
6. 一時ファイルに環境変数形式で書き出し
7. `bun sst secret load`で再保存

**前後の処理との関連**：update-models.tsでモデル設定が更新された後、他のステージへ同期する際に使用されます。

**影響範囲**：ZEN APIのモデル設定全体に影響し、利用可能なLLMモデル、価格設定、レート制限設定に関わります。

## バッチ種別

設定管理 / データ同期

## 実行スケジュール

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

## 実行条件

### 前提条件

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

### 実行可否判定

- コマンドライン引数でステージが指定されていること
- ZEN_MODELS1〜ZEN_MODELS20がすべて存在すること

## 入力仕様

### 入力パラメータ

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

### 入力データソース

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

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| SST secrets | Key=Value | 再保存されたモデル設定 |
| 一時ファイル | .env | 環境変数形式の中間ファイル |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | models-{timestamp}.env |
| 出力先 | OS一時ディレクトリ |
| 文字コード | UTF-8 |
| 区切り文字 | 改行 |

## 処理フロー

### 処理シーケンス

```
1. 引数検証
   └─ process.argv[2]からステージ名取得
   └─ ステージ未指定の場合エラー
2. ルートディレクトリ計算
   └─ process.cwdから3階層上を計算
3. シークレット一覧取得
   └─ bun sst secret list --stage {stage}
4. シークレット値抽出
   └─ ZEN_MODELS{1-20}を順番に抽出
   └─ 1つでも欠落していればエラー
5. JSON結合・検証
   └─ 20個の値を結合
   └─ ZenData.validateでスキーマ検証
6. 環境ファイル生成
   └─ 一時ファイルにenv形式で出力
   └─ ダブルクォートをエスケープ
7. シークレット再保存
   └─ bun sst secret load {envFile}
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B{ステージ指定あり?}
    B -->|No| C[Error: Stage is required]
    B -->|Yes| D[ルートパス計算]
    D --> E[sst secret list実行]
    E --> F[ZEN_MODELS1-20抽出]
    F --> G{全20個存在?}
    G -->|No| H[Error: ZEN_MODELSx not found]
    G -->|Yes| I[JSON結合]
    I --> J[ZenData.validate]
    J --> K{検証OK?}
    K -->|No| L[バリデーションエラー]
    K -->|Yes| M[一時envファイル生成]
    M --> N[sst secret load実行]
    N --> O[バッチ終了]
    C --> P[異常終了]
    H --> P
    L --> P
```

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

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

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

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

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

データベース操作なし

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

### 障害時対応

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

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

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

## パフォーマンス要件

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

## 排他制御

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

## ログ出力

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

## 監視・アラート

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

## 備考

- PARTS定数は20（シークレット分割数）
- モデル設定はZenData.validateで検証される
- 一時ファイルはOSの一時ディレクトリに作成される
