# 画面設計書 186-ワークフロー実行詳細画面

## 概要

本ドキュメントは、Medusa Admin Dashboard におけるワークフロー実行詳細画面の設計仕様を定義する。

### 本画面の処理概要

ワークフロー実行詳細画面は、特定のワークフロー実行の詳細情報を表示し、各ステップの状態や実行結果を確認するための画面である。

**業務上の目的・背景**：
ワークフローベースのシステムにおいて、処理の詳細な実行状況を把握することは、障害対応やパフォーマンス分析に不可欠である。本画面では、ワークフロー実行のタイムライン、各ステップの入出力データ、エラー情報などを詳細に確認でき、問題の原因特定や処理結果の検証に活用できる。開発者やシステム管理者が効率的にトラブルシューティングを行うための情報を提供する。

**画面へのアクセス方法**：
設定画面 > ワークフロー実行一覧画面 > 対象の実行行をクリックすることでアクセスする。

**主要な操作・処理内容**：
1. ワークフロー実行の基本情報を確認（実行ID、ワークフローID、トランザクションID、状態）
2. タイムラインでワークフローの全体構造と各ステップの状態を視覚的に確認
3. ペイロード（入力データ）の確認
4. 各ステップの履歴と詳細（定義、出力、エラー情報）を確認
5. 特定のステップへのスクロールナビゲーション

**画面遷移**：
- 遷移元：ワークフロー実行一覧画面
- 遷移先：なし（詳細閲覧のみ）

**権限による表示制御**：
管理者権限を持つユーザーのみがアクセス可能。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 93 | ワークフロー実行 | 主機能 | ワークフロー実行詳細の表示 |
| 94 | ワークフローオーケストレーション | 補助機能 | ステップ状態の確認 |

## 画面種別

詳細

## URL/ルーティング

`/settings/workflows/:id`

## 入出力項目

本画面は参照のみのため、入力項目はない。

## 表示項目

### 基本情報セクション

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| 実行ID | テキスト + コピーボタン | ワークフロー実行の識別子（wf_exec_プレフィックス除去） |
| 状態バッジ | StatusBadge | 実行状態を色分けして表示 |
| ワークフローID | バッジ | 実行されたワークフローの識別子 |
| トランザクションID | バッジ | トランザクションの識別子 |
| 進捗 | プログレス表示 | 完了ステップ数 / 全ステップ数 |

### タイムラインセクション

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| ステップノード | インタラクティブ図 | 各ステップをノードとして表示 |
| 接続線 | 矢印 | ステップ間の依存関係を表示 |
| ズームコントロール | ボタン群 | 50%〜150%のズーム調整 |
| リセットボタン | ボタン | キャンバスを初期状態に戻す |

### ペイロードセクション

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| 入力データ | JSONビューアー | ワークフローへの入力データ |

### 履歴セクション

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| ステップ一覧 | 折りたたみリスト | 各ステップの詳細情報 |
| ステップ状態 | カラーインジケーター | 成功/失敗/進行中/スキップなど |
| 定義 | コードブロック | ステップの定義JSON |
| 出力 | コードブロック | ステップの出力データ |
| エラー | コードブロック | エラー情報（エラー時のみ） |

## イベント仕様

### 1-画面初期表示

URLパラメータのIDを使用して`useWorkflowExecution`フックでワークフロー実行データをAPIから取得し、各セクションに表示する。

### 2-タイムラインのステップクリック

1. タイムライン上のステップノードをクリック
2. URLハッシュを変更（#ステップ名）
3. 履歴セクションの該当ステップを展開
4. 該当ステップまでスムーズスクロール

### 3-ズーム操作

1. ズームイン/アウトボタンで50%〜150%の範囲でスケール変更
2. ドロップダウンで特定のズーム倍率を選択
3. キャンバスのドラッグで表示範囲を移動

### 4-履歴ステップの展開/折りたたみ

1. ステップ行をクリック
2. 折りたたみ状態を切り替え
3. 展開時は定義・出力・エラー情報を表示

## データベース更新仕様

### 操作別データベース影響一覧

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面初期表示 | workflow_execution | SELECT | ワークフロー実行詳細の取得 |

### テーブル別更新項目詳細

本画面は参照のみのため、データベース更新は発生しない。

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| workflowExecutions.history.runningState | 情報 | 実行中表示 | ステップが実行中の場合 |
| workflowExecutions.history.skippedState | 情報 | スキップ表示 | ステップがスキップされた場合 |
| workflowExecutions.history.failedState | エラー | 失敗表示 | ステップが失敗した場合 |

## 例外処理

| 例外ケース | 処理内容 |
|-----------|----------|
| 対象のワークフロー実行が存在しない | エラーをスローし、エラーバウンダリでキャッチ |
| API通信エラー | エラーをスローし、エラーバウンダリでキャッチ |
| データ取得中 | SingleColumnPageSkeletonを表示 |

## 備考

- SingleColumnPageレイアウトを使用（JSON表示あり）
- 拡張ウィジェット機能に対応（workflow.details.before/after）
- タイムラインはmotion/reactライブラリを使用してアニメーション対応
- タイムラインはドラッグ操作で表示範囲を移動可能
- 各ステップの状態は色分けして視覚的に識別可能（緑:成功、オレンジ:進行中、赤:失敗、グレー:非アクティブ/スキップ）

