qgraphflow 0.0.6 → 0.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. package/.claude-plugin/marketplace.json +1 -1
  2. package/.claude-plugin/plugin.json +1 -1
  3. package/.codex-plugin/plugin.json +2 -2
  4. package/.cursor-plugin/plugin.json +1 -1
  5. package/.qoder-plugin/plugin.json +1 -1
  6. package/README.md +119 -70
  7. package/docs/clients.de.md +15 -24
  8. package/docs/clients.es.md +15 -24
  9. package/docs/clients.ja.md +15 -24
  10. package/docs/clients.md +15 -24
  11. package/docs/clients.pt.md +15 -24
  12. package/docs/clients.ru.md +15 -24
  13. package/docs/clients.zh-CN.md +15 -24
  14. package/docs/readme/README.de.md +120 -71
  15. package/docs/readme/README.es.md +120 -71
  16. package/docs/readme/README.ja.md +120 -71
  17. package/docs/readme/README.pt.md +120 -71
  18. package/docs/readme/README.ru.md +120 -71
  19. package/docs/readme/README.zh-CN.md +106 -59
  20. package/examples/jeepay/README.md +23 -0
  21. package/examples/jeepay/capabilities.graph.json +270 -0
  22. package/examples/jeepay/class.graph.json +237 -0
  23. package/examples/jeepay/collection.graph.json +3057 -0
  24. package/examples/jeepay/dataflow.graph.json +212 -0
  25. package/examples/jeepay/deployment.graph.json +222 -0
  26. package/examples/jeepay/engineering.graph.json +277 -0
  27. package/examples/jeepay/er.graph.json +482 -0
  28. package/examples/jeepay/flowchart.graph.json +312 -0
  29. package/examples/jeepay/relations.graph.json +289 -0
  30. package/examples/jeepay/sequence.graph.json +355 -0
  31. package/examples/jeepay/source.json +95 -0
  32. package/examples/jeepay/state.graph.json +175 -0
  33. package/examples/jeepay/usecase.graph.json +222 -0
  34. package/package.json +14 -3
  35. package/skills/q-flow/SKILL.md +28 -20
  36. package/skills/q-flow/agents/openai.yaml +1 -1
  37. package/skills/q-flow/assets/viewer/package.json +1 -1
  38. package/skills/q-flow/assets/viewer/src/architecture-overview-theme.js +22 -0
  39. package/skills/q-flow/assets/viewer/src/architecture-overview.js +340 -0
  40. package/skills/q-flow/assets/viewer/src/diagrams/architecture.js +8 -5
  41. package/skills/q-flow/assets/viewer/src/diagrams/card.js +35 -17
  42. package/skills/q-flow/assets/viewer/src/diagrams/deployment.js +7 -5
  43. package/skills/q-flow/assets/viewer/src/diagrams/drawing.js +5 -2
  44. package/skills/q-flow/assets/viewer/src/diagrams/registry.js +10 -0
  45. package/skills/q-flow/assets/viewer/src/diagrams/sequence.js +13 -7
  46. package/skills/q-flow/assets/viewer/src/edge-routing.js +43 -22
  47. package/skills/q-flow/assets/viewer/src/export-svg.js +27 -5
  48. package/skills/q-flow/assets/viewer/src/graph-validation.js +72 -15
  49. package/skills/q-flow/assets/viewer/src/i18n-messages.json +184 -8
  50. package/skills/q-flow/assets/viewer/src/layout-compaction.js +123 -0
  51. package/skills/q-flow/assets/viewer/src/layout-measure.js +14 -8
  52. package/skills/q-flow/assets/viewer/src/layout-policy.js +6 -0
  53. package/skills/q-flow/assets/viewer/src/layout-quality.js +61 -15
  54. package/skills/q-flow/assets/viewer/src/layout-refinement.js +271 -0
  55. package/skills/q-flow/assets/viewer/src/layout-semantics.js +8 -0
  56. package/skills/q-flow/assets/viewer/src/layout-spacing.js +23 -4
  57. package/skills/q-flow/assets/viewer/src/layout-templates.js +298 -0
  58. package/skills/q-flow/assets/viewer/src/node-svg.js +1 -1
  59. package/skills/q-flow/assets/viewer/src/orthogonal-routing.js +475 -0
  60. package/skills/q-flow/assets/viewer/src/presentation-graph.js +31 -0
  61. package/skills/q-flow/assets/viewer/src/route-clearance.js +144 -0
  62. package/skills/q-flow/assets/viewer/src/sequence-executions.js +22 -0
  63. package/skills/q-flow/assets/viewer/src/sequence-fragments.js +20 -2
  64. package/skills/q-flow/assets/viewer/src/session-graph.js +46 -3
  65. package/skills/q-flow/assets/viewer/src/text-layout.js +33 -6
  66. package/skills/q-flow/assets/viewer/src/view-identity.js +26 -0
  67. package/skills/q-flow/assets/viewer/src/visual-style.js +13 -5
  68. package/skills/q-flow/assets/viewer-dist/index.html +30 -28
  69. package/skills/q-flow/references/evidence-sources.md +7 -5
  70. package/skills/q-flow/references/graph-common.md +34 -34
  71. package/skills/q-flow/references/graph-schema.md +28 -7
  72. package/skills/q-flow/references/guided-intake.md +51 -71
  73. package/skills/q-flow/references/layout-routing.md +47 -0
  74. package/skills/q-flow/references/types/architecture.md +42 -22
  75. package/skills/q-flow/references/types/class.md +9 -2
  76. package/skills/q-flow/references/types/dataflow.md +11 -4
  77. package/skills/q-flow/references/types/deployment.md +11 -3
  78. package/skills/q-flow/references/types/er.md +8 -1
  79. package/skills/q-flow/references/types/flowchart.md +12 -5
  80. package/skills/q-flow/references/types/sequence.md +20 -16
  81. package/skills/q-flow/references/types/state.md +10 -3
  82. package/skills/q-flow/references/types/usecase.md +6 -0
  83. package/skills/q-flow/references/viewer-development.md +37 -24
  84. package/skills/q-flow/references/visual-contract.md +12 -6
  85. package/skills/q-flow/scripts/compile-layout.mjs +85 -102
  86. package/skills/q-flow/scripts/compile-sequence.mjs +4 -21
  87. package/skills/q-flow/scripts/generate-viewer.mjs +18 -9
  88. package/skills/q-flow/scripts/validate-graph.mjs +38 -21
  89. package/examples/order-flow.graph.json +0 -94
