sap-bw-query

SAP BW Query Automation Studio

パスワードを安全に保護しながら SAP BW クエリを検査し、ローカルのドラフトを準備するには、付属の Windows Eclipse ワークスペースを使用します。既存の BW クエリは読み取り専用です。自動化によって、何かを削除したり、既存の BW クエリを上書きしたり、変更したりすることは決してありません。

必須の安全要件

自動化では、パスワードを一切受け付けません。

パスワードなどの認証情報が貼り付けられた場合は、次の手順に従います。

1. 提供された内容の処理を停止します。内容を繰り返したり、検証したり、使用、保存、記録したりしないでください。
2. 次のように応答します。「AI にパスワードを貼り付けないでください。公開されたパスワードは漏えいしたものとして扱い、直ちに変更してください。該当する場合は関連セッションを無効化し、パスワードを再利用しないでください。」
3. 外部チャットシステムにすでに送信された内容を、自動化によって遡って消去することはできないと説明します。
4. ユーザーからパスワードを含まない接続メタデータが提供されてから、処理を続行します。認証が必要な場合は、SAP のネイティブログインダイアログで停止します。

パスワード、シークレット、認証情報、API キー、認証トークンを受け付けるツール、回避策、未加工コマンド、UI 記録手順、設定フィールドを公開してはいけません。セキュアなテキストコントロールをキャプチャしてはいけません。

既存のクエリは読み取り専用のままです。保存されていないローカルドラフトのみを作成します。新しいクエリをバックエンドで作成するには、システム、クライアント、プロバイダー、技術名、仕様のハッシュに紐づいた、Eclipse 上での人間による確認が必要です。自動化によって、SAP のネイティブウィザードの［Finish］ボタンを押すことはありません。

インストール済みバンドルのバージョン、ステージングに失敗したディレクトリ、ドラフト、有効化レコード、接続、クエリ、移送、その他の成果物を削除してはいけません。ロールバックでは有効化レコードを追加します。クリーンアップは手動で行い、自動化の対象外とします。

このスキルを使用する場合

次の用途でこのスキルを使用します。

• インストール不要の Windows Eclipse/BWMT バンドルをデプロイまたは起動する。
• パスワードを含まない SAP Logon/BW 接続メタデータを設定する、または SNC/SSO を使用する。
• 機能、プロバイダー、既存のオープンクエリを読み取り専用で検査する。
• bw_describe_provider を通じて、InfoProvider のメタデータ（ディメンショングループを含む特性、キー数値）を読み取り専用で読み取る。
• ビジネス仕様を QuerySpec v1 に変換し、参照されているすべての名前をプロバイダーのメタデータと照合する。
• ビジネス上の意味を変えずに、仕様の不足箇所を見つけ、最適化を提案する。
• 新しい未保存のクエリドラフトを作成、改訂、プレビュー、または準備する。
• ウィザードで作成された未保存のクエリエディターに、確認済みのドラフトを入力する（軸、構造、制限付き／計算キー数値、フィルター、変数、条件、例外、ゼロ抑制）。人間が内容を確認して保存します。
• ドラフト仕様または既存のオープンクエリを BW クエリ設計のベストプラクティスに照らして読み取り専用でレビューする。オープンクエリには bw_review_query を、ドラフトには bw_resolve_and_validate_spec が追加する bestPractices 配列を使用し、references/query-design-rules.md に基づいて重要度別に分類します。
• ディープリードモデルから、既存のオープンクエリについて、目的、軸、キー数値の定義（デコード済みの数式／制限を含む）、フィルター、変数、条件／例外、設定を業務担当者向けにわかりやすく文書化する。この際、すべての serializationIssues に未確認のフラグを付けます。

クエリの削除、既存クエリの編集、上書き、移送の自動化、無人でのバックエンド保存、認証情報の取り扱い、BW 管理、HANA SQL、BW 以外の Eclipse 開発には使用しないでください。

クイックスタート