---

## コードリーディングガイド

本画面を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

まず、ワークフロー実行のデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | types.ts | `packages/admin/dashboard/src/routes/workflow-executions/types.ts` | TransactionState, TransactionStepStateの定義 |
| 1-2 | constants.ts | `packages/admin/dashboard/src/routes/workflow-executions/constants.ts` | STEP_OK_STATES, STEP_ERROR_STATESなどの状態分類定数 |
| 1-3 | utils.ts | `packages/admin/dashboard/src/routes/workflow-executions/utils.ts` | 状態の翻訳と色の取得関数 |

**読解のコツ**: ステップの状態は複数のカテゴリに分類されており、それぞれ異なる色で表示される。

#### Step 2: エントリーポイントを理解する

画面のメインコンポーネントを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | workflow-detail.tsx | `packages/admin/dashboard/src/routes/workflow-executions/workflow-execution-detail/workflow-detail.tsx` | ページ構造と各セクションの配置 |

**主要処理フロー**:
1. **13行目**: useParamsでURLからidを取得
2. **15-16行目**: useWorkflowExecutionでワークフロー実行データを取得
3. **20-22行目**: ローディング中はスケルトンを表示
4. **28-41行目**: 4つのセクションコンポーネントを配置

#### Step 3: 各セクションコンポーネントを理解する

詳細画面の各セクションを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | workflow-execution-general-section.tsx | `.../components/workflow-execution-general-section/workflow-execution-general-section.tsx` | 基本情報の表示 |
| 3-2 | workflow-execution-timeline-section.tsx | `.../components/workflow-execution-timeline-section/workflow-execution-timeline-section.tsx` | タイムライン（キャンバス）の実装 |
| 3-3 | workflow-execution-history-section.tsx | `.../components/workflow-execution-history-section/workflow-execution-history-section.tsx` | 履歴の折りたたみ表示 |

**主要処理フロー（タイムラインセクション）**:
- **44-62行目**: createNodeClusters関数でステップを深さ別にクラスタ化
- **84-156行目**: Canvasコンポーネントでズーム・ドラッグ操作を実装
- **367-446行目**: Nodeコンポーネントで各ステップを表示、クリックでスクロール

**主要処理フロー（履歴セクション）**:
- **29-51行目**: _rootを除外し、到達不能なステップを特定
- **88-276行目**: Eventコンポーネントで各ステップの詳細を折りたたみ表示
- **110-114行目**: URLハッシュに応じて自動展開

### プログラム呼び出し階層図

```
ExecutionDetail (workflow-detail.tsx)
    │
    ├─ useParams() - URLパラメータからID取得
    │
    ├─ useWorkflowExecution(id) - ワークフロー実行データ取得
    │      └─ sdk.admin.workflowExecution.retrieve()
    │
    ├─ WorkflowExecutionGeneralSection - 基本情報
    │      └─ Progress - 進捗表示
    │
    ├─ WorkflowExecutionTimelineSection - タイムライン
    │      ├─ createNodeClusters() - ステップのクラスタ化
    │      ├─ Canvas - ズーム/ドラッグ可能なキャンバス
    │      └─ Node - 各ステップのノード表示
    │
    ├─ WorkflowExecutionPayloadSection - ペイロード
    │
    └─ WorkflowExecutionHistorySection - 履歴
           ├─ Event - 各ステップの詳細
           └─ StepState - ステップ状態の表示
```

### データフロー図

```
[入力]               [処理]                    [出力]

URLパラメータ ───▶ useWorkflowExecution ───▶ 各セクションに表示
    (id)              (API取得)

タイムライン
ノードクリック ───▶ URLハッシュ変更 ───▶ 履歴セクションスクロール
                                        ステップ展開
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| workflow-detail.tsx | `packages/admin/dashboard/src/routes/workflow-executions/workflow-execution-detail/workflow-detail.tsx` | ソース | 詳細画面のメインコンポーネント |
| workflow-execution-general-section.tsx | `.../components/workflow-execution-general-section/workflow-execution-general-section.tsx` | ソース | 基本情報セクション |
| workflow-execution-timeline-section.tsx | `.../components/workflow-execution-timeline-section/workflow-execution-timeline-section.tsx` | ソース | タイムラインセクション |
| workflow-execution-payload-section.tsx | `.../components/workflow-execution-payload-section/workflow-execution-payload-section.tsx` | ソース | ペイロードセクション |
| workflow-execution-history-section.tsx | `.../components/workflow-execution-history-section/workflow-execution-history-section.tsx` | ソース | 履歴セクション |
| workflow-executions.tsx | `packages/admin/dashboard/src/hooks/api/workflow-executions.tsx` | ソース | APIフック |
| types.ts | `packages/admin/dashboard/src/routes/workflow-executions/types.ts` | ソース | 型定義 |
| constants.ts | `packages/admin/dashboard/src/routes/workflow-executions/constants.ts` | ソース | 定数定義 |
| utils.ts | `packages/admin/dashboard/src/routes/workflow-executions/utils.ts` | ソース | ユーティリティ関数 |
