# 画面設計書 30-利用状況画面

## 概要

本ドキュメントは、Giselle Studioの利用状況画面の設計仕様を記載したものです。

### 本画面の処理概要

この画面は、チームのエージェント（AIワークフロー）利用状況を確認するための画面です。アプリ使用時間の合計と、各アプリの実行履歴を表示します。プランに応じて表示内容が異なります。

**業務上の目的・背景**：AIワークフローの利用状況を把握することで、リソース消費の監視、コスト管理、利用パターンの分析が可能になります。Freeプランでは使用時間の上限管理が表示され、Proプランでは制限なしの状態が表示されます。

**画面へのアクセス方法**：設定画面のサイドバーから「Usage」、または「/settings/team/usage」パスに直接アクセスします。

**主要な操作・処理内容**：
1. アプリ使用時間の合計表示
2. 最近のアプリ使用履歴の表示（直近3件）
3. 詳細な使用履歴の確認（ダイアログ表示、最大50件）

**画面遷移**：この画面からはAgentUsageDialogでの詳細表示（モーダル）、外部ドキュメント（docs.giselles.ai）への遷移があります。

**権限による表示制御**：ログイン済みユーザーで、チームに所属しているユーザーのみアクセス可能です。プランによって使用時間セクションの表示が異なります。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 99 | 使用量制限 | 主機能 | チームのエージェント利用状況、使用時間の取得と表示 |

## 画面種別

情報表示

## URL/ルーティング

`/settings/team/usage`

## 入出力項目

なし（表示のみ）

## 表示項目

| 項目名 | 説明 | データソース |
|--------|------|-------------|
| ページタイトル | "Usage" | 静的テキスト |
| アプリ使用時間 | 合計使用時間（分） | calculateAgentTimeUsageMs関数 |
| 使用状況バー | プログレスバー | usedMinutes / 制限 |
| 最近のアプリ使用 | 直近3件の使用履歴 | getAgentActivities関数 |
| 使用履歴詳細 | 最大50件の使用履歴（ダイアログ） | getAgentActivities関数 |

## イベント仕様

### 1-See All押下

AgentUsageDialogが表示され、最大50件の使用履歴を確認できます。

### 2-ドキュメントリンク押下

About Usageリンク押下時、外部ドキュメント（docs.giselles.ai）が新しいタブで開きます。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | agentActivities | SELECT | 使用履歴と使用時間を取得 |

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

#### agentActivities

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | totalDurationMs, etc. | teamDbId = チームID | 使用履歴の取得 |
| SELECT | sum(totalDurationMs) | teamDbId = チームID | 合計使用時間の計算 |

## メッセージ仕様

| 種別 | メッセージ | 表示条件 |
|------|----------|----------|
| 取得エラー | Failed to load agent activities | 使用履歴取得失敗時 |
| カード説明 | This shows the usage data from running your Apps in Giselle. | 常時表示 |
| Freeプラン案内 | 使用時間の上限と残り時間を表示 | Freeプランの場合 |
| Proプラン案内 | Unlimited | Proプランの場合 |

## 例外処理

| 状態 | 処理 |
|------|------|
| 使用履歴取得エラー | "Failed to load agent activities"メッセージを表示 |
| データ0件 | 空状態を表示 |

## 備考

- Freeプランの場合、AgentTimeChargeセクションで使用時間の上限管理が表示されます
- Proプランの場合、AgentTimeChargeは非表示になります
- 使用時間はミリ秒から分に変換され、小数点以下2桁で表示されます
- 使用履歴は最大50件まで取得され、直近3件が画面に表示されます
- See Allボタンで詳細ダイアログが表示されます

---

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

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

### 推奨読解順序

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

利用状況で使用されるデータ構造を把握します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | schema.ts | `apps/studio.giselles.ai/db/schema.ts` | agentActivitiesテーブル定義 |

**読解のコツ**: agentActivitiesはアプリ実行ごとに記録され、totalDurationMsで実行時間が管理されます。

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

ページコンポーネントの構造を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | page.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/usage/page.tsx` | プラン判定とコンポーネント構成 |

**主要処理フロー**:
1. **行9-10**: fetchCurrentTeamでチーム取得、Freeプラン判定
2. **行15-17**: PageHeadingとDocsLink表示
3. **行23-33**: Freeプランの場合のみAgentTimeChargeを表示
4. **行36**: AgentUsageを表示

#### Step 3: 使用時間コンポーネントを理解する

使用時間表示のロジックを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | agent-time-charge.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/agent-time-charge.tsx` | 使用時間の計算と表示 |

**主要処理フロー**:
- **行10-11**: fetchCurrentTeam、isProPlan判定
- **行12**: calculateAgentTimeUsageMsで使用時間取得
- **行14**: ミリ秒から分に変換（小数点2桁）
- **行17-23**: プランに応じたUI切り替え

#### Step 4: 使用履歴コンポーネントを理解する

使用履歴表示のロジックを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | agent-usage.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/agent-usage.tsx` | 使用履歴の取得と表示 |

**主要処理フロー**:
- **行7**: getAgentActivitiesで使用履歴取得（最大50件）
- **行9-17**: 取得エラー時のエラー表示
- **行19-20**: 直近3件を抽出
- **行22-34**: Card内にテーブルとダイアログボタン表示

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

```
page.tsx (Server Component)
    │
    ├─ fetchCurrentTeam() - チーム情報取得
    │
    ├─ isProPlan() - プラン判定
    │
    ├─ PageHeading - タイトル表示
    │
    ├─ DocsLink - ドキュメントリンク
    │
    ├─ Suspense (Freeプランのみ)
    │      └─ AgentTimeCharge
    │             ├─ fetchCurrentTeam()
    │             ├─ isProPlan()
    │             ├─ calculateAgentTimeUsageMs() - 使用時間計算
    │             └─ AgentTimeUsageForFreePlan / AgentTimeUsageForProPlan
    │
    └─ AgentUsage
           ├─ getAgentActivities() - 使用履歴取得
           ├─ AgentUsageTable - テーブル表示
           └─ AgentUsageDialog - 詳細ダイアログ
```

### データフロー図

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

agentActivities テーブル ────────▶ calculateAgentTimeUsageMs() ─▶ usedMinutes
         │                              │                              │
         │                              ▼                              │
         │                       ミリ秒 → 分 変換                     │
         │                              │                              ▼
         │                              └─────────────────────────▶ AgentTimeUsage UI
         │
         │
agentActivities テーブル ────────▶ getAgentActivities() ─────────▶ activities[]
                                        │                              │
                                        ▼                              │
                                 activities.slice(0, 3) ──────────▶ AgentUsageTable
                                        │
                                        └──────────────────────────▶ AgentUsageDialog
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| page.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/usage/page.tsx` | ソース | サーバーコンポーネント、メインページ |
| agent-time-charge.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/agent-time-charge.tsx` | ソース | 使用時間表示 |
| agent-usage.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/agent-usage.tsx` | ソース | 使用履歴表示 |
| agent-usage-table.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/agent-usage-table.tsx` | ソース | 使用履歴テーブルUI |
| agent-usage-dialog.tsx | `apps/studio.giselles.ai/app/(main)/settings/team/agent-usage-dialog.tsx` | ソース | 使用履歴詳細ダイアログ |
| actions.ts | `apps/studio.giselles.ai/app/(main)/settings/team/actions.ts` | ソース | getAgentActivities関数 |
| activities.ts | `apps/studio.giselles.ai/services/agents/activities.ts` | ソース | calculateAgentTimeUsageMs関数 |
