btp-diagram-generator

BTP ソリューション図ジェネレーター

ワークスペースに SAP BTP ソリューション図のガイドラインに準拠した .drawio ファイルを生成し、設定されている draw.io MCP サーバーを通じて開きます。

検証と成果物の提供に関する方針は、Archifyの考え方を取り入れています。決定論的な成果物、機械可読な修復記録、明示的な品質ゲート、正常な成果物の保持、自動レビューと視覚的レビューに関する主張の分離が含まれます。

⚡ クイックパス（まずはこちらを使用）

大半の図では、XML を手書きしないでください。btp_builder Python パッケージを使用します。このパッケージがアイコンの検索、SAP パレット、ポートの固定、ラベルの HTML、A4 サイズ設定、SVG の拡大、検証を担います。一般的な L1 図は約 20 行で作成できます。

# scripts/examples/task_center_arch.py — runnable end-to-end
import sys
from pathlib import Path
# Add the skill's scripts/ dir to sys.path so `btp_builder` imports work
# regardless of where the skill is installed
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))

from btp_builder import BtpDiagram

d = BtpDiagram(level="L1", title="Task Center Reference Architecture")

btp = d.btp_container(x=260, y=80, w=560, h=440)
sub = d.subaccount(parent=btp, label="Subaccount",
                   x=btp.x + 24, y=btp.y + 110, w=520, h=170)

wz = d.service("work zone",   in_=sub, x=sub.x + 60, y=sub.y + 60)
tc = d.service("task center", right_of=wz)
ci = d.service("cloud identity", below=tc)

eu = d.user("End User", x=60, y=btp.y + 100)
ac = d.app_client("Application Clients\n(Mobile or Desktop)", below=eu)

s4    = d.external("SAP S/4HANA\nOn-Premise Solutions",
                   x=btp.right_edge() + 40, y=btp.y + 70, kind="sap")
third = d.external("3rd Party\nApplications", below=s4, kind="non-sap")
cloud = d.external("SAP Cloud\nApplications", below=third, kind="sap")
idp   = d.idp("3rd-party Identity Provider",
              x=ci.center_x() - 140, y=btp.bottom_edge() + 60)

d.connect(eu, ac, direction="down")
d.connect(ac, wz, direction="right")
d.connect(wz, tc, kind="dblhd")
d.connect(tc, ci, kind="dblhd", direction="down")
d.connect(tc, s4); d.connect(tc, third); d.connect(tc, cloud)
d.connect(idp, ci, kind="dashed", direction="up")

d.save("btp-task-center-architecture.drawio")  # validates, then atomically commits

リポジトリのルートから uv run python <script>.py で実行します。save() は最初に検証し、問題があればエラー一覧全体を含む ValueError を送出します。警告は出力されます。 ビルダーの出力は決定論的です。同じ内容の図を作成すると、XML のバイト列と図 ID は常に同じになります。save() は同じディレクトリに候補ファイルを書き込み、検証に成功した場合にのみターゲットをアトミックに置き換えるため、コミットに失敗しても以前の成果物は保持されます。

クイックパス API の概要

呼び出し	戻り値	備考
BtpDiagram(level, title)	ビルダー	level ∈ L0/L1/L2。アイコンのサイズとラベルのウェイトを決定します。
.btp_container(x,y,w,h, sub_label, env_label, with_logo)	NodeRef	水色の外枠 ＋ SAP のコーナーロゴ ＋ Subaccount／Multi-Cloud ラベル。
.subaccount(parent, label, ...)	NodeRef	BTP コンテナー内の白いカード。
.inner_card(parent, label, ...)	NodeRef	汎用の白いサブカード（例：CIS サービスグループ）。
.service(name, in_=, right_of=, left_of=, below=, above=)	NodeRef	name は references/icon-aliases.json を使ってあいまい一致します（例："task center"、"cpi"、"hana cloud"）。
.user(label, kind="sap")	NodeRef	kind ∈ sap／non-sap／highlight。
.app_client(label, ...)	NodeRef	汎用のモバイル／デスクトップタイル。
.external(label, kind="sap"/"non-sap", ...)	NodeRef	右側に配置する外部システムタイル。
.idp(label, ...)	NodeRef	サードパーティのアイデンティティプロバイダータイル。
.connect(src, tgt, kind, direction)	エッジ ID	kind ∈ std/dblhd/dashed/optional/auth/scim/trust/neutral。direction はポートを自動で固定します。"right"／"left"／"up"／"down"で上書きできます。
.save(path, validate=True)	Path	検証後、決定的な XML をアトミックにコミットします（エラー時は例外を送出します）。

位置指定用のキーワード引数（right_of、left_of、below、above、in_）でノードが自動配置されます。各行／列の最初のアンカーにのみ、明示的な x,y を設定してください。

アイコン名の確認

from btp_builder import list_aliases, list_icons, lookup_icon
print(list(list_aliases())[:30])     # short names → canonical keys
print(lookup_icon("integration suite", "L1")["key"])

lookup_icon が IconNotFound を送出した場合は、スタイル付きタイル（external(label, kind="sap")）に切り替え、最終応答でその旨を明記してください。

図を開く

uv run python skills/btp-diagram-generator/scripts/open_diagram.py btp-task-center-architecture.drawio

