# 非機能要件定義書

## 概要

本ドキュメントは、Microsoft Windows Terminal プロジェクト（conhost.exe および Windows Terminal アプリケーション）のソースコードから読み取れる非機能要件を定義するものである。本プロジェクトは C++ をベースとしたネイティブ Windows デスクトップアプリケーションであり、DirectX/Direct2D によるレンダリングエンジン、ConPTY による疑似コンソール接続、Azure Cloud Shell 接続、多言語対応などの機能を持つ。

## 性能要件

### レスポンスタイム

| 処理種別 | 目標値 | 備考 |
| --- | --- | --- |
| レンダリングフレーム描画 | フレーム単位でバックオフ付きリトライ（100ms～1600ms） | `renderer.cpp` にて最大5回リトライ。指数バックオフ（100, 200, 400, 800, 1600ms）を適用 |
| SwapChain フレーム待機 | 100ms 以内 | `AtlasEngine.r.cpp` にて `WaitForSingleObjectEx` のタイムアウトを 100ms に設定 |
| ConPTY 出力スレッド終了待機 | 1000ms | `ConptyConnection.cpp` にて `WaitForSingleObject` のタイムアウトを 1000ms に設定 |
| ウィンドウメッセージ送信タイムアウト | 1000ms | `IslandWindow.cpp` にて `SendMessageTimeoutW` を 1000ms で設定（SMTO_NOTIMEOUTIFNOTHUNG） |
| MSAA アクセシビリティ遅延 | 100ms（デフォルト） | `settings.hpp` にて `_msaaDelay = 100` |
| UIA アクセシビリティ遅延 | 25ms（デフォルト） | `settings.hpp` にて `_uiaDelay = 25` |

### スループット

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| 初期ターミナルサイズ | 80列 x 30行（デフォルト） | `MTSMSettings.h` にて `InitialCols=80`, `InitialRows=30` |
| テキストバッファスクロール性能 | メモリ配置最適化で約40%向上 | `Row.hpp` にてバッファアライメントを16バイト境界に設定し、SIMD処理でスクロール性能を向上。最大5.8%のメモリ増加を許容 |
| コマンド履歴バッファサイズ | DEFAULT_HISTORY_SIZE | `MTSMSettings.h` にて `HistorySize` 設定 |
| レンダリング方式 | DirectX (Atlas Engine) / Direct2D / GDI / WDDM | 複数レンダリングバックエンドをサポート。`GraphicsAPI` 設定で選択可能 |

## 可用性要件

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| レンダリングエラー耐性 | 最大5回リトライ後にフォールバック | `renderer.cpp` にて `maxRetriesForRenderEngine = 5`。失敗後はレンダリングを無効化するが、アプリケーションは終了しない |
| DXGI デバイスロスト復旧 | 自動再作成 | `AtlasEngine.r.cpp` にて `DXGI_ERROR_DEVICE_REMOVED` / `DXGI_ERROR_DEVICE_RESET` / `D2DERR_RECREATE_TARGET` 検出時にアダプタとバックエンドを自動再作成 |
| Atlas Engine Present フォールバック | Release/WindowsInbox ビルドで有効 | `features.xml` にて `Feature_AtlasEnginePresentFallback` が Release および WindowsInbox ビルドで有効 |
| ConPTY 接続終了処理 | 複数の終了パスに対応 | `ConptyConnection.cpp` にて Close()、プロセス終了、読み取りハンドル終了の3つの終了シナリオを管理。接続状態による「フラッピング」防止 |
| Azure Cloud Shell 接続 | WebSocket 接続の安全な終了 | `AzureConnection.cpp` にて接続状態管理、出力スレッドの安全な終了待機（INFINITE）を実装 |
| ターミナルハンドオフ | conhost から OpenConsole への接続引き渡し | `features.xml` にて `Feature_ReceiveIncomingHandoff` (AlwaysEnabled)、`Feature_AttemptHandoff` (WindowsInbox で有効) |
| 計画停止時間 | N/A（デスクトップアプリケーション） | ローカル実行のデスクトップアプリケーションのため該当なし |
| 障害復旧時間（RTO） | N/A | デスクトップアプリケーションのため該当なし |
| 目標復旧時点（RPO） | N/A | デスクトップアプリケーションのため該当なし |

## セキュリティ要件

### 実行権限管理

