# 画面設計書 8-アクティビティ一覧画面

## 概要

本ドキュメントは、Fizzyアプリケーションのアクティビティ一覧画面（`app/views/events/index.html.erb`）の設計仕様を記述したものです。

### 本画面の処理概要

アクティビティ一覧画面は、Fizzyアプリケーションのホーム画面として機能し、ユーザーの日次タイムライン（イベント履歴）を時系列で表示します。カードの作成、編集、コメント追加などの各種アクティビティが時間順に表示され、ユーザーは最新の活動状況を一目で把握できます。

**業務上の目的・背景**：チームやプロジェクトにおける活動の可視化を目的としています。メンバーがどのような作業を行っているかをリアルタイムで把握し、コラボレーションを促進します。ボードをまたいだ活動の一元管理により、複数プロジェクトを担当するユーザーでも効率的に状況を確認できます。

**画面へのアクセス方法**：認証後のルートURL（`/`）にアクセスするとこの画面が表示されます。これがFizzyのメインのホーム画面です。

**主要な操作・処理内容**：
1. タイムラインでアクティビティを時系列で確認する
2. ボードでフィルタリングして特定のボードのアクティビティのみを表示する
3. 「Add card」ボタンで新規カードを作成する
4. 「Add board」ボタンで新規ボードを作成する
5. 各イベントをクリックして詳細（カード詳細画面など）に遷移する
6. 無限スクロールで過去のアクティビティを読み込む

**画面遷移**：
- 遷移元：ログイン完了後、サインアップ完了後、各画面からのホームリンク
- 遷移先：カード詳細画面、ボード詳細画面、日別アクティビティ画面、カード作成、ボード作成

**権限による表示制御**：
- 認証済みユーザーのみアクセス可能
- ユーザーが参加しているボードのアクティビティのみ表示される
- フィルター設定により表示範囲をカスタマイズ可能

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 62 | タイムライン表示 | 主機能 | ユーザーの日次タイムライン（イベント履歴）を時系列で表示 |

## 画面種別

一覧（タイムライン）

## URL/ルーティング

| 項目 | 値 |
|------|-----|
| URL | `/`（ルート）、`/events` |
| HTTPメソッド | GET |
| コントローラー | `EventsController` |
| アクション | `index` |
| レイアウト | application（デフォルト） |

## 入出力項目

### 入力項目（クエリパラメータ）

| No | 項目名 | 物理名 | データ型 | 必須 | 説明 | 備考 |
|----|--------|--------|---------|------|------|------|
| 1 | 日付 | day | string | 任意 | 表示する日付 | YYYY-MM-DD形式、省略時は当日 |
| 2 | フィルターID | filter_id | integer | 任意 | 保存済みフィルターのID | - |
| 3 | ボードID | board_ids[] | array | 任意 | 表示するボードのID | 複数指定可 |
| 4 | 展開フラグ | expand_all | boolean | 任意 | すべて展開して表示 | - |

### 出力項目

なし（画面表示のみ）

## 表示項目

| No | 項目名 | 表示条件 | データソース | 備考 |
|----|--------|----------|-------------|------|
| 1 | ページタイトル「Home」 | 常時 | 固定文言 | - |
| 2 | ヘッダータイトル | 常時 | 動的生成 | "Latest Activity" または "Activity in/across [boards]" |
| 3 | フィルター | 常時 | @user_filtering | ボードフィルター |
| 4 | 「Add card」ボタン | 常時 | - | 新規カード作成 |
| 5 | 「Add board」ボタン | 常時 | - | 新規ボード作成 |
| 6 | 日次タイムライン | 常時 | @day_timeline | イベント一覧 |
| 7 | ページネーションリンク | 過去データ存在時 | @day_timeline | 無限スクロール対応 |

## イベント仕様

### 1-フィルター変更

**トリガー**: フィルターUIの操作

**処理フロー**:
1. ボード選択などのフィルター条件を変更
2. URLパラメータが更新される
3. ページがリロードされ、新しいフィルター条件でタイムラインが表示される

### 2-「Add card」ボタン押下

**トリガー**: ボタンクリック

**処理**: カード作成のモーダルまたは画面が表示される

### 3-「Add board」ボタン押下

**トリガー**: ボタンクリック

**処理**: ボード作成のモーダルまたは画面が表示される

### 4-無限スクロール（ページネーション）

**トリガー**: ページ下部へのスクロール（Intersection Observer）

**処理フロー**:
1. `pagination` Stimulusコントローラーがスクロール位置を監視
2. ページネーションリンクが表示領域に入ると自動的にリクエスト
3. 新しい日のタイムラインがDOMに追加される

### 5-イベント項目クリック

**トリガー**: イベント項目のクリック

**処理**: 対象のカード詳細画面またはコメント詳細画面に遷移

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

なし（参照のみ）

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | events | SELECT | タイムラインのイベント取得 |
| 画面表示 | boards | SELECT | ユーザーが参加しているボード取得 |
| 画面表示 | filters | SELECT | ユーザーのフィルター設定取得 |

## メッセージ仕様

| No | メッセージ種別 | メッセージ内容 | 表示条件 |
|----|--------------|---------------|---------|
| 1 | 情報 | （空の日の表示） | イベントがない日 |

## 例外処理

| 例外パターン | 対応内容 | 備考 |
|------------|---------|------|
| 無効な日付パラメータ | HTTP 404 Not Found | ArgumentErrorをrescue |
| フィルターが見つからない | ActiveRecord::RecordNotFoundエラー | filter_idが無効な場合 |

## 備考