システムのオープナーが見つからない場合は、https://app.diagrams.net/?…#create=... URL を出力します。実行環境で draw.io MCP ツールを利用できる場合は、そちらを優先してください。ツール一覧に実際に表示されている MCP ツールのみを呼び出してください。

---

XML を手動で扱う方法（高度なケース／特殊なケースのみ）

クイックパスでは必要なものを作成できない場合（例：特殊な凡例のバリエーション、カスタムのフロープロトコル用ピル、ビルダーでまだサポートされていない新しいレイアウト）にのみ使用してください。以下では、ビルダーが生成する基盤となる XML プリミティブについて説明します。

使用する場面

次のような依頼があった場合に使用します。

• 「…の BTP アーキテクチャを図にして」
• 「CAP + HANA Cloud + Build Workzone を示す BTP ソリューション図を生成して」
• 「SAP BTP の統合ランドスケープを draw.io で作成して」
• 「<ユースケース>の L0 / L1 / L2 BTP 図」

一般的なフローチャート、シーケンス図、または SAP 以外のアーキテクチャの依頼には、このスキルを使用しないでください。代わりに Mermaid を生成するか、通常の draw.io ワークフローを使用してください。

収集する入力（簡潔に一度だけ質問）

生成する前に、不足している情報を確認します。指定がない場合は L1 をデフォルトにします。

入力	デフォルト	備考
対象者のレベル	L1	L0 = ビジネス概要（凡例なし、中立的なコネクター）；L1 = 技術（サービス + 主なフロー）；L2 = 詳細（データフロー、プロトコル、コンポーネント）
BTP サービス / SaaS アプリ	（要確認）	例：CAP、Build Code、Integration Suite（CPI/Event Mesh/API Mgmt）、HANA Cloud、SAC、AI Core、Joule、Build Workzone、Identity Authentication、Destination、Connectivity
BTP 以外のシステム	（任意）	例：S/4HANA Cloud、SuccessFactors、Ariba、サードパーティ SaaS、オンプレミスシステム、エンドユーザー
環境 / ランタイム	Cloud Foundry	Cloud Foundry、Kyma、ABAP Environment
リージョン / マルチリージョンか？	シングル	グループ化するコンテナーに影響します
主なフロー	（要確認）	何が何に接続するか、方向、目的
出力形式	.drawio + PNG	.drawio は必須です。必要に応じて draw.io CLI で PNG（-s 2）、SVG、または PDF にエクスポートできます
出力ファイル名	btp-diagram.drawio	ユーザーが指定しない限り、ワークスペースのルートに保存します

サービスが十分に示され、フローが明確な一行のプロンプトがユーザーから提示された場合は、質問せずに進めてください。最終回答で前提を明示してください。

コンポーネントの許可リストを厳守

レイアウトの前に、依頼内容に基づいてコンポーネントの許可リストを明確に作成します。

1. 指定されたアクター、クライアント、サービス、接続先、およびアーキテクチャ上必要なサポートサービス（認証フローにおける CIS など）を列挙します。
2. おなじみの製品を装飾として追加しないでください。 SAP Build Work Zone、SuccessFactors、追加の転記先は、明示的に指定されているか、説明されたフローで必要な場合にのみ含めます。
3. 指定された順序を、順序付きエッジリストとして維持します。例：Outlook → Document AI → Integration Suite → S/4HANA Cloud は、記載された隣接エッジのみを意味します。中間ステップや追加の接続先を挿入しないでください。

ワークフロー

1. 要件を BTP アイコンに対応付ける

mxgraph.sap.* ステンシルファミリーはありません。 draw.io の SAP BTP アイコンは、shape=image;image=data:image/svg+xml,<base64>;… 形式のスタイル文字列に base64 で埋め込まれた SVG であり、SAP draw.io shape library XML files で配布されています。shape=mxgraph.sap.foo を生成すると、キャンバスに空の四角形が表示されます。すでにこの方法が失敗することを確認しています。

リクエストされたサービスごとに、references/icon-index.json を調べて実際の style 文字列を取得してください。

1. 推奨： references/icon-index.json（約660 KB、100個のアイコン）を読み込みます。各アイコンのタイトル（例：31068-sap-build-work-zone_sd）と、その style 文字列、ライブラリセルの width／height が対応付けられています。リクエストされたサービス名に部分一致するものを探してください。
2. ソース XML ライブラリ（デフォルト以外のサイズや、インデックスにないメタデータフィールドが必要な場合）は references/libraries/ にあります。アイコンセットごとに、サイズMの mxlibrary が1つずつあります（foundational、integration suite、app-dev、AI、data-analytics、BTP-SaaS、all-in-one）。
3. スタイルの参照元： 複合パターン（サブアカウントカード、NETWORK 境界、ピルラベル、凡例カード）については、厳選された references/examples/ の公式編集可能図を11個参照してください（Task Center L0/L1/L2、Build Work Zone L2、Process Automation L2、Cloud Identity Services L1/L2、Private Link L2、SAP Start L2）。いずれかを開き、スタイル文字列をそのままコピーしてください。
4. ライブラリにサービスが実際に存在しない場合は、スタイル付きの代替タイル（下記§3を参照）を使い、最終回答でそのサービスを一覧にしてください。ユーザーは後から置き換えられます。

対象者レベルごとのデフォルトアイコン形状（公式の例と一致します。references/example-patterns.md §5 を参照してください）。