- **最小権限の原則**: `conhost.exe.manifest` にて `requestedExecutionLevel` を `asInvoker` に設定。管理者権限は要求しない
- **権限昇格の分離**: `ElevateShim` モジュールにより、管理者権限が必要な操作は別プロセス（`elevate-shim.exe`）で `ShellExecuteExW` の `runas` 動詞を使用して実行。XAML 関連のクラッシュを回避する設計
- **プロファイル単位の権限昇格**: `MTSMSettings.h` にて `Elevate` 設定（デフォルト: false）により、プロファイルごとに管理者権限での実行を制御可能
- **管理者シールド表示**: `ShowAdminShield` 設定（デフォルト: true）により、管理者権限で実行中であることをUIで明示

### 認証情報管理

- **Azure Cloud Shell**: `AzureConnection.cpp` にて Windows Credential Manager (`PasswordVault`) を使用してアクセストークンおよびリフレッシュトークンを安全に保管
- **資格情報バージョン管理**: `CurrentCredentialVersion = 2` による資格情報フォーマットのバージョニング

### 入出力セキュリティ

- **クリップボードフィルタリング**: `FilterOnPaste` 設定により、ペースト時のテキストフィルタリングを実施
- **大量ペースト警告**: `WarnAboutLargePaste` 設定（デフォルト: true）により、大量テキストのペースト時にユーザーに警告
- **複数行ペースト警告**: `WarnAboutMultiLinePaste` 設定（デフォルト: Automatic）により、複数行のペーストに対して警告
- **OSC 52 クリップボード書き込み制御**: `AllowVtClipboardWrite` 設定（デフォルト: true）による VT シーケンス経由のクリップボード操作の制御
- **DECRQCRA チェックサムレポート制御**: `AllowVtChecksumReport` 設定（デフォルト: false）により、画面内容の読み取りが可能なエスケープシーケンスをデフォルトで無効化

### プロセスセキュリティ

- **プロセス属性リスト**: `ConptyConnection.cpp` にて `PROC_THREAD_ATTRIBUTE_PSEUDOCONSOLE` を使用し、疑似コンソールハンドルの安全な受け渡しを実施
- **環境変数の分離**: 各接続セッションに固有の `WT_SESSION` および `WT_PROFILE_ID` 環境変数を設定

## 拡張性要件

### アーキテクチャの拡張性

- **レンダリングエンジンの差し替え**: `IRenderEngine` インターフェースにより、レンダリングエンジンを差し替え可能。Atlas Engine（DirectX 11）、Direct2D、GDI、WDDM の4種類を実装
- **接続タイプの拡張**: `ITerminalConnection` インターフェースにより、新しい接続タイプを追加可能。ConPTY、Azure Cloud Shell が実装済み
- **動的プロファイル生成**: `IDynamicProfileGenerator` インターフェースにより、プロファイルを動的に生成。PowerShell Core、WSL ディストリビューション、Visual Studio、SSH ホスト、Azure Cloud Shell のジェネレータが実装済み
- **フィーチャーフラグシステム**: `features.xml` によるフィーチャーフラグ管理。`AlwaysEnabled` / `AlwaysDisabled` / ブランディングトークンによる段階的リリースが可能

### 設定の拡張性

- **JSON ベースの設定**: `CascadiaSettings` による階層的な設定管理。デフォルト設定（`defaults.json`）とユーザー設定のレイヤリングをサポート
- **設定の継承**: `IInheritable` インターフェースにより、グローバル設定からプロファイル設定への設定継承を実現
- **テーマシステム**: `Theme` モデルにより、ウィンドウ、タブ行、タブの外観をカスタマイズ可能
- **カラースキーム**: `ColorScheme` により、色テーマの追加・複製・削除が可能
- **新規タブメニューのカスタマイズ**: `NewTabMenuEntry` によりメニュー構造をカスタマイズ可能

### プラットフォームの拡張性

- **WPF コントロール**: `WpfTerminalControl` により、WPF アプリケーションへのターミナルコントロールの埋め込みが可能
- **シェル拡張**: `ShellExtension` (OpenTerminalHere) により、エクスプローラーのコンテキストメニューからの起動をサポート
- **アーキテクチャ対応**: x64、ARM64、x86 の複数アーキテクチャに対応

## 保守性要件

### コード品質

- **モジュラー設計**: 主要コンポーネント（バッファ、レンダラー、パーサー、ホスト、ターミナルコア、コントロール、設定モデル）が独立したモジュールとして分離
- **共有コンポーネント**: テキストバッファ、VT パーサー/エミッター、テキストレイアウト/レンダリングエンジンなどのコアコンポーネントは、Console と Terminal で共有
- **STL コンテナの活用**: レガシーな独自コレクションから STL コンテナへの移行が完了。安全性と効率性を向上
- **WIL (Windows Implementation Libraries) の使用**: リソース管理に RAII パターンを徹底（`wil::unique_handle`, `wil::unique_event`, `wil::scope_exit` 等）
- **静的解析**: `StaticAnalysis.ruleset` による静的解析ルールの適用
- **コーディング規約**: `doc/STYLE.md` および `doc/ORGANIZATION.md` によるコーディング標準の文書化