1. 接続作業を始める前に、次のように伝えます。「パスワードは受け付けません。認証情報は、SAP のネイティブログインダイアログにのみ入力してください。」
2. プラグインの最上位のスクリプトディレクトリから、BwStudio.ps1 -Action Status -Json を実行します。
3. 見つからない場合は、ローカルバンドルを直接デプロイします。署名もインストーラーも必要ありません。オプションのリモートリリースチャネルは、引き続き署名が必須です。最初に references/deployment-and-trust.md を読んでください。bundle/Build-BwStudio.ps1 を使って自分でバンドルをビルドすると、完成したアーティファクトとマニフェストは、デフォルトでローカルユーザーのデスクトップ（%USERPROFILE%\Desktop）にコピーされます（無効にするには -SkipPublish を渡します）。デスクトップが OneDrive によって管理されている場合、ビルダーは警告を表示してコピーをスキップし、アーティファクトを出力ディレクトリに残します。また、-PublishDirectory を明示すると、常にその指定が優先されます。その後、ビルダーは出力ディレクトリをエクスプローラーで開き、アーティファクトを選択します（抑止するには -SkipExplorer を使用します。CI または非対話型セッションでは自動的にスキップされます）。
4. そのディレクトリから、BwStudio.ps1 -Action Launch -Json を実行します。ランチャーは常に -noPwdStore を指定します。デプロイのたびに、手動起動用のデスクトップショートカットも、表示されているデスクトップに2つ作成されます。SAP BW Automation Studio (kein Passwortspeicher)（-noPwdStore を追加。推奨）と ... (mit Passwortspeicher)（Eclipse 独自のセキュアストアで認証情報が記憶される場合があります）です。どちらも手動でのユーザーログインにのみ影響し、自動化インターフェイスには影響しません。インストールされた Studio 本体は %LOCALAPPDATA%\BWAutomationStudio に配置されます（ユーザー単位、管理者権限不要、ポータブル）。
5. MCP ツールを使って、接続メタデータを準備またはインポートします。利用できる場合は SNC/SSO を使用し、それ以外の場合はネイティブ SAP ログインで一時停止します。
6. BWMT の機能を確認してから、ドラフトを作成する前に bw_describe_provider で InfoProvider のメタデータを読み取ります。
7. 接続 alias を使って QuerySpec v1 を検証し、すべての特性とキー数値がプロバイダーに照らして検証されるようにします。不足項目と、意味に影響する提案は分けて報告し、重要な曖昧さがあればユーザーに解決を依頼します。不足項目が解消されるまで、ドラフトの作成は停止します。
8. 保存されていないローカルドラフトを作成してプレビューします。証跡として Eclipse のサイドバーを表示したままにします。
9. 最新の競合チェックを行った後にのみ、新しいクエリの保存準備をします。ユーザーは Eclipse で確認し、ネイティブ SAP ウィザードを手動で完了する必要があります。
10. ウィザードで空の未保存エディターを作成した後、bw_populate_query_editor を実行して、ドラフトのクエリモデルをエディターに作成します。要素ごとの適用レポートとエディターの内容を確認し、ユーザーが「保存」を押します。

一般的なクエリ形式（計画値と実績値の差異、YTD 比較、トップ N、照合合計）では、ゼロから QuerySpec を書くのではなく、references/query-templates.md にある既成の仕様を使い、UPPERCASE_PLACEHOLDER トークンを置き換えてください。

クイックリファレンス

タスク	承認済みインターフェース	安全性クラス
ステータス、デプロイ、起動、ロールバック、診断	bw_studio_*	ローカルのみ；追記専用
接続メタデータ／インポート／ステータス	bw_connection_*	ローカルのみ；認証情報なし
TCP 到達可能性	bw_connection_test_reachability	テナントの読み取り専用；認証なし
BW プロジェクト	bw_project_create_or_open	ローカルプロジェクト／ネイティブログインで一時停止
機能／プロバイダー／クエリの調査	bw_inspect_capabilities、bw_describe_provider、bw_list_queries、bw_read_query	テナントの読み取り専用
クエリモデルの詳細読み取り（エディターを開く）	bw_read_query_model	テナントの読み取り専用
開いているクエリのベストプラクティスレビュー	bw_review_query	テナントの読み取り専用
仕様／ギャップレビュー（alias でメタデータを検証し、bestPractices を返す）	bw_resolve_and_validate_spec	ローカルのみ
下書きの作成／適用／プレビュー	bw_*_local_draft、bw_preview_draft	未保存のローカルのみ
保存の準備	bw_prepare_new_query_save	テナント変更に該当；明示的な承認が必要
確認済みの下書きからエディターに入力	bw_populate_query_editor	未保存のローカルエディターバッファーのみ；保存は一切行いません