SVG の固有サイズに関する警告： SAP シェイプライブラリのすべてのアイコンは、サイズMのセットであっても、ルート <svg> 要素の width="16" height="16" が設定されています。draw.io はこの固有サイズでラスタライズしてから拡大するため、アイコンがぼやけます。base64 SVG を取り出した後、再エンコードする前に、ルート <svg> の width と height を対象セルのサイズ（L1 なら48など）に合わせて修正してください。viewBox は変更しないでください。Python ヘルパーについては references/example-patterns.md §11 を参照してください。

レベル	アイコンサイズ	ラベル
L0	50×50	Arial 14 bold
L1	48×48	Arial 14 bold
L2	32×32	Arial 12 regular

ラベルはセルの value= 属性に設定され、アイコンの下に表示されます（ライブラリのスタイルでは、すでに verticalLabelPosition=bottom が設定されています）。コネクターが正しく接続されるよう、ライブラリのスタイルにある points=[[0,0,0,0,0],…] の12個のアンカー配列は必ず保持してください。

2. SAP Fiori Horizon のカラーパレットを適用する

常に次の色のみを使用してください（任意の塗りつぶし色は選ばないでください）。出典：SAP BTP Solution Diagram guideline — Foundation (Atoms) および Areas：

トークン	16 進数	用途
SAP/BTP 境界線（プライマリ）	#0070F2	BTP コンテナーの境界線、アクセントの塗りつぶし、サブカードの境界線
SAP/BTP 塗りつぶし	#EBF8FF	BTP コンテナーの背景
非 SAP 境界線	#475E75	非 SAP／外部領域の境界線、汎用データフローコネクター
非 SAP 塗りつぶし／控えめな背景	#F5F6F7	非 SAP 領域、ページ背景、汎用ピルの塗りつぶし
タイトルテキスト	#1D2D3E	見出し、主要なラベル
セカンダリテキスト	#556B82	サブラベル、説明、脚注
ポジティブ（認証、緑）	#188918 / bg #F5FAE5	認証フロー（SAML、OIDC）— ガイドラインに準拠
クリティカル（警告、オレンジ）	#C35500 / bg #FFF8D6	警告
ネガティブ（エラー、赤）	#D20A0A / bg #FFEAF4	エラー
ティールのアクセント	#07838F / bg #DAFDF5	強調領域
インディゴ（認可）	#5D36FF / bg #F1ECFF	認可／プロビジョニング（SCIM）フロー — ガイドラインに準拠
ピンク（信頼）	#CC00DC / bg #FFF0FA	信頼フロー（相互信頼、フェデレーション）— ガイドラインに準拠

フォント：Arial（または見出しには Arial Black）、本文ラベルはサイズ 12、サービスラベルは 14、グループタイトルは 16 です。

3. アトミック構造を適用する

SAP のアトミックデザインシステム（Atoms → Molecules → Organisms）に従います。コピーする正確なスタイル文字列、サイズ、HTML ラベルのパターンは references/example-patterns.md に記載されています。独自のバリエーションを考案せず、そちらに合わせてください。

• ドキュメントタイトル（すべての図）：BTP コンテナの上に浮かぶテキストセル。青 #0070F2、太字の Arial 16、形式は "{Scenario} - SAP BTP Solution Diagram"。
• 外側のコンテナ（サブアカウント／マルチクラウド）：rounded=1;strokeColor=#0070F2;fillColor=#EBF8FF;arcSize=32;absoluteArcSize=1;strokeWidth=1.5;。左上に SAP ロゴの画像タイルを配置し、2段のラベルを付けます。太字の Subaccount（Arial 16）と、小さめの Multi-Cloud（Arial 12）です。
• サブコンテナ（BTP の境界内にある白いカード。例：Cloud Identity Services グループ）：同じ #0070F2 のストローク、#FFFFFF の塗りつぶし、arcSize=16 を使用します。BTP コンテナ内のカードでは、常に青いストロークを使い、スレート色は使いません。ガイドラインの Areas / Nesting に従い、視覚的なコントラストを保つため、親と子で塗りつぶしの有無を交互にします（BTP コンテナは #EBF8FF で塗りつぶされているため、内側のカードは白にします）。
• サービスノード：別個のテキストラベルが必要な場合、または別の図形と同じ位置に配置する場合は、BTP アイコン（§1）を style="group" connectable="0" のセルで囲みます。子要素の座標はグループの原点からの相対座標にします。
• 外部システムのタイル（例：SAP S/4HANA On-Premise）：（arcSize=14 の白いカード＋左上の約 28×28 のアイコン＋右側の太字 font-size:16px のラベル）をグループ化します。BTP コンテナの外側に配置します。
• ユーザー／アクター：ユーザー SVG 画像と、その下に中央揃えの End User テキストラベルを含む group を使用します。
• コネクタ — サンプルパターンのリファレンスから適切なバリエーションをコピーします。ガイドラインの Connectors セクションに従い、線の スタイル はフローの性質を、線の 色 はフローの意味を表します。
  • 線のスタイル： 実線＝直接的な同期リクエスト／レスポンス · dashed=1＝間接的／非同期 · dashed=1;dashPattern=1 4;（点線）＝任意 · strokeWidth=3＝ファイアウォール／ネットワーク境界のみ。
  • 意味を表す色： 認証＝緑 #188918 · 認可／プロビジョニング（SCIM）＝インディゴ #5D36FF · 相互信頼／フェデレーション＝ピンク #CC00DC · 汎用データ＝スレート #475E75。
  • 標準的なデータフロー：endArrow=blockThin;strokeColor=#475E75;endFill=1;endSize=4;startSize=4;strokeWidth=1.5;
  • 直交：先頭に edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto; を付けます。
  • 認証（SAML/OIDC）：同じ形状で、strokeColor=#188918 を指定します。
  • 認可／プロビジョニング（SCIM）：同じ形状で、strokeColor=#5D36FF を指定します。
  • 相互信頼：startArrow=blockThin;startFill=1 と strokeColor=#CC00DC を追加します。
  • 非同期／間接：edgeStyle=entityRelationEdgeStyle;rounded=0;html=1;strokeColor=#475E75;strokeWidth=1.5;endArrow=blockThin;endFill=1;endSize=4;startArrow=none;startFill=0;startSize=4;jumpStyle=none;jumpSize=0;targetPerimeterSpacing=15;dashed=1; を使用します（SAP 公式の間接コネクタスタイル — entityRelationEdgeStyle ＋ targetPerimeterSpacing=15）。
  • 任意：上記の非同期スタイルに dashed=1;dashPattern=1 4;（点線）を追加します。
  • ネットワーク／ファイアウォール境界線：太い灰色の縦線 strokeColor=#475E75;strokeWidth=3;jumpStyle=gap; と、その横に小さな大文字の NETWORK ラベル（#475E75）を配置します。strokeWidth=3 はファイアウォール／ネットワーク境界に限って使用します。通常のデータフローには使用しません。
  • 斜めの自動ルーティングを避けるため、出口／入口ポートを常に固定します。exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0; を追加します（方向に応じて X/Y を調整してください）。垂直コネクタでは exitY=1／entryY=0 を使用します。意図的に迂回させる場合を除き、手動の <mxPoint> ウェイポイントは削除し、<Array as="points"/> は空のままにします。ポート固定の詳細は references/example-patterns.md §8 を参照してください。
