# 画面設計書 16-スケジュール一覧画面（デスクトップ）

## 概要

本ドキュメントは、Actual Budgetアプリケーションにおけるデスクトップ向けスケジュール一覧画面の設計仕様を定義する。

### 本画面の処理概要

スケジュール一覧画面（デスクトップ）は、定期取引スケジュールの一覧表示と管理を行う画面である。家賃、光熱費、サブスクリプションなどの定期的な支払いや収入を登録し、自動取引生成の設定を管理できる。

**業務上の目的・背景**：定期的な支出（家賃、保険料、サブスクリプション等）や収入（給与、配当等）は、毎月または定期的に発生するため、手動で入力する手間を省くためにスケジュール機能が提供される。スケジュールを設定することで、取引が自動的に生成されるか、または予定取引として口座画面にプレビュー表示される。

**画面へのアクセス方法**：サイドバーの「Schedules」メニューをクリックしてアクセスする。URLパターンは `/schedules` である。

**主要な操作・処理内容**：
1. スケジュール一覧の表示（フィルタリング対応）
2. 新規スケジュールの作成（モーダル）
3. 既存スケジュールの編集（モーダル）
4. スケジュールの削除
5. スケジュールのスキップ（次回をスキップ）
6. スケジュールの完了（今後の生成を停止）
7. スケジュールの再開（完了済みを再アクティブ化）
8. スケジュールからの取引即時生成
9. スケジュール発見機能（既存取引からスケジュールを推測）
10. 予定取引の表示期間設定

**画面遷移**：
- 遷移元：サイドバー
- 遷移先：スケジュール編集モーダル、スケジュール発見モーダル、表示期間設定モーダル

**権限による表示制御**：特になし。認証済みユーザーであれば全機能を利用可能。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 21 | 定期取引スケジュール | 主機能 | 定期取引スケジュールの一覧表示・管理 |
| 22 | 自動取引生成 | 補助機能 | スケジュールに基づく取引自動生成設定 |

## 画面種別

一覧

## URL/ルーティング

`/schedules`

## 入出力項目

| 項目名 | 項目ID | 入力/出力 | 型 | 必須 | 説明 |
|--------|--------|----------|-----|------|------|
| フィルタ | filter | 入力 | string | No | スケジュール検索用キーワード |

## 表示項目

| 項目名 | 説明 | データソース |
|--------|------|-------------|
| ページタイトル | 「Schedules」固定 | i18n |
| スケジュール一覧テーブル | スケジュールのリスト | schedules |

### スケジュールテーブル列

| 列名 | 説明 |
|------|------|
| Name | スケジュール名（または支払先名） |
| Payee | 支払先 |
| Account | 口座 |
| Date | 次回実行日 |
| Status | ステータス（Due/Paid/Upcoming/Missed/Completed） |
| Amount | 金額 |
| アクションメニュー | 編集/削除/スキップ/完了等 |

## イベント仕様

### 1-スケジュール行クリック

スケジュール行をクリックすると、schedule-editモーダルが開き、スケジュールを編集できる。

### 2-フィルタ入力

検索フィールドにキーワードを入力すると、スケジュール一覧がフィルタリングされる。

### 3-「Add new schedule」ボタン押下

右下の「Add new schedule」ボタンを押下すると、空のschedule-editモーダルが開き、新規スケジュールを作成できる。

### 4-「Find schedules」ボタン押下

左下の「Find schedules」ボタンを押下すると、schedules-discoverモーダルが開き、既存取引から定期取引パターンを検出する。

### 5-「Change upcoming length」ボタン押下

「Change upcoming length」ボタンを押下すると、schedules-upcoming-lengthモーダルが開き、予定取引の表示期間を設定できる。

### 6-アクションメニュー操作

各スケジュール行のアクションメニューから以下の操作が可能：
- **Post transaction**：スケジュールの日付で取引を即時生成
- **Post transaction today**：今日の日付で取引を即時生成
- **Skip next date**：次回の実行をスキップ
- **Complete**：スケジュールを完了（今後の生成停止）
- **Restart**：完了済みスケジュールを再アクティブ化
- **Delete**：スケジュールを削除

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | schedules | SELECT | 全スケジュールを取得 |
| Post transaction | transactions | INSERT | スケジュールから取引を生成 |
| Post transaction | schedules | UPDATE | next_dateを更新 |
| Skip next date | schedules | UPDATE | next_dateを次回にスキップ |
| Complete | schedules | UPDATE | completedをtrueに更新 |
| Restart | schedules | UPDATE | completedをfalseに更新、next_dateをリセット |
| Delete | schedules | DELETE | スケジュールを削除 |

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

