# 画面設計書 23-アプリ詳細画面

## 概要

本ドキュメントは、Giselle Studioのアプリ詳細画面の設計仕様を記載したものです。

### 本画面の処理概要

この画面は、ショーケースに公開されている特定のアプリ（ワークフロー）の詳細情報、実行統計、実行履歴を表示するための画面です。ユーザーはアプリの実行回数、平均ランタイム、使用LLMモデルなどのメトリクスを確認し、直接実行や編集を行うことができます。

**業務上の目的・背景**：AIワークフローの詳細情報を把握し、実行パフォーマンスや利用状況を分析することで、ワークフローの改善や運用計画の策定に役立てます。また、お気に入り機能により頻繁に使用するアプリを素早くアクセスできるようになります。

**画面へのアクセス方法**：ショーケース画面のアプリ一覧からアプリをクリック、または「/stage/showcase/{appId}」パスに直接アクセスします。stageV2Flagが有効な場合にのみ表示されます。

**主要な操作・処理内容**：
1. アプリの基本情報表示（名前、説明、作成者、チーム）
2. 実行統計の表示（実行回数、平均ランタイム、ステータス）
3. 実行履歴の一覧表示
4. アプリの実行（Runボタン、モーダル表示）
5. アプリの編集（Editボタン、ワークフローエディタへ遷移）
6. お気に入り登録/解除

**画面遷移**：この画面からはワークフローエディタ画面（/workspaces/{workspaceId}）に遷移できます。また、Runモーダルからアプリを実行できます。パンくずリストからショーケース画面に戻ることができます。

**権限による表示制御**：ログイン済みユーザーのみアクセス可能です。実行履歴は自分が実行したもののみが表示されます。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 61 | アプリ取得 | 主機能 | アプリの詳細情報、実行統計の取得と表示 |
| 25 | タスク取得 | 補助機能 | アプリの実行履歴（タスク一覧）の取得 |

## 画面種別

詳細

## URL/ルーティング

`/stage/showcase/[appId]`
- 動的パラメータ: `appId` (TriggerId形式)

## 入出力項目

| 項目名 | 型 | 入出力 | 必須 | 説明 |
|--------|-----|--------|------|------|
| appId | string | 入力 | 必須 | アプリのID（URLパラメータ） |

## 表示項目

| 項目名 | 説明 | データソース |
|--------|------|-------------|
| アプリ名 | アプリの表示名 | agents.name |
| 説明 | アプリの説明 | 固定値（"No description"） |
| チーム名 | アプリが属するチーム | teams.name |
| 作成者名 | アプリを作成したユーザー | users.displayName |
| 作成者アバター | 作成者のアバター画像 | users.avatarUrl |
| 更新日時 | 最終更新日時 | agents.updatedAt |
| ステータス | アクティブ/非アクティブ | 最近の実行有無から算出 |
| 平均ランタイム | 実行時間の平均 | agentActivities.totalDurationMs |
| 実行回数 | 総実行回数 | acts テーブルのカウント |
| 使用LLMモデル | 使用されているLLMモデル一覧 | workspace.nodes |
| お気に入り数 | お気に入り登録数 | 固定値（42） |
| 実行履歴一覧 | ユーザーの実行履歴 | acts テーブル |

## イベント仕様

### 1-Runボタン押下

Runボタン押下時、RunModalが表示され、ユーザーはモーダル内でアプリを実行できます。

### 2-Editボタン押下

Editリンク押下時、/workspaces/{workspaceId}に遷移し、ワークフローエディタでアプリを編集します。

### 3-お気に入り押下

Starボタン押下時、isFavorite状態がトグルされ、UIが更新されます（API保存は未実装）。

### 4-パンくずリストクリック

Showcaseリンク押下時、/stage/showcaseに遷移します。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | flowTriggers, agents, teams, users, acts, agentActivities | SELECT | アプリ詳細情報と統計を取得 |
| お気に入り登録 | - | - | 未実装 |

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

#### flowTriggers

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | sdkWorkspaceId | sdkFlowTriggerId = appId | アプリIDからワークスペースIDを取得 |

#### agents

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, dbId, name, updatedAt, workspaceId, createdAt | workspaceId = sdkWorkspaceId | アプリ情報を取得 |

#### acts

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | count(*) | sdkWorkspaceId = workspaceId | 総実行回数 |
| SELECT | sdkActId, createdAt, updatedAt | sdkWorkspaceId && directorDbId = user | 実行履歴（最大10件） |

#### agentActivities

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | avg(totalDurationMs), sum(totalDurationMs) | agentDbId = agent.dbId | ランタイム統計 |

## メッセージ仕様

| 種別 | メッセージ | 表示条件 |
|------|----------|----------|
| 空状態 | No execution history found | 実行履歴が0件の場合 |
| デフォルト説明 | No description | 説明が未設定の場合 |
| デフォルトランタイム | No runtime data | ランタイムデータがない場合 |

## 例外処理

| 状態 | 処理 |
|------|------|
| stageV2Flag無効 | 404ページ（notFound）を表示 |
| appIdのパース失敗 | 404ページを表示 |
| flowTriggersにアプリが存在しない | 404ページを表示 |
| agentデータが存在しない | 404ページを表示 |
| ワークスペースノード取得エラー | "Mixed models"を表示 |

