# 機能設計書 104-KSONエクスポート

## 概要

本ドキュメントは、K-Shoot Editor(譜面エディタ)におけるKSONフォーマットへのエクスポート機能の設計を記述する。kson.dllを使用して、KSH形式からKSON形式(v2以降の新フォーマット)への変換・書き出しを行う。

### 本機能の処理概要

本機能は、現在編集中のKSH譜面データをKSON形式(新世代の譜面フォーマット)にエクスポートする。内部的にはまずKSH形式で一時保存し(`*command_save`で`is_kson_export=1`を設定)、kson.dllのKSON_FromKSH関数でKSON形式に変換後、指定ファイルパスに出力する。

**業務上の目的・背景**: KSONはKSHの後継フォーマットであり、より多くの機能(レーザー直角音のカスタマイズ、新エフェクト等)をサポートする。将来のゲーム・ツール互換性のためにKSON形式でのエクスポートが求められる。

**機能の利用シーン**: ファイルメニューの「エクスポート」>「KSON形式で書き出し」から実行する。保存ダイアログでKSONファイルの保存先を指定する。

**主要な処理内容**:
1. `is_kson_export=1` フラグを設定
2. `*command_save` サブルーチンを呼び出し(KSH形式のデータ準備)
3. 保存処理内部でKSON_FromKSH関数によりKSH→KSON変換を実行
4. 変換結果をファイルに出力
5. エラー/警告があれば対応するダイアログを表示
6. `is_kson_export=0` にフラグをリセット

**関連システム・外部連携**: kson.dll(KSON_FromKSH関数、KSON_GetLastEditorDiagWarning関数)。

**権限による制御**: 特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 譜面エディタ | 主画面 | ファイルメニュー > エクスポート > KSON形式で書き出し |

## 機能種別

データ連携(ファイルエクスポート)

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| 譜面データ | 各種配列 | Yes | 現在編集中のKSH譜面データ | - |

### 入力データソース

メモリ上の譜面データ配列(*command_saveで生成されるKSH形式テキスト)

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| KSONファイル | テキストファイル | KSON形式の譜面データ |

### 出力先

ユーザーが指定した.ksonファイルパス

## 処理フロー

### 処理シーケンス

```
1. CMD_EXPORT_KSON受信
   └─ is_kson_export=1 を設定
2. *command_save サブルーチン呼び出し
   └─ KSH形式のデータ生成と保存処理
3. KSON_FromKSH呼び出し
   └─ KSH形式テキストをKSON形式に変換
4. 変換結果の検証
   └─ 戻り値が負の場合はエラーダイアログ(lang.0.70)
5. 警告の確認
   └─ KSON_GetLastEditorDiagWarningで警告メッセージ取得、あれば表示(lang.0.71)
6. ファイル書き出し
7. is_kson_export=0 にリセット
   └─ fname_kson_export="" にリセット
```

### フローチャート

```mermaid
flowchart TD
    A[CMD_EXPORT_KSON受信] --> B[is_kson_export=1]
    B --> C[*command_save呼び出し]
    C --> D[KSON_FromKSH変換]
    D --> E{変換成功?}
    E -->|No| F[エラーダイアログ表示]
    E -->|Yes| G{警告あり?}
    G -->|Yes| H[警告ダイアログ表示]
    G -->|No| I[ファイル書き出し]
    H --> I
    I --> J[is_kson_export=0にリセット]
    F --> J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-104-01 | KSH経由変換 | KSON形式へのエクスポートはKSH形式のデータを経由してkson.dllで変換する | 常時 |
| BR-104-02 | エラーハンドリング | KSON_FromKSHが負の値を返した場合はエクスポート失敗としてエラーダイアログを表示 | 変換失敗時 |
| BR-104-03 | 警告通知 | 変換時に警告(データ欠落等)が発生した場合は詳細を表示して続行 | 変換成功だが警告発生時 |

### 計算ロジック

該当なし(kson.dll内部で変換処理を実行)。

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | KSON変換失敗 | KSON_FromKSHが負の値を返した場合 | lang.0.70エラーダイアログ表示 |
| - | KSON変換警告 | KSON_GetLastEditorDiagWarningが非空文字列を返した場合 | lang.0.71警告ダイアログ表示して続行 |

### リトライ仕様

リトライ処理はなし。

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

該当なし。

## パフォーマンス要件

特になし。

## セキュリティ考慮事項

特になし。

## 備考

- KSONエクスポートとKSONインポートは対になる機能であり、KSONインポートはCMD_OPENの一部として実装されている
- kson.dllのバージョンは1752以上が必要(kshooteditor.hsp 636行目)

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kson.as | `src/kson.as` | KSON DLLの関数バインディング(KSON_FromKSH, KSON_GetLastEditorDiagWarning等) |

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | kshooteditor.hsp | `kshooteditor.hsp` | 5152-5163行目: CMD_EXPORT_KSON処理 |

**主要処理フロー**:
1. **5152行目**: `if(cmd=CMD_EXPORT_KSON)` でコマンド判定
2. **5160行目**: `is_kson_export=1` フラグ設定
3. **5161行目**: `gosub *command_save` で保存処理呼び出し
4. **5162行目**: `is_kson_export=0` フラグリセット
5. **5163行目**: `fname_kson_export=""` リセット

#### Step 3: KSON DLL関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | kson.as | `src/kson.as` | KSON_FromKSH: KSH→KSON変換関数 |
| 3-2 | kson.as | `src/kson.as` | KSON_GetLastEditorDiagWarning: 警告メッセージ取得関数 |

### プログラム呼び出し階層図

```
*OnCommand
    └─ CMD_EXPORT_KSON
        ├─ is_kson_export=1 (フラグ設定)
        ├─ *command_save (KSH保存処理)
        │   ├─ KSON_FromKSH (KSH→KSON変換)
        │   ├─ KSON_GetLastEditorDiagWarning (警告確認)
        │   └─ notesave (ファイル書き出し)
        └─ is_kson_export=0 (フラグリセット)
```

### データフロー図

```
[入力]                          [処理]                           [出力]

メモリ上の譜面データ  ──────▶  *command_save             ───▶  KSHテキスト(中間)
                              (KSH形式テキスト生成)

KSHテキスト(中間)    ──────▶  KSON_FromKSH             ───▶  .ksonファイル
                              (kson.dllによる変換)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| kshooteditor.hsp | `kshooteditor.hsp` | ソース | KSONエクスポート処理(5152-5163行目) |
| kson.as | `src/kson.as` | ソース | KSON DLL関数バインディング |
| kson.dll | `kson.dll` | DLL | KSH/KSON形式の変換処理 |