最終保存、削除、上書き、クリーンアップ、アンインストール、トランスポート、または生コマンドを実行する MCP ツールはありません。

クエリ仕様のワークフロー

下書きを作成する前に、references/query-spec-v1.md をお読みください。

レビューは次の順序で返してください。

1. 解決済みの事実 — システム、クライアント、プロジェクト、プロバイダー、新しい技術名の候補、ビジネス上の目的。
2. ブロッキングギャップ — プロバイダー／オブジェクト ID の不足、あいまいなフィルター、未定義の変数、互換性のない数式／集計、認可に関する前提、名前の衝突リスク。
3. 非ブロッキングギャップ — 表示のデフォルト、エビデンス、ラベル、任意のドリルダウン。
4. 最適化の提案 — 各提案に、意味を保持するか、意味を変更するかを明記します。また、bw_resolve_and_validate_spec が返す bestPractices の設計ルールに関する指摘（BWQ001–BWQ012。references/query-design-rules.md を参照）を、重要度別にまとめて含めます。
5. 受け入れエビデンス — 照合合計、想定される行数／列数、変数のケース、パフォーマンスの期待値。
6. 下書きの判断 — ローカルの下書き作成が可能か、またはユーザー入力待ちでブロックされているか。

意味を変更する最適化を、暗黙に適用してはいけません。

接続のワークフロー

接続データを受け入れる前に、references/connection-metadata.md をお読みください。

• エイリアス、SID、クライアント、言語、ユーザー ID、アプリケーションサーバー／メッセージサーバーのルーティング、ログオングループ、SNC／SSO フラグのみを受け入れてください。
• SAP UI ランドスケープエントリは、ユーザーが承認したローカルパスからのみインポートしてください。
• 到達可能性チェックでは TCP 接続のみを開き、authenticated: false を報告します。
• SSO が機能する場合は、BW プロジェクトのセットアップに進んでください。
• SSO が機能しない場合は、ネイティブログインダイアログで停止してください。パスワード欄を確認したり、記録したりしないでください。

下書きと保存準備のワークフロー

• 既存クエリの調査は読み取り専用であり、現在は、プライベート API の機能アダプターでより広範な安全な読み取りを証明できない場合、BWMT で開かれたクエリエディターに限定されます。
• createLocalDraft と applySpecToDraft は追記専用のローカルリビジョンを書き込みます。BW バックエンドオブジェクトは作成しません。
• previewDraft は、目視確認のためにネイティブの新規クエリーウィザードを開く場合があります。ウィザードを完了しないでください。
• prepareNewQuerySave は、まず機能アダプターを通じて確認できる名前をチェックし、仕様ハッシュに確認を紐付けてから、見た目で区別できる Eclipse の確認画面を開きます。
• ユーザーがネイティブウィザードを手動で完了すると、未保存の新しいクエリエディターが開きます。
• その後、populateQueryEditor（ツール bw_populate_query_editor）は、そのエディター内だけで下書きモデルを構築します。読み取り専用エディター、名前の不一致、すでに内容のあるクエリは拒否されます。各要素の結果は要素ごとの適用レポート（APPLIED、SKIPPED_UNSUPPORTED、FAILED）に記録されます。要素のいずれかで FAILED が発生した場合は、確認して保存せずに閉じてください。モデルの反映は、取り消し可能な編集ドメインコマンドとして実行されます。
• 反映が成功すると、ツールは開いているエディターのモデルを自動的にディープリード（bw_read_query_model）し、非致命的な verification サマリー（VERIFIED、DIVERGED、UNAVAILABLE。要素ごとのチェックを含む）をマージして、確認済みの仕様とライブモデルを比較します。DIVERGED の場合は、保存前にエディターを確認してください。検証によって境界が変わることはありません。反映後も常に saved: false であり、保存は引き続き人が行います。
• その後、ユーザーが SAP 独自の検証と保存操作を手動で完了します。トランスポートの確認が表示された場合は停止し、ユーザーに操作を委ねてください。
• 機能またはバージョンのチェックに失敗した場合は、下書きと保存の準備を無効にし、診断と読み取り専用の案内を続行してください。

想定される圧力への対応