## 備考

- この画面はstageV2Flagによる機能フラグ制御下にあります
- ステータスは最近7日以内に実行があれば"Active"、なければ"Inactive"と表示されます
- お気に入り数は現在固定値（42）が表示されています
- totalOutput、tokensの統計は現在"---"と表示されます（追加メトリクス追跡が必要）
- 説明文は現在固定値"No description"が使用されています

---

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

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

### 推奨読解順序

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

アプリ詳細で使用されるデータ構造を把握します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | app-detail-client.tsx | `apps/studio.giselles.ai/app/(main)/stage/showcase/[appId]/app-detail-client.tsx` | AppDetailsインターフェース定義（行13-46） |

**読解のコツ**: AppDetailsは複数テーブルからの情報を統合した複合型です。previewCardやcreator、executionHistoryなどのネスト構造に注目してください。

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

サーバーコンポーネントとしてのページの処理を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | page.tsx | `apps/studio.giselles.ai/app/(main)/stage/showcase/[appId]/page.tsx` | getAppDetails関数でのデータ取得ロジック |

**主要処理フロー**:
1. **行236-240**: stageV2Flagの確認と404処理
2. **行242-247**: appIdのパースとアプリ詳細取得
3. **行72-84**: flowTriggersテーブルからアプリを検索
4. **行97-113**: agentsテーブルからアプリ情報とチーム、作成者情報を結合取得
5. **行122-141**: actsテーブルから実行統計と最近の実行を取得
6. **行144-150**: agentActivitiesから平均ランタイムを取得
7. **行152-168**: ステータス（Active/Inactive）の判定
8. **行171-187**: ユーザーの実行履歴を取得
9. **行38-70**: extractLLMLabels関数でLLMモデル情報を抽出

#### Step 3: クライアントコンポーネントを理解する

UIとインタラクションの実装を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | app-detail-client.tsx | `apps/studio.giselles.ai/app/(main)/stage/showcase/[appId]/app-detail-client.tsx` | お気に入りトグル、Runモーダル表示、各セクションの表示 |

**主要処理フロー**:
- **行53-59**: お気に入りトグル処理
- **行61-63**: Runモーダル表示処理
- **行65-207**: レイアウトとアプリ情報表示
- **行209-260**: 実行履歴セクション
- **行262-327**: アプリ詳細セクション

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

```
page.tsx (Server Component)
    │
    ├─ stageV2Flag() - 機能フラグ確認
    │
    ├─ getAppDetails()
    │      ├─ TriggerId.safeParse() - appIdの検証
    │      │
    │      ├─ db.query.flowTriggers.findFirst() - アプリ取得
    │      │
    │      ├─ getUser() - 現在ユーザー取得
    │      │
    │      ├─ db.select (agents + teams + users) - アプリ情報結合取得
    │      │
    │      ├─ db.select (acts) - 実行統計取得
    │      │
    │      ├─ db.select (agentActivities) - ランタイム統計取得
    │      │
    │      ├─ extractLLMLabels() - LLMモデル抽出
    │      │      └─ giselle.getWorkspace()
    │      │
    │      └─ db.select (acts) - 実行履歴取得
    │
    └─ AppDetailClient (Client Component)
           ├─ toggleFavorite() - お気に入りトグル
           ├─ StatusBadge - ステータス表示
           └─ RunModal - 実行モーダル
```

### データフロー図

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

appId (URL param) ───────────▶ TriggerId.safeParse() ─────────▶ validatedAppId
         │                           │
         ▼                           ▼
flowTriggers テーブル ─────────▶ db.query.findFirst() ─────────▶ flowTrigger
         │                           │
         ▼                           ▼
agents/teams/users ────────────▶ db.select (JOIN) ─────────────▶ agentWithTeam
         │                           │
acts テーブル ─────────────────▶ count() / select() ───────────▶ executionStats
         │                                                       │
agentActivities テーブル ──────▶ avg() / sum() ────────────────▶ runtimeStats
         │                                                       │
         └───────────────────────────────────────────────────────▶ AppDetails
                                                                        │
                                                                        ▼
                                                              AppDetailClient
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| page.tsx | `apps/studio.giselles.ai/app/(main)/stage/showcase/[appId]/page.tsx` | ソース | サーバーコンポーネント、データ取得 |
| app-detail-client.tsx | `apps/studio.giselles.ai/app/(main)/stage/showcase/[appId]/app-detail-client.tsx` | ソース | クライアントコンポーネント、UI表示 |
| run-modal.tsx | `apps/studio.giselles.ai/app/(main)/stage/showcase/[appId]/components/run-modal.tsx` | ソース | 実行モーダルコンポーネント |
| status-badge.tsx | `internal-packages/ui/src/status-badge/status-badge.tsx` | ソース | ステータスバッジUI |
| giselle.ts | `apps/studio.giselles.ai/app/giselle.ts` | ソース | Giselleクライアント |
| flags.ts | `apps/studio.giselles.ai/flags.ts` | ソース | stageV2Flagの定義 |