• エッジラベルは、エッジ内のテキストではなく、独立した頂点ピルにします。小さな角丸長方形で arcSize=50、高さは約 16 px とし、コネクタに合わせた色を使います（汎用 #475E75／#F5F6F7、認証 #188918／#F5FAE5、認可／SCIM #5D36FF／#F1ECFF、信頼 #CC00DC／#FFF0FA）。
• L0：凡例、プロトコルピルはなし。中立的な endArrow=block または endArrow=none のコネクタを使用します。
• L1：方向を示す endArrow=blockThin のコネクタを使用し、必要に応じて、色付きの認証／プロビジョニングフローとピルラベルをいくつか追加します。
• L2：説明ブロックと、タイトルの下に Diagram Level: L2 を追加します。意味のあるすべてのエッジにピルタグを付け、右上に凡例カード（白いカード、strokeColor=#eaecee。各フロータイプを示す色付きの 16×16 の楕円形スウォッチと、矢印の各スタイルを示すサンプル矢印を配置）を追加します。

4. draw.io XML を生成する

draw.io の AI 生成ルールに従ってください。

• 非圧縮 XML を使用し、完全な <mxfile> ラッパーを含めます（ファイルレベルの変数を使用できるようにするため）。
• <mxCell id="0"/> と <mxCell id="1" parent="0"/> を必ず含めます。
• 頂点：vertex="1"。エッジ：edge="1" と source／target。相互に排他的です。
• 図全体で ID が重複しないようにします。
• 座標：左上が (0,0)、x は右方向、y は下方向です。グループ内の子要素は、グループを基準とした相対座標を使用します。
• 図形に合わせて外周を指定します（例：楕円には perimeter=ellipsePerimeter）。
• ラベルを XML エスケープします（&、<、>、"）。value= 内の HTML マークアップは使用できます。テキストの太字化やサイズ変更には標準の方法です。公式の例を参照してください。
• HTML ラベルのエスケープ： まず HTML 文字列全体（タグとテキストを含み、<／>／" はそのまま）を組み立ててから、value="…" 属性に挿入する前に、完全なエスケープを 1 回だけ実行します（&→&、<→<、>→>、"→"）。xml.etree.ElementTree を使用する場合は、エスケープしていない値を渡し、シリアライザーにエスケープさせます。書き込んだファイルを実際の XML パーサーで解析し、表示されるラベルに <font、<font、<div が含まれていたら拒否します。
• エリア図形（BTP の境界、サブアカウントカード）には container=0; を使用します。draw.io のコンテナー動作は使用しません。これにより、コネクターが正しくその中を通るようになります。
• グリッド間隔は 10 px の倍数にします（gridSize="10"）。兄弟要素間には 20 px 以上の間隔を空け、サブコンテナーには約 18～24 px の余白を設けます。
• 図を負の座標空間（例：x="-2200"）で作成するのは通常のことで、想定されています。draw.io はコンテンツを中央に配置します。
• すべてのエッジ mxCell に <mxGeometry relative="1" as="geometry" /> を必ず含めます。自己終了するエッジセルは無効で、描画されません。

