# 帳票設計書 6-設定ファイルJSON出力（settings.json）

## 概要

本ドキュメントは、Windows Terminal のアプリケーション設定（プロファイル・配色・キーバインド等）をJSON形式でsettings.jsonファイルに書き出す処理の設計を記述する。

### 本帳票の処理概要

CascadiaSettings オブジェクトが保持するアプリケーション設定情報を、JSON形式にシリアライズしてsettings.jsonファイルに永続化する。グローバル設定、プロファイル一覧、配色テーマ、テーマ設定を含む完全な設定ファイルを生成する。

**業務上の目的・背景**：ユーザーが設定画面やsettings.jsonの直接編集で変更したアプリケーション設定を、ディスクに永続化するための出力機能を提供する。設定の永続化により、アプリケーション再起動後も同じ設定が維持される。また、設定ファイルのバックアップや他の環境への設定移行にも利用される。

**帳票の利用シーン**：ユーザーが設定画面で変更を保存した際、または設定のリセット時に使用される。設定ファイルはLocalAppData配下に保存される。

**主要な出力内容**：
1. JSON Schema参照（$help, $schema）
2. グローバル設定（_globals->ToJson()）
3. プロファイル設定（defaults + list）
4. 配色テーマ（schemes）- ユーザー定義のもののみ
5. UIテーマ設定（themes）- ビルトインテーマを除く

**帳票の出力タイミング**：設定変更の保存操作時、設定のリセット時に出力される。WriteSettingsToDisk() の呼び出しにより実行。

**帳票の利用者**：Windows Terminal を使用するすべてのユーザー。設定ファイルを直接編集する上級ユーザーも含む。

## 帳票種別

設定シリアライズ（JSONファイル出力）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | 設定画面 | - | 設定変更の保存操作 |
| - | コマンドパレット | - | 設定リセットコマンド |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | JSON |
| 用紙サイズ | 該当なし |
| 向き | 該当なし |
| ファイル名 | settings.json（固定） |
| 出力方法 | ファイル書き込み（アトミック操作） |
| 文字コード | UTF-8 |

### PDF固有設定

該当なし

### Excel固有設定

該当なし

## 帳票レイアウト

### レイアウト概要

JSON文書はトップレベルオブジェクトとして、$help, $schema, グローバル設定、profiles, schemes, themes を含む。

```
┌─────────────────────────────────────┐
│ {                                   │
│   "$help": "...",                   │
│   "$schema": "...",                 │
│   (グローバル設定: defaultProfile等) │
│   "profiles": {                     │
│     "defaults": { ... },            │
│     "list": [ ... ]                 │
│   },                                │
│   "schemes": [ ... ],              │
│   "themes": [ ... ]                │
│ }                                   │
└─────────────────────────────────────┘
```

### ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | $help | ドキュメントURLへの参照 | 固定値 | "https://aka.ms/terminal-documentation" |
| 2 | $schema | JSON Schemaの参照URL | ビルド構成に依存 | ブランド別のURL |

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 列幅 |
|----|-------|------|-------------|---------|------|
| 1 | グローバル設定 | defaultProfile, theme等 | _globals->ToJson() | JSONキー・バリュー | 可変 |
| 2 | profiles.defaults | デフォルトプロファイル設定 | _baseLayerProfile->ToJson() | JSONオブジェクト | 可変 |
| 3 | profiles.list | 個別プロファイル一覧 | _allProfiles (Deleted除外) | JSON配列 | 可変 |
| 4 | schemes | 配色テーマ一覧 | _globals->ColorSchemes() (User origin) | JSON配列 | 可変 |
| 5 | themes | UIテーマ一覧 | _globals->Themes() (ビルトイン除外) | JSON配列 | 可変 |

### フッター部

該当なし

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| profiles.list | Deleted フラグが false のプロファイルのみ | Yes |
| schemes | Origin が User のもののみ | Yes |
| themes | ビルトインテーマ（system, dark, light, legacySystem, legacyDark, legacyLight）を除外 | Yes |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | プロファイル: _allProfiles の登録順 | 登録順 |
| 2 | スキーム: ColorSchemes の列挙順 | 列挙順 |
| 3 | テーマ: Themes の列挙順 | 列挙順 |

