# 画面設計書 114-ホーム画面

## 概要

本ドキュメントは、Chatwootのチャットウィジェットにおけるホーム画面の設計書です。顧客向けウィジェットの初期表示画面として機能します。

### 本画面の処理概要

**業務上の目的・背景**：チャットウィジェットは、Webサイトに埋め込まれる顧客向けのチャットインターフェースです。ホーム画面は、顧客がチャットウィジェットを開いたときに最初に表示される画面であり、サポートチームの可用性表示、会話開始ボタン、ヘルプ記事へのアクセスを提供します。顧客の第一印象を左右する重要な画面であり、スムーズなサポート開始体験を提供することを目的としています。

**画面へのアクセス方法**：ウィジェットバブルをクリックしてウィジェットを開く、またはウィジェット内でホームアイコンをクリックすることでアクセスします。URLハッシュパスは `/` です。

**主要な操作・処理内容**：
1. サポートチームの可用性状態表示
2. 利用可能なエージェントのアバター表示
3. 新規会話の開始ボタン
4. 既存会話への継続ボタン
5. ヘルプセンター記事の検索・閲覧
6. 未読メッセージカウントの表示

**画面遷移**：
- 遷移元：ウィジェットバブル、メッセージ画面
- 遷移先：プリチャットフォーム画面（新規会話・フォーム有効時）、メッセージ画面（会話継続時）、記事ビューア画面

**権限による表示制御**：ウィジェットはWebサイト訪問者（顧客）向けのため、特別な権限制御はありません。インボックス設定によりプリチャットフォームの有無が制御されます。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 160 | Widget設定 | 主機能 | ウィジェットホーム画面表示 |
| 165 | Widgetキャンペーン | 補助機能 | キャンペーンメッセージ表示 |

## 画面種別

一覧・ナビゲーション画面

## URL/ルーティング

- パス: `#/`（ウィジェット内ハッシュルーティング）
- ルート名: `home`
- コンポーネント: `Home.vue`

## 入出力項目

### 入力項目

本画面には直接の入力項目はありません（記事検索はサブコンポーネントで処理）。

### 出力項目

| 項目名 | 項目ID | 型 | 説明 |
|--------|--------|-----|------|
| 利用可能エージェント一覧 | availableAgents | array | オンラインエージェントの情報 |
| 会話サイズ | conversationSize | number | 既存会話のメッセージ数 |
| 未読メッセージ数 | unreadMessageCount | number | 未読メッセージの件数 |

## 表示項目

### チーム可用性セクション

| 項目名 | 説明 |
|--------|------|
| 可用性コンテナ | エージェントのオンライン状況 |
| エージェントアバター | 利用可能なエージェントのアバター表示 |
| 可用性メッセージ | 「We are online」等のステータスメッセージ |
| アクションボタン | 「Start Conversation」または「Continue Conversation」 |

### 記事コンテナセクション

| 項目名 | 説明 |
|--------|------|
| 記事検索入力 | ヘルプ記事検索用の入力欄 |
| 記事一覧 | 推奨記事またはカテゴリ一覧 |

## イベント仕様

### 1-会話開始

**トリガー**: 「Start Conversation」または「Continue Conversation」ボタンクリック

**処理フロー**:
1. `startConversation`メソッド呼び出し
2. プリチャットフォーム設定の確認（`preChatFormEnabled`）
3. 既存会話の有無を確認（`conversationSize`）
4. 条件分岐:
   - プリチャットフォーム有効 かつ 既存会話なし: `prechat-form`へ遷移
   - それ以外: `messages`へ遷移
5. 既存会話がない場合、SDKイベント `CHATWOOT_ON_START_CONVERSATION` を送信

### 2-記事表示

**トリガー**: 記事一覧から記事をクリック

**処理フロー**:
1. 記事のURLを取得
2. `article-viewer`ルートへ遷移（queryパラメータにリンクを含む）

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 会話開始 | - | - | 本画面では直接のDB更新なし |

本画面自体はデータベースへの直接更新を行いません。会話作成はプリチャットフォーム画面またはメッセージ画面で行われます。

## メッセージ仕様

