# 機能設計書 18-Webページノード

## 概要

本ドキュメントは、Giselleワークフローエンジンにおける Webページノード（WebPageNode）の機能設計を記述する。WebページノードはWebページからスクレイピングしたデータを保持し、他のノードへ提供するための変数ノードである。

### 本機能の処理概要

Webページノードは、ワークフロー内でWebページのコンテンツを管理する機能である。指定されたURLからWebページを取得し、そのコンテンツ（タイトル、ファビコン、テキスト内容等）を保持して、接続された後続ノードへ入力として提供する。

**業務上の目的・背景**：AIワークフローにおいて、Webページの内容を参照して処理を行うケースが増加している。Webページノードは、そのようなWeb上の情報を取得・管理し、AIモデルへの入力として提供する役割を担う。

**機能の利用シーン**：
- Webページの内容をAIで要約する場合
- 複数のWebページから情報を収集して分析する場合
- ニュース記事やブログ記事をAIで処理する場合

**主要な処理内容**：
1. URLからのWebページ取得（フェッチ）
2. ページメタデータ（タイトル、ファビコン）の抽出
3. ページコンテンツのファイルとしての保存
4. fetching/fetched/failed状態の管理
5. 出力ポートを通じた後続ノードへのデータ提供

**関連システム・外部連携**：
- Webページ追加機能（No.75）
- ファイル管理機能
- 外部Webサーバー

**権限による制御**：特になし（ワークスペース編集権限に依存）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 17 | ワークフローエディタ画面 | 主画面 | Webページノードの追加・編集、URL入力 |

## 機能種別

データ格納 / 外部データ取得

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| type | "webPage" | Yes | ノードコンテンツタイプ | リテラル値 |
| webpages | WebPage[] | Yes | Webページデータ配列 | 配列形式 |

### WebPageデータ構造

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|-----|------|
| id | WebPageId | Yes | WebページID（wbpg-で始まる） |
| url | string (URL) | Yes | WebページのURL |
| status | string | Yes | 状態（fetching/fetched/failed） |
| favicon | string | fetched時 | ファビコンURL |
| title | string | fetched時 | ページタイトル |
| fileId | FileId | fetched時 | コンテンツファイルID |
| errorMessage | string | failed時 | エラーメッセージ |

### 入力データソース

- **UIからのURL入力**: ユーザーがURL入力フィールドに入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| outputs | Output[] | 出力ポート配列（1要素） |
| outputs[0].id | OutputId | 出力ポートID |
| outputs[0].label | "Output" | 表示ラベル |
| outputs[0].accessor | "web-page" | アクセサー名 |

### 出力先

- 接続された後続ノードへのWebページコンテンツ提供
- テキスト生成ノードへの入力

## 処理フロー

### 処理シーケンス

```
1. ノード生成（createWebPageNode）
   └─ 空のwebpages配列で初期化
   └─ 出力ポート（accessor: "web-page"）を生成

2. Webページ追加
   └─ URLを入力
   └─ status: "fetching"でWebPage追加
   └─ Webページ取得処理開始

3. 取得処理
   └─ 成功: status: "fetched"、title/favicon/fileId設定
   └─ 失敗: status: "failed"、errorMessage設定

4. ワークフロー実行時
   └─ fetched状態のWebページコンテンツを取得
   └─ fileIdからファイル内容を読み取り
```

### フローチャート