- 本画面はFizzyのルートURL（`/`）に設定されており、ホーム画面として機能する
- `fresh_when @day_timeline`によるHTTPキャッシュが実装されている（ETag）
- `pagination` Stimulusコントローラーにより無限スクロールが実装されている
- `data-pagination-paginate-on-intersection-value: true`で交差点監視による自動読み込み
- `related-element` Stimulusコントローラーで関連イベントのハイライト表示が可能
- フィルター機能は`User::Filtering`クラスで管理されている
- タイムラインは`@day_timeline`オブジェクトで管理され、日ごとにグループ化される

---

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

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

### 推奨読解順序

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

まず、タイムライン表示に関わるデータモデルの構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | event.rb | `app/models/event.rb` | Eventモデルの構造、関連、scope |
| 1-2 | filter.rb | `app/models/filter.rb` | フィルターの構造 |
| 1-3 | user/filtering.rb | `app/models/user/filtering.rb` | ユーザーフィルタリングロジック |

**読解のコツ**: Eventモデルは`eventable`ポリモーフィック関連を持ち、カード・コメント・ステップなど様々なイベントタイプに対応しています。

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

処理の起点となるコントローラーを特定します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | events_controller.rb | `app/controllers/events_controller.rb` | indexアクション、DayTimelinesScopedのinclude |
| 2-2 | day_timelines_scoped.rb | `app/controllers/concerns/day_timelines_scoped.rb` | タイムライン取得ロジック |
| 2-3 | filter_scoped.rb | `app/controllers/concerns/filter_scoped.rb` | フィルター設定ロジック |

**主要処理フロー**:
1. **4-6行目（events_controller.rb）**: `index`アクション - fresh_whenでキャッシュ制御
2. **11-13行目（day_timelines_scoped.rb）**: `set_day_timeline` - タイムライン取得
3. **10-16行目（filter_scoped.rb）**: `set_filter` - フィルター設定

#### Step 3: ビューとテンプレートを理解する

画面表示のテンプレートを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.html.erb | `app/views/events/index.html.erb` | 全体構造、ヘッダー、タイムライン |
| 3-2 | _day.html.erb | `app/views/events/_day.html.erb` | 日ごとのイベント表示 |
| 3-3 | index/_filter.html.erb | `app/views/events/index/_filter.html.erb` | フィルターUI |

**主要処理フロー**:
- **6-20行目**: ヘッダー部（タイトル、フィルター、ボタン）
- **22-28行目**: タイムライン部（ページネーション対応）

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

```
EventsController#index
    │
    ├─ [before_action] set_filter (FilterScoped)
    │      └─ Current.user.filters.from_params or find
    │
    ├─ [before_action] set_user_filtering (FilterScoped)
    │      └─ User::Filtering.new(Current.user, @filter)
    │
    ├─ [before_action] set_day_timeline (DayTimelinesScoped)
    │      └─ Current.user.timeline_for(day, filter: @filter)
    │
    └─ fresh_when @day_timeline
           │
           └─ [ETag一致] 304 Not Modified
           │
           └─ [ETag不一致] render index
                  │
                  ├─ events/index.html.erb
                  │      │
                  │      ├─ header部分
                  │      │      ├─ events/index/_add_card_button
                  │      │      ├─ events/index/_filter
                  │      │      └─ events/index/_add_board_button
                  │      │
                  │      └─ タイムライン部分
                  │             ├─ events/_day
                  │             └─ pagination_link
                  │
                  └─ レスポンス
```

### データフロー図

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

day (param) ─────────▶ EventsController#index
filter_id (param) ───▶        │
board_ids (param) ───▶        │
                              │
                              ├──▶ set_filter
                              │        │
                              │        └─▶ Filter取得/生成
                              │
                              ├──▶ set_user_filtering
                              │        │
                              │        └─▶ User::Filtering生成
                              │
                              ├──▶ set_day_timeline
                              │        │
                              │        └─▶ Timeline取得（Events + Boards）
                              │
                              └──▶ fresh_when（キャッシュ制御）
                                       │
                                       └─▶ HTML出力（タイムライン表示）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| events_controller.rb | `app/controllers/events_controller.rb` | コントローラー | アクティビティ一覧の制御 |
| index.html.erb | `app/views/events/index.html.erb` | ビュー | アクティビティ一覧画面テンプレート |
| _day.html.erb | `app/views/events/_day.html.erb` | パーシャル | 日ごとのイベント表示 |
| _filter.html.erb | `app/views/events/index/_filter.html.erb` | パーシャル | フィルターUI |
| _add_card_button.html.erb | `app/views/events/index/_add_card_button.html.erb` | パーシャル | カード追加ボタン |
| _add_board_button.html.erb | `app/views/events/index/_add_board_button.html.erb` | パーシャル | ボード追加ボタン |
| event.rb | `app/models/event.rb` | モデル | イベント管理 |
| filter.rb | `app/models/filter.rb` | モデル | フィルター管理 |
| filtering.rb | `app/models/user/filtering.rb` | モデル | ユーザーフィルタリング |
| day_timelines_scoped.rb | `app/controllers/concerns/day_timelines_scoped.rb` | Concern | タイムライン取得 |
| filter_scoped.rb | `app/controllers/concerns/filter_scoped.rb` | Concern | フィルター設定 |
| pagination_controller.js | `app/javascript/controllers/pagination_controller.js` | Stimulus | 無限スクロール |
| related_element_controller.js | `app/javascript/controllers/related_element_controller.js` | Stimulus | 関連要素ハイライト |
| routes.rb | `config/routes.rb` | 設定 | ルーティング定義 |