#### schedules

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | next_date | 次回実行日 | スキップ/取引生成時 |
| UPDATE | completed | true/false | 完了/再開時 |
| DELETE | - | id = 指定ID | 削除時 |

#### transactions

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | schedule | スケジュールID | 生成時にリンク |
| INSERT | date | スケジュールのnext_dateまたは今日 | Post transaction時 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|---------|
| M001 | 情報 | Filter schedules... | 検索プレースホルダー |
| M002 | 情報 | Find schedules | スケジュール発見ボタン |
| M003 | 情報 | Change upcoming length | 期間設定ボタン |
| M004 | 情報 | Add new schedule | 新規作成ボタン |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| スケジュールデータなし | 空のテーブルを表示 |
| 取引生成エラー | エラーメッセージを表示 |

## 備考

- useSchedulesフックでスケジュールデータとステータスを取得
- ステータス（Due/Paid/Upcoming/Missed/Completed）はstatusesマップで管理
- allowCompleted=trueで完了済みスケジュールも表示
- SchedulesTableコンポーネントで一覧表示（テーマカラーのbackground適用）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | models/index.d.ts | `packages/loot-core/types/models/` | ScheduleEntityの型定義 |

**読解のコツ**: _conditions, _actions, posts_transaction, completedフィールドに注目。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.tsx | `packages/desktop-client/src/components/schedules/index.tsx` | Schedulesコンポーネント |

**主要処理フロー**:
1. **行24**: useStateでフィルタ状態管理
2. **行26-33**: onEditコールバック - schedule-editモーダル呼び出し
3. **行35-37**: onAddコールバック - 空のschedule-editモーダル呼び出し
4. **行39-41**: onDiscoverコールバック - schedules-discoverモーダル呼び出し
5. **行43-45**: onChangeUpcomingLengthコールバック - schedules-upcoming-lengthモーダル呼び出し
6. **行47-78**: onActionコールバック - 各アクション処理（send関数でAPI呼び出し）
7. **行80-85**: useSchedulesフックでデータ取得

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | SchedulesTable.tsx | `packages/desktop-client/src/components/schedules/SchedulesTable.tsx` | スケジュールテーブル表示 |

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

```
Schedules (エントリーポイント)
    |
    +-- Page (ヘッダー「Schedules」)
    |
    +-- View (フィルタ行)
    |       +-- Search (フィルタ入力)
    |
    +-- SchedulesTable
    |       +-- スケジュール行
    |       +-- アクションメニュー
    |
    +-- View (ボタン行)
            +-- Button (Find schedules) --> schedules-discoverモーダル
            +-- Button (Change upcoming length) --> schedules-upcoming-lengthモーダル
            +-- Button (Add new schedule) --> schedule-editモーダル
```

### データフロー図

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

DB schedules      --->  useSchedules               --->  schedules array
(q('schedules'))        (フック)                          statuses Map

User action       --->  send('schedule/post-transaction') --> 取引生成
(Post transaction)

User action       --->  send('schedule/skip-next-date')   --> next_date更新
(Skip)

User action       --->  send('schedule/update')            --> completed更新
(Complete/Restart)      {completed: true/false}

User action       --->  send('schedule/delete')            --> スケジュール削除
(Delete)

User action       --->  pushModal                          --> モーダル表示
(Add/Edit/Find)         (schedule-edit/schedules-discover)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.tsx | `packages/desktop-client/src/components/schedules/index.tsx` | ソース | メインコンポーネント |
| SchedulesTable.tsx | `packages/desktop-client/src/components/schedules/SchedulesTable.tsx` | ソース | スケジュールテーブル |
| useSchedules.ts | `packages/desktop-client/src/hooks/useSchedules.ts` | ソース | スケジュールデータフック |
| Search.tsx | `packages/desktop-client/src/components/common/Search.tsx` | ソース | 検索コンポーネント |
| modalsSlice.ts | `packages/desktop-client/src/modals/modalsSlice.ts` | ソース | モーダル管理 |
