VRCT/src-python/docs/modules/controller_ref.md

Controller リファクタリングノート (2025-10-09)

概要: このドキュメントは controller.py に適用した互換性修正と実装上の注意点をまとめた参照用メモです。既存の controller.md を直接上書きするのではなく、参照版として保存しています。

実施内容（要約）:

• Model の lazy-init 対応に合わせ、Controller.__init__() 内で明示的に model.init() を呼び出す互換レイヤを追加しました。これにより、既存コードが import 時に model の属性へアクセスしていても安全に動作します。
• オーバーレイの存在チェックを安全に行うため、_is_overlay_available() ヘルパを導入しました。以前に直接参照していた model.overlay.initialized をこのヘルパで置換しています（合計 5 箇所を置換）。
• micMessage 内の翻訳周りで発生していたインデントの回帰を修正しました（try/except ブロックの整合性を回復）。
• 未使用の import copy を削除しました。
• ドキュメント編集は非破壊を原則とし、既存ファイルの安全な上書きが困難な場合は参照版（このファイル）を作成する方針を採りました。

互換性と注意点:

• Controller は起動時に model を初期化するため、多くの通常の利用ケースで変更の影響はありません。
• ただし、外部のモジュールやテストコードが import 時に model の内部属性（例: model.overlay や model.translator）へ直接アクセスしている場合は、明示的に model.init() を呼ぶか、Controller を経由して初期化することを推奨します。

検証:

• 軽量なローカル検証を行い、from controller import Controller; Controller() の実行で初期化が成功することを確認しました。

今後の作業候補:

• 既存の docs/modules/controller.md とこの参照ドキュメントのマージ（必要であれば差分を反映して上書きを行う）。
• linter/mypy を通して型安全性の追加と残存する静的解析の問題を解消する。
• テスト: Controller の初期化・主要ハンドラ（micMessage/chatMessage）を対象にしたユニットテストを追加して、model.lazy-init による破壊的変更が再発しないことを保証する。

このファイルは自動生成ではなく、安全に変更履歴を残すための参照メモです。上書きを希望する場合はご指示ください。