# 画面設計書 185-ワークフロー実行一覧画面

## 概要

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

### 本画面の処理概要

ワークフロー実行一覧画面は、システムで実行されたすべてのワークフローの実行履歴を一覧表示し、各実行の状態を確認するための画面である。

**業務上の目的・背景**：
Medusaはワークフローベースのアーキテクチャを採用しており、注文処理、在庫管理、支払い処理など多くの業務処理がワークフローとして実行される。本画面では、これらのワークフロー実行の履歴と状態を一覧で確認でき、システムの動作状況の監視やトラブルシューティングに活用できる。ワークフローの成功・失敗・進行中の状態を把握することで、運用上の問題を早期に発見し対応することが可能となる。

**画面へのアクセス方法**：
設定画面 > 「ワークフロー」メニューをクリックすることでアクセスする。URLに直接アクセスすることも可能。

**主要な操作・処理内容**：
1. ワークフロー実行一覧の閲覧 - 実行されたワークフローをテーブル形式で表示
2. ワークフロー実行の検索 - 検索機能で特定のワークフロー実行を絞り込み
3. ワークフロー実行詳細の確認 - 行をクリックして詳細画面へ遷移

**画面遷移**：
- 遷移元：設定画面
- 遷移先：ワークフロー実行詳細画面

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 93 | ワークフロー実行 | 主機能 | ワークフロー実行一覧の取得・表示 |

## 画面種別

一覧

## URL/ルーティング

`/settings/workflows`

## 入出力項目

本画面は一覧表示が主目的のため、入力項目は検索フィールドのみ。

| 項目名 | 項目ID | 型 | 必須 | 入力/出力 | バリデーション | 説明 |
|--------|--------|-----|------|-----------|----------------|------|
| 検索 | search | string | 任意 | 入力 | なし | ワークフロー実行の検索キーワード |

## 表示項目

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| タイトル | テキスト | "Workflow Executions" |
| サブタイトル | テキスト | ワークフロー実行の説明文 |
| 検索フィールド | テキスト入力 | キーワード検索 |
| ワークフロー実行テーブル | DataTable | ワークフロー実行の一覧 |
| ページネーション | コンポーネント | ページ切り替え |

### テーブルカラム

| カラム名 | 説明 |
|---------|------|
| 実行ID | ワークフロー実行の識別子 |
| ワークフローID | 実行されたワークフローの識別子 |
| 状態 | 実行状態（成功/失敗/進行中など） |
| 実行日時 | ワークフローが実行された日時 |

## イベント仕様

### 1-画面初期表示

`useWorkflowExecutions` フックを使用してAPIからワークフロー実行一覧を取得し、DataTableに表示する。

### 2-検索実行

検索キーワードに基づいてフィルタリングされたワークフロー実行一覧を表示する。

### 3-行クリック（詳細画面遷移）

1. テーブル行をクリック
2. `/{実行ID}` へ遷移
3. ワークフロー実行詳細画面を表示

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

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

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

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

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

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| workflowExecutions.list.noRecordsMessage | 情報 | レコードなしメッセージ | データが存在しない場合 |

## 例外処理

| 例外ケース | 処理内容 |
|-----------|----------|
| API通信エラー | エラーをスローし、エラーバウンダリでキャッチ |
| データが存在しない | 空状態のメッセージを表示 |

## 備考

- ページサイズは20件固定
- SingleColumnPageレイアウトを使用
- 拡張ウィジェット機能に対応（workflow.list.before/after）
- keepPreviousDataオプションでページ遷移時のちらつきを防止
- hasOutlet=falseのため、子ルートのアウトレットは使用しない

---

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

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

### 推奨読解順序

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

まず、APIレスポンスの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | types.ts | `packages/admin/dashboard/src/routes/workflow-executions/types.ts` | ワークフロー実行の状態定義 |
| 1-2 | constants.ts | `packages/admin/dashboard/src/routes/workflow-executions/constants.ts` | 状態に関する定数定義 |

**読解のコツ**: TransactionState, TransactionStepStateなどの列挙型が定義されており、ワークフローの各状態を理解する上で重要。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | workflow-execution-list.tsx | `packages/admin/dashboard/src/routes/workflow-executions/workflow-execution-list/workflow-execution-list.tsx` | ページ構造とレイアウト |

**主要処理フロー**:
1. **6行目**: useExtensionでウィジェット機能を取得
2. **8-19行目**: SingleColumnPageでページレイアウトを構築（hasOutlet=false）
3. **17行目**: WorkflowExecutionListTableコンポーネントを配置

#### Step 3: テーブルコンポーネントを理解する

一覧表示の実装詳細を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | workflow-execution-list-table.tsx | `packages/admin/dashboard/src/routes/workflow-executions/workflow-execution-list/components/workflow-execution-list-table/workflow-execution-list-table.tsx` | テーブル表示処理 |

**主要処理フロー**:
- **10行目**: PAGE_SIZE = 20の定義
- **15-17行目**: useWorkflowExecutionTableQueryで検索パラメータを管理
- **18-26行目**: useWorkflowExecutionsでデータ取得（keepPreviousData使用）
- **28行目**: useWorkflowExecutionTableColumnsでテーブルカラムを構築
- **30-37行目**: useDataTableでテーブル状態を管理
- **43-68行目**: _DataTableコンポーネントで一覧表示
- **59行目**: navigateTo={(row) => `${row.id}`}で詳細画面への遷移を設定

#### Step 4: API連携を理解する

APIフックの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | workflow-executions.tsx | `packages/admin/dashboard/src/hooks/api/workflow-executions.tsx` | ワークフロー実行関連のAPIフック |

**主要処理フロー**:
- **12-31行目**: useWorkflowExecutionsで一覧取得

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

```
WorkflowExcecutionList (workflow-execution-list.tsx)
    │
    └─ WorkflowExecutionListTable
           │
           ├─ useWorkflowExecutionTableQuery() - 検索パラメータ管理
           │
           ├─ useWorkflowExecutions() - 一覧データ取得
           │      └─ sdk.admin.workflowExecution.list()
           │
           ├─ useWorkflowExecutionTableColumns() - カラム定義
           │
           ├─ useDataTable() - テーブル状態管理
           │
           └─ _DataTable - テーブル表示
                  └─ navigateTo - 詳細画面への遷移
```

### データフロー図

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

検索パラメータ ───▶ useWorkflowExecutions ───▶ テーブル表示
                     (API取得)

行クリック ───▶ navigateTo ───▶ 詳細画面遷移
                 (ルーティング)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| workflow-execution-list.tsx | `packages/admin/dashboard/src/routes/workflow-executions/workflow-execution-list/workflow-execution-list.tsx` | ソース | 一覧画面のメインコンポーネント |
| workflow-execution-list-table.tsx | `packages/admin/dashboard/src/routes/workflow-executions/workflow-execution-list/components/workflow-execution-list-table/workflow-execution-list-table.tsx` | ソース | テーブルコンポーネント |
| use-workflow-execution-table-query.tsx | `packages/admin/dashboard/src/routes/workflow-executions/workflow-execution-list/components/workflow-execution-list-table/use-workflow-execution-table-query.tsx` | ソース | 検索クエリフック |
| use-workflow-execution-table-columns.tsx | `packages/admin/dashboard/src/routes/workflow-executions/workflow-execution-list/components/workflow-execution-list-table/use-workflow-execution-table-columns.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` | ソース | 定数定義 |