### テスト

- **ユニットテスト**: `UnitTests_Control`、`UnitTests_SettingsModel`、`UnitTests_TerminalCore` 等の各コンポーネントに対するユニットテスト
- **統合テスト**: `LocalTests_TerminalApp` によるアプリケーションレベルの統合テスト
- **UI 自動化テスト**: `WindowsTerminal_UIATests` および `ft_uia` による UI Automation テスト
- **ファジングテスト**: `ft_fuzzer` によるVTパーサーのファジングテスト
- **整合性テスト**: `ft_integrity` によるセキュリティ整合性テスト

### 設定の変更追跡

- **設定変更ログ**: `GlobalAppSettings` にて `_changeLog` と `LogSettingChanges` により、設定変更を追跡可能
- **設定のバリデーション**: `Settings::Validate()` メソッドにより、設定値の妥当性検証を実施

## 運用・監視要件

### テレメトリ・トレーシング

- **ETW (Event Tracing for Windows)**: `TraceLoggingProvider` を使用したETWベースのトレーシングを全コンポーネントで実装
  - `Microsoft.Windows.Console.Host` プロバイダ（conhost）
  - `Microsoft.Terminal.TerminalConnection` プロバイダ（接続）
  - `Microsoft.Terminal.App` プロバイダ（アプリケーション）
- **トレースキーワード**: `TraceKeywords` 列挙体により、Chars、Output、General、Input、UIA、CookedRead、ConsoleAttachDetach 等のカテゴリ別トレーシングが可能
- **テレメトリイベント**:
  - ConPTY 接続開始イベント（セッションGUID、クライアントプロセス名）
  - 初回バイト受信イベント（所要時間を計測）
  - コマンドパレット操作イベント（検索テキスト長、ネストされたコマンド深度）
  - ショートカットアクション実行イベント
  - ターミナルハンドオフイベント
- **エラートレーシング**: `Tracing::TraceFailure` により、WIL の `FailureInfo`（HResult、ファイル、行番号、関数名、メッセージ）を記録

### パフォーマンス計測

- **レンダリング性能プロファイリング**: `Terminal.wprp` および `ConsolePerf.wprp` (Windows Performance Recorder プロファイル) によるパフォーマンスプロファイリングのサポート
- **初回バイト受信時間の計測**: `ConptyConnection.cpp` にて接続開始から初回出力までの時間（Duration）を `PDT_ProductAndServicePerformance` タグでテレメトリ送信

### 国際化対応

- **多言語リソース**: 以下の16言語のリソースファイル（`.resw`）を提供
  - de-DE, en-US, es-ES, fr-FR, it-IT, ja-JP, ko-KR, pt-BR, ru-RU, sr-Cyrl-RS, uk-UA, zh-CN, zh-TW
  - 疑似ローカライズ: qps-ploc, qps-ploca, qps-plocm
- **テキストエンコーディング**: UTF-16 をネイティブフォーマットとし、UTF-8 との相互変換をサポート。テキストバッファは UTF-16 と UTF-8 の両方を格納可能
- **言語設定**: `Language` グローバル設定により、アプリケーション表示言語を制御可能

### デバッグ機能

- **デバッグフィーチャー**: `DebugFeaturesEnabled` 設定によるデバッグ機能の有効化（デバッグビルドではデフォルト有効、リリースビルドではデフォルト無効）
- **Atlas Engine デバッグ**: `ATLAS_DEBUG_RENDER_DELAY` および `ATLAS_DEBUG_CONTINUOUS_REDRAW` によるレンダリングデバッグ支援
- **デバッグモード UI**: `Feature_DebugModeUI` フィーチャーフラグ（非リリースビルドで有効）

## 備考

- 本プロジェクトは Windows 10 2004 (build 19041) 以降を動作要件としている
- Microsoft Store、GitHub リリース、winget、Chocolatey、Scoop による複数の配布チャネルを持つ
- Windows Terminal Canary (nightly build) として、App Installer 配布（Windows 11のみ）とポータブルZIP配布を提供
- ライセンスは MIT License を採用
- CI/CD は Azure DevOps パイプラインを使用