### 改ページ条件

該当なし

## データベース参照仕様

### 参照テーブル一覧

該当なし（メモリ上の CascadiaSettings オブジェクトからデータを取得する）

### テーブル別参照項目詳細

#### CascadiaSettings（メモリ上設定オブジェクト）

| 参照項目（カラム名） | 帳票項目との対応 | 取得条件 | 備考 |
|-------------------|----------------|---------|------|
| _globals | グローバル設定 | - | ToJson() でJSONに変換 |
| _baseLayerProfile | profiles.defaults | _baseLayerProfile != null | ToJson() でJSONに変換 |
| _allProfiles | profiles.list | entry.Deleted() == false | 各プロファイルを ToJson() |
| _globals->ColorSchemes() | schemes | scheme.Origin() == OriginTag::User | 各スキームを ToJson() |
| _globals->Themes() | themes | builtinThemes に含まれないもの | 各テーマを ToJson() |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| _hash | til::hash(settings) + lastWriteTime | 該当なし | 設定ファイルの変更検出用ハッシュ |
| $schema URL | ビルド構成により分岐 | 該当なし | Release/Preview/Debug/Other で異なるURL |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[設定保存操作] --> B[CascadiaSettings::WriteSettingsToDisk]
    B --> C[Json::StreamWriterBuilder 構成]
    C --> D[enableYAMLCompatibility = true]
    D --> E[indentation = 4スペース]
    E --> F[precision = 6]
    F --> G[CascadiaSettings::ToJson 呼び出し]
    G --> H[_globals->ToJson でグローバル設定]
    H --> I[$help, $schema を追加]
    I --> J[profiles オブジェクト構築]
    J --> K[defaults: _baseLayerProfile->ToJson]
    K --> L[list: 各プロファイル ToJson - Deleted除外]
    L --> M[schemes: ユーザー定義スキーム ToJson]
    M --> N[themes: 非ビルトインテーマ ToJson]
    N --> O[Json::writeString で文字列化]
    O --> P[_writeSettingsToDisk 呼び出し]
    P --> Q[write_utf8_string_to_file_atomic で書き込み]
    Q --> R[_hash 更新]
    R --> S[DefaultTerminal::Current 永続化]
    S --> T[終了]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| 書き込み失敗 | ファイルシステムエラー | なし | LOG_CAUGHT_EXCEPTION() でログ記録、FailedToWriteToSettings 警告を追加、false を返却 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | プロファイル数十件、スキーム数十件、テーマ数件 |
| 目標出力時間 | 即座（同期処理） |
| 同時出力数上限 | 1 |

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

- settings.json はユーザーの LocalAppData 配下に保存され、ユーザーレベルのアクセス権限で保護される
- ファイル書き込みはアトミック操作（一時ファイル作成 → リネーム）で行われ、破損リスクを低減
- デフォルトターミナルの選択はレジストリにも永続化される

## 備考

- $schema の URL はビルドブランディングに依存する（Release, Preview, Debug, Other）
- enableYAMLCompatibility = true により、コロン周辺のスペースが抑制される
- precision = 6 により、浮動小数点値の不要な精度（1.1000000000000001 等）を防止
- WriteSettingsToDisk() は bool を返し、成功/失敗を通知する
- ビルトインテーマ6種（system, dark, light, legacySystem, legacyDark, legacyLight）はシリアライズ対象外

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | CascadiaSettingsSerialization.cpp | `src/cascadia/TerminalSettingsModel/CascadiaSettingsSerialization.cpp` | 34-48行目のJSONキー定数定義（ProfilesKey, SchemesKey, ThemesKey等）とビルトインテーマ名 |

**読解のコツ**: settings.json のトップレベル構造はToJson() メソッドで組み立てられる。profiles は "defaults" と "list" のネスト構造を持つオブジェクトである。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | CascadiaSettingsSerialization.cpp | `src/cascadia/TerminalSettingsModel/CascadiaSettingsSerialization.cpp` | WriteSettingsToDisk メソッド（1591-1610行目）。StreamWriterBuilder の設定、ToJson() 呼び出し、_writeSettingsToDisk 呼び出し |