@@ -1,6 +1,6 @@
1
1
  <div align="center">
2
2
 
3
- # QGraphFlow
3
+ <h1><picture><source media="(prefers-color-scheme: dark)" srcset="../images/brand/qgraphflow-lockup-dark.svg"><img src="../images/brand/qgraphflow-lockup-light.svg" alt="QGraphFlow" height="64"></picture></h1>
4
4
 
5
5
  ### 複雑なコードを、探索できる図へ。
6
6
 
@@ -10,17 +10,25 @@
10
10
 
11
11
  [English](../../README.md) · [中文](../../docs/readme/README.zh-CN.md) · [Русский](../../docs/readme/README.ru.md) · [Português](../../docs/readme/README.pt.md) · [日本語](../../docs/readme/README.ja.md) · [Deutsch](../../docs/readme/README.de.md) · [Español](../../docs/readme/README.es.md)
12
12
 
13
- [オンラインデモ](https://supermax92.github.io/qgraphflow/) · [クライアントへの導入](#インストールガイド) · [問題を報告](https://github.com/supermax92/qgraphflow/issues) · [MIT](../../LICENSE)
13
+ [オンラインデモ](https://supermax92.github.io/qgraphflow/) · [はじめに](#はじめに) · [クライアントへの導入](#インストールガイド) · [問題を報告](https://github.com/supermax92/qgraphflow/issues) · [MIT](../../LICENSE)
14
14
 
15
15
  </div>
16
16
 
17
- ![agent-desk サンプルのアーキテクチャ図・シーケンス図・ER 図を 1.5 秒ずつ](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/agent-desk.ja.hero.gif)
18
-
19
- *9種類の図に対応:アーキテクチャ、フローチャート、シーケンス、ER、配置、クラス、状態、ユースケース、データフロー。*
17
+ *11 種類の図に対応:プラットフォーム機能アーキテクチャ図、エンジニアリング層アーキテクチャ図、コンポーネント関係アーキテクチャ図、フローチャート、シーケンス図、ER 図、配置図、クラス図、状態図、ユースケース図、データフロー図。*
20
18
 
21
19
  QGraphFlow はソースコード、データ構造、設定、要件から対話型のソフトウェア図を生成します。関係の根拠を確認し、共有可能なオフライン HTML として届けます。
22
20
 
23
- **ここが違う:** 1 つのスキルで 9 種類の図、すべての関係に出典、自動レイアウト、ページ上での編集。プラグインのスクリプトと Viewer 自体はネットワーク通信を一切行いません。
21
+ **ここが違う:** 1 つのスキルで 11 種類の図、すべての関係に根拠の種別、コードで裏付けられた関係にはその根拠となるソース行、自動レイアウト、ページ上での編集。プラグインのスクリプトと Viewer 自体はネットワーク通信を一切行いません。
22
+
23
+ ![Jeepay の複数ビュー操作デモ:コンポーネント関係アーキテクチャ図、シーケンス図、ER 図](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/jeepay.en.hero.gif)
24
+
25
+ Jeepay の実際のソースを例に、コンポーネント関係アーキテクチャ図、シーケンス図、ER 図を切り替えて、コンポーネントと呼び出し関係を探索します。 [原寸の GIF を見る](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/jeepay.en.hero.gif)
26
+
27
+ **複雑なシーケンス図の紹介**
28
+
29
+ ![複雑なシーケンス図の段階的な描画:参加者、ライフライン、メッセージ、活性区間、入れ子の結合フラグメント](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/checkout.en.sequence-drawing.gif)
30
+
31
+ 架空の EC シナリオに 9 人の参加者、29 件のメッセージ、6 個の結合フラグメントを含め、在庫の再試行、入れ子の分岐、並行処理、失敗時の補償、非同期コールバックを扱います。生成済みの図をアニメーションで段階的に表示し、複雑なシーケンス図の構造と詳細を紹介します。 [原寸の GIF を見る](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/checkout.en.sequence-drawing.gif)
24
32
 
25
33
  ```bash
26
34
  npx skills add supermax92/qgraphflow
@@ -30,21 +38,67 @@ npx skills add supermax92/qgraphflow
30
38
 
31
39
  - **探索:** 検索・拡大縮小・パンで、責務と上流・下流の関係を確認。
32
40
 
33
- ![探索:refund を検索して注文ツールへジャンプし、上流のエージェントオーケストレーターと下流の注文データベース・配送追跡サービスが見えるまで縮小してからパンする](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/agent-desk.ja.explore.gif)
34
-
35
41
  - **検証:** ノードや接続線からファイル、行番号、シンボル、明示された不確実性を確認。
36
42
 
37
- ![検証:src/gateway/chat-gateway.js:5-19 を示すカード、シンボルと根拠事実を示す詳細パネル、そして inference と記された POST /chat の接続線](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/agent-desk.ja.verify.gif)
38
-
39
43
  - **編集:** ロック解除後に文字や位置を変更。必要に応じてリセット。
40
44
 
41
- ![編集:ロックを解除し、LLM プロバイダーを LLM ゲートウェイに改名し、接続線ごとドラッグしてからリセットする](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/agent-desk.ja.edit.gif)
42
-
43
45
  - **共有:** オフライン HTML を開くか、図全体を SVG / PNG に出力。
44
46
 
45
- ![共有:オフライン HTML を開き、「その他」から PNG を書き出し、書き出されたファイルそのものを表示する](https://github.com/supermax92/qgraphflow/releases/download/showcase-v2/agent-desk.ja.share.gif)
47
+ 実際のソースに基づく [Jeepay コーパス](../../examples/jeepay)には、CI とオンラインデモで使う 11 種類のビューがすべて含まれます。
48
+
49
+ ## はじめに
50
+
51
+ インストール後、クライアントで業務プロジェクトを開き、`q-flow` スキルを選択します。以下は Claude Code の `/q-flow` を使う例です。Codex ではクライアントが実際に提供する `$q-flow` または `$qgraphflow:q-flow` を使ってください。まだインストールしていない場合は、先に[インストールガイド](#インストールガイド)を参照してください。
52
+
53
+ ### 1. 空の入力:どこから始めるか分からない
54
+
55
+ 要件を付けずにスキルだけを呼び出します。
56
+
57
+ ```text
58
+ /q-flow
59
+ ```
60
+
61
+ スキルが、分析する部分と図で答えてほしい問いの選択を案内します。必要な情報が明確になったら描画を始めます。
62
+
63
+ ### 2. 機能を尋ねる:何を描けるか知る
64
+
65
+ ```text
66
+ /q-flow どの種類の図を描けますか?各種類はどのような問いに答えるのに適していますか?プロジェクトを引き継いだばかりなので、まず機能を紹介し、始める場所を提案してください。
67
+ ```
68
+
69
+ まず 11 種類の図の用途を知り、それからプロジェクト構造、呼び出し順序、データ関係など、何を見るかを決めます。
70
+
71
+ ### 3. 曖昧な入力:大まかな目的だけがある
72
+
73
+ ```text
74
+ /q-flow このプロジェクトを図にしてください。できるだけ早く理解したいです。
75
+ ```
76
+
77
+ 先に図の種類を指定する必要はありません。スキルがプロジェクトと目的に応じて適したビューを決め、必要な情報が不足している場合に質問します。
78
+
79
+ ### 4. 正確な入力:範囲を明示して描画の詳細を求める
80
+
81
+ 次の業務名と手順を、プロジェクトに実際に存在するフローに置き換えてください。
82
+
83
+ ```text
84
+ /q-flow 現在のプロジェクトの注文作成フローを分析し、中国語のシーケンス図を生成してください。
85
+ リクエスト入口、価格計算、在庫引当、支払い承認、注文の永続化を含めてください。
86
+ ソースに実際に存在する同期呼び出し、非同期メッセージ、対応する戻り、活性区間、条件分岐、再試行、失敗時の補償を残し、簡潔さのために詳細を省略しないでください。
87
+ コンポーネントと呼び出しのソースファイルと行番号を示し、結果を docs/qgraphflow/order-sequence/ に保存してください。
88
+ ```
89
+
90
+ 対象、問い、詳細度、出力先を明確に伝えると、そのまま開始できます。図には根拠のある事実だけを残します。
91
+
92
+ ### 5. さらに詳しく:前の図の一部分を展開する
93
+
94
+ 結果の生成後、同じ会話で続けます。
95
+
96
+ ```text
97
+ /q-flow 前のシーケンス図の在庫引当ステップを展開し、独立した中国語のフローチャートを生成してください。
98
+ 在庫確認、引当成功、再試行可能な失敗、再試行上限、在庫解放の分岐をすべて示してください。ソースコードに従い、コードにない手順は追加しないでください。
99
+ ```
46
100
 
47
- 上部のアニメーションはアーキテクチャ図・シーケンス図・ER 図を 1.5 秒ずつ(1 ループ 4.5 秒)表示し、4 つの機能アニメーションは 6.5〜8.5 秒です。すべてソースからビルドした Viewer で [agent-desk サンプル](../../examples/showcase/agent-desk)(架空の業務、実在のコード)を日本語の図と UI で録画しています。[showcase-v2 Release のアセット](https://github.com/supermax92/qgraphflow/releases/tag/showcase-v2)として配置し、Git 履歴やプラグインパッケージには含めないため閲覧にはネットワークが必要です。生成された図の HTML 自体はオフラインで動作します。
101
+ まず全体を見てから、ひとつの手順を掘り下げます。既存の図の詳細追加や、関係の検証を続けて依頼することもできます。
48
102
 
49
103
  ## インストールガイド
50
104
 
@@ -62,9 +116,18 @@ npx skills add supermax92/qgraphflow
62
116
 
63
117
  ### 1. プラグインをダウンロード
64
118
 
65
- [qgraphflow-0.0.6.zip](https://github.com/supermax92/qgraphflow/releases/download/v0.0.6/qgraphflow-0.0.6.zip) をダウンロードし、隠しファイルを保持したまま専用のディレクトリに展開します。
119
+ npmjs.com からプラグインを取得します。アカウント、ログイン、トークンは不要です。業務プロジェクトの外に専用ディレクトリを作成します。
120
+
121
+ ```bash
122
+ mkdir qgraphflow-install
123
+ cd qgraphflow-install
124
+ npm install qgraphflow --ignore-scripts
125
+ cd node_modules/qgraphflow
126
+ ```
127
+
128
+ これでプラグインのルートディレクトリに移動できました。**npm でダウンロードしても、クライアントへのインストールは自動では行われません。** 手順 2 に進んでください。このパッケージには `qgraphflow` コマンドも含まれ、[図とコードを同期させる](#図とコードを同期させる)で使います。
66
129
 
67
- 以下のコマンドはすべて、**展開後の `skills/` を含むプラグインのルートディレクトリ**で実行してください。
130
+ 以下のコマンドはすべて、**`skills/` を含むプラグインのルートディレクトリ**で実行してください。
68
131
 
69
132
  ### 2. クライアントにインストール
70
133
 
@@ -81,17 +144,8 @@ codex plugin add qgraphflow@supermax92
81
144
 
82
145
  #### Claude Code
83
146
 
84
- ZIP をダウンロードせず、GitHub から直接インストールします:
85
-
86
147
  ```bash
87
- claude plugin marketplace add supermax92/qgraphflow
88
- claude plugin install qgraphflow@supermax92 --scope user
89
- ```
90
-
91
- または、展開したプラグインのルートで実行します:
92
-
93
- ```bash
94
- claude plugin marketplace add .
148
+ claude plugin marketplace add ./
95
149
  claude plugin install qgraphflow@supermax92 --scope user
96
150
  ```
97
151
 
@@ -107,9 +161,9 @@ qodercli plugins install .
107
161
 
108
162
  #### Qoder Desktop
109
163
 
110
- **推奨:** **Settings → Plugins → Marketplace** を開き、**代码图谱可视化** または **qgraphflow** を検索してインストールします。新しいセッションを開始し、`q-flow` を選択します。ZIP のダウンロードやソースのビルドは不要です。
164
+ **推奨:** **Settings → Plugins → Marketplace** を開き、**QGraphFlow** または **代码图谱可视化** を検索してインストールします。新しいセッションを開始し、`q-flow` を選択します。
111
165
 
112
- ローカルインストールの場合は手順 1 を完了し、**Settings → Plugins → Custom → Import** を開いて、展開したプラグインのルートディレクトリ全体をインポートします。新しいセッションで `q-flow` を選択します。
166
+ ローカルインストールの場合は手順 1 を完了し、**Settings → Plugins → Custom → Import** を開いて、プラグインのルートディレクトリ全体をインポートします。新しいセッションで `q-flow` を選択します。
113
167
 
114
168
  #### Cursor
115
169
 
@@ -123,23 +177,7 @@ qodercli plugins install .
123
177
 
124
178
  ### 3. 使い始める
125
179
 
126
- クライアントで対象のプロジェクトを開き、新しいセッションでスキルを選択します。下の[すぐに使う](#すぐに使う)の例を参考に依頼し、生成された HTML をブラウザで開いてください。
127
-
128
- <details>
129
- <summary>別のインストール方法:npm</summary>
130
-
131
- ZIP の代わりに npmjs.com からプラグインを取得することもできます。アカウント、ログイン、トークンは不要です。業務プロジェクトの外に専用ディレクトリを作成します。
132
-
133
- ```bash
134
- mkdir qgraphflow-install
135
- cd qgraphflow-install
136
- npm install qgraphflow --ignore-scripts
137
- cd node_modules/qgraphflow
138
- ```
139
-
140
- これでプラグインのルートディレクトリに移動できました。上記のクライアント別インストール手順に進んでください。**npm でダウンロードしても、クライアントへのインストールは自動では行われません。** このパッケージには `qgraphflow` コマンドも含まれ、[図とコードを同期させる](#図とコードを同期させる)で使います。
141
-
142
- </details>
180
+ クライアントで業務プロジェクトを開き、新しいセッションでスキルを選択します。[はじめに](#はじめに)の例を参考に要件を伝えてください。生成後、出力された HTML をブラウザで開きます。
143
181
 
144
182
  自分でビルドする場合は、[ソースからのビルド手順](https://github.com/supermax92/qgraphflow/blob/main/docs/distribution.md#prepare-locally)を参照してください。
145
183
 
@@ -158,7 +196,7 @@ $qgraphflow:q-flow
158
196
  ### 例1:プロジェクト構造を理解する
159
197
 
160
198
  ```text
161
- $qgraphflow:q-flow 現在のプロジェクトを分析し、主要モジュールの責務、依存関係、システム境界を示す日本語のアーキテクチャ図を作成してください。
199
+ $qgraphflow:q-flow 現在のプロジェクトを分析し、主要モジュールの責務、依存関係、システム境界を示す中国語のアーキテクチャ図を作成してください。
162
200
  ```
163
201
 
164
202
  初めて触れるプロジェクトの全体像をつかむのに適しています。
@@ -166,13 +204,13 @@ $qgraphflow:q-flow 現在のプロジェクトを分析し、主要モジュー
166
204
  ### 例2:業務の呼び出しを追う
167
205
 
168
206
  ```text
169
- $qgraphflow:q-flow 注文作成フローを分析し、価格計算、在庫引当、支払い、注文保存の呼び出し順と失敗分岐を示す日本語のシーケンス図を作成してください。
207
+ $qgraphflow:q-flow 注文作成フローを分析し、価格計算、在庫引当、支払い、注文保存の呼び出し順と失敗分岐を示す中国語のシーケンス図を作成してください。
170
208
  ```
171
209
 
172
210
  「注文作成」と各手順を実際の業務フローに置き換えてください。同じ会話で続けて依頼できます。
173
211
 
174
212
  ```text
175
- $qgraphflow:q-flow 前の図の在庫引当を掘り下げ、成功時と失敗時の処理を示す日本語のフローチャートを別に作成してください。
213
+ $qgraphflow:q-flow 前の図の在庫引当を掘り下げ、成功時と失敗時の処理を示す中国語のフローチャートを別に作成してください。
176
214
  ```
177
215
 
178
216
  既定の保存先は `docs/qgraphflow/` 配下です。`index.html` を開いて探索・編集・出力でき、`graph.json` に図データが残ります。各ビューは SVG(`diagram.svg`、複数ビューでは `diagram-<n>-<type>.svg`)としても書き出され、README、プルリクエスト、Wiki に画像として埋め込めます。
@@ -180,26 +218,23 @@ $qgraphflow:q-flow 前の図の在庫引当を掘り下げ、成功時と失敗
180
218
  ページで編集したあと、Chrome または Edge で「その他 → 変更を保存」を実行し、図のフォルダーを一度選ぶと、ページ、`graph.json`、SVG がその場で書き換わります。ほかのブラウザーは `graph.json` だけを保存します。そのフォルダーに置いてから `npx -y qgraphflow generate docs/qgraphflow/<name>/graph.json docs/qgraphflow/<name> --layout preserve --force` でページと SVG を再生成してください。
181
219
 
182
220
  <details>
183
- <summary>EC の9種類のサンプルを手動で実行</summary>
221
+ <summary>Jeepay のソースに基づく 11 ビューの例を実行する</summary>
184
222
 
185
- 次のコマンドはリポジトリ内のサンプル用です。導入済みプラグインの使用には、このリポジトリの複製は不要です。Node.js 22 以降を用意して実行します。
223
+ 根拠を検証するため、ローカルの Jeepay ソースチェックアウトを指定してください。
186
224
 
187
225
  ```bash
188
- git clone https://github.com/supermax92/qgraphflow.git
189
- cd qgraphflow
190
- node skills/q-flow/scripts/validate-graph.mjs examples/showcase/ecommerce.ja.graph.json
191
- node skills/q-flow/scripts/generate-viewer.mjs examples/showcase/ecommerce.ja.graph.json output/ecommerce-ja
226
+ export JEEPAY_REPO_ROOT="<local Jeepay repository root>"
227
+ node skills/q-flow/scripts/validate-graph.mjs examples/jeepay/collection.graph.json --input-only --repo-root "$JEEPAY_REPO_ROOT"
228
+ node skills/q-flow/scripts/generate-viewer.mjs examples/jeepay/collection.graph.json output/jeepay --repo-root "$JEEPAY_REPO_ROOT"
192
229
  ```
193
230
 
194
- ブラウザーで `output/ecommerce-ja/index.html` を開きます。9 つの SVG も同じディレクトリにあります。上部の「図の種類」から切り替えます。各図で保存した文字と位置は切り替えても保持されます。「その他 → 変更を保存」で、上で説明したとおり全ビューを保存します。同じページは[オンラインデモ](https://supermax92.github.io/qgraphflow/)でも見られます。
195
-
196
- ビルド済み Viewer からのページ生成には、依存関係のインストール、API キー、バックエンドは不要です。AI による根拠収集と図の作成には、選んだクライアントのモデルサービスを使います。
231
+ `output/jeepay/index.html` を開いてください。11 個の SVG も同じディレクトリにあります。ソースのリビジョンと更新手順は[コーパスの README](../../examples/jeepay)を参照してください。
197
232
 
198
233
  </details>
199
234
 
200
235
  ## 図とコードを同期させる
201
236
 
202
- リポジトリのルートを指定して生成した図には、各コンポーネントの定義位置が記録されます。`--repo-root` 付きで検証すると、記録したファイルがない、行範囲がファイルに収まらない、記録したシンボルが元の行範囲から外れた、のいずれかで失敗し、エラーにはシンボルの現在の行が示されます。次のジョブを CI に追加してください。ビルド、ログイン、トークンは不要です。
237
+ リポジトリのルートを指定して生成した図には、各コンポーネントの定義位置と、コードで裏付けられた各関係を成立させている行(呼び出し、外部キーなど)が記録されます。`--repo-root` 付きで検証すると、記録したファイルがない、行範囲がファイルに収まらない、記録したシンボルが元の行範囲から外れた、のいずれかで失敗し、エラーにはシンボルの現在の行が示されます。次のジョブを CI に追加してください。ビルド、ログイン、トークンは不要です。
203
238
 
204
239
  ```yaml
205
240
  name: Diagrams
@@ -227,19 +262,21 @@ $qgraphflow:q-flow CI で docs/qgraphflow/order-sequence の図が古いと出
227
262
 
228
263
  スキルは、ファイル内で 1 か所だけ見つかったシンボルのアンカーを移し、なお失敗するアンカーだけを修正し、編集した位置と文字を保ったままページと SVG を再生成します。図を描き直すことはしません。
229
264
 
230
- ## 9種類の図が答えること
265
+ ## 11 種類の図がそれぞれ答えること
231
266
 
232
- | 図 · PNG | 主な問い | サンプルの範囲 |
267
+ | ビュー · PNG | 主な問い | 本サンプルの範囲 |
233
268
  | --- | --- | --- |
234
- | アーキテクチャ | どの責務が協調するか? | チャネル、決済、価格、リスク、在庫、支払い、注文、イベント、出荷 |
235
- | フローチャート | 判断はどこで分岐・合流するか? | 欠品、リスク拒否、支払い補償、正常コミット |
236
- | シーケンス | 呼び出しと戻りの順序は? | 決済成功経路と非同期 OrderPaid |
237
- | ER | 主要データはどう関連するか? | カート、注文、明細、支払い、引当、荷物 |
238
- | 配置 | 実行単位をどこに置き、どう接続するか? | エッジ、Kubernetes、データサービス、支払い、倉庫配送ネットワーク |
239
- | クラス | ドメインオブジェクトと契約はどう依存するか? | 決済サービス、Order、4つのポート |
240
- | 状態 | どのイベントとガードが注文を進めるか? | 支払い、出荷、取消、返金、終了 |
241
- | ユースケース | 各利用者に何ができるか? | 購入者、店舗、倉庫、サポート |
242
- | データフロー | データをどう変換・保存するか? | カート、取引判断、注文イベント、倉庫、配送受領記録 |
269
+ | プラットフォーム機能アーキテクチャ図 | プラットフォームにはどんな機能があるか? | 機能の区分とマトリクス |
270
+ | エンジニアリング層アーキテクチャ図 | プロジェクトのコードはどう構成されているか? | エンジニアリング層と共通の支援機能 |
271
+ | コンポーネント関係アーキテクチャ図 | システムのどの責務境界が協調するか? | チャネル、取引のオーケストレーション、価格、リスク、在庫、支払い、注文、イベント、注文履行 |
272
+ | フローチャート | 各判断点はどう分岐・合流するか? | 欠品、リスク拒否、支払い失敗時の補償、正常コミット |
273
+ | シーケンス図 | ひとつのリクエストはどの順序で呼び出しと戻りを行うか? | 決済成功の主経路と非同期 OrderPaid |
274
+ | ER 図 | 主要データはどう関連するか? | カート、注文、明細、支払い、在庫引当、荷物 |
275
+ | 配置図 | 実行単位をどこに置き、どう接続するか? | エッジ、Kubernetes、データサービス、支払い、倉庫配送ネットワーク |
276
+ | クラス図 | ドメインオブジェクトとコードの契約はどう依存するか? | Checkout アプリケーションサービス、Order、4 つのポート |
277
+ | 状態図 | どのイベントとガード条件が注文を進めるか? | 支払い、注文履行、取消、返金、終了 |
278
+ | ユースケース図 | 各参加者にはどんな機能があるか? | 購入者、店舗、倉庫、カスタマーサポート |
279
+ | データフロー図 | データ資産はどの変換と保存を経るか? | カート、取引判断、注文イベント、倉庫配送、配送受領記録 |
243
280
 
244
281
  これは QGraphFlow の機能を示す概念モデルで、特定の EC リポジトリに対応しません。サンプルの `graph.json` に架空のソースパスは入れず、関係の証拠を `inference` に統一しています。実際のプロジェクトでは、追跡可能なソース、DDL、設定、テスト、合意済み要件を使ってください。
245
282
 
@@ -253,10 +290,22 @@ node --test tests/*.test.mjs skills/q-flow/scripts/*.test.mjs
253
290
 
254
291
  開発には Node.js 22 以降、npm、tar、zip、unzip が必要です。問題報告には、機密情報を除いた最小限の図データ、クライアントとブラウザーのバージョン、再現手順を添えてください。
255
292
 
256
- リファレンス(英語):[証拠の出典](../../skills/q-flow/references/evidence-sources.md) · [図データ形式](../../skills/q-flow/references/graph-schema.md) · [対話による要件確認](../../skills/q-flow/references/guided-intake.md) · [Viewer の開発](../../skills/q-flow/references/viewer-development.md) · [図の構成](../../skills/q-flow/references/visual-contract.md)
293
+ リファレンス(英語):[証拠の出典](../../skills/q-flow/references/evidence-sources.md) · [図データ形式](../../skills/q-flow/references/graph-schema.md) · [対話による要件確認](../../skills/q-flow/references/guided-intake.md) · [Viewer の開発と受け入れ検証](../../skills/q-flow/references/viewer-development.md) · [図の構成](../../skills/q-flow/references/visual-contract.md)
257
294
 
258
295
  ## ライセンスと帰属
259
296
 
260
297
  [MIT](../../LICENSE) · [第三者の表示](../../THIRD_PARTY_NOTICES.md)
261
298
 
262
- QGraphFlow は MIT ライセンスの独立プロジェクトです。本文のシナリオは概念例で、実在する企業の本番構成を表しません。提携、後援、推奨を意味するものでもありません。
299
+ QGraphFlow は MIT ライセンスを採用する独立したプロジェクトです。本文のシナリオは概念例で、実在する企業の本番アーキテクチャを表しません。
300
+
301
+ ## アーキテクチャの全体像
302
+
303
+ アーキテクチャには、コンポーネント関係、プラットフォーム機能、エンジニアリング層が含まれます。対象と問いを伝えると、スキルがテンプレートを選びます。依頼したコレクションには、個別に編集できる複数のアーキテクチャビューを含められます。
304
+
305
+ ```text
306
+ $qgraphflow:q-flow 現在のプロジェクトのプラットフォーム機能と業務の接続方法を分析し、中国語のプラットフォーム機能全体図を生成してください。
307
+ $qgraphflow:q-flow 現在のプロジェクト構成とコンポーネントの階層を分析し、プロジェクト全体とひとつのコンポーネント断面の中国語の全体図を生成してください。
308
+ $qgraphflow:q-flow このプロジェクトのプラットフォーム機能の全体図を英語で生成し、アプリケーションモジュールがどのように統合されるかを示してください。
309
+ ```
310
+
311
+ 実際のソースに基づくプラットフォーム、エンジニアリング、コンポーネント関係のアーキテクチャビューは [examples/jeepay](../../examples/jeepay)を参照してください。全体図のロックを解除すると、同じ層のカードの並べ替えや文字の編集ができます。保存は全ビューを保持し、リセットは現在のビューだけを戻します。