# バッチ設計書 24-update-models.ts

## 概要

本ドキュメントは、ZENモデル設定をvimエディタで編集し、SST secretsに保存するスクリプトの設計を記載したバッチ設計書です。

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

update-models.tsは、SST secretsに保存されているZENモデル設定を取得し、JSON形式で一時ファイルに展開してvimで編集できるようにし、編集後の内容を検証して再度SST secretsに保存する管理スクリプトです。LLMモデルの追加・削除・設定変更を行う際に使用されます。

**業務上の目的・背景**：ZEN APIのモデル設定は大規模なJSONデータ（モデル定義、プロバイダー設定、コスト情報、レート制限等）で構成されており、直接編集するには専用のツールが必要です。本スクリプトにより、管理者はvimを使って視覚的にモデル設定を編集でき、保存時に自動でスキーマ検証が行われるため、設定ミスを防止できます。

**バッチの実行タイミング**：管理者による手動実行。新規LLMモデルの追加、既存モデルの設定変更、プロバイダー情報の更新時に使用されます。

**主要な処理内容**：
1. `bun sst secret list`でデフォルトステージのシークレット一覧を取得
2. ZEN_MODELS1〜ZEN_MODELS30の30個のシークレットを抽出・結合
3. JSONを整形して一時ファイルに書き出し
4. vimエディタを起動して編集
5. 編集後のJSONをZenData.validateで検証
6. 検証成功後、30個のパーツに分割
7. 環境ファイル経由でSST secretsに保存

**前後の処理との関連**：更新後の設定はZEN APIで即時反映されます。他のステージへの同期にはpull-models.tsを使用します。

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

## バッチ種別

設定管理 / 対話型編集

## 実行スケジュール

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

## 実行条件

### 前提条件

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

### 実行可否判定

- ZEN_MODELS1〜ZEN_MODELS30がすべて存在すること
- 編集後のJSONがZenDataスキーマに準拠すること

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| （なし） | - | - | - | コマンドライン引数なし |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| SST secrets | Key=Value | ZEN_MODELS1〜ZEN_MODELS30シークレット |
| vim編集 | JSON | ユーザーによる対話型編集 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| SST secrets | Key=Value | 更新されたモデル設定 |
| console.log | Text | 一時ファイルパス |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | models-{timestamp}.json（編集用）、models-{timestamp}.env（保存用） |
| 出力先 | OS一時ディレクトリ |
| 文字コード | UTF-8 |
| 区切り文字 | 改行（env形式） |

## 処理フロー

### 処理シーケンス

```
1. ルートディレクトリ計算
   └─ process.cwdから3階層上を計算
2. シークレット一覧取得
   └─ bun sst secret list（デフォルトステージ）
3. シークレット値抽出
   └─ ZEN_MODELS{1-30}を順番に抽出
   └─ 1つでも欠落していればエラー
4. JSON整形・一時ファイル作成
   └─ 30個の値を結合
   └─ JSON.stringify(data, null, 2)で整形
   └─ models-{timestamp}.jsonに書き出し
5. vim編集
   └─ vim {tempFile}を起動
   └─ ユーザー編集を待機
6. 編集結果読み込み・検証
   └─ 一時ファイルを再読み込み
   └─ JSON.parseで解析
   └─ ZenData.validateで検証
7. 分割・環境ファイル生成
   └─ 文字列長を30等分
   └─ env形式でファイル出力
8. シークレット保存
   └─ bun sst secret load {envFile}
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[ルートパス計算]
    B --> C[sst secret list実行]
    C --> D[ZEN_MODELS1-30抽出]
    D --> E{全30個存在?}
    E -->|No| F[Error: ZEN_MODELSx not found]
    E -->|Yes| G[JSON結合・整形]
    G --> H[一時JSONファイル作成]
    H --> I[console.log:tempFile]
    I --> J[vim起動]
    J --> K[ユーザー編集]
    K --> L[ファイル再読み込み]
    L --> M[JSON.parse]
    M --> N[ZenData.validate]
    N --> O{検証OK?}
    O -->|No| P[バリデーションエラー]
    O -->|Yes| Q[30パーツに分割]
    Q --> R[envファイル生成]
    R --> S[sst secret load実行]
    S --> T[バッチ終了]
    F --> U[異常終了]
    P --> U
```

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

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

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

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

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

データベース操作なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | シークレット欠落 | ZEN_MODELSxが見つからない | シークレット設定を確認 |
| - | JSON解析エラー | 編集後のJSONが不正 | vim編集を再確認 |
| - | バリデーションエラー | スキーマ不一致 | モデル設定形式を確認 |

### リトライ仕様

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

### 障害時対応

- バリデーションエラー時は保存されないため、元の設定が維持される
- 編集内容は一時ファイルに残るため、再実行時に参照可能

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1回/実行 |
| 目標処理時間 | ユーザー操作依存 |
| メモリ使用量上限 | 制限なし |

## 排他制御

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

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | - | - |
| 進捗ログ | 一時ファイル作成後 | tempFile パス |
| 終了ログ | - | - |
| エラーログ | エラー発生時 | throw Error メッセージ |

## 監視・アラート

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

## 備考

- PARTS定数は30（シークレット分割数、pull-models.tsの20とは異なる）
- JSONは2スペースインデントで整形される
- vimが終了するまで処理はブロックされる
- 一時ファイルは自動削除されない