ページサイズ：常に A4 横向きにします。L2 が密集している場合でも、pageWidth="1169" pageHeight="827" を使用します。大きな仮想キャンバスは、ページサイズを変更するのではなく、グループを負の座標方向に広げて確保します。L2 ではさらに、<mxGraphModel> に background="none" を設定します。

5. ファイルを書き込む

ユーザーが指定したパス（デフォルト：ワークスペースのルート、btp-diagram.drawio）に保存します。確認せずに既存のファイルを上書きしないでください。

6. MCP サーバー経由で開く

利用可能な draw.io MCP 統合を次の順で検出し、設定済みの最初のものを使用します。

1. MCP Tool Server（@drawio/mcp／npx @drawio/mcp）：生成した XML を使って「図を開く」ツールを呼び出し、ブラウザーでエディターを起動します。
2. MCP App Server（mcp.draw.io/mcp リモート）：レンダリングツールを呼び出し、チャット内にインタラクティブなビューアーを埋め込みます。
3. どちらも設定されていない場合：何も伝えずにスキップし、代わりに FAQ に従って作成した https://app.diagrams.net/?pv=0&grid=0#create=... URL を出力します（{"type":"xml","compressed":true,"data":"<base64-deflate-raw>"} の JSON を URI エンコードします）。この場で圧縮できない場合は、ファイルパスを出力し、インストール済みの draw.io で開くようユーザーに案内します。

利用可能なツール一覧に実際に表示されているツールだけを呼び出してください。MCP ツール名を捏造してはいけません。

7. 提出前に検証する

候補を編集するたびに検証します。反復作業では standard を使用します。警告は許容されますが、報告されます。最終提出では showcase を使用します。警告はすべてブロッキングエラーになります。

python3 skills/btp-diagram-generator/scripts/validate_diagram.py \
  <file.drawio> --quality standard --json

python3 skills/btp-diagram-generator/scripts/validate_diagram.py \
  <file.drawio> --quality showcase --json

JSON レシートには、安定した診断コード、対象箇所の正確なローカル位置、対応する修正方法、チェックごとのステータス、成果物のバイト数と SHA-256 が含まれます。失敗した場合は、診断された箇所だけを変更して、検証を再実行します。修正を 2 回続けてもエラー数が減らない場合は、図全体を書き直さず、解決されていない診断を報告して作業を停止してください。

最終 showcase のレシートが合格した時点で、成果物は確定します。その後は編集しないでください。合格したファイルそのものだけを開くか、エクスポートしてください。検証または保存に失敗し、古い出力が残っている場合、そのファイルが最後に正常だった成果物であり、却下された候補ではありません。

ぼやけたアイコン（SVG の固有サイズがセルより小さい）について警告された場合は、その場で修正してください。

python3 skills/btp-diagram-generator/scripts/upscale_svg_icons.py <file.drawio> --size 48 --in-place

自動検証で確認できるのは、XML 構造、コネクターとスタイルの契約、およびバイト単位の同一性です。見た目の仕上がりは確認できません。次の項目は別途、目視で確認してください。

• すべてのラベルが XML エスケープされている（生の <font> が表示されていない）。
• 図形が重なっていない（間隔は 20px 以上）。
• BTP コンテナーがすべての BTP サービスを視覚的に囲み、外部システムがその外側に配置されている。
• L0 図には凡例がなく、コネクターはニュートラルになっている。L2 図には右上に凡例カードがあり、タイトルの下に説明ブロックがある。
• エッジラベルはピル型の vertex セルであり、edge="1" セルの value= にインラインで指定されていない。
• コネクターが無関係なコンテナーを通過していない。
• 要求されていないコンポーネントが含まれていない（許可リストと照合する）。
• サービスの並び順がユーザーの指定どおりである。
• CIS が Subaccount の外側、BTP の内側にある。
• 凡例がある場合、コネクターと重なっていない。

これ以外の項目はバリデーターが確認します。対象は、ルートセル、一意の ID、vertex と edge の排他性、mxgraph.sap.* がないこと、エッジの source/target の有効性、ポートの固定、手動ウェイポイント、セルの形状に対する SVG の固有サイズ、パレットの色、A4 横向きのページサイズです。

より詳細な検証については、mxfile.xsd とスタイル参照チェックリストを参照してください。

最終回答のテンプレート

完了したら、次の内容を回答してください。

1. ワークスペース相対の Markdown リンクで示した保存先のファイルパス。
2. 図を MCP エディターで開いたかどうか（開いた場合はその方法）、または代替の URL／手順。
3. 最終的な品質プロファイル、チェック数、エラー数／警告数、JSON レシートに記載された成果物の SHA-256 とバイト数。
4. 自動検証とは別に、目視レビューのステータス。
5. 行った前提と、汎用タイルに置き換えたアイコンがあれば、それらを短い箇条書きで示し、ユーザーが修正できるようにする。
6. 図を draw.io ワークスペースでダークテーマを使って開いた場合は、SAP ラベル（#1D2D3E）が Fiori Horizon 仕様に従って意図的に暗く設定されており、ダークキャンバスでは薄く見えることを伝える。確認するには、draw.io をライトテーマに切り替えるか、PNG／SVG にエクスポートする。
7. 反復方法を一文で示す（例：「サービス X の追加、または対象ユーザー層を L2 に変更するよう依頼してください」）。

