MENU

問い合わせ

    お問い合わせ


    【CAD図面PDFをExcelへ自動転記するツール開発 第10回】ローカル完結モードと外部AIモードを切り替え、APIキーをWindowsの資格情報マネージャーに保存する

    (2026年10月29日 追記:記事どおりに再現できるよう、必要なコードと手順を追加しました)

    前回(第9回)では、フォルダ内の図面PDFをまとめて処理する一括処理と、重い処理を別スレッドで動かす仕組みを作りました。

    第10回は、図面を社外に出さない「ローカル完結モード」と、精度を優先する「外部AIモード」を設定画面で切り替えられるようにし、外部AIのAPIキーを安全に保存する仕組みをPythonで作ります。ポイントは次の3つです。

    • 設定(モード・モデルID)は設定ファイルに、APIキーは設定ファイルに書かずOSの資格情報ストアに、と保存先を分ける
    • 既定はローカル完結。ローカル完結のあいだは画面で「外部AI」を選べず、送信する関数の側でも止める(画面だけに頼らない)
    • APIキーは画面・ログ・エラーメッセージに出さない。出ないことをpytestで確かめる
    目次

    今回作る機能と完成イメージ

    メイン画面の読み取り方式の横に「設定…」ボタンを追加し、次の項目を持つ設定画面を開けるようにします。

    項目内容保存先
    読み取りモードローカル完結(既定)/外部AIを許可設定ファイル
    モデルID外部AIのモデル。空欄なら既定設定ファイル
    APIキー「保存」「削除」のみ。保存済みのキーは表示しないOSの資格情報ストア
    起動時の転記設定ファイル第8回のYAMLを起動時に読み込む設定ファイル

    第10回からは、設定で「外部AIを許可」にしない限り外部AIは使えません。一括処理(第9回)はこれまでどおりローカルだけで読み取ります。

    仕組みの説明:設定とAPIキーは保存先を分ける

    設定ファイルはユーザーごとの設定フォルダへ

    設定は settings.json に保存します。保存先はアプリの置き場所ではなく利用者ごとの設定フォルダなので、exe(第11回)をどこに置いても保存でき、利用者ごとに設定が分かれます。

    OS保存先
    Windows%APPDATA%\MadoriOCR\settings.json(例:C:\Users\<ユーザー名>\AppData\Roaming\MadoriOCR)
    macOS~/Library/Application Support/MadoriOCR/settings.json
    Linux~/.config/madori-ocr/settings.json(XDG_CONFIG_HOME があればその下)

    APIキーは「資格情報ストア」へ

    APIキー(外部AIを呼ぶための合言葉。これがあれば誰でも発行元の料金で利用できる)を設定ファイルに平文で書くと、ファイルのコピーやバックアップと一緒に漏れます。そこで keyring ライブラリを使い、OSの資格情報ストア(パスワードなどを保管するOSの仕組み。Windowsでは「資格情報マネージャー」)に保存します。

    keyringの公式ページでは、推奨のバックエンド(実際の保存先)として、macOSのキーチェーン、LinuxのSecret Service・KWallet、Windowsの「Windows Credential Locker」が挙げられています。バックエンドは環境に合わせて自動で選ばれ、set_keyring() で差し替えることもできます。

    📰 出典:keyring(PyPI)

    採用したのは keyring 25.7.0(2025年11月公開・MITライセンス)です。APIキーは「資格情報ストア → 環境変数 ANTHROPIC_API_KEY(第5回からの方法。開発用)」の順に探し、どちらにも無ければ送信確認より前に止めます。

    「外部AIを許可」していなければ、2か所で止める

    画面の選択肢を無効にするだけでは、画面の作り間違いや後から追加する別の入口から送信されるおそれがあります。そこで、送信する関数(app/core/ocr_ai.py)が設定を必ず受け取り、ローカル完結なら通信の前に例外にするようにしました。

    場所ローカル完結のときの動き
    メイン画面「外部AI」の選択肢を無効化し、選択をローカルに戻す
    読み取り開始の処理念のため再確認し、エラーを表示して止める
    送信する関数(コア処理)設定を確認し、通信・画像化の前に ExternalAiDisabledError

    実装

    ファイル構成(第10回時点の差分)

    app/
    ├ core/
    │  ├ settings.py        … 新規:設定ファイルの読み書き・検証、APIキーの保存・読み込み(keyring)
    │  └ ocr_ai.py          … 変更:送信する関数が設定を必ず受け取り、ローカル完結なら送信しない
    └ ui/
       ├ settings_dialog.py … 新規:設定画面(モード・モデルID・APIキー・起動時の転記設定ファイル)
       └ main_window.py     … 変更:「設定...」ボタン、ローカル完結中は「外部AI」を無効化
    tests/
    ├ conftest.py           … 新規:全テストでkeyringをメモリ上の実装に差し替える
    ├ test_settings.py      … 新規48件
    └ test_ocr_ai.py        … 変更:設定を渡す形に修正、ローカル完結で止まることなど7件を追加
    requirements.txt        … keyring==25.7.0 を追加
    .env.example            … 変更:APIキーの保存先が設定画面になったことを説明に追記

    設定の型:APIキーの欄をそもそも持たない(app/core/settings.py)

    設定は変更できないデータクラス(frozen=True)で持ちます。APIキーの項目を作らないことで、設定ファイルにキーが書かれる経路をなくしています。

    # app/core/settings.py(抜粋)
    MODE_LOCAL = "local"
    MODE_EXTERNAL_AI = "external_ai"
    
    
    @dataclass(frozen=True)
    class AppSettings:
        """アプリの設定。APIキーは意図的に持たない(keyring に別に保存する)。"""
    
        #: 読み取りモード(`MODE_LOCAL` / `MODE_EXTERNAL_AI`)
        read_mode: str = MODE_LOCAL
        #: 外部AIのモデルID。空なら `app/core/ocr_ai.py` の既定(DEFAULT_AI_MODEL)
        ai_model: str = ""
        #: 起動時に読み込む転記の設定ファイル(第8回のYAML)。空なら読み込まない
        default_mapping_path: str = ""
    
        @property
        def external_ai_allowed(self) -> bool:
            """外部AIへの送信を許可しているか。"""
            return self.read_mode == MODE_EXTERNAL_AI

    設定ファイルが無ければ既定(ローカル完結)、壊れていればエラーを表示してローカル完結で起動するので、外部AIが勝手に有効になることはありません。モデルIDの欄にAPIキーらしい値(sk- で始まる)を貼り付けた場合も保存を拒否します。

    保存先のフォルダをOSごとに決める

    # app/core/settings.py(抜粋)
    def default_settings_dir(
        platform: str | None = None,
        environ: Mapping[str, str] | None = None,
        home: Path | None = None,
    ) -> Path:
        plat = sys.platform if platform is None else platform
        env = os.environ if environ is None else environ
        base_home = Path.home() if home is None else home
        if plat.startswith("win"):
            appdata = env.get("APPDATA", "").strip()
            base = Path(appdata) if appdata else base_home / "AppData" / "Roaming"
            return base / "MadoriOCR"
        if plat == "darwin":
            return base_home / "Library" / "Application Support" / "MadoriOCR"
        xdg = env.get("XDG_CONFIG_HOME", "").strip()
        base = Path(xdg) if xdg else base_home / ".config"
        return base / "madori-ocr"

    引数で差し替えられるので、Linux上のpytestでもWindowsの保存先を確かめられます。

    APIキーを保存する:エラーにキーを混ぜない

    # app/core/settings.py(抜粋)
    KEYRING_SERVICE = "madori-ocr"
    KEYRING_USERNAME = "anthropic-api-key"
    
    
    def save_api_key(text: str) -> None:
        value = validate_api_key(text)
        if not is_keyring_available():
            raise ApiKeyStoreError(
                "この環境ではOSの資格情報ストアが使えないため、APIキーを保存できません。"
                f"開発時は環境変数 {ENV_API_KEY} を使ってください。"
            )
        try:
            keyring.set_password(KEYRING_SERVICE, KEYRING_USERNAME, value)
        except Exception as exc:
            raise ApiKeyStoreError(f"APIキーを資格情報ストアに保存できませんでした({type(exc).__name__})。") from None
        logger.info("APIキーを資格情報ストアに保存しました(サービス名=%s)", KEYRING_SERVICE)

    失敗時は元の例外を連結せず(from None)、種類名だけを伝えます。バックエンドによってはエラーメッセージに保存しようとした値を含める可能性があるためです。使えるバックエンドが無い環境(Linuxのサーバーなど)では、is_keyring_available() で見分けて保存ボタンを無効にし、環境変数だけを使います。

    APIキーを読み込む:資格情報ストア → 環境変数

    # app/core/settings.py(抜粋)
    @dataclass(frozen=True)
    class ResolvedApiKey:
        """読み込んだAPIキーと、その読み込み元。`repr()`・`str()` にキーの値を出さない。"""
    
        value: str = field(repr=False)
        source: str
    
        def __str__(self) -> str:
            return f"{MASKED_KEY}({self.source})"
    
    
    def load_api_key(environ: Mapping[str, str] | None = None) -> ResolvedApiKey | None:
        stored = _read_stored_api_key()
        if stored is not None:
            logger.debug("APIキーを資格情報ストアから読み込みました")
            return ResolvedApiKey(stored, SOURCE_KEYRING)
        env = os.environ if environ is None else environ
        from_env = env.get(ENV_API_KEY, "").strip()
        if from_env:
            logger.debug("APIキーを環境変数 %s から読み込みました(開発用)", ENV_API_KEY)
            return ResolvedApiKey(from_env, SOURCE_ENV)
        return None

    field(repr=False) にしておくと、デバッグ用に print(resolved) やログに %r で出しても、キーの値は表示されません。

    送信する関数の側でも止める(app/core/ocr_ai.py)

    ai_ocr_image() などに引数 settings を必須で追加しました。ローカル完結なら何も送らずに例外になります。

    # app/core/ocr_ai.py(抜粋)
    def ensure_external_ai_allowed(settings: AppSettings) -> None:
        if not isinstance(settings, AppSettings):
            raise TypeError("settings には AppSettings を渡してください。")
        if not settings.external_ai_allowed:
            raise ExternalAiDisabledError(
                "ローカル完結モードのため、外部AIへは送信できません。外部AIを使う場合は、"
                "「設定...」画面で読み取りモードを「外部AIを許可」に切り替えてください。"
            )
    
    
    def ai_ocr_image(
        image: Image.Image,
        *,
        settings: AppSettings,
        base_scale: float,
        # (以下の引数は第5回と同じため省略)
    ) -> AiOcrResult:
        ensure_external_ai_allowed(settings)
        if client is None:
            client = create_client(get_api_key())
        used_model = model or resolve_model(settings=settings)
        # (以下は第5回と同じ:画像の縮小 → 送信 → 応答JSONのパース)

    モデルIDは「設定画面 → 環境変数 MADORI_OCR_AI_MODEL → 既定」の順です。APIのエラーメッセージは、APIキーらしい文字列を伏せ字にしてから表示します。

    画面:ローカル完結のあいだは「外部AI」を選べない(app/ui/main_window.py)

    # app/ui/main_window.py(抜粋)
        def _apply_settings(self) -> None:
            """設定を画面に反映する。ローカル完結モードなら「外部AI」の選択肢を無効にし、ローカルに戻す。"""
            if self.settings.external_ai_allowed:
                self.ai_radio.configure(state="normal", text=AI_RADIO_TEXT_ALLOWED)
            else:
                self.ai_radio.configure(state="disabled", text=AI_RADIO_TEXT_DISABLED)
                self.read_mode_var.set(READ_MODE_LOCAL)

    送信時は、送信確認ダイアログ(第5回。許可モードでも毎回出ます)を出した時点の設定を、別スレッドの送信関数へ渡します。

    設定画面:入力欄は伏せ字、保存済みのキーは見せない(app/ui/settings_dialog.py)

    # app/ui/settings_dialog.py(抜粋)
            # show= で入力した文字を伏せ字にする。保存後は入力欄を空に戻し、値を画面に残さない
            self.api_key_entry = ttk.Entry(key_row, textvariable=self.api_key_var, show=_MASK_CHAR, width=30)

    保存済みのキーは状態だけを表示し、末尾の数文字も出しません。キーを入力したまま「OK」を押すと、保存し忘れとして警告します。

    この回で追加・変更するファイル

    APIキーの保存にkeyringを追加します(Windowsでは、keyringが使う pywin32-ctypes も自動で入ります)。

    requirements.txt に次の変更を加えます(+ が追加、- が削除)。

    --- a/requirements.txt
    +++ b/requirements.txt
    @@ -30,3 +30,9 @@ anthropic==0.77.0
     # 第7回〜:Excelテンプレート(既存の様式)を開き、決まったセルへ部屋名を書き込む(import openpyxl。
     # 3.1.5は2024-06-28公開・MIT License)。書式・数式はそのまま残し、値だけを書き込んで別名で保存する。
     openpyxl==3.1.5
    +
    +# 第10回〜:外部AIのAPIキーをOSの資格情報ストア(Windowsでは資格情報マネージャー)へ保存する
    +# (import keyring。25.7.0は2025-11-16公開・MIT License)。APIキーは設定ファイル(settings.json)に
    +# 書かない。Windowsでは依存の pywin32-ctypes が自動で入る。Linuxのサーバー等で使えるバックエンドが
    +# 無い場合は保存できず、開発用の環境変数 ANTHROPIC_API_KEY だけを使う。
    +keyring==25.7.0
    pip install keyring==25.7.0

    上で抜粋した設定のコア処理(app/core/settings.py)と、設定画面(app/ui/settings_dialog.py)の全体です。

    app/core/settings.py を新しく作ります(全文)。

    app/core/settings.py の全文(385行)
    # app/core/settings.py
    """アプリの設定(読み取りモード・モデルID・既定の転記設定ファイル)とAPIキーの保存・読み込み(第10回)。
    
    第5回では、外部AI(Claude API)のAPIキーを環境変数 `ANTHROPIC_API_KEY` から
    読んでいた。開発者には手軽だが、配布先の担当者に「環境変数を設定してください」
    とは頼みにくい。第10回では、次の2つを分けて保存する。
    
    - **設定ファイル(settings.json)**:読み取りモード(ローカル完結/外部AIを許可)、
      外部AIのモデルID、起動時に読み込む転記の設定ファイル(第8回のYAML)。
      保存先はOSごとのユーザー用の設定フォルダ(Windowsなら `%APPDATA%\\MadoriOCR`)。
      **APIキーはこのファイルに書かない**(フィールド自体を持たない)。
    - **APIキー**:keyring ライブラリで、OSの資格情報ストア(Windowsでは資格情報
      マネージャー)に保存する。読み込みは「keyring → 環境変数 `ANTHROPIC_API_KEY`
      (開発用)」の順。
    
    既定(設定ファイルが無いとき)は **ローカル完結モード**。外部AIは、利用者が
    設定画面で「外部AIを許可」に切り替えた場合だけ使える。画面の選択肢を無効に
    するだけでなく、`app/core/ocr_ai.py` 側でもこの設定を確認してから送信する
    (UIの作り間違いがあっても図面が送られないようにするため)。
    
    APIキーの値は、ログ・例外メッセージ・`repr()` のどこにも出さない。
    tkinterなどGUIライブラリはimportしない(pytestで検証するコア処理)。
    """
    
    from __future__ import annotations
    
    import json
    import logging
    import os
    import re
    import sys
    import tempfile
    from collections.abc import Mapping
    from dataclasses import dataclass, field, replace
    from pathlib import Path
    
    import keyring
    import keyring.errors
    from keyring.backends import fail as keyring_fail
    
    logger = logging.getLogger(__name__)
    
    #: 読み取りモード。既定はローカル完結(図面を社外に送らない)
    MODE_LOCAL = "local"
    MODE_EXTERNAL_AI = "external_ai"
    READ_MODES = (MODE_LOCAL, MODE_EXTERNAL_AI)
    
    #: 設定ファイルの形式のバージョン(将来項目を増やしたときの読み替え用)
    SETTINGS_VERSION = 1
    SETTINGS_FILE_NAME = "settings.json"
    #: 設定ファイルの大きさの上限(壊れた・想定外のファイルを読み込まないため)
    MAX_SETTINGS_BYTES = 64 * 1024
    
    #: keyring に保存するときの「サービス名」と「ユーザー名」。
    #: Windowsの資格情報マネージャーでは、サービス名が「汎用資格情報」の名前として使われる
    #: (keyring 25.7.0 の `keyring/backends/Windows.py` の実装による)。
    KEYRING_SERVICE = "madori-ocr"
    KEYRING_USERNAME = "anthropic-api-key"
    
    #: 開発用に、keyring に保存が無いとき読む環境変数(第5回から)
    ENV_API_KEY = "ANTHROPIC_API_KEY"
    
    #: APIキーをどこから読んだか
    SOURCE_KEYRING = "keyring"
    SOURCE_ENV = "env"
    
    #: 画面にAPIキーの代わりに出す伏せ字(長さも分からないよう固定の長さにする)
    MASKED_KEY = "●" * 12
    
    #: APIキーとして受け付ける長さの上限(貼り付け間違いで長文が入るのを防ぐ)
    MAX_API_KEY_LENGTH = 512
    
    #: モデルIDとして受け付ける文字(英数字と . _ : @ / -)。空欄は「既定のモデル」
    _MODEL_ID_PATTERN = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:@/-]{0,99}")
    #: AnthropicのAPIキーらしき文字列(ログや画面に出す前に伏せるため)
    _API_KEY_LIKE_PATTERN = re.compile(r"sk-ant-[A-Za-z0-9_-]+")
    
    
    class SettingsError(RuntimeError):
        """設定ファイルの読み込み・保存、設定値の検証に失敗した場合の例外。"""
    
    
    class ApiKeyStoreError(RuntimeError):
        """APIキーの保存・削除に失敗した場合の例外(メッセージにキーの値は含めない)。"""
    
    
    @dataclass(frozen=True)
    class AppSettings:
        """アプリの設定。APIキーは意図的に持たない(keyring に別に保存する)。"""
    
        #: 読み取りモード(`MODE_LOCAL` / `MODE_EXTERNAL_AI`)
        read_mode: str = MODE_LOCAL
        #: 外部AIのモデルID。空なら `app/core/ocr_ai.py` の既定(DEFAULT_AI_MODEL)
        ai_model: str = ""
        #: 起動時に読み込む転記の設定ファイル(第8回のYAML)。空なら読み込まない
        default_mapping_path: str = ""
    
        @property
        def external_ai_allowed(self) -> bool:
            """外部AIへの送信を許可しているか。"""
            return self.read_mode == MODE_EXTERNAL_AI
    
    
    # --- 保存先 --------------------------------------------------------------------
    
    
    def default_settings_dir(
        platform: str | None = None,
        environ: Mapping[str, str] | None = None,
        home: Path | None = None,
    ) -> Path:
        """OSごとのユーザー用の設定フォルダを返す(作成はしない)。
    
        - Windows:`%APPDATA%\\MadoriOCR`(例:C:\\Users\\<ユーザー名>\\AppData\\Roaming\\MadoriOCR)
        - macOS:`~/Library/Application Support/MadoriOCR`
        - Linuxなど:`$XDG_CONFIG_HOME/madori-ocr`(未設定なら `~/.config/madori-ocr`)
    
        `platform`・`environ`・`home` はテストで差し替えるための引数。
        """
        plat = sys.platform if platform is None else platform
        env = os.environ if environ is None else environ
        base_home = Path.home() if home is None else home
        if plat.startswith("win"):
            appdata = env.get("APPDATA", "").strip()
            base = Path(appdata) if appdata else base_home / "AppData" / "Roaming"
            return base / "MadoriOCR"
        if plat == "darwin":
            return base_home / "Library" / "Application Support" / "MadoriOCR"
        xdg = env.get("XDG_CONFIG_HOME", "").strip()
        base = Path(xdg) if xdg else base_home / ".config"
        return base / "madori-ocr"
    
    
    def default_settings_path() -> Path:
        """既定の設定ファイルのパス(`default_settings_dir()` の下の settings.json)。"""
        return default_settings_dir() / SETTINGS_FILE_NAME
    
    
    # --- 設定値の検証 ----------------------------------------------------------------
    
    
    def validate_model_id(text: str) -> str:
        """モデルIDの入力を検証して前後の空白を除いた値を返す。空欄は「既定のモデル」。
    
        APIキーをモデルIDの欄に貼り付けてしまうと設定ファイルに平文で残るため、
        APIキーらしい値(sk- で始まる)は受け付けない。エラーメッセージには入力値を含めない。
        """
        value = text.strip()
        if not value:
            return ""
        if value.lower().startswith("sk-"):
            raise SettingsError(
                "モデルIDの欄にAPIキーのような値が入力されています。APIキーは「APIキー」欄で保存してください"
                "(モデルIDの欄の値は設定ファイルに平文で保存されます)。"
            )
        if not _MODEL_ID_PATTERN.fullmatch(value):
            raise SettingsError(
                "モデルIDに使えない文字が含まれているか、長すぎます(英数字と . _ : @ / - の100文字以内)。"
            )
        return value
    
    
    def validate_settings(settings: AppSettings) -> AppSettings:
        """設定値を検証し、正規化した `AppSettings` を返す。"""
        if settings.read_mode not in READ_MODES:
            raise SettingsError(f"読み取りモードの値が不正です({', '.join(READ_MODES)} のいずれか)。")
        return replace(
            settings,
            ai_model=validate_model_id(settings.ai_model),
            default_mapping_path=settings.default_mapping_path.strip(),
        )
    
    
    # --- 設定ファイルの読み書き --------------------------------------------------------
    
    
    def load_settings(path: str | Path | None = None) -> AppSettings:
        """設定ファイルを読み込む。ファイルが無ければ既定(ローカル完結モード)を返す。
    
        壊れている(JSONでない・値が不正)場合は `SettingsError`。呼び出し側(画面)は
        エラーを表示したうえで既定の設定で起動する(外部AIが勝手に有効になることはない)。
        知らない項目は無視する(新しい版で保存した設定を古い版で開いた場合のため)。
        """
        settings_path = default_settings_path() if path is None else Path(path)
        if not settings_path.exists():
            return AppSettings()
        try:
            raw = settings_path.read_bytes()
        except OSError as exc:
            raise SettingsError(f"設定ファイルを読み込めませんでした: {settings_path}({exc.strerror})") from None
        if len(raw) > MAX_SETTINGS_BYTES:
            raise SettingsError(f"設定ファイルが大きすぎます({MAX_SETTINGS_BYTES // 1024}KBまで): {settings_path}")
        try:
            data = json.loads(raw.decode("utf-8-sig"))
        except UnicodeDecodeError:
            raise SettingsError(f"設定ファイルがUTF-8ではありません: {settings_path}") from None
        except json.JSONDecodeError as exc:
            raise SettingsError(f"設定ファイルの形式が壊れています({exc.lineno}行目): {settings_path}") from None
        if not isinstance(data, dict):
            raise SettingsError(f"設定ファイルの形式が不正です(JSONのオブジェクトではありません): {settings_path}")
        if data.get("version", SETTINGS_VERSION) != SETTINGS_VERSION:
            raise SettingsError(f"対応していない設定ファイルの版です(version: {SETTINGS_VERSION} のみ対応)。")
    
        values: dict[str, str] = {}
        for name in ("read_mode", "ai_model", "default_mapping_path"):
            if name not in data:
                continue
            if not isinstance(data[name], str):
                raise SettingsError(f"設定ファイルの「{name}」は文字列で指定してください: {settings_path}")
            values[name] = data[name]
        return validate_settings(AppSettings(**values))
    
    
    def save_settings(settings: AppSettings, path: str | Path | None = None) -> Path:
        """設定をJSONで保存し、保存したパスを返す。保存先のフォルダが無ければ作る。
    
        一時ファイルに書いてから置き換えるため、保存中に落ちても設定ファイルが
        中途半端な内容で残らない。APIキーは `AppSettings` に無いので書かれない。
        """
        checked = validate_settings(settings)
        settings_path = default_settings_path() if path is None else Path(path)
        data = {
            "version": SETTINGS_VERSION,
            "read_mode": checked.read_mode,
            "ai_model": checked.ai_model,
            "default_mapping_path": checked.default_mapping_path,
        }
        text = json.dumps(data, ensure_ascii=False, indent=2) + "\n"
        try:
            settings_path.parent.mkdir(parents=True, exist_ok=True)
            fd, tmp_name = tempfile.mkstemp(prefix="~settings", suffix=".tmp", dir=settings_path.parent)
            try:
                with os.fdopen(fd, "w", encoding="utf-8") as tmp:
                    tmp.write(text)
                os.replace(tmp_name, settings_path)
            except BaseException:
                Path(tmp_name).unlink(missing_ok=True)
                raise
        except OSError as exc:
            raise SettingsError(f"設定ファイルを保存できませんでした: {settings_path}({exc.strerror})") from None
        logger.info("設定を保存しました(読み取りモード=%s): %s", checked.read_mode, settings_path)
        return settings_path
    
    
    # --- APIキー(keyring) -------------------------------------------------------------
    
    
    @dataclass(frozen=True)
    class ResolvedApiKey:
        """読み込んだAPIキーと、その読み込み元。`repr()`・`str()` にキーの値を出さない。"""
    
        value: str = field(repr=False)
        #: `SOURCE_KEYRING`(資格情報ストア)または `SOURCE_ENV`(環境変数・開発用)
        source: str
    
        def __str__(self) -> str:
            return f"{MASKED_KEY}({self.source})"
    
    
    @dataclass(frozen=True)
    class ApiKeyStatus:
        """設定画面に出すAPIキーの状態(キーの値そのものは持たない)。"""
    
        #: 資格情報ストアにAPIキーが保存されているか
        stored: bool
        #: 開発用の環境変数 ANTHROPIC_API_KEY が設定されているか
        env_set: bool
        #: この環境で資格情報ストアが使えるか(Linuxのサーバー等では使えないことが多い)
        store_available: bool
    
    
    def is_keyring_available() -> bool:
        """資格情報ストア(keyringのバックエンド)が使えるか。
    
        使えるバックエンドが無い環境では、keyring は `keyring.backends.fail.Keyring`
        (呼ぶと必ず `NoKeyringError` になる)を返す。
        """
        try:
            return not isinstance(keyring.get_keyring(), keyring_fail.Keyring)
        except Exception:  # バックエンドの初期化そのものに失敗した場合も「使えない」とする
            return False
    
    
    def validate_api_key(text: str) -> str:
        """保存する前にAPIキーの入力を検証する。エラーメッセージには入力値を一切含めない。"""
        value = text.strip()
        if not value:
            raise ApiKeyStoreError("APIキーが入力されていません。")
        if len(value) > MAX_API_KEY_LENGTH:
            raise ApiKeyStoreError(f"APIキーが長すぎます({MAX_API_KEY_LENGTH}文字まで)。貼り付けた内容を確認してください。")
        if any(ch.isspace() or not ch.isprintable() for ch in value):
            raise ApiKeyStoreError("APIキーに空白・改行などの使えない文字が含まれています。貼り付けた内容を確認してください。")
        return value
    
    
    def save_api_key(text: str) -> None:
        """APIキーをOSの資格情報ストアに保存する(設定ファイルには書かない)。
    
        失敗したときの例外は `ApiKeyStoreError` にまとめ、元の例外は連結しない
        (`from None`)。バックエンドによってはエラーメッセージに保存しようとした
        値を含める可能性があり、それがログやエラー画面に出ないようにするため。
        """
        value = validate_api_key(text)
        if not is_keyring_available():
            raise ApiKeyStoreError(
                "この環境ではOSの資格情報ストアが使えないため、APIキーを保存できません。"
                f"開発時は環境変数 {ENV_API_KEY} を使ってください。"
            )
        try:
            keyring.set_password(KEYRING_SERVICE, KEYRING_USERNAME, value)
        except Exception as exc:
            raise ApiKeyStoreError(f"APIキーを資格情報ストアに保存できませんでした({type(exc).__name__})。") from None
        logger.info("APIキーを資格情報ストアに保存しました(サービス名=%s)", KEYRING_SERVICE)
    
    
    def delete_api_key() -> bool:
        """資格情報ストアからAPIキーを削除する。保存されていなければ `False`。"""
        if not is_keyring_available():
            return False
        try:
            keyring.delete_password(KEYRING_SERVICE, KEYRING_USERNAME)
        except keyring.errors.PasswordDeleteError:
            return False  # 保存されていない
        except Exception as exc:
            raise ApiKeyStoreError(f"APIキーを資格情報ストアから削除できませんでした({type(exc).__name__})。") from None
        logger.info("APIキーを資格情報ストアから削除しました(サービス名=%s)", KEYRING_SERVICE)
        return True
    
    
    def _read_stored_api_key() -> str | None:
        if not is_keyring_available():
            return None
        try:
            stored = keyring.get_password(KEYRING_SERVICE, KEYRING_USERNAME)
        except Exception as exc:  # 資格情報ストアが一時的に使えない等。環境変数へ進む
            logger.warning("資格情報ストアからAPIキーを読み込めませんでした(%s)", type(exc).__name__)
            return None
        if stored is None or not stored.strip():
            return None
        return stored.strip()
    
    
    def load_api_key(environ: Mapping[str, str] | None = None) -> ResolvedApiKey | None:
        """APIキーを「資格情報ストア → 環境変数 ANTHROPIC_API_KEY(開発用)」の順に探す。
    
        どちらにも無ければ `None`。見つかったキーの値はログに出さず、読み込み元だけを記録する。
        """
        stored = _read_stored_api_key()
        if stored is not None:
            logger.debug("APIキーを資格情報ストアから読み込みました")
            return ResolvedApiKey(stored, SOURCE_KEYRING)
        env = os.environ if environ is None else environ
        from_env = env.get(ENV_API_KEY, "").strip()
        if from_env:
            logger.debug("APIキーを環境変数 %s から読み込みました(開発用)", ENV_API_KEY)
            return ResolvedApiKey(from_env, SOURCE_ENV)
        return None
    
    
    def api_key_status(environ: Mapping[str, str] | None = None) -> ApiKeyStatus:
        """設定画面に表示するAPIキーの状態を調べる。"""
        env = os.environ if environ is None else environ
        return ApiKeyStatus(
            stored=_read_stored_api_key() is not None,
            env_set=bool(env.get(ENV_API_KEY, "").strip()),
            store_available=is_keyring_available(),
        )
    
    
    def describe_api_key_status(status: ApiKeyStatus) -> str:
        """APIキーの状態を画面用の文章にする(キーの値・一部の文字も出さない)。"""
        if status.stored:
            return f"保存済み({MASKED_KEY})。キーは表示しません"
        if status.env_set:
            return f"資格情報ストアには未保存。開発用の環境変数 {ENV_API_KEY} のキーを使います"
        if not status.store_available:
            return f"未設定(この環境では資格情報ストアを使えません。開発時は環境変数 {ENV_API_KEY})"
        return "未設定"
    
    
    def redact_secrets(text: str, secret: str | None = None) -> str:
        """文字列からAPIキー(とそれらしい文字列)を伏せ字にする。エラー表示・ログの直前に使う。"""
        if secret:
            text = text.replace(secret, MASKED_KEY)
        return _API_KEY_LIKE_PATTERN.sub("sk-ant-" + MASKED_KEY, text)

    app/ui/settings_dialog.py を新しく作ります(全文)。

    app/ui/settings_dialog.py の全文(225行)
    # app/ui/settings_dialog.py
    """設定画面(第10回)。
    
    - 読み取りモード:「ローカル完結(既定)」か「外部AIを許可」か
    - 外部AIのモデルID(空欄なら既定のモデル)
    - APIキー:OSの資格情報ストア(Windowsでは資格情報マネージャー)への保存・削除。
      入力欄は伏せ字で、保存済みのキーは画面に一切表示しない(状態だけを出す)
    - 起動時に読み込む転記の設定ファイル(第8回のYAML)
    
    「OK」で `AppSettings` を返し、保存は呼び出し側(メイン画面)が `save_settings()` で行う。
    APIキーの「保存」「削除」は資格情報ストアへすぐに反映する(OK/キャンセルとは別)。
    設定値の検証・保存・keyringの操作は `app/core/settings.py`(GUI非依存)にあり、この画面は
    それを呼ぶだけの薄い層にしている。
    """
    
    from __future__ import annotations
    
    import tkinter as tk
    from pathlib import Path
    from tkinter import filedialog, messagebox, ttk
    
    from app.core.ocr_ai import DEFAULT_AI_MODEL
    from app.core.settings import (
        MODE_EXTERNAL_AI,
        MODE_LOCAL,
        ApiKeyStoreError,
        AppSettings,
        SettingsError,
        api_key_status,
        delete_api_key,
        describe_api_key_status,
        save_api_key,
        validate_model_id,
        validate_settings,
    )
    
    DIALOG_TITLE = "設定"
    MAPPING_FILETYPES = [("転記の設定ファイル(YAML)", "*.yaml *.yml")]
    #: 入力欄に表示する伏せ字の文字
    _MASK_CHAR = "●"
    
    
    class SettingsDialog(tk.Toplevel):
        """設定画面。`result` に「OK」で確定した `AppSettings`(キャンセルなら `None`)が入る。"""
    
        def __init__(self, master: tk.Misc, *, settings: AppSettings, settings_path: Path) -> None:
            super().__init__(master)
            self.title(DIALOG_TITLE)
            self.resizable(False, False)
            self.result: AppSettings | None = None
            self._settings_path = settings_path
    
            self.mode_var = tk.StringVar(value=settings.read_mode)
            self.model_var = tk.StringVar(value=settings.ai_model)
            self.api_key_var = tk.StringVar(value="")
            self.key_status_var = tk.StringVar(value="")
            self.mapping_var = tk.StringVar(value=settings.default_mapping_path)
    
            self._build_widgets()
            self._refresh_key_status()
            self.protocol("WM_DELETE_WINDOW", self._on_cancel)
            self.bind("<Escape>", lambda _e: self._on_cancel())
    
        def _build_widgets(self) -> None:
            body = ttk.Frame(self, padding=16)
            body.pack(fill="both", expand=True)
            body.columnconfigure(0, weight=1)
    
            mode = ttk.LabelFrame(body, text="読み取りモード", padding=10)
            mode.grid(row=0, column=0, sticky="ew")
            ttk.Radiobutton(
                mode,
                text="ローカル完結(既定):図面を社外へ送信しません。メイン画面の「外部AI」は選べません",
                variable=self.mode_var,
                value=MODE_LOCAL,
            ).pack(anchor="w")
            ttk.Radiobutton(
                mode,
                text="外部AIを許可:メイン画面で「外部AI」を選び、送信を確認したときだけ図面画像を送信します",
                variable=self.mode_var,
                value=MODE_EXTERNAL_AI,
            ).pack(anchor="w", pady=(4, 0))
    
            ai = ttk.LabelFrame(body, text="外部AI(Anthropic Claude API)", padding=10)
            ai.grid(row=1, column=0, sticky="ew", pady=(12, 0))
            ai.columnconfigure(1, weight=1)
    
            ttk.Label(ai, text="モデルID:").grid(row=0, column=0, sticky="w")
            ttk.Entry(ai, textvariable=self.model_var, width=40).grid(row=0, column=1, sticky="ew")
            ttk.Label(ai, text=f"空欄なら既定({DEFAULT_AI_MODEL})", foreground="#555555").grid(
                row=1, column=1, sticky="w", pady=(0, 8)
            )
    
            ttk.Label(ai, text="APIキーの状態:").grid(row=2, column=0, sticky="w")
            self.key_status_label = ttk.Label(ai, textvariable=self.key_status_var, foreground="#1f5fbf")
            self.key_status_label.grid(row=2, column=1, sticky="w")
    
            ttk.Label(ai, text="新しいAPIキー:").grid(row=3, column=0, sticky="w", pady=(6, 0))
            key_row = ttk.Frame(ai)
            key_row.grid(row=3, column=1, sticky="ew", pady=(6, 0))
            # show= で入力した文字を伏せ字にする。保存後は入力欄を空に戻し、値を画面に残さない
            self.api_key_entry = ttk.Entry(key_row, textvariable=self.api_key_var, show=_MASK_CHAR, width=30)
            self.api_key_entry.pack(side="left", fill="x", expand=True)
            self.save_key_button = ttk.Button(key_row, text="保存", command=self._on_save_key)
            self.save_key_button.pack(side="left", padx=(6, 0))
            self.delete_key_button = ttk.Button(key_row, text="削除", command=self._on_delete_key)
            self.delete_key_button.pack(side="left", padx=(4, 0))
            ttk.Label(
                ai,
                text=(
                    "APIキーは設定ファイルに書かず、OSの資格情報ストア(Windowsでは資格情報マネージャー)に\n"
                    "保存します。「保存」「削除」はすぐに反映されます(OK・キャンセルとは別)。"
                ),
                foreground="#555555",
                justify="left",
            ).grid(row=4, column=0, columnspan=2, sticky="w", pady=(6, 0))
    
            mapping = ttk.LabelFrame(body, text="起動時に読み込む転記の設定ファイル(任意・YAML)", padding=10)
            mapping.grid(row=2, column=0, sticky="ew", pady=(12, 0))
            mapping.columnconfigure(0, weight=1)
            ttk.Label(mapping, textvariable=self.mapping_var, foreground="#555555", width=60).grid(
                row=0, column=0, sticky="w"
            )
            mapping_buttons = ttk.Frame(mapping)
            mapping_buttons.grid(row=0, column=1, sticky="e")
            ttk.Button(mapping_buttons, text="選ぶ...", command=self._on_choose_mapping).pack(side="left")
            ttk.Button(mapping_buttons, text="外す", command=lambda: self.mapping_var.set("")).pack(
                side="left", padx=(4, 0)
            )
    
            ttk.Label(body, text=f"設定の保存先:{self._settings_path}", foreground="#555555").grid(
                row=3, column=0, sticky="w", pady=(12, 0)
            )
    
            buttons = ttk.Frame(body)
            buttons.grid(row=4, column=0, sticky="e", pady=(12, 0))
            ttk.Button(buttons, text="キャンセル", command=self._on_cancel).pack(side="right")
            ttk.Button(buttons, text="OK", command=self._on_ok).pack(side="right", padx=(0, 6))
    
        # --- APIキー -----------------------------------------------------------------
    
        def _refresh_key_status(self) -> None:
            status = api_key_status()
            self.key_status_var.set(describe_api_key_status(status))
            self.key_status_label.configure(foreground="#1f5fbf" if status.stored or status.env_set else "#b00020")
            store_state = "normal" if status.store_available else "disabled"
            self.save_key_button.configure(state=store_state)
            self.delete_key_button.configure(state="normal" if status.stored else "disabled")
    
        def _on_save_key(self) -> None:
            try:
                save_api_key(self.api_key_var.get())
            except ApiKeyStoreError as exc:
                messagebox.showerror("APIキーを保存できません", str(exc), parent=self)
                return
            finally:
                self.api_key_var.set("")  # 成功・失敗どちらでも、入力した値を画面に残さない
            self._refresh_key_status()
            messagebox.showinfo("APIキーを保存しました", "APIキーを資格情報ストアに保存しました。", parent=self)
    
        def _on_delete_key(self) -> None:
            if not messagebox.askyesno(
                "APIキーを削除します",
                "資格情報ストアに保存したAPIキーを削除しますか?",
                detail="削除すると、外部AIを使うにはAPIキーの保存が再び必要になります。",
                icon="warning",
                default="no",
                parent=self,
            ):
                return
            try:
                delete_api_key()
            except ApiKeyStoreError as exc:
                messagebox.showerror("APIキーを削除できません", str(exc), parent=self)
            self._refresh_key_status()
    
        # --- その他 -------------------------------------------------------------------
    
        def _on_choose_mapping(self) -> None:
            path = filedialog.askopenfilename(title="転記の設定ファイルを選択", filetypes=MAPPING_FILETYPES, parent=self)
            if path:
                self.mapping_var.set(path)
    
        def _collect(self) -> AppSettings:
            """画面の入力から `AppSettings` を作って検証する(不正なら `SettingsError`)。"""
            model = validate_model_id(self.model_var.get())
            return validate_settings(
                AppSettings(
                    read_mode=self.mode_var.get(),
                    ai_model=model,
                    default_mapping_path=self.mapping_var.get(),
                )
            )
    
        def _on_ok(self) -> None:
            if self.api_key_var.get().strip():
                # 入力したまま「保存」を押し忘れた場合。黙って捨ても保存もせず、確認する
                messagebox.showwarning(
                    "APIキーが保存されていません",
                    "入力したAPIキーはまだ保存されていません。「保存」を押すか、入力欄を空にしてください。",
                    parent=self,
                )
                return
            try:
                self.result = self._collect()
            except SettingsError as exc:
                messagebox.showerror("設定のエラー", str(exc), parent=self)
                return
            self.destroy()
    
        def _on_cancel(self) -> None:
            self.api_key_var.set("")
            self.result = None
            self.destroy()
    
    
    def open_settings_dialog(master: tk.Misc, *, settings: AppSettings, settings_path: Path) -> AppSettings | None:
        """設定画面をモーダルで開き、「OK」なら新しい `AppSettings`、キャンセルなら `None` を返す。"""
        dialog = SettingsDialog(master, settings=settings, settings_path=settings_path)
        dialog.transient(master.winfo_toplevel())
        dialog.wait_visibility()
        dialog.grab_set()
        dialog.focus_set()
        master.wait_window(dialog)
        return dialog.result

    外部AIの処理は、送信する関数が設定を必ず受け取り、ローカル完結なら送信の前に止めるようにします。APIキーの環境変数名 ENV_API_KEY は settings.py へ移します。

    app/core/ocr_ai.py に次の変更を加えます(+ が追加、- が削除)。

    app/core/ocr_ai.py の差分(195行)
    --- a/app/core/ocr_ai.py
    +++ b/app/core/ocr_ai.py
    @@ -19,8 +19,14 @@ AIは図面全体の文脈(部屋の枠の中央にある語か、寸法線の
       前後に説明文やコードフェンス(```json ... ```)が付くこともあるため、
       `parse_ai_response()` で頑健に取り出し、形式が崩れていれば
       `AiResponseFormatError` にする。
    -- **APIキーと利用料金が必要**。APIキーはコード・設定ファイルに書かず、
    -  環境変数 `ANTHROPIC_API_KEY` から読む(保存方法は第10回で見直す)。
    +- **APIキーと利用料金が必要**。APIキーはコード・設定ファイルに書かない。
    +  第10回から、設定画面で保存したOSの資格情報ストア(Windowsでは資格情報
    +  マネージャー。keyring経由)→ 環境変数 `ANTHROPIC_API_KEY`(開発用)の順に
    +  読む(`app/core/settings.py`)。
    +- **第10回から、設定が「外部AIを許可」でなければ送信しない**。画面で選択肢を
    +  無効にしているだけでなく、送信する関数(`ai_ocr_image()` など)が設定
    +  (`AppSettings`)を必ず受け取り、ローカル完結モードなら通信の前に
    +  `ExternalAiDisabledError` にする。
     
     戻り値は第2回・第4回と同じ `ExtractedWord`(文字列・座標・文字の高さ・
     ページ番号)にそろえ、プレビューのハイライト表示や部屋名辞書との照合を
    @@ -48,16 +54,17 @@ from PIL import Image
     
     from app.core.ocr_local import image_from_ppm_bytes
     from app.core.pdf_loader import DEFAULT_DPI, PdfDocument, RenderedPage
    +from app.core.settings import ENV_API_KEY, AppSettings, load_api_key, redact_secrets
     from app.core.text_extractor import ExtractedWord
     
    -#: APIキーを読む環境変数名(値はコード・設定ファイルに書かない)
    -ENV_API_KEY = "ANTHROPIC_API_KEY"
    +# APIキーの環境変数名 ENV_API_KEY は第10回で settings.py へ移した(第5回と同じ名前で import できる)
    +
     #: 使用するモデルIDを差し替えるための環境変数名
     ENV_MODEL = "MADORI_OCR_AI_MODEL"
     
     #: 既定のモデルID(執筆時点。画像入力に対応したClaude Haiku 4.5のスナップショットID)。
     #: モデルは入れ替わりが速いため、公式ドキュメントのモデル一覧で最新を確認し、
    -#: 必要なら環境変数 `MADORI_OCR_AI_MODEL` で差し替える。
    +#: 必要なら設定画面のモデルID(開発時は環境変数 `MADORI_OCR_AI_MODEL`)で差し替える。
     DEFAULT_AI_MODEL = "claude-haiku-4-5-20251001"
     
     #: 応答の最大トークン数。返してほしいのは部屋名と座標の短いJSONだけなので小さめにする。
    @@ -98,7 +105,11 @@ class AiOcrError(RuntimeError):
     
     
     class AiApiKeyMissingError(AiOcrError):
    -    """環境変数 `ANTHROPIC_API_KEY` にAPIキーが設定されていない場合に送出する例外。"""
    +    """APIキーが資格情報ストアにも環境変数 `ANTHROPIC_API_KEY` にも無い場合に送出する例外。"""
    +
    +
    +class ExternalAiDisabledError(AiOcrError):
    +    """ローカル完結モード(外部AIを許可していない)のまま送信しようとした場合の例外(第10回)。"""
     
     
     class AiResponseFormatError(AiOcrError):
    @@ -132,27 +143,43 @@ class PreparedImage:
     
     
     def get_api_key(environ: dict[str, str] | None = None) -> str:
    -    """環境変数 `ANTHROPIC_API_KEY` からAPIキーを読む。
    +    """APIキーを「資格情報ストア → 環境変数(開発用)」の順に探す(第10回から)。
     
    -    未設定・空白だけの場合は、分かりやすいメッセージで `AiApiKeyMissingError`(キーの値は含めない)。
    +    どちらにも無ければ、分かりやすいメッセージで `AiApiKeyMissingError`(キーの値は含めない)。
         """
    -    env = os.environ if environ is None else environ
    -    key = env.get(ENV_API_KEY, "").strip()
    -    if not key:
    +    resolved = load_api_key(environ)
    +    if resolved is None:
             raise AiApiKeyMissingError(
    -            f"外部AIのAPIキーが設定されていません。環境変数 {ENV_API_KEY} にAPIキーを設定してから"
    -            "アプリを起動し直してください(キーはコードや設定ファイルに書かないでください)。"
    +            "外部AIのAPIキーが設定されていません。「設定...」画面でAPIキーを保存してください"
    +            f"(開発時は環境変数 {ENV_API_KEY} でも可。キーはコードや設定ファイルに書かないでください)。"
                 "外部AIを使わない場合は、読み取り方式を「ローカル」に戻してください。"
             )
    -    return key
    +    return resolved.value
     
     
    -def resolve_model(environ: dict[str, str] | None = None) -> str:
    -    """使用するモデルIDを返す(環境変数 `MADORI_OCR_AI_MODEL` があればそれ、無ければ既定)。"""
    +def resolve_model(environ: dict[str, str] | None = None, *, settings: AppSettings | None = None) -> str:
    +    """使用するモデルIDを返す。設定画面のモデルID → 環境変数 `MADORI_OCR_AI_MODEL` → 既定の順。"""
    +    if settings is not None and settings.ai_model.strip():
    +        return settings.ai_model.strip()
         env = os.environ if environ is None else environ
         return env.get(ENV_MODEL, "").strip() or DEFAULT_AI_MODEL
     
     
    +def ensure_external_ai_allowed(settings: AppSettings) -> None:
    +    """設定が「外部AIを許可」でなければ `ExternalAiDisabledError`(通信の前に必ず呼ぶ)。
    +
    +    画面の選択肢を無効にするだけでは、画面の作り間違いや別の呼び出し口(一括処理など)
    +    から送信されてしまうおそれがある。送信する関数そのものでも止める。
    +    """
    +    if not isinstance(settings, AppSettings):
    +        raise TypeError("settings には AppSettings を渡してください。")
    +    if not settings.external_ai_allowed:
    +        raise ExternalAiDisabledError(
    +            "ローカル完結モードのため、外部AIへは送信できません。外部AIを使う場合は、"
    +            "「設定...」画面で読み取りモードを「外部AIを許可」に切り替えてください。"
    +        )
    +
    +
     def create_client(api_key: str) -> anthropic.Anthropic:
         """Anthropic公式SDKのクライアントを作る(タイムアウトと自動リトライ回数を明示)。"""
         return anthropic.Anthropic(api_key=api_key, timeout=DEFAULT_TIMEOUT_SECONDS, max_retries=DEFAULT_MAX_RETRIES)
    @@ -283,6 +310,7 @@ def _parse_bbox(raw: Any, image_width: int, image_height: int) -> tuple[float, f
     def ai_ocr_image(
         image: Image.Image,
         *,
    +    settings: AppSettings,
         base_scale: float,
         page_number: int = 0,
         client: Any | None = None,
    @@ -291,14 +319,18 @@ def ai_ocr_image(
     ) -> AiOcrResult:
         """画像を外部AIに送り、部屋名を読み取って `AiOcrResult` を返す。
     
    -    `client` を省略すると、環境変数のAPIキーで `create_client()` を呼ぶ
    -    (キーが無ければ、通信する前に `AiApiKeyMissingError`)。テストでは
    +    最初に `settings` を確認し、ローカル完結モードなら何もせず `ExternalAiDisabledError`
    +    (第10回。`client` を渡した場合も同じ)。
    +    `client` を省略すると、資格情報ストア(無ければ環境変数)のAPIキーで `create_client()` を
    +    呼ぶ(キーが無ければ、通信する前に `AiApiKeyMissingError`)。テストでは
         `messages.create()` を持つダミーを渡す。
         APIのエラーは種類ごとに分かりやすい日本語メッセージの `AiOcrError` に変換する。
    +    メッセージにAPIキーらしい文字列が混ざっていれば伏せ字にする。
         """
    +    ensure_external_ai_allowed(settings)
         if client is None:
             client = create_client(get_api_key())
    -    used_model = model or resolve_model()
    +    used_model = model or resolve_model(settings=settings)
         prepared = prepare_image(image, base_scale=base_scale, max_long_edge=max_long_edge)
         request = build_request(prepared, model=used_model)
     
    @@ -306,18 +338,21 @@ def ai_ocr_image(
         try:
             response = client.messages.create(**request)
         except anthropic.AuthenticationError as exc:  # 401
    -        raise AiOcrError(f"APIキーが無効です。環境変数 {ENV_API_KEY} の値を確認してください。") from exc
    +        raise AiOcrError(
    +            f"APIキーが無効です。「設定...」画面で保存したAPIキー(開発時は環境変数 {ENV_API_KEY})を確認してください。"
    +        ) from exc
         except anthropic.PermissionDeniedError as exc:  # 403
             raise AiOcrError("このAPIキーには、このモデル・機能を使う権限がありません。") from exc
         except anthropic.NotFoundError as exc:  # 404
             raise AiOcrError(
    -            f"モデル '{used_model}' が見つかりません。環境変数 {ENV_MODEL} のモデルIDを"
    +            f"モデル '{used_model}' が見つかりません。「設定...」画面のモデルID(開発時は環境変数 {ENV_MODEL})を"
                 "公式ドキュメントで確認してください。"
             ) from exc
         except anthropic.RateLimitError as exc:  # 429(SDKの自動リトライ後もなお失敗)
             raise AiOcrError("APIの利用上限(レート制限)に達しました。しばらく待ってから再実行してください。") from exc
         except anthropic.APIStatusError as exc:  # その他のHTTPエラー(400・5xxなど)
    -        raise AiOcrError(f"外部AIの呼び出しに失敗しました(HTTP {exc.status_code}): {exc.message}") from exc
    +        detail = redact_secrets(str(exc.message))  # 応答のメッセージにキーらしい文字列があれば伏せる
    +        raise AiOcrError(f"外部AIの呼び出しに失敗しました(HTTP {exc.status_code}): {detail}") from exc
         except anthropic.APIConnectionError as exc:  # 通信エラー・タイムアウト
             raise AiOcrError("外部AIに接続できませんでした。ネットワーク接続・プロキシ設定を確認してください。") from exc
         elapsed = time.perf_counter() - started
    @@ -346,6 +381,7 @@ def ai_ocr_pdf_page(
         document: PdfDocument,
         page_number: int,
         *,
    +    settings: AppSettings,
         dpi: int = DEFAULT_DPI,
         client: Any | None = None,
         model: str | None = None,
    @@ -356,13 +392,15 @@ def ai_ocr_pdf_page(
         画像化は第4回のOCRと同じく `PdfDocument.render_page(zoom=1.0)` を再利用する
         (プレビューの拡大率に結果が左右されないようにするため)。
         """
    +    ensure_external_ai_allowed(settings)  # 画像化の前に止める
         rendered = document.render_page(page_number, zoom=1.0, dpi=dpi)
    -    return ai_ocr_rendered_page(rendered, client=client, model=model, max_long_edge=max_long_edge)
    +    return ai_ocr_rendered_page(rendered, settings=settings, client=client, model=model, max_long_edge=max_long_edge)
     
     
     def ai_ocr_rendered_page(
         rendered: RenderedPage,
         *,
    +    settings: AppSettings,
         client: Any | None = None,
         model: str | None = None,
         max_long_edge: int = DEFAULT_MAX_LONG_EDGE,
    @@ -376,6 +414,7 @@ def ai_ocr_rendered_page(
         base_scale = (rendered.dpi / 72.0) * rendered.zoom
         return ai_ocr_image(
             image,
    +        settings=settings,
             base_scale=base_scale,
             page_number=rendered.page_number,
             client=client,

    メイン画面には「設定…」ボタンと、設定を画面に反映する処理を追加します。

    app/ui/main_window.py に次の変更を加えます(+ が追加、- が削除)。

    app/ui/main_window.py の差分(227行)
    --- a/app/ui/main_window.py
    +++ b/app/ui/main_window.py
    @@ -39,6 +39,13 @@ AI(Anthropic Claude)へ送り、部屋名だけをJSONで受け取る。送
       いまはPyMuPDFでの画像化(短時間)だけをこの画面のスレッドで行い、OCR・外部AIの
       呼び出しを別スレッドへ渡す。処理中は進捗バーを動かし、「中止」を押せる。
       画面(ウィジェット)の更新は、結果が戻ってきたあとにこの画面のスレッドでだけ行う。
    +第10回では、「設定...」ボタンから設定画面(`app/ui/settings_dialog.py`)を開けるようにした。
    +設定(`app/core/settings.py`。ユーザーの設定フォルダの settings.json)の読み取りモードが
    +「ローカル完結」(既定)のあいだは、読み取り方式の「外部AI」を選べない(無効化)。
    +外部AIのAPIキーは、設定画面で保存したOSの資格情報ストア(Windowsでは資格情報
    +マネージャー)→ 環境変数 `ANTHROPIC_API_KEY`(開発用)の順に探す。送信する関数
    +(`ai_ocr_rendered_page()`)にも設定を渡し、コア側でもローカル完結なら送信を止める。
    +起動時に読み込む転記の設定ファイルも設定画面で指定できる。
     """
     
     from __future__ import annotations
    @@ -77,6 +84,14 @@ from app.core.ocr_ai import (
         get_api_key,
         resolve_model,
     )
    +from app.core.settings import (
    +    AppSettings,
    +    SettingsError,
    +    default_settings_path,
    +    load_settings,
    +    redact_secrets,
    +    save_settings,
    +)
     from app.core.ocr_local import OcrError, is_tesseract_available, ocr_rendered_page
     from app.core.pdf_loader import PdfDocument, PdfLoadError
     from app.core.review_model import ReviewedRoom, ReviewError, ReviewList
    @@ -85,6 +100,7 @@ from app.core.text_extractor import ExtractedWord, extract_words
     from app.ui.batch_dialog import open_batch_dialog
     from app.ui.preview_canvas import PreviewCanvas
     from app.ui.review_dialog import open_review_dialog
    +from app.ui.settings_dialog import open_settings_dialog
     
     WINDOW_TITLE = "間取りOCR転記ツール"
     WINDOW_SIZE = "760x980"
    @@ -100,6 +116,10 @@ MAPPING_NOT_SELECTED = "未選択(既定:シート「部屋一覧」のC5か
     READ_MODE_LOCAL = "local"
     READ_MODE_AI = "ai"
     
    +#: 読み取り方式「外部AI」の表示(第10回:設定で許可していないときは選べない)
    +AI_RADIO_TEXT_ALLOWED = "外部AI(Claude。図面画像を送信)"
    +AI_RADIO_TEXT_DISABLED = "外部AI(設定で無効:ローカル完結)"
    +
     #: 検出に使った方式ごとの、ステータス行に添える説明
     _SOURCE_NOTES = {"embedded": "", "ocr": "(OCRで検出)", "ai": "(外部AIで検出)"}
     
    @@ -117,6 +137,15 @@ class MainWindow(ttk.Frame):
             # 読み取り方式。既定は必ずローカル(外部AIは利用者が明示的に選んだときだけ使う)
             self.read_mode_var = tk.StringVar(value=READ_MODE_LOCAL)
     
    +        # アプリの設定(第10回)。読めなければ既定(ローカル完結)で起動する
    +        self.settings_path = default_settings_path()
    +        settings_error: str | None = None
    +        try:
    +            self.settings = load_settings(self.settings_path)
    +        except SettingsError as exc:
    +            self.settings = AppSettings()
    +            settings_error = str(exc)
    +
             # 直近に「4.」で絞り込んだ結果(第6回の確認画面へ渡す)と、確認画面で確定した一覧
             self._last_detection: tuple[list[ExtractedWord], list[RoomCandidate], str, int] | None = None
             self.reviewed_rooms: list[ReviewedRoom] | None = None
    @@ -142,10 +171,18 @@ class MainWindow(ttk.Frame):
                 self._room_dictionary_error = None
     
             self._build_widgets()
    +        self._apply_settings()
             self._refresh_run_button()
             if self._room_dictionary is None:
                 self.filter_room_button.configure(state="disabled")
                 messagebox.showerror("部屋名辞書エラー", self._room_dictionary_error)
    +        if settings_error is not None:
    +            messagebox.showwarning(
    +                "設定ファイルを読み込めません",
    +                settings_error,
    +                detail="既定の設定(ローカル完結モード)で起動します。「設定...」から保存し直してください。",
    +            )
    +        self._load_default_mapping()
     
         def _build_widgets(self) -> None:
             self.columnconfigure(0, weight=1)
    @@ -181,16 +218,20 @@ class MainWindow(ttk.Frame):
             ttk.Label(mode_frame, text="読み取り方式:").pack(side="left")
             ttk.Radiobutton(
                 mode_frame,
    -            text="ローカル(埋め込み文字→OCR。社外に送信しない)",
    +            text="ローカル(社外に送信しない)",
                 variable=self.read_mode_var,
                 value=READ_MODE_LOCAL,
             ).pack(side="left")
    -        ttk.Radiobutton(
    +        self.ai_radio = ttk.Radiobutton(
                 mode_frame,
    -            text="外部AI(Claude。図面画像を送信)",
    +            text=AI_RADIO_TEXT_ALLOWED,
                 variable=self.read_mode_var,
                 value=READ_MODE_AI,
    -        ).pack(side="left", padx=(8, 0))
    +        )
    +        self.ai_radio.pack(side="left", padx=(8, 0))
    +        # 第10回:設定画面(読み取りモード・APIキー・モデルID・起動時の転記設定ファイル)
    +        self.settings_button = ttk.Button(mode_frame, text="設定...", command=self._on_open_settings)
    +        self.settings_button.pack(side="right", padx=(0, 8))
     
             self.detect_text_button = ttk.Button(
                 self,
    @@ -350,6 +391,7 @@ class MainWindow(ttk.Frame):
             self.batch_button.configure(
                 state=normal_if[self.selected.excel_path is not None and not busy and self._room_dictionary is not None]
             )
    +        self.settings_button.configure(state=normal_if[not busy])
             if busy:
                 self.run_button.configure(state="disabled")
             else:
    @@ -401,7 +443,8 @@ class MainWindow(ttk.Frame):
                 if isinstance(exc, (AiOcrError, OcrError, PdfLoadError)):
                     messagebox.showerror(error_title, str(exc))
                 else:
    -                messagebox.showerror("予期しないエラー", f"{type(exc).__name__}: {exc}")
    +                # 想定外の例外のメッセージにAPIキーらしい文字列が混ざっていても画面に出さない
    +                messagebox.showerror("予期しないエラー", redact_secrets(f"{type(exc).__name__}: {exc}"))
                 self.status_var.set("読み取りに失敗しました。")
     
             self._job = BackgroundJob(work, schedule=self.after, on_done=done, on_error=error)
    @@ -435,6 +478,15 @@ class MainWindow(ttk.Frame):
                 return
             page_number = self.preview.page_number
             if self.read_mode_var.get() == READ_MODE_AI:
    +            if not self.settings.external_ai_allowed:
    +                # 選択肢は無効化しているが、念のためここでも止める(コア側でも止まる)
    +                self.read_mode_var.set(READ_MODE_LOCAL)
    +                messagebox.showerror(
    +                    "外部AIは使えません",
    +                    "ローカル完結モードのため、外部AIへは送信できません。",
    +                    detail="外部AIを使う場合は「設定...」で読み取りモードを「外部AIを許可」にしてください。",
    +                )
    +                return
                 self._start_ai_detection(document, page_number, on_detected)
                 return
     
    @@ -469,7 +521,7 @@ class MainWindow(ttk.Frame):
         ) -> None:
             """表示中のページを外部AIに送り、部屋名を読み取る(第5回。第9回から別スレッドで通信する)。
     
    -        1. APIキー(環境変数 `ANTHROPIC_API_KEY`)が無ければ、送信確認より前にエラーを表示して終わる
    +        1. APIキー(資格情報ストア→環境変数。第10回)が無ければ、送信確認より前にエラーを表示して終わる
                (確認ダイアログで「OK」を押させてから失敗させないため)。
             2. 「図面画像を外部サービスへ送信します」という確認ダイアログを毎回出す。
                「キャンセル」なら何も送信せずに終わる。
    @@ -481,7 +533,8 @@ class MainWindow(ttk.Frame):
                 messagebox.showerror("外部AIの設定エラー", str(exc))
                 return
     
    -        model = resolve_model()
    +        settings = self.settings  # 送信までに設定が変わっても、確認した時点の設定で送る
    +        model = resolve_model(settings=settings)
             if not messagebox.askokcancel(
                 SEND_CONFIRMATION_TITLE,
                 SEND_CONFIRMATION_TITLE,
    @@ -499,7 +552,7 @@ class MainWindow(ttk.Frame):
                 return
             client = self._create_ai_client(api_key)
             self._run_in_background(
    -            lambda _job: ai_ocr_rendered_page(rendered, client=client, model=model).words,
    +            lambda _job: ai_ocr_rendered_page(rendered, settings=settings, client=client, model=model).words,
                 message="外部AIで読み取っています(通信中)...「中止」で結果を捨てられます",
                 on_done=lambda words: self._deliver_detection(document, page_number, words, "ai", on_detected),
                 error_title="外部AIエラー",
    @@ -523,6 +576,54 @@ class MainWindow(ttk.Frame):
             """外部AIのクライアントを作る(スクリーンショット撮影時などに差し替えられるよう分けている)。"""
             return create_client(api_key)
     
    +    # --- 設定(第10回) ------------------------------------------------------------
    +
    +    def _apply_settings(self) -> None:
    +        """設定を画面に反映する。ローカル完結モードなら「外部AI」の選択肢を無効にし、ローカルに戻す。"""
    +        if self.settings.external_ai_allowed:
    +            self.ai_radio.configure(state="normal", text=AI_RADIO_TEXT_ALLOWED)
    +        else:
    +            self.ai_radio.configure(state="disabled", text=AI_RADIO_TEXT_DISABLED)
    +            self.read_mode_var.set(READ_MODE_LOCAL)
    +
    +    def _load_default_mapping(self) -> None:
    +        """設定画面で指定した「起動時に読み込む転記の設定ファイル」を読み込む(無ければ何もしない)。"""
    +        path = self.settings.default_mapping_path
    +        if not path:
    +            return
    +        try:
    +            config = load_mapping_config(path, self._room_dictionary)
    +        except MappingError as exc:
    +            messagebox.showwarning(
    +                "既定の転記設定ファイルを読み込めません",
    +                str(exc),
    +                detail="第7回と同じ既定の対応付けで起動します。「設定...」または「2-2.」で選び直してください。",
    +            )
    +            return
    +        self.mapping_config = config
    +        self.mapping_path_var.set(f"{path}({len(config.templates)}種類のテンプレートの設定・起動時に読み込み)")
    +        self._refresh_mapping_status()
    +
    +    def _on_open_settings(self) -> None:
    +        """「設定...」ボタン。設定画面で「OK」なら保存して画面に反映する。"""
    +        if self._job is not None:
    +            return
    +        new_settings = open_settings_dialog(self, settings=self.settings, settings_path=self.settings_path)
    +        if new_settings is None:
    +            return
    +        try:
    +            save_settings(new_settings, self.settings_path)
    +        except SettingsError as exc:
    +            messagebox.showerror("設定を保存できません", str(exc))
    +            return
    +        mapping_changed = new_settings.default_mapping_path != self.settings.default_mapping_path
    +        self.settings = new_settings
    +        self._apply_settings()
    +        if mapping_changed:
    +            self._load_default_mapping()
    +        mode = "外部AIを許可" if new_settings.external_ai_allowed else "ローカル完結"
    +        self.status_var.set(f"設定を保存しました(読み取りモード:{mode})。")
    +
         def _on_detect_text(self) -> None:
             """表示中のページの文字を検出し、検出枠をプレビューに重ねて表示する。
     

    .env.example に次の変更を加えます(+ が追加、- が削除)。

    --- a/.env.example
    +++ b/.env.example
    @@ -1,6 +1,9 @@
     # .env.example
     # 外部AIモード(第5回〜)で使う環境変数の例。実際の値はこのファイルに書かず、
     # OSの環境変数として設定してください(このファイルはキー名の一覧です)。
    +# 第10回から、APIキーはアプリの「設定...」画面でOSの資格情報ストア(Windowsでは
    +# 資格情報マネージャー。keyring経由)に保存します。環境変数は、資格情報ストアに
    +# 保存が無いときだけ使う開発用の手段です。モデルIDも設定画面の値が優先されます。
     
     # Anthropic のAPIキー(Claude Console で発行)。値はコミットしないこと
     ANTHROPIC_API_KEY=

    すべてのテストで、keyringをメモリ上の実装に差し替える共通設定です(開発者のPCの本物の資格情報に触れないため)。tests フォルダに置くと、pytestが自動で読み込みます。

    tests/conftest.py を新しく作ります(全文)。

    # tests/conftest.py
    """pytest全体の共通設定(第10回)。
    
    APIキーの保存先(keyring)は、実行するPCのOSの資格情報ストアにつながる。
    テストが開発者の本物の資格情報を読んだり書き換えたりしないよう、すべてのテストで
    keyring のバックエンドをメモリ上の実装に差し替える(`keyring.set_keyring()`)。
    Linuxのサーバー・CIのように資格情報ストアが使えない環境でも同じように動く。
    """
    
    from __future__ import annotations
    
    from collections.abc import Iterator
    
    import keyring
    import keyring.backend
    import keyring.errors
    import pytest
    
    
    class MemoryKeyring(keyring.backend.KeyringBackend):
        """テスト用:パスワードを辞書に持つだけのkeyringバックエンド(プロセス終了で消える)。"""
    
        priority = 1  # type: ignore[assignment]
    
        def __init__(self) -> None:
            super().__init__()
            self.passwords: dict[tuple[str, str], str] = {}
    
        def get_password(self, service: str, username: str) -> str | None:
            return self.passwords.get((service, username))
    
        def set_password(self, service: str, username: str, password: str) -> None:
            self.passwords[(service, username)] = password
    
        def delete_password(self, service: str, username: str) -> None:
            if (service, username) not in self.passwords:
                raise keyring.errors.PasswordDeleteError("not found")
            del self.passwords[(service, username)]
    
    
    @pytest.fixture(autouse=True)
    def memory_keyring(monkeypatch: pytest.MonkeyPatch) -> Iterator[MemoryKeyring]:
        """すべてのテストで、keyringをメモリ上の実装に差し替え、開発用の環境変数も外す。"""
        monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)
        previous = keyring.get_keyring()
        backend = MemoryKeyring()
        keyring.set_keyring(backend)
        try:
            yield backend
        finally:
            keyring.set_keyring(previous)

    設定の保存・読み込みとAPIキーの扱いのテストです。

    tests/test_settings.py を新しく作ります(全文)。

    tests/test_settings.py の全文(325行)
    # tests/test_settings.py
    """`app/core/settings.py` のテスト(第10回)。
    
    keyring のバックエンドは `tests/conftest.py` でメモリ上の実装に差し替えている
    (OSの資格情報ストアには触れない)。APIキーはすべて架空の値。
    """
    
    from __future__ import annotations
    
    import ast
    import json
    import logging
    from pathlib import Path
    
    import keyring
    import keyring.backend
    import keyring.errors
    import pytest
    from keyring.backends import fail as keyring_fail
    
    from app.core import settings as settings_module
    from app.core.settings import (
        ENV_API_KEY,
        KEYRING_SERVICE,
        KEYRING_USERNAME,
        MASKED_KEY,
        MODE_EXTERNAL_AI,
        MODE_LOCAL,
        SOURCE_ENV,
        SOURCE_KEYRING,
        ApiKeyStoreError,
        AppSettings,
        ResolvedApiKey,
        SettingsError,
        api_key_status,
        default_settings_dir,
        delete_api_key,
        describe_api_key_status,
        is_keyring_available,
        load_api_key,
        load_settings,
        redact_secrets,
        save_api_key,
        save_settings,
        validate_model_id,
    )
    
    #: 架空のAPIキー(実在しない。伏せ字処理を確かめるため先頭だけAnthropicのキーと同じ「sk-ant-」にしている)
    FAKE_KEY = "sk-ant-" + "FAKE-NOT-A-REAL-KEY"
    
    CODE_DIR = Path(__file__).resolve().parents[1]
    
    
    # --- 既定値と保存先 ------------------------------------------------------------------
    
    
    def test_default_is_local_mode() -> None:
        settings = AppSettings()
        assert settings.read_mode == MODE_LOCAL
        assert settings.external_ai_allowed is False
    
    
    def test_missing_file_gives_local_mode(tmp_path: Path) -> None:
        assert load_settings(tmp_path / "none" / "settings.json") == AppSettings()
    
    
    @pytest.mark.parametrize(
        ("platform", "environ", "expected"),
        [
            ("win32", {"APPDATA": r"C:\Users\taro\AppData\Roaming"}, Path(r"C:\Users\taro\AppData\Roaming") / "MadoriOCR"),
            ("win32", {}, Path("/home/taro") / "AppData" / "Roaming" / "MadoriOCR"),
            ("darwin", {}, Path("/home/taro") / "Library" / "Application Support" / "MadoriOCR"),
            ("linux", {"XDG_CONFIG_HOME": "/xdg"}, Path("/xdg") / "madori-ocr"),
            ("linux", {}, Path("/home/taro") / ".config" / "madori-ocr"),
        ],
    )
    def test_default_settings_dir_per_os(platform: str, environ: dict[str, str], expected: Path) -> None:
        assert default_settings_dir(platform, environ, Path("/home/taro")) == expected
    
    
    # --- 設定ファイルの読み書き ------------------------------------------------------------
    
    
    def test_save_and_load_round_trip(tmp_path: Path) -> None:
        path = tmp_path / "MadoriOCR" / "settings.json"
        original = AppSettings(
            read_mode=MODE_EXTERNAL_AI,
            ai_model="claude-haiku-4-5-20251001",
            default_mapping_path="C:/設定/mapping.yaml",
        )
        saved = save_settings(original, path)
        assert saved == path and path.exists()
        assert load_settings(path) == original
        data = json.loads(path.read_text(encoding="utf-8"))
        assert data == {
            "version": 1,
            "read_mode": "external_ai",
            "ai_model": "claude-haiku-4-5-20251001",
            "default_mapping_path": "C:/設定/mapping.yaml",
        }
        assert [p.name for p in path.parent.iterdir()] == ["settings.json"]  # 一時ファイルが残らない
    
    
    def test_settings_file_never_contains_api_key(tmp_path: Path) -> None:
        save_api_key(FAKE_KEY)
        path = save_settings(AppSettings(read_mode=MODE_EXTERNAL_AI), tmp_path / "settings.json")
        text = path.read_text(encoding="utf-8")
        assert FAKE_KEY not in text
        assert "key" not in json.loads(text)  # APIキー用の項目そのものが無い
        assert "api_key" not in AppSettings.__dataclass_fields__
    
    
    def test_unknown_keys_are_ignored_and_not_used(tmp_path: Path) -> None:
        path = tmp_path / "settings.json"
        path.write_text(json.dumps({"version": 1, "read_mode": "local", "api_key": FAKE_KEY, "future": 1}), "utf-8")
        assert load_settings(path) == AppSettings()
    
    
    def test_load_accepts_utf8_bom(tmp_path: Path) -> None:
        path = tmp_path / "settings.json"
        path.write_bytes(b"\xef\xbb\xbf" + json.dumps({"read_mode": "external_ai"}).encode("utf-8"))
        assert load_settings(path).external_ai_allowed
    
    
    @pytest.mark.parametrize(
        ("content", "message"),
        [
            (b"{ broken", "壊れています"),
            (b"[1, 2]", "オブジェクト"),
            ('{"read_mode": "cloud"}'.encode(), "読み取りモード"),
            (b'{"read_mode": true}', "文字列"),
            (b'{"version": 2}', "版"),
            ('{"ai_model": "モデル"}'.encode(), "モデルID"),
            ('{"x": "寝室"}'.encode("shift_jis"), "UTF-8"),
        ],
    )
    def test_broken_settings_raise_clear_error(tmp_path: Path, content: bytes, message: str) -> None:
        path = tmp_path / "settings.json"
        path.write_bytes(content)
        with pytest.raises(SettingsError, match=message):
            load_settings(path)
    
    
    def test_too_large_settings_file_is_rejected(tmp_path: Path) -> None:
        path = tmp_path / "settings.json"
        path.write_text('{"ai_model": "' + "a" * 70_000 + '"}', "utf-8")
        with pytest.raises(SettingsError, match="大きすぎます"):
            load_settings(path)
    
    
    def test_save_rejects_invalid_mode(tmp_path: Path) -> None:
        with pytest.raises(SettingsError):
            save_settings(AppSettings(read_mode="cloud"), tmp_path / "settings.json")
        assert not (tmp_path / "settings.json").exists()
    
    
    @pytest.mark.parametrize("value", ["", "  ", "claude-haiku-4-5-20251001", "claude-haiku-4-5", " claude-x "])
    def test_validate_model_id_accepts(value: str) -> None:
        assert validate_model_id(value) == value.strip()
    
    
    @pytest.mark.parametrize("value", ["claude haiku", "claude;rm", "a" * 101, "モデル"])
    def test_validate_model_id_rejects(value: str) -> None:
        with pytest.raises(SettingsError):
            validate_model_id(value)
    
    
    def test_api_key_in_model_field_is_rejected_without_echo(tmp_path: Path) -> None:
        """モデルIDの欄にAPIキーを貼っても、設定ファイルに平文で残らず、メッセージにも出ない。"""
        with pytest.raises(SettingsError) as excinfo:
            save_settings(AppSettings(ai_model=FAKE_KEY), tmp_path / "settings.json")
        assert "APIキー" in str(excinfo.value)
        assert FAKE_KEY not in str(excinfo.value)
        assert not (tmp_path / "settings.json").exists()
    
    
    # --- APIキー(keyring) -------------------------------------------------------------
    
    
    def test_save_and_load_api_key_uses_keyring(memory_keyring: object) -> None:
        save_api_key(f"  {FAKE_KEY}  ")
        assert keyring.get_password(KEYRING_SERVICE, KEYRING_USERNAME) == FAKE_KEY
        resolved = load_api_key({})
        assert resolved is not None
        assert (resolved.value, resolved.source) == (FAKE_KEY, SOURCE_KEYRING)
    
    
    def test_keyring_is_preferred_over_environment() -> None:
        save_api_key(FAKE_KEY)
        resolved = load_api_key({ENV_API_KEY: "dummy-env-key"})
        assert resolved is not None and resolved.source == SOURCE_KEYRING
    
    
    def test_environment_is_used_when_keyring_is_empty() -> None:
        resolved = load_api_key({ENV_API_KEY: "  dummy-env-key  "})
        assert resolved is not None
        assert (resolved.value, resolved.source) == ("dummy-env-key", SOURCE_ENV)
        assert load_api_key({}) is None
        assert load_api_key({ENV_API_KEY: "   "}) is None
    
    
    def test_delete_api_key() -> None:
        save_api_key(FAKE_KEY)
        assert delete_api_key() is True
        assert load_api_key({}) is None
        assert delete_api_key() is False  # 2回目は「保存されていない」
    
    
    def test_blank_stored_value_is_treated_as_missing(memory_keyring: object) -> None:
        keyring.set_password(KEYRING_SERVICE, KEYRING_USERNAME, "  ")
        assert load_api_key({}) is None
    
    
    @pytest.mark.parametrize("value", ["", "   ", "sk-ant key", "sk-ant\nkey", "k" * 513])
    def test_invalid_api_key_is_rejected_without_echo(value: str) -> None:
        with pytest.raises(ApiKeyStoreError) as excinfo:
            save_api_key(value)
        if value.strip():
            assert value.strip() not in str(excinfo.value)
        assert keyring.get_password(KEYRING_SERVICE, KEYRING_USERNAME) is None
    
    
    def test_resolved_api_key_repr_and_str_are_masked() -> None:
        resolved = ResolvedApiKey(FAKE_KEY, SOURCE_KEYRING)
        assert FAKE_KEY not in repr(resolved)
        assert FAKE_KEY not in str(resolved)
        assert MASKED_KEY in str(resolved)
    
    
    def test_status_and_description_never_show_key() -> None:
        assert describe_api_key_status(api_key_status({})) == "未設定"
        env_status = api_key_status({ENV_API_KEY: FAKE_KEY})
        assert env_status.env_set and not env_status.stored
        assert ENV_API_KEY in describe_api_key_status(env_status)
        save_api_key(FAKE_KEY)
        status = api_key_status({})
        text = describe_api_key_status(status)
        assert status.stored and "保存済み" in text
        assert FAKE_KEY not in text and FAKE_KEY[-4:] not in text  # 末尾の数文字も出さない
        assert FAKE_KEY not in repr(status)
    
    
    def test_redact_secrets() -> None:
        assert FAKE_KEY not in redact_secrets(f"error: {FAKE_KEY}")
        assert redact_secrets("value=abc123", "abc123") == f"value={MASKED_KEY}"
        assert redact_secrets("ふつうの文章") == "ふつうの文章"
    
    
    # --- 資格情報ストアが使えない・失敗する環境 ---------------------------------------------
    
    
    class LeakyFailingKeyring(keyring.backend.KeyringBackend):
        """保存・削除に失敗し、エラーメッセージに渡された値をそのまま含めてしまうバックエンド。"""
    
        priority = 1  # type: ignore[assignment]
    
        def get_password(self, service: str, username: str) -> str | None:
            raise RuntimeError(f"cannot read {service}/{username}")
    
        def set_password(self, service: str, username: str, password: str) -> None:
            raise keyring.errors.PasswordSetError(f"failed to store {password}")
    
        def delete_password(self, service: str, username: str) -> None:
            raise RuntimeError("backend is locked")
    
    
    def test_no_keyring_backend_falls_back_to_environment() -> None:
        """Linuxのサーバー等(使えるバックエンドが無い)では、保存はできず環境変数だけを使う。"""
        keyring.set_keyring(keyring_fail.Keyring())
        assert is_keyring_available() is False
        with pytest.raises(ApiKeyStoreError, match="資格情報ストアが使えない"):
            save_api_key(FAKE_KEY)
        assert delete_api_key() is False
        resolved = load_api_key({ENV_API_KEY: "dummy-env-key"})
        assert resolved is not None and resolved.source == SOURCE_ENV
        status = api_key_status({})
        assert status.store_available is False
        assert "資格情報ストアを使えません" in describe_api_key_status(status)
    
    
    def test_backend_errors_do_not_leak_key_to_message_or_logs(caplog: pytest.LogCaptureFixture) -> None:
        keyring.set_keyring(LeakyFailingKeyring())
        caplog.set_level(logging.DEBUG, logger="app.core.settings")
        with pytest.raises(ApiKeyStoreError) as excinfo:
            save_api_key(FAKE_KEY)
        error = excinfo.value
        assert FAKE_KEY not in str(error)
        assert "PasswordSetError" in str(error)
        # 元の例外(メッセージにキーを含む)を連結していない
        assert error.__cause__ is None and error.__suppress_context__ is True
        with pytest.raises(ApiKeyStoreError, match="RuntimeError"):
            delete_api_key()
        assert load_api_key({ENV_API_KEY: "dummy-env-key"}) is not None  # 読み込みに失敗しても環境変数へ進む
        assert FAKE_KEY not in caplog.text
    
    
    def test_logs_never_contain_api_key(caplog: pytest.LogCaptureFixture, tmp_path: Path) -> None:
        caplog.set_level(logging.DEBUG)
        save_api_key(FAKE_KEY)
        resolved = load_api_key({})
        status = api_key_status({})
        save_settings(AppSettings(read_mode=MODE_EXTERNAL_AI), tmp_path / "settings.json")
        delete_api_key()
        load_api_key({ENV_API_KEY: FAKE_KEY})
        logging.getLogger("test").info("読み込み結果: %r %s %r", resolved, resolved, status)
        assert caplog.records  # ログ自体は出ている
        assert FAKE_KEY not in caplog.text
    
    
    def test_settings_module_does_not_import_gui() -> None:
        tree = ast.parse((CODE_DIR / "app" / "core" / "settings.py").read_text(encoding="utf-8"))
        imported = {
            alias.name.split(".")[0]
            for node in ast.walk(tree)
            if isinstance(node, (ast.Import, ast.ImportFrom))
            for alias in (node.names if isinstance(node, ast.Import) else [ast.alias(node.module or "")])
        }
        assert "tkinter" not in imported
    
    
    def test_batch_processing_never_calls_external_ai() -> None:
        """一括処理(第9回)はローカルだけで読み取る。外部AIのモジュールを参照していないことを確かめる。"""
        source = (CODE_DIR / "app" / "core" / "batch.py").read_text(encoding="utf-8")
        assert "ocr_ai" not in source
        assert settings_module.MODE_LOCAL == "local"

    外部AIのテストは、送信する関数に設定を渡す形に直し、ローカル完結で止まることなどのテストを足します。

    tests/test_ocr_ai.py に次の変更を加えます(+ が追加、- が削除)。

    tests/test_ocr_ai.py の差分(137行)
    --- a/tests/test_ocr_ai.py
    +++ b/tests/test_ocr_ai.py
    @@ -34,6 +34,7 @@ from app.core.ocr_ai import (
         AiApiKeyMissingError,
         AiOcrError,
         AiResponseFormatError,
    +    ExternalAiDisabledError,
         ai_ocr_image,
         ai_ocr_pdf_page,
         build_request,
    @@ -44,6 +45,10 @@ from app.core.ocr_ai import (
         resolve_model,
     )
     from app.core.pdf_loader import PdfDocument
    +from app.core.settings import MODE_EXTERNAL_AI, AppSettings, save_api_key
    +
    +#: 外部AIを許可した設定(第10回から、送信する関数は設定を必ず受け取る)
    +AI_ALLOWED = AppSettings(read_mode=MODE_EXTERNAL_AI)
     
     
     class FakeMessages:
    @@ -133,7 +138,7 @@ def test_ai_ocr_image_sends_one_request_with_resolved_model(monkeypatch: pytest.
         monkeypatch.setenv(ENV_MODEL, "claude-test-model")
         messages = FakeMessages('{"rooms": []}')
     
    -    result = ai_ocr_image(_white_image(), base_scale=1.0, client=FakeClient(messages))
    +    result = ai_ocr_image(_white_image(), settings=AI_ALLOWED, base_scale=1.0, client=FakeClient(messages))
     
         assert len(messages.calls) == 1
         assert messages.calls[0]["model"] == "claude-test-model"
    @@ -215,7 +220,7 @@ def test_parse_normalizes_reversed_bbox() -> None:
     def test_ai_ocr_image_raises_when_response_truncated() -> None:
         messages = FakeMessages('{"rooms": [', stop_reason="max_tokens")
         with pytest.raises(AiResponseFormatError, match="max_tokens"):
    -        ai_ocr_image(_white_image(), base_scale=1.0, client=FakeClient(messages), model="m")
    +        ai_ocr_image(_white_image(), settings=AI_ALLOWED, base_scale=1.0, client=FakeClient(messages), model="m")
     
     
     def test_ai_ocr_pdf_page_returns_words_in_pdf_coordinates(tmp_path: Path) -> None:
    @@ -228,7 +233,7 @@ def test_ai_ocr_pdf_page_returns_words_in_pdf_coordinates(tmp_path: Path) -> Non
         # A4・150dpi(1240×1754px)は長辺1568pxに縮小されて送られる
         messages = FakeMessages('{"rooms": [{"name": "居間", "bbox": [100, 100, 200, 140]}]}')
         with PdfDocument(pdf_path) as document:
    -        result = ai_ocr_pdf_page(document, 0, client=FakeClient(messages), model="m")
    +        result = ai_ocr_pdf_page(document, 0, settings=AI_ALLOWED, client=FakeClient(messages), model="m")
     
         prompt = messages.calls[0]["messages"][0]["content"][1]["text"]
         assert "高さ1568px" in prompt
    @@ -264,7 +269,7 @@ def test_ai_ocr_image_without_client_and_key_fails_before_sending(monkeypatch: p
     
         monkeypatch.setattr(ocr_ai, "create_client", _must_not_be_called)
         with pytest.raises(AiApiKeyMissingError):
    -        ai_ocr_image(_white_image(), base_scale=1.0)
    +        ai_ocr_image(_white_image(), settings=AI_ALLOWED, base_scale=1.0)
     
     
     def test_resolve_model_default_and_override() -> None:
    @@ -289,7 +294,7 @@ def test_resolve_model_default_and_override() -> None:
     def test_api_errors_are_converted_to_readable_messages(error: Exception, expected: str) -> None:
         messages = FakeMessages(error=error)
         with pytest.raises(AiOcrError, match=expected):
    -        ai_ocr_image(_white_image(), base_scale=1.0, client=FakeClient(messages), model="m")
    +        ai_ocr_image(_white_image(), settings=AI_ALLOWED, base_scale=1.0, client=FakeClient(messages), model="m")
     
     
     def test_confirmation_message_mentions_external_send_and_model() -> None:
    @@ -298,3 +303,70 @@ def test_confirmation_message_mentions_external_send_and_model() -> None:
         assert "Claude API" in message
         assert "claude-test" in message
         assert "秘密保持" in message
    +
    +
    +
    +# --- 4. ローカル完結モードでは送信しない(第10回) ---------------------------------
    +
    +
    +def test_local_mode_blocks_sending_even_with_client() -> None:
    +    """設定がローカル完結なら、クライアントを渡されても通信の前に止まる(UIだけに頼らない)。"""
    +    messages = FakeMessages('{"rooms": []}')
    +    with pytest.raises(ExternalAiDisabledError, match="ローカル完結モード"):
    +        ai_ocr_image(_white_image(), settings=AppSettings(), base_scale=1.0, client=FakeClient(messages), model="m")
    +    assert messages.calls == []
    +
    +
    +def test_local_mode_blocks_before_rendering_pdf(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
    +    pdf_path = tmp_path / "blank.pdf"
    +    doc = fitz.open()
    +    doc.new_page(width=200, height=200)
    +    doc.save(pdf_path)
    +    doc.close()
    +    messages = FakeMessages('{"rooms": []}')
    +    with PdfDocument(pdf_path) as document:
    +        rendered: list[int] = []
    +        monkeypatch.setattr(document, "render_page", lambda *a, **k: rendered.append(1))
    +        with pytest.raises(ExternalAiDisabledError):
    +            ai_ocr_pdf_page(document, 0, settings=AppSettings(), client=FakeClient(messages), model="m")
    +    assert rendered == [] and messages.calls == []
    +
    +
    +def test_settings_are_required_to_send() -> None:
    +    messages = FakeMessages('{"rooms": []}')
    +    with pytest.raises(TypeError):
    +        ai_ocr_image(_white_image(), base_scale=1.0, client=FakeClient(messages))  # type: ignore[call-arg]
    +    with pytest.raises(TypeError):
    +        ai_ocr_image(_white_image(), settings=None, base_scale=1.0, client=FakeClient(messages))  # type: ignore[arg-type]
    +    assert messages.calls == []
    +
    +
    +def test_get_api_key_prefers_keyring_over_environment(memory_keyring: object) -> None:
    +    save_api_key("dummy-key-in-keyring")
    +    assert get_api_key({ENV_API_KEY: "dummy-key-in-env"}) == "dummy-key-in-keyring"
    +
    +
    +def test_resolve_model_prefers_settings() -> None:
    +    settings = AppSettings(read_mode=MODE_EXTERNAL_AI, ai_model="claude-from-settings")
    +    assert resolve_model({ENV_MODEL: "claude-from-env"}, settings=settings) == "claude-from-settings"
    +    assert resolve_model({ENV_MODEL: "claude-from-env"}, settings=AppSettings()) == "claude-from-env"
    +
    +
    +def test_ai_ocr_image_uses_model_from_settings() -> None:
    +    messages = FakeMessages('{"rooms": []}')
    +    settings = AppSettings(read_mode=MODE_EXTERNAL_AI, ai_model="claude-from-settings")
    +    result = ai_ocr_image(_white_image(), settings=settings, base_scale=1.0, client=FakeClient(messages))
    +    assert messages.calls[0]["model"] == result.model == "claude-from-settings"
    +
    +
    +def test_api_error_message_does_not_leak_api_key_like_text() -> None:
    +    fake_key = "sk-ant-" + "FAKE-NOT-A-REAL-KEY"  # 架空の値(実在しない)
    +    request = httpx.Request("POST", "https://api.anthropic.com/v1/messages")
    +    error = anthropic.BadRequestError(
    +        f"invalid header: {fake_key}", response=httpx.Response(400, request=request), body=None
    +    )
    +    messages = FakeMessages(error=error)
    +    with pytest.raises(AiOcrError) as excinfo:
    +        ai_ocr_image(_white_image(), settings=AI_ALLOWED, base_scale=1.0, client=FakeClient(messages), model="m")
    +    assert "HTTP 400" in str(excinfo.value)
    +    assert fake_key not in str(excinfo.value)

    動かしてみる

    pytest
    ruff check .
    python -m app.main

    pytest で「352 passed」と表示されれば完了です。アプリを起動した直後は「外部AI」を選べません。「設定…」で読み取りモードを「外部AIを許可」にして「OK」を押すと選べるようになります。設定はWindowsでは %APPDATA%\MadoriOCR\settings.json に保存されます。

    動作確認の方法

    pytest は352件すべて成功しました(第9回までの297件に、設定・APIキー48件と外部AI側の7件を追加)。ruff check . もエラーはありません。

    pip install -r requirements.txt   # keyring==25.7.0 が追加されています
    pytest tests/test_settings.py tests/test_ocr_ai.py

    このLinux開発環境には使える資格情報ストアが無いため、tests/conftest.py でkeyringのバックエンドをメモリ上のテスト用実装に差し替えています(keyring.set_keyring())。開発者のPCでも本物の資格情報には触れません。主に次を確かめています。

    • ローカル完結なら送信関数が通信も画像化もしない
    • APIキーが資格情報ストア→環境変数の順で読まれ、設定ファイルに書かれない
    • エラーに値を含めてしまう架空のバックエンドでも、エラー・ログ(DEBUGまで)に架空のキーが出ない

    次は、設定画面で「外部AIを許可」を選び、APIキーの入力欄に架空の値を入力した状態です(開発環境(Linux)での確認画面です。Windows実機では見た目が異なります)。

    設定画面。読み取りモードで「外部AIを許可」が選ばれ、APIキーの状態は「保存済み(伏せ字)。キーは表示しません」、新しいAPIキーの入力欄は伏せ字で表示されている

    「OK」を押すと、設定ファイルにはAPIキー以外の3項目だけが保存され、メイン画面の「外部AI」が選べるようになることも確認しました。

    確認できていないこと

    • Windowsの資格情報マネージャーでの実際の保存・読み込み・削除。keyring 25.7.0のソースを読むと、サービス名(今回は madori-ocr)を名前とする汎用資格情報として保存する実装ですが、Windows実機では試していません
    • Windows実機での設定画面の見た目、%APPDATA% への保存
    • 実際のClaude APIでの動作(今回もAPIキーは使っていません)

    つまずきやすい点・セキュリティ上の注意

    • 設定の切り替えは「うっかり送信」を防ぐもので、利用者本人の操作は止められない:設定ファイルは利用者が書き換えられます。組織としてオフライン完結を徹底したい場合は、外部AIの機能を含まない版を配布するなど、別の対策が必要です
    • 資格情報ストアに入れれば絶対安全、ではない:keyringの公式ページのセキュリティの注意では、Windows Credential Lockerについて「分析は行われていない」と書かれています(macOSについては、同じPythonから動く別のスクリプトがパスワードの確認なしに読めることが注意として挙がっています)。PC自体の管理(ログインの保護・不審なソフトを入れない)が前提です
    • 環境変数は開発用に限る:環境変数にキーを置いたままにすると、資格情報ストアに保存が無いとき自動で使われます。配布先のPCでは設定しない運用にします
    • テストで本物の資格情報ストアに触れない:keyring.set_keyring() で差し替えないと、開発者のPCの資格情報を書き換えてしまうことがあります
    • ログ・エラー画面にキーを出さない:例外の連結やデバッグ出力から漏れやすいので、キーを持つ値は repr を伏せ、エラーは種類名だけにします

    発注者向けメモ

    「オフラインで完結させたい」か「精度を優先したい」かを、契約時に決めておく

    同じツールでも、ローカル完結(図面を社外に出さない代わりに、スキャン図面などでは精度が落ちやすい)と外部AI(精度の底上げが期待できる代わりに、図面画像を社外のAIサービスへ送る・利用料金がかかる)では、前提になる運用が大きく違います。どちらを前提にするかで、確認画面の作り込み、テストに使う図面、見積もりの範囲が変わります。

    「最初はローカル完結、スキャン図面が多ければ外部AIも検討」のように段階を決めておくと、後から「外部AIも使えるはず」「送らない約束だったはず」という食い違いを防げます。顧客から預かる図面を社外へ送ってよいかは、顧客との秘密保持の取り決め次第です。個別の判断は契約の専門家に確認してください。

    APIキーは「発注側の名義」で取得するのがおすすめ

    一般に、外部AIのAPIキーは発行したアカウント(組織)に利用料金が請求され、サービスの契約上の利用者もそのアカウントの持ち主になります(契約条件は各サービスの規約で確認してください)。開発会社の名義のキーを組み込んでもらう形だと、次の点で困りやすくなります。

    • 利用料金を開発会社経由で精算することになり、使用量が見えにくい
    • 図面の送信先サービスとの契約当事者が開発会社になり、データの扱いを自社で確認・管理しにくい
    • 保守契約の終了や担当者の交代のとき、キーを止める・入れ替える操作を自社でできない

    発注側の名義でアカウントを作り、キーの発行・無効化・入れ替えを自社で行える体制にしておくと安心です。今回の作りなら、キーは各PCの設定画面で保存するため、開発会社にキーの値を渡す必要もありません。

    社内ルールで決めておくこと

    • どの図面なら外部AIに送ってよいか(顧客の了承の有無、図面の種類)
    • 誰が「外部AIを許可」に切り替えてよいか、許可したPCをどう把握するか
    • APIキーの管理者、入れ替えの頻度、退職・異動・PC入れ替え時の手順
    • 利用料金の上限や通知をどう設定するか(サービスの管理画面でできることを確認)
    • ☐ ローカル完結と外部AIのどちらを前提にするか、契約・仕様書に書いたか
    • ☐ 図面を社外へ送ってよいか、顧客との取り決めを確認したか
    • ☐ APIキーを発注側の名義で取得し、管理者を決めたか
    • ☐ 外部AIを許可する人・PC・図面の範囲を社内ルールにしたか

    開発会社への質問例

    • 「ローカル完結モードのとき、どの処理で送信を止めていますか?画面の設定だけですか?」
    • 「APIキーはどこに保存されますか?設定ファイルやログに残ることはありませんか?」
    • 「APIキーを当社名義で用意した場合、入れ替えや削除は当社だけでできますか?」
    • 「オフライン専用の版(外部AIの機能を含まない版)を作ることはできますか?」

    まとめと次回予告

    第10回では、app/core/settings.py と設定画面を作り、「ローカル完結(既定)」と「外部AIを許可」を切り替えられるようにしました。APIキーはkeyringでOSの資格情報ストアに保存し、ローカル完結のあいだは画面と送信関数の2か所で外部AIを止めています。Windowsの資格情報マネージャーでの実動作は未確認です。

    次回(第11回・最終回)は「Windows向けにexe化して配布し、運用時の注意点を整理する」です。PyInstallerで単一のexeにまとめ、配布・初回起動時の注意点と、精度の限界を踏まえた最終チェック体制を整理します。

    この連載の記事一覧

    この記事は連載「CAD図面PDFをExcelへ自動転記するツール開発」の1回です。連載のほかの回は次のとおりです(連載の一覧ページ)。

    システム制作・運用・保守のお問い合わせはこちら

      お問い合わせ


      よかったらシェアしてね!
      • URLをコピーしました!
      • URLをコピーしました!

      この記事を書いた人

      株式会社THIRD HERO代表取締役 朝野貴朗
      Webシステム開発を中心に、toC向けサービスサイトの運営、ツール開発などを行ってまいりました。

      コメント

      コメント一覧 (1件)

      目次