**主要処理フロー**:
1. **1594-1597行目**: JSON Writer の設定（enableYAMLCompatibility, indentation, precision）
2. **1601行目**: Json::writeString(wbuilder, ToJson()) でJSON文字列生成
3. **1601行目**: _writeSettingsToDisk() でファイル書き込み

#### Step 3: ToJson の実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | CascadiaSettingsSerialization.cpp | `src/cascadia/TerminalSettingsModel/CascadiaSettingsSerialization.cpp` | ToJson メソッド（1642-1701行目）。JSON構造の組み立て |

**主要処理フロー**:
- **1645行目**: _globals->ToJson() でグローバル設定取得
- **1646-1657行目**: $help, $schema の設定
- **1660-1672行目**: profiles オブジェクト構築（defaults + list）
- **1674-1683行目**: schemes 配列構築（User origin のみ）
- **1685-1698行目**: themes 配列構築（ビルトイン除外）

#### Step 4: _writeSettingsToDisk を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | CascadiaSettingsSerialization.cpp | `src/cascadia/TerminalSettingsModel/CascadiaSettingsSerialization.cpp` | _writeSettingsToDisk メソッド（1612-1625行目）。アトミック書き込み、ハッシュ更新、デフォルトターミナル永続化 |

**主要処理フロー**:
- **1615行目**: write_utf8_string_to_file_atomic でアトミック書き込み
- **1617行目**: _hash 更新（変更検出用）
- **1621-1623行目**: デフォルトターミナルの永続化

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

```
CascadiaSettings::WriteSettingsToDisk (CascadiaSettingsSerialization.cpp:1591)
    |
    +-- CascadiaSettings::ToJson() (CascadiaSettingsSerialization.cpp:1642)
    |       |
    |       +-- _globals->ToJson()
    |       +-- _baseLayerProfile->ToJson()
    |       +-- Profile::ToJson() (各プロファイル)
    |       +-- ColorScheme::ToJson() (各配色)
    |       +-- Theme::ToJson() (各テーマ)
    |
    +-- Json::writeString(wbuilder, json) (JSON文字列化)
    |
    +-- CascadiaSettings::_writeSettingsToDisk (CascadiaSettingsSerialization.cpp:1612)
            |
            +-- til::io::write_utf8_string_to_file_atomic()
            +-- _calculateHash()
            +-- DefaultTerminal::Current()
```

### データフロー図

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

CascadiaSettings (メモリ)     ---> ToJson()               ---> Json::Value
  |                                  |                            |
  +-- _globals                     +-- グローバル設定組立         +-- Json::writeString()
  +-- _baseLayerProfile            +-- profiles 構築               |
  +-- _allProfiles                 +-- schemes 構築               +-- JSON文字列 (std::string)
  +-- ColorSchemes                 +-- themes 構築                  |
  +-- Themes                                                      +-- _writeSettingsToDisk()
                                                                    |
                                                                  +-- settings.json
                                                                    (LocalAppData)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| CascadiaSettingsSerialization.cpp | `src/cascadia/TerminalSettingsModel/CascadiaSettingsSerialization.cpp` | ソース | WriteSettingsToDisk, ToJson, _writeSettingsToDisk の実装 |
| CascadiaSettings.h | `src/cascadia/TerminalSettingsModel/CascadiaSettings.h` | ヘッダー | CascadiaSettings クラス定義 |
| GlobalAppSettings.cpp | `src/cascadia/TerminalSettingsModel/GlobalAppSettings.cpp` | ソース | グローバル設定の ToJson |
| Profile.cpp | `src/cascadia/TerminalSettingsModel/Profile.cpp` | ソース | プロファイルの ToJson |
| ColorScheme.cpp | `src/cascadia/TerminalSettingsModel/ColorScheme.cpp` | ソース | 配色テーマの ToJson |
| Theme.cpp | `src/cascadia/TerminalSettingsModel/Theme.cpp` | ソース | UIテーマの ToJson |