同梱アセット

• references/icon-index.json — すべての BTP サービスアイコン 100 個と汎用ユーザーアイコン 3 個（generic:user-sap／-non-sap／-highlight）のフラットな {title → {style, width, height}} マップです。アイコンスタイルの主要な参照元です。 Quick-Path ビルダーが読み込みます。
• references/icon-aliases.json — 短縮名から正規キーへのマップです（"task center"、"cpi"、"hana cloud"、"end user" などのエイリアス 132 個）。BtpDiagram.service() のあいまい検索に使用します。
• references/styles.json — SAP の名前付きスタイル文字列（container_btp、card_subaccount、tile_external_sap、arrow_dblhd、pill_auth など）、ポートピンのフラグメント、レベルごとのアイコンサイズが含まれています。ビルダーによって読み込まれます。XML を手作業で作成する際に、コピー＆ペースト用のリファレンスとして便利です。
• references/templates/ — すぐに内容を追加できる、空の L0／L1／L2 mxfile スケルトンです。
• references/sap-logo.b64.txt — btp_container(with_logo=True) に埋め込まれる、SAP のコーナーロゴ SVG の base64 データです。
• references/libraries/ — SAP 公式の draw.io mxlibrary XML ファイル 7 個（foundational、integration-suite、app-dev-automation、data-analytics、AI、BTP-SaaS、オールインワンのサイズ M セット）です。インデックスにない生のライブラリデータが必要な場合に使用します。
• references/svg/ — すべての BTP サービスアイコンの生の .svg ソースファイル 129 個です。アイコンを編集・再配色する場合、draw.io 以外の形式にエクスポートする場合、または draw.io のスタイル文字列以外にアイコンを埋め込む場合に使用します。
• references/examples/ — SAP 公式の編集可能なサンプル図 11 個（Task Center L0／L1／L2、Build Work Zone L2、Process Automation L2、Cloud Identity Services L1／L2、Private Link L2、SAP Start L2）です。複合スタイルパターンの主要な参照元です（サブアカウントカード、ネットワーク境界、ピルラベル、凡例カード）。
• references/sap-btp-palette.json — 上記の正確なカラーコードです。draw.io の Extras → Configuration の customColorSchemes にコピーして使用できます。
• references/example-patterns.md — サンプル図から抽出した、すぐにコピーできるスタイル文字列、サイズ、ラベル HTML、コネクター／ピルのレシピです。コンテナー、アイコン、エッジ、ピルの正確なスタイルが必要な場合は、必ず参照してください。独自に推測しないでください。

同梱スクリプト

scripts/ 内にあり、uv run python で実行できます（サードパーティ依存関係はありません）。

• scripts/btp_builder/ — Quick-Path パッケージです。BtpDiagram DSL、エイリアス解決に対応したアイコン検索、パレット定数、ポートピンヘルパー、SVG のアップスケーリング、名前付きスタイルが含まれています。from btp_builder import BtpDiagram としてインポートします。
• scripts/examples/task_center_arch.py — Task Center のリファレンスアーキテクチャを最初から最後まで再現する、実行可能な標準サンプルです。
• scripts/open_diagram.py — OS のオープナー（macOS の open、Linux の xdg-open、Windows の start）を使って .drawio ファイルを開きます。開けない場合は、app.diagrams.net の URL を出力します。
• scripts/validate_diagram.py — §7 のチェックリストを適用します。mxgraph.sap.* の誤記、ID の重複、source／target が壊れたエッジ、ポートピンの不足、手動のウェイポイント、パレット外の色、SVG の固有サイズによるぼやけを検出します。警告ゼロの最終チェックと機械可読な結果を得るには、--quality showcase --json を使用します。従来の --strict-palette フラグと --strict-waypoints フラグも引き続き使用できます。Python から再利用するための validate_xml(xml)／validate_path(path) も公開しています。
• scripts/upscale_svg_icons.py — ルートの <svg> の width／height をセルのジオメトリに合わせて修正し、ぼやけたアイコンを直します（viewBox は変更しません）。既定のターゲットは 48 px です。L2 には --size 32、L0 には --size 50 を指定します。上書きするには --in-place を使用します。（Quick-Path ビルダーはこれを自動的に適用します。手作業で作成した XML に対してのみ手動で実行してください。）

レイアウトのヒント

コネクタの重なりを避ける

接続が多い図を生成するときは、次の点に従います。

1. 出入口の位置を固定する — コネクタには常に明示的な exitX、exitY、entryX、entryY を設定し、図形から出る位置と図形に到達する位置を正確に制御します。
2. 周囲に分散する — 1つの図形から N 本の接続を出す場合は、出口の位置を分散します。例：下辺に3本なら exitX=0.25、0.5、0.75 とします（すべてを exitX=0.5 にしないでください）。
3. 中継点を使う — 複雑な経路では、<Array as="points"> の中に <mxPoint> の中継点を追加し、エッジが特定の経路を通るようにします。
4. 垂直方向の間隔をずらす — 接続が多い要素は異なる Y 座標に配置し、コネクタが通るスペースを確保します。
5. フローの種類を視覚的に分ける — フローの種類ごとに図形の異なる辺を使います（データフローは右側から出し、認証フローは下側から出します）。
6. 共有の接続先エリアにはコネクタを1本だけ使う — S/4HANA と SuccessFactors が1つの「SAP Cloud Solutions」エリア内にある場合は、それぞれから分岐させるのではなく、エリアの境界にコネクタを1本だけ接続します。
7. 外部の接続先は横に並ぶ列に配置する — SAP のリファレンス図のように、外部エリアをインテグレーションハブと水平方向に揃えます。