```mermaid
flowchart TD
    A[ノード追加] --> B[空webpagesで初期化]
    B --> C[出力ポート生成]
    C --> D{URL追加}
    D -->|URL入力| E[status: fetching]
    E --> F[Webページ取得]
    F --> G{取得結果}
    G -->|成功| H[status: fetched]
    G -->|失敗| I[status: failed]
    H --> J[title/favicon/fileId設定]
    I --> K[errorMessage設定]
    J --> L[ワークスペース保存]
    K --> L
    L --> D
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | URL検証 | webpages[].urlは有効なURL形式であること | Webページ追加時 |
| BR-002 | 状態遷移 | fetching→fetched/failed | 取得処理完了時 |
| BR-003 | コンテンツ保存 | 取得したコンテンツはファイルとして保存 | 取得成功時 |
| BR-004 | 複数ページ対応 | 1つのノードで複数のWebページを管理可能 | webpages配列管理 |

### 計算ロジック

特になし（データ取得ノードのため）

## データベース操作仕様

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | 本ノード単体ではDB操作なし（ストレージ連携） |

### テーブル別操作詳細

Webページノード単体でのDB操作はない。ストレージ機能と連携してファイルを管理する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | フェッチエラー | Webページ取得失敗時 | status: "failed"、errorMessage設定 |

### リトライ仕様

Webページ取得の失敗時は、UIから再取得可能。

## トランザクション仕様

本ノード単体でのトランザクション制御はない。

## パフォーマンス要件

- 外部Webサーバーへのリクエストタイムアウトは実装依存

## セキュリティ考慮事項

- HTTPSサイトへのアクセスを推奨
- 取得したコンテンツはワークスペース内で管理

## 備考

- WebPageId: "wbpg-"で始まるID
- 取得したコンテンツはFileIdで参照可能なファイルとして保存される

---

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

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

### 推奨読解順序

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

まず、Webページノードのスキーマ定義を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | web-page.ts | `packages/protocol/src/node/variables/web-page.ts` | WebPageContent、WebPage、各状態のスキーマ定義 |
| 1-2 | index.ts | `packages/protocol/src/node/variables/index.ts` | WebPageNode型、isWebPageNode判定関数 |

**読解のコツ**: WebPageはstatus（fetching/fetched/failed）によって異なるプロパティを持つdiscriminatedUnion型。

#### Step 2: ノード生成ファクトリを理解する

ノードがどのように生成されるかを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | node-factories.ts | `packages/node-registry/src/node-factories.ts` | webPageFactoryImplの実装 |

**主要処理フロー**:
- **713-746行目**: webPageFactoryImplのcreate/clone実装
- **1035-1037行目**: createWebPageNode関数のエクスポート

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

```
createWebPageNode (node-factories.ts)
    │
    └─ WebPageNode生成
           ├─ id: NodeId.generate()
           ├─ type: "variable"
           ├─ content.type: "webPage"
           ├─ content.webpages: []
           ├─ inputs: []
           └─ outputs: [{accessor: "web-page"}]

Webページ追加時
    │
    ├─ WebPageId.generate()
    │
    └─ FetchingWebPage生成
           ├─ id: WebPageId
           ├─ url: URL
           └─ status: "fetching"

取得完了時
    │
    └─ FetchedWebPage
           ├─ status: "fetched"
           ├─ favicon: string
           ├─ title: string
           └─ fileId: FileId
```

### データフロー図

```
[ノード生成]                    [URL追加]                    [取得処理]

createWebPageNode ──▶ 空WebPageNode    URL入力
       │                                   │
       ▼                                   ▼
webpages: [] ◀──────────── FetchingWebPage生成
       │                                   │
       ▼                                   ▼
[ワークフロー保存]                   Webページ取得
                                          │
                               ┌──────────┴──────────┐
                               │                     │
                               ▼                     ▼
                        FetchedWebPage        FailedWebPage
                               │                     │
                               ▼                     ▼
                    title/favicon/fileId      errorMessage
                               │                     │
                               └──────────┬──────────┘
                                          │
                                          ▼
                                   webpages配列更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| web-page.ts | `packages/protocol/src/node/variables/web-page.ts` | ソース | WebPageContentスキーマ定義 |
| index.ts | `packages/protocol/src/node/variables/index.ts` | ソース | WebPageNode型、isWebPageNode関数 |
| node-factories.ts | `packages/node-registry/src/node-factories.ts` | ソース | ノード生成ファクトリ |
| add-web-page.ts | `packages/giselle/src/sources/add-web-page.ts` | ソース | Webページ追加処理 |
