# 画面設計書 46-フロー管理

## 概要

本ドキュメントは、Shopware 6 Administration（管理画面）における「フロー管理」画面の設計書です。この画面は自動化ワークフロー（フロービルダー）の設定を行うイベント駆動アクション管理機能を提供します。

### 本画面の処理概要

**業務上の目的・背景**：ECサイト運営において、特定のイベント（注文完了、在庫切れ、顧客登録など）に応じて自動的にアクション（メール送信、ステータス変更、タグ付与など）を実行する自動化は業務効率化に不可欠です。本画面は、ノーコードでビジネスプロセスの自動化を設定できるフロービルダー機能を提供します。トリガー（イベント）、条件、アクションを組み合わせて複雑なワークフローを構築できます。

**画面へのアクセス方法**：管理画面にログイン後、左側メニューの「設定」→「自動化」→「フロービルダー」をクリックすることでアクセスできます。URLパスは `/admin#/sw/flow/index` となります。`flow.viewer` 権限を持つユーザーのみがアクセス可能です。

**主要な操作・処理内容**：
1. フロー一覧の表示 - 名前、トリガー、有効状態を一覧表示
2. フローの検索 - キーワード検索による絞り込み
3. フローの作成 - 新規フローの作成（テンプレートからも可能）
4. フローの編集 - トリガー、条件、アクションの編集
5. フローの複製 - 既存フローをコピーして新規作成
6. フローの削除 - 不要なフローを削除
7. フローテンプレートの管理 - テンプレートからのフロー作成

**画面遷移**：
- 遷移元: ダッシュボード、設定メニュー
- 遷移先: フロー詳細画面（sw.flow.detail）、フロー作成画面（sw.flow.create）

**権限による表示制御**：
- `flow.viewer`: 閲覧権限 - フロー一覧の表示が可能
- `flow.creator`: 作成権限 - 新規作成ボタンが表示
- `flow.editor`: 編集権限 - 編集が可能
- `flow.deleter`: 削除権限 - 削除ボタンが表示

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 67 | エラーページ | 補助機能 | 自動化ワークフローの設定 |

## 画面種別

一覧（タブ切替: フロー一覧 / テンプレート一覧）

## URL/ルーティング

- **パス**: `/admin#/sw/flow/index`
- **コンポーネント**: `sw-flow-index` → `sw-flow-list`
- **ルート名**: `sw.flow.index` → `sw.flow.index.flows`
- **必要権限**: `flow.viewer`

## 入出力項目

| 項目名 | 種別 | 型 | 必須 | 説明 |
|--------|------|-----|------|------|
| searchTerm | 入力 | string | - | 検索キーワード |
| page | 入力 | number | - | ページ番号 |
| limit | 入力 | number | - | 1ページあたりの表示件数 |
| sortBy | 入力 | string | - | ソート対象カラム（デフォルト: createdAt） |
| sortDirection | 入力 | string | - | ソート方向（デフォルト: DESC） |

## 表示項目

| 項目名 | カラム名 | 説明 | 編集可否 |
|--------|----------|------|----------|
| 有効 | active | フローの有効/無効状態 | - |
| 名前 | name | フロー名（詳細へのリンク） | - |
| トリガー | eventName | フローを起動するイベント名 | - |

## イベント仕様

### 1-ページ読み込み（createComponent）

画面初期表示時にフロー一覧を取得する。

**処理フロー**:
1. `Shopware.Store.get('swFlow').fetchTriggerActions()` でトリガーイベント一覧を取得
2. `flowRepository.search()` でフローデータを取得
3. 取得結果を `flows` データに格納し表示

### 2-検索実行

検索ボックスにキーワードを入力し検索を実行。

**処理フロー**:
1. 親コンポーネントから `searchTerm` がpropsで渡される
2. `watch` で `searchTerm` の変更を監視
3. `onSearch()` が呼び出され `getList()` を実行

### 3-フロー作成

新規作成ボタンをクリック。

**処理フロー**:
1. `$router.push({ name: 'sw.flow.create.general' })` で作成画面へ遷移

### 4-フロー編集（onEditFlow）

フロー名または編集ボタンをクリック。

**処理フロー**:
1. 選択されたフローのIDを取得
2. `$router.push({ name: 'sw.flow.detail', params: { id } })` で詳細画面へ遷移

### 5-フロー複製（onDuplicateFlow）

コンテキストメニューの複製をクリック。

**処理フロー**:
1. 複製時の上書き設定を構築（名前 + " - Copy"）
2. `flowRepository.clone()` でフローを複製
3. 成功時、複製したフローの詳細画面へ遷移
4. 成功/失敗の通知を表示

### 6-フロー削除（onConfirmDelete）

削除ボタンをクリックし確認モーダルで確定。

**処理フロー**:
1. 削除確認モーダルを表示
2. 確定時、`flowRepository.delete()` を実行
3. 成功時、リストを再取得
4. 成功/失敗の通知を表示

### 7-トリガー有効性確認（isValidTrigger）

各フローのトリガーイベントが有効かを確認。

**処理フロー**:
1. `triggerEvents` 配列からイベント名を検索
2. 存在しない場合、無効なトリガーとして表示

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| フロー一覧取得 | flow | SELECT | フローデータの取得 |
| フロー複製 | flow, flow_sequence | INSERT | フローと関連シーケンスの複製 |
| フロー削除 | flow | DELETE | フローの削除 |

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

#### flow

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | * | ページネーション、ソート条件に基づく | |
| INSERT | name | 元の名前 + " - Copy" | 複製時 |
| INSERT | event_name, active, ... | 元フローの値 | 複製時 |
| DELETE | - | id指定 | 削除時 |