コネクタをコンテナ内に通さない

接続先ではないコンテナを、線が視覚的に通過してはいけません。

1. 経路全体（すべてのセグメント）をたどり、無関係なコンテナの境界ボックスと交差しないことを確認します。
2. 線の通り道が確保できるようにコンテナを配置します。
3. 各直交セグメントを個別に確認します。X=V の垂直線は、その X 座標にまたがるコンテナと交差してはいけません。Y=H の水平線は、その Y 座標にまたがるコンテナと交差してはいけません。

直線で均一な線（曲がり角は最小限に）

曲がり角は0が望ましく、通常は90°の曲がり角を1つまでにします。障害物によって避けられない場合に限り、2つ以上の曲がり角を許容します。

1. 中心座標を揃える — 2つの要素を直線でつなぐ場合は、同じ X 中心（垂直線）または Y 中心（水平線）を共有するようにします。
2. コネクタの形状に合わせてレイアウトを設計する — まず直線にするための制約を決めてから、要素を配置します。
3. 曲がり角の上限を守る：曲がり角0＝中心軸を共有、曲がり角1＝mxPoint を1つ固定、曲がり角2以上＝障害物による必然性がない限り却下して再配置します。
4. ずれた要素には自動の直交ルーティングを使わない — 意図しない迂回が発生します。中継点を明示的に固定します。

コネクタラベルのための間隔

コネクタがアイコンのラベル、製品名、エリアタイトルを通過してはいけません。

1. アイコンセルの value="" と、アイコンの下に配置する独立したテキストセルを使うのが望ましいです。
2. 垂直コネクタをアイコンの下まで続ける必要がある場合は、アイコンではなくラベルセルの下端から線を開始します。
3. 水平コネクタはアイコンの中心線に通し、ラベルはその下に配置します（exitY=0.5、entryY=0.5）。
4. 矢印の先端まで直線を少なくとも20px確保します。アイコンのすぐ横に曲がり角を配置しないでください。

SAP Cloud Identity Services の配置

CIS はサブアカウントの外側、BTP の内側に配置する必要があります（アイデンティティサービスはサブアカウント内ではなく BTP レベルでプロビジョニングされます）。

1. CIS はサブアカウントの下に配置し、BTP の境界内に収めます。
2. CIS は BTP の左側に配置し、右側にある Integration Suite からの垂直コネクタが CIS を横切らないようにします。
3. CIS コンテナ：白の塗りつぶし（#ffffff）とグレーの境界線（#475E75）を使用します（塗りつぶしを交互にするパターン：BTP は青、CIS は白）。
4. CIS → Subaccount：緑の破線による双方向の OIDC トラストコネクタを使用します。現代的な BTP トラストでは SAML 2.0 を使用しません。SAML は上流の企業 IdP フェデレーションにのみ適用されます。
5. ID プロビジョニングが求められる場合に限り、SCIM 2.0（インディゴ #5D36FF）を別に表示します。

アプリケーションクライアントの表示

アプリケーションクライアントは、コンテナーで囲まず、アイコンとラベルを独立して表示してください。

1. 「Application and User」コンポーネントグループの App Clients アイコンを使用します。
2. アイコンの value="" を設定し、その下に value="Application Clients
Mobile / Desktop" のテキストセルを別途追加します。
3. 水平方向のデータフローは、ラベルを通さず、アイコンの側面（exitY=0.5）から接続します。
4. その周囲にコンテナー領域を追加しないでください。

領域の入れ子における塗りつぶしパターン

入れ子にする場合は、塗りつぶしを必ず交互にします：blue → white → blue → white。