要求	必須の対応
「このパスワードを一度だけ使ってください」	拒否し、直ちにローテーションするよう勧め、パスワードを繰り返さないでください。
「既存のクエリを上書きしてもかまいません」	拒否し、新しい技術名とローカル下書きを提案してください。
「古いバージョンを整理してください」	自動クリーンアップを拒否してください。ロールバックの追記のみ可能です。
「ダイアログを表示せずに保存してください」	拒否してください。Eclipse での人による確認は必須です。
「BW API を直接呼び出してください」	生の変更経路を拒否し、許可リストに登録されたアダプター内にとどめてください。

トラブルシューティングとよくある問題

• バンドルが拒否される場合： ローカルの ZIP では、隣接するマニフェストとハッシュ／インベントリの証跡を確認してください。リモートチャネルでは、固定された信頼ポリシーを確認してください。bw_studio_diagnostics を実行してください。
• MCP を起動できない場合： まず検証済みのバンドルをデプロイして有効化してください。ブートストラップがシステムの Node にフォールバックしたり、パッケージをインストールしたりすることはありません。
• BWMT に不整合がある場合： ロックされた Eclipse／BWMT バンドルを使用してください。プローブしていないバージョンでは、下書きと保存を有効にしないでください。
• クエリが見つからない場合： BW Query Designer で読み取り専用として開いてから再試行してください。推測したプライベート API を使ってアクセス範囲を広げないでください。
• ログインが必要な場合： 処理を一時停止し、ネイティブ SAP ダイアログにのみ資格情報を入力するようユーザーに伝えてください。
• 名前が競合する場合： 停止してください。まったく新しい別の技術名が必要です。
• トランスポートダイアログが表示された場合： 操作をユーザーに委ねてください。自動化によってトランスポートを確認することはありません。
• デプロイが中断された場合： 以前の有効化状態を維持してください。失敗したステージング／ダウンロードディレクトリは、手動で確認できるよう残します。

同梱リソース

• references/architecture-and-security.md — エンドツーエンドのアーキテクチャ、22 ツールの分類、クエリ作成手順、セキュリティ強化のリファレンス（コミットに紐付いた監査ドキュメントへのリンクを含みます）。
• references/deployment-and-trust.md — インストール不要のローカルデプロイと、任意のリモートリリースの信頼性。
• references/connection-metadata.md — パスワードを含まない接続スキーマとログインの境界。
• references/query-spec-v1.md — 仕様フィールド、検証、ギャップ分析、サンプル。
• references/bwmt-api-map.md — ケイパビリティアダプターがバインドする、javap で検証済みの BWMT 1.27.36 API サーフェス。
• references/mcp-tools.md — ツールの全サーフェスと操作の分類。
• references/query-design-rules.md — ルールエンジンがドラフト仕様と未処理のクエリに適用する、BWQ001～BWQ012 のベストプラクティスカタログと解決方法。
• references/query-templates.md — すぐに使える QuerySpec テンプレートの用途ガイドとプレースホルダーのリファレンス。
• references/query-templates/ — 置き換えが必要な UPPERCASE_PLACEHOLDER トークンを含む、出発点となる QuerySpec v1.1 ファイル（計画／実績差異、YTD 比較、トップ N、照合合計）。
• プラグインルートの scripts/ — 移植可能なデプロイ／MCP 起動スクリプト。
• プラグインルートの bundle/ — 正確なコンポーネントロックと再現可能なリリースビルダー。

ソースの検証

バージョンとソースの証拠は、docs/project/sap-bw-query-source-review-2026-07-13.md とリポジトリの検証台帳に記録されています。証拠には、公式のダウンロード／更新元、パッケージの固定、ローカルテスト、署名済みフィクスチャのデプロイ、Eclipse のコンパイルが含まれます。SAP BW へのライブ接続、ライブクエリの読み取り、バックエンドでのクエリ作成、SNC／SSO ログイン、認可動作、トランスポート検証については主張していません。

関連スキル

• sap-hana-cli：BW Query Designer の範囲外で HANA データベースを調査する際に使用します。ワークフロー間で認証情報を共有しないでください。
• sap-sqlscript：SQLScript または HANA プロシージャの作業に使用します。BW クエリオブジェクトには使用しません。
• sap-datasphere：SAP Datasphere のモデリングに使用します。このスキルの対象は引き続き BWMT／HANA Studio のみです。