add-new-setting-field by tsukumijima

---
name: add-new-setting-field
description: "【設定追加時は必ず参照】KonomiTV に新しい設定 (v-switch/v-select など) を追加する際の必須手順。SettingsStore.ts / Settings.ts / config.py / Settings/*.vue への追加が必要"
---
以下に、KonomiTV のフロントエンドに新しい設定フィールドを追加する際の手順を示します。

## KonomiTV のフロントエンド設定の保存方式

ブラウザの LocalStorage に JSON データで保存しています。  
KonomiTV アカウントで同期が有効な際は、UI 表示中はサーバーが保持している設定データと双方向に同期されます。  
サーバーと同期される設定と同期されない設定があり、後者はサーバー側には送られません。

## 設定フィールド追加手順

### 00. 事前準備

まず自動同期する設定かしない設定かを把握する必要があります。  
同期される設定とされない設定で記述内容が異なります。

また、各設定ごとのキー名は、必ず「見ただけである程度どのような設定項目なのかが理解できる」ものである必要があります。  
すでに追加されている他のキー名の命名を参考にしながら、多少長くても意味が明快で、設定項目の実装詳細を端的に表している表現を用いてください。

次に、設定値が新しく追加された際、もしくははじめてそのブラウザで KonomiTV を開いた際のデフォルト値を把握しましょう。

また、設定値は原則「設定画面から直接変更できない設定値」->「L字画面のクロップ設定」-> 設定ページ上での並び順 (client/src/views/Settings/Base.vue などを参照) で記述してください。  
フィールドは複数の箇所に追加する必要がありますが、原則個々の記述箇所でフィールドの並び順が共通でなければなりません。

### 01. client/src/stores/SettingsStore.ts に当該設定フィールドを追加する

- ILocalClientSettings: ブラウザの LocalStorage に保持される設定データの型定義です。すべてのフィールドが含まれます。
- ILocalClientSettingsDefault: ILocalClientSettings 型のデフォルト値を表す定数です。設定値の詳細を示すコメントを含めます（コメントの内容は概ね今後記載する設定 UI と一致している必要があります）。
- SYNCABLE_SETTINGS_KEYS: ILocalClientSettings 型に含まれるフィールドのうち、どのフィールドが同期対象かを示す、フィールド名が入る配列です。
  - 把握性向上のため、同期対象でない設定キーであっても同じ順序で代わりにコメントを残すようにしてあります。

### 02. client/src/services/Settings.ts に当該設定フィールドを追加する

- IClientSettings: サーバーにも保存され同期対象となる設定キーのみが含まれた設定データの型定義です。
  - 把握性向上のため、同期対象でない設定キーであっても同じ順序で代わりにコメントを残すようにしてあります。

### 03. server/app/config.py に当該設定フィールドを追加する

- ClientSettings: サーバーにも保存され同期対象となる設定キーのみが含まれた設定データを表す Pydantic モデルです。
  - 把握性向上のため、同期対象でない設定キーであっても同じ順序で代わりにコメントを残すようにしてあります。
  - デフォルト値は常に SettingsStore に記載した値を設定してください。

### 04. 設定 UI を追加する

client/src/views/Settings/ 以下に、各設定ページごとの .vue ファイルがあるので、一番適している位置（あるいは指定があったセクション）に新しい設定を、わかりやすく簡潔な言い回しの説明文と共に追加します。
HTML やフォーム UI の props は周囲のコードに合わせてください。