L0: BTP Platform   (border #0070F2, fill #EBF8FF)
  L1: Subaccount   (border #475E75, fill #ffffff)
    L2: Service group (border #0070F2, fill #EBF8FF)
  L1: CIS          (border #475E75, fill #ffffff)

青で塗りつぶされたコンテナーの直接の子要素は、必ず白で塗りつぶします（青の上に青を重ねないでください）。

凡例の配置

凡例は、コネクターや要素と重ならないようにしてください。

1. 空いている隅に配置します（フローが左から右、上から下に進むため、右下を推奨します）。
2. すべてのコネクターの経路を確認し、凡例がどの経路とも交差しないようにします。
3. コネクターが通る始点と終点の間には配置しないでください。

図のタイトルの配置

コンテナーの境界線でタイトルが隠れないようにしてください。

1. BTP コンテナーの上端より上に配置します（例：タイトルの y=10、BTP の y=50）。
2. または、BTP の内側に、境界線から 10px 以上の余白を空けて配置します。
3. すべての領域の上部に、タイトル用として 45～60px のスペースを確保します。

エクスポートのワークフロー（draw.io CLI）

前提条件

# macOS (Homebrew installs as `drawio`, no dot)
drawio --version

# macOS (full path fallback)
/Applications/draw.io.app/Contents/MacOS/draw.io --version

# Linux
draw.io --version

# Windows
"C:\Program Files\draw.io\draw.io.exe" --version

見つからない場合は、jgraph/drawio-desktop/releases からインストールします。

手順 1 — プレビュー PNG をエクスポートする（-e なし）

drawio -x -f png -s 2 -o diagram.png diagram.drawio

手順 2 — 自己チェック

利用可能な場合は、ビジョン機能を使ってエクスポートした PNG を確認します。

チェック項目	確認する内容
SAP のカラーが正しい	SAP は青 #0070F2、非 SAP はグレー #475E75
領域の入れ子	青と白の塗りつぶしが交互になっている
図形の重なり	すべての兄弟要素間に 20px 以上の間隔がある
ラベルの切り取り	テキストが切れている場合 → 図形のサイズを大きくする
接続の不足	矢印がつながっていない場合 → 始点／終点の ID を確認する
線のスタイル	実線＝同期、破線＝非同期
未リクエストのコンポーネント	許可リストにない製品 → 削除する
サービスの順序が誤っている	エッジの順序が指定された順序と異なる → 修正する
タイトルの衝突	アイコン／ラベルが領域タイトルに触れている → 確保したスペースの下に移動する
生の HTML テキスト	<font> マークアップが表示されている → エスケープを修正する

また、次を実行します：python3 scripts/validate_diagram.py diagram.drawio --strict-palette

自己チェックは最大 2 回までです。

手順 3 — レビューのループ

プレビューをユーザーに見せます。フィードバックに応じて、対象を絞った XML 編集を行います。承認されるまで繰り返します。**安全策：**5 回繰り返した後は、手動で細部を調整できるよう、draw.io デスクトップで .drawio を開くことを提案します。

手順 4 — 最終エクスポート（図を埋め込む場合は -e を指定）

# PNG with embedded diagram XML (editable in draw.io)
drawio -x -f png -e -s 2 -o diagram.drawio.png diagram.drawio

# SVG with embedded diagram
drawio -x -f svg -e -o diagram.drawio.svg diagram.drawio

# PDF
drawio -x -f pdf -o diagram.pdf diagram.drawio

主なフラグ：-x エクスポートモード · -f 形式 · -e 図の XML を埋め込む · -s スケール（PNG では 2 を推奨） · -o 出力先パス · -b 10 境界線。

既知の問題：-e を指定した PNG で IEND が切り詰められる

draw.io CLI は、IEND が 8 バイト切り詰められた -e PNG を出力するため、一部のビューアーや API でファイルが拒否されます。SVG／PDF のエクスポートには影響しません。最終 PNG が開けない場合は、ユーザーに表示する画像を -e なしで再エクスポートします。

フォールバックチェーン

シナリオ	動作
draw.io CLI がなく、Python が利用可能	.drawio を生成し、https://app.diagrams.net/?… のブラウザー URL を出力します
draw.io CLI と Python の両方がない	.drawio XML のみを生成し、手動で開くようユーザーに案内します
サンドボックス（macOS）で CLI を利用できない	ブラウザーのフォールバックを使用し、サンドボックス外のターミナルでエクスポートするようユーザーに依頼します
自己チェックで Vision を利用できない	視覚的な検証を省略し、ファイルをユーザーに提示します
Linux のヘッドレスエクスポートに失敗	xvfb-run -a drawio … を試し、EGL エラーが発生した場合は --disable-gpu を追加します

WSL2 の詳細

# CLI path on WSL2
"/mnt/c/Program Files/draw.io/draw.io.exe" --version

# Open exported file (convert path first)
cmd.exe /c start "" "$(wslpath -w diagram.drawio.png)"

よくある間違い

間違い	修正
ルートセル id="0" / id="1" がない	<root> の先頭に必ず両方を含めます
自己終了形式のエッジ mxCell（<mxCell ... edge="1" />）	子要素として <mxGeometry relative="1" as="geometry" /> を含む展開形式を使用します
XML コメント内に -- がある	XML 仕様では無効です — 言い換えてください
shape=mxgraph.sap.* スタイル	存在しません。icon-index.json の shape=image;image=data:image/svg+xml,... を使用します
ラベル内にリテラルの \n がある	value 属性内の改行には &#xa; を使用します
HTML ラベルの二重エスケープ	HTML 文字列を先に作成し、value="…" に挿入する前に全体を一度だけエスケープします（&amp;、&lt;、&gt;、&quot;）
図に未加工の <font> マークアップが表示される	生成後に XML パーサーで確認します。xml.etree.ElementTree.fromstring() を使用します
アイコンがぼやける	エンコード前に SVG の width / height をセルサイズに合わせて修正し、upscale_svg_icons.py を実行します
エッジが無関係なコンテナーを通過する	コンテナーの位置を変更するか、経由点を追加します
すべてのコネクターが同じ点から出る	外周に沿って出口／入口を分散します（exitX=0.25、0.5、0.75）
自動ルーティングでジグザグが発生する	経由点を明示的に固定し、直線になるよう中心を揃えます
データフローに strokeWidth=3 を使用する	太いグレーの線は、ファイアウォール／ネットワーク障壁にのみ使用します
command not found: draw.io（macOS）	Homebrew では drawio（ドットなし）としてインストールされます
Vision の「dimensions exceed 2576×2576px」	-s 2 ではなく --width 2000 を指定して再エクスポートします