| 種別 | キー | メッセージ内容 | 表示タイミング |
|------|-----|---------------|---------------|
| ボタン | START_CONVERSATION | 会話を開始 | 既存会話なし時 |
| ボタン | CONTINUE_CONVERSATION | 会話を続ける | 既存会話あり時 |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| エージェント情報取得失敗 | 可用性セクションにフォールバック表示 |
| 記事取得失敗 | 記事セクションを非表示または空表示 |

## 備考

- ウィジェットはiframe内で動作するため、親ページとの通信はpostMessageを使用
- ダークモード対応（ウィジェット設定に依存）
- レスポンシブデザイン対応（モバイル・デスクトップ両対応）
- configMixinを使用してウィジェット設定を取得

---

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

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

### 推奨読解順序

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

ウィジェットのストア構造と取得データを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.js | `app/javascript/widget/store/modules/conversation/index.js` | 会話ストアのstate構造 |
| 1-2 | getters.js | `app/javascript/widget/store/modules/conversation/getters.js` | getConversationSize, getUnreadMessageCount |

**読解のコツ**: ウィジェットはダッシュボードとは別のVuexストアを使用している。

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

ルーティングとホーム画面コンポーネントの構成を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | router.js | `app/javascript/widget/router.js` | L23-26: homeルート定義 |
| 2-2 | Home.vue | `app/javascript/widget/views/Home.vue` | メインコンポーネント |

**主要処理フロー**:
1. **L19-23**: mapGettersでストアからデータ取得
2. **L26-31**: startConversationメソッド - 遷移先の決定ロジック

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

チーム可用性と記事表示のコンポーネントを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | TeamAvailability.vue | `app/javascript/widget/components/TeamAvailability.vue` | エージェント表示、ボタンイベント |
| 3-2 | ArticleContainer.vue | `app/javascript/widget/components/pageComponents/Home/Article/ArticleContainer.vue` | ヘルプ記事表示 |

**TeamAvailability.vue主要処理**:
- **L7-9**: props定義（availableAgents, hasConversation）
- **L16-25**: startConversationイベント発火、SDKイベント送信

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

```
Home.vue
    |
    +-- TeamAvailability.vue
    |       |
    |       +-- AvailabilityContainer.vue
    |       |       +-- エージェントアバター表示
    |       |
    |       +-- button (Start/Continue Conversation)
    |               |
    |               +-- @click -> emit('startConversation')
    |                               |
    |                               +-- Home.vue: startConversation()
    |                                       |
    |                                       +-- router.replace('prechat-form' or 'messages')
    |
    +-- ArticleContainer.vue
            |
            +-- 記事検索・一覧表示
                    |
                    +-- router.push('article-viewer')
```

### データフロー図

```
[ストア]                  [コンポーネント]              [出力]

agent/availableAgents --> Home.vue ------------> TeamAvailability.vue
                              |
conversation/getConversationSize
                              |
conversation/getUnreadMessageCount
                              |
                              v
                     startConversation()
                              |
                    +---------+---------+
                    |                   |
                    v                   v
           prechat-form            messages
         (フォーム有効時)        (フォーム無効/既存会話時)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Home.vue | `app/javascript/widget/views/Home.vue` | ソース | メイン画面コンポーネント |
| router.js | `app/javascript/widget/router.js` | ソース | ウィジェットルーティング |
| TeamAvailability.vue | `app/javascript/widget/components/TeamAvailability.vue` | ソース | チーム可用性表示 |
| AvailabilityContainer.vue | `app/javascript/widget/components/Availability/AvailabilityContainer.vue` | ソース | 可用性詳細表示 |
| ArticleContainer.vue | `app/javascript/widget/components/pageComponents/Home/Article/ArticleContainer.vue` | ソース | 記事コンテナ |
| configMixin.js | `app/javascript/widget/mixins/configMixin.js` | ソース | ウィジェット設定mixin |
| ViewWithHeader.vue | `app/javascript/widget/components/layouts/ViewWithHeader.vue` | ソース | ヘッダー付きレイアウト |
| index.js | `app/javascript/widget/store/modules/conversation/index.js` | ソース | 会話ストアモジュール |
| getters.js | `app/javascript/widget/store/modules/conversation/getters.js` | ソース | 会話getter定義 |