#### flow_sequence

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | flow_id, ... | 複製されたflowのIDと元の設定 | 複製時 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|--------------|----------|
| sw-flow.flowNotification.messageDuplicateSuccess | 成功 | フローを複製しました | 複製成功時 |
| sw-flow.flowNotification.messageDuplicateError | エラー | 複製に失敗しました | 複製失敗時 |
| sw-flow.flowNotification.messageDeleteSuccess | 成功 | フローを削除しました | 削除成功時 |
| sw-flow.flowNotification.messageDeleteError | エラー | 削除に失敗しました | 削除失敗時 |
| sw-flow.list.warningDeleteText | 警告 | このフローを削除すると... | 削除確認時 |

## 例外処理

| 例外ケース | 処理内容 |
|-----------|---------|
| 検索結果0件 | 空状態の画面を表示 |
| 無効なトリガー | トリガー名に警告アイコンを表示 |
| 複製失敗 | エラー通知を表示 |
| 削除失敗 | エラー通知を表示 |
| 権限不足 | 該当機能のボタンを非表示/無効化 |

## 備考

- フローはイベント駆動型で、`eventName` で指定されたShopwareイベント発生時に実行される
- フローシーケンスは条件（if/then/else）とアクションの組み合わせで構成される
- テンプレートタブから事前定義されたフローテンプレートを選択して新規作成可能
- トリガーイベントは `swFlow` ストアで管理され、利用可能なイベント一覧はAPIから取得
- イベント名は翻訳キー形式（`global.businessEvents.*`）で国際化対応

---

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

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

### 推奨読解順序

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

フローエンティティとシーケンスの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | FlowDefinition | `src/Core/Content/Flow/FlowDefinition.php` | フローエンティティの定義 |
| 1-2 | FlowSequenceDefinition | `src/Core/Content/Flow/Aggregate/FlowSequence/FlowSequenceDefinition.php` | シーケンス構造 |

**読解のコツ**: FlowはFlowSequenceの親であり、シーケンスはツリー構造で条件分岐とアクションを表現する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.js | `src/Administration/Resources/app/administration/src/module/sw-flow/index.js` | モジュール登録、ルート定義 |

**主要処理フロー**:
1. **68-183行**: `Module.register('sw-flow', ...)` でモジュールを登録
2. **80-108行**: `routes.index` で一覧画面のルート定義（flows, templatesタブ）
3. **177-182行**: `settingsItem` で設定メニューへの登録

#### Step 3: 一覧画面コンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | sw-flow-list/index.js | `src/Administration/Resources/app/administration/src/module/sw-flow/view/listing/sw-flow-list/index.js` | Vue.jsコンポーネントの定義 |

**主要処理フロー**:
- **39-51行**: `data()` - コンポーネントの状態定義
- **64-76行**: `flowCriteria` - 検索条件の構築
- **78-101行**: `flowColumns` - テーブルカラム定義
- **134-147行**: `getList()` - フローデータ取得処理
- **153-179行**: `onDuplicateFlow()` - 複製処理

#### Step 4: フローストアを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | flow.store.js | `src/Administration/Resources/app/administration/src/module/sw-flow/store/flow.store.js` | フロー状態管理 |

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

```
sw-flow-index (親コンポーネント)
    │
    └─ sw-flow-list (子コンポーネント)
           │
           ├─ createComponent()
           │      ├─ swFlow.fetchTriggerActions()
           │      └─ getList()
           │             └─ flowRepository.search(criteria)
           │                    └─ Shopware API (POST /api/search/flow)
           │
           ├─ onDuplicateFlow(item)
           │      └─ flowRepository.clone(id, behavior)
           │             └─ Shopware API (POST /api/_action/clone/flow/{id})
           │
           └─ onConfirmDelete(item)
                  └─ flowRepository.delete(id)
                         └─ Shopware API (DELETE /api/flow/{id})
```

### データフロー図

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

検索キーワード ─────────┐
                        │
ソート設定 ─────────────┼──▶ sw-flow-list Component
                        │         │
ページング ─────────────┘         ├──▶ flowCriteria構築
                                  │         │
                                  │         ▼
                                  │    Criteria API
                                  │         │
                                  │         ▼
                                  │    flowRepository.search()
                                  │         │
                                  │         ▼
                                  │    Shopware API
                                  │         │
                                  │         ▼
                                  └──▶ flows データ ──▶ 一覧表示

swFlow Store ──────────▶ triggerEvents ──▶ イベント名の翻訳・検証
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.js | `src/Administration/Resources/app/administration/src/module/sw-flow/index.js` | ソース | モジュール定義 |
| sw-flow-list/index.js | `src/Administration/Resources/app/administration/src/module/sw-flow/view/listing/sw-flow-list/index.js` | ソース | 一覧画面コンポーネント |
| sw-flow-list.html.twig | `src/Administration/Resources/app/administration/src/module/sw-flow/view/listing/sw-flow-list/sw-flow-list.html.twig` | テンプレート | 画面テンプレート |
| flow.store.js | `src/Administration/Resources/app/administration/src/module/sw-flow/store/flow.store.js` | ソース | 状態管理 |
| flow.constant.js | `src/Administration/Resources/app/administration/src/module/sw-flow/constant/flow.constant.js` | ソース | 定数定義 |
| acl/index.js | `src/Administration/Resources/app/administration/src/module/sw-flow/acl/index.js` | ソース | 権限定義 |
| FlowDefinition.php | `src/Core/Content/Flow/FlowDefinition.php` | ソース | エンティティ定義 |
