# Liam ERD 業務運用マニュアル

## 目次

**【基本操作】**
1. [システム概要](#1-システム概要)
2. [ログイン・ログアウト手順](#2-ログインログアウト手順)
3. [トップページ（TOP画面）](#3-トップページtop画面)

**【業務フローに沿った機能】**
4. [【STEP1】プロジェクト作成・スキーマ登録](#4-step1プロジェクト作成スキーマ登録)
5. [【STEP2-3】デザインセッション機能（AI設計支援）](#5-step2-3デザインセッション機能ai設計支援)
6. [【STEP3-4】スキーマ表示・ER図機能](#6-step3-4スキーマ表示er図機能)
7. [【STEP4-5】共有・公開機能](#7-step4-5共有公開機能)

**【サポート機能】**
8. [組織管理機能](#8-組織管理機能)
9. [メンバー管理・招待機能](#9-メンバー管理招待機能)
10. [設定画面機能](#10-設定画面機能)

**【運用ガイド】**
11. [日常業務の流れ](#11-日常業務の流れ)
12. [よくある質問と対処法](#12-よくある質問と対処法)
13. [トラブルシューティング](#13-トラブルシューティング)

---

## 1. システム概要

### 1.1 Liam ERDとは

Liam ERDは、データベーススキーマから美しくインタラクティブなER図（Entity-Relationship Diagram）を自動生成するオープンソースツールです。GitHubリポジトリと連携し、複雑なデータベーススキーマを視覚的に分かりやすく可視化できます。また、AIエージェントを活用したデータベース設計支援機能により、対話形式でスキーマ設計を行うことができます。

### 1.2 本システムで行う主要業務

本システムは、主に以下の業務を支援します：

| 業務カテゴリ | 具体的な業務内容 |
|------------|----------------|
| **スキーマ可視化** | GitHubリポジトリのスキーマファイルからER図を自動生成、テーブル構造・リレーションシップの視覚的確認 |
| **データベース設計** | AIエージェントとの対話によるスキーマ設計、要件分析からのスキーマ自動生成 |
| **チーム共同作業** | 設計セッションの公開共有、組織メンバーとのプロジェクト共有 |
| **プロジェクト管理** | GitHubリポジトリ連携、スキーマファイルの監視設定、バージョン管理 |

### 1.3 業務フロー概要

本システムにおける業務は、以下の流れで進行します：

```
+-----------------------------------------------------------------+
|                        業務フロー                                 |
+-----------------------------------------------------------------+
|                                                                 |
|  【STEP 1】プロジェクト作成・スキーマ登録                          |
|      GitHubリポジトリと連携し、スキーマファイルを設定               |
|      ↓                                                          |
|  【STEP 2】デザインセッション開始                                  |
|      AIエージェントとの対話で要件を分析・スキーマを設計              |
|      ↓                                                          |
|  【STEP 3】スキーマ確認・ER図表示                                  |
|      生成されたスキーマをER図で視覚的に確認                         |
|      ↓                                                          |
|  【STEP 4】設計のレビュー・共有                                    |
|      チームメンバーと設計を共有し、フィードバックを収集               |
|      ↓                                                          |
|  【STEP 5】設計の確定・出力                                        |
|      最終スキーマの確定、マイグレーションファイルの生成               |
|                                                                 |
+-----------------------------------------------------------------+
```

**役割別の業務概要：**

| 役割 | 主な業務 |
|------|---------|
| **開発者** | プロジェクト作成、デザインセッションでのスキーマ設計、ER図確認、スキーマ変更の追跡 |
| **DBアーキテクト** | データベース設計の要件分析、AIエージェントとの対話による設計、設計レビュー |
| **管理者** | 組織作成・管理、メンバー招待、プロジェクト設定管理 |

### 1.4 主な機能

| 機能 | 説明 | 業務フローでの位置 |
|------|------|------------------|
| ER図自動生成 | データベーススキーマからER図を自動生成 | STEP 3 |
| デザインセッション | AIエージェントとの対話形式でスキーマ設計 | STEP 2 |
| スキーマパース | PostgreSQL、Rails schema.rb、Prisma等のスキーマ解析 | STEP 1 |
| プロジェクト管理 | GitHubリポジトリとの連携、スキーマ監視 | STEP 1 |
| 公開共有 | デザインセッションの公開リンク生成 | STEP 4 |
| 組織管理 | 組織作成、メンバー招待・管理 | 随時利用 |
| 設定画面 | 組織設定、プロジェクト設定、請求管理 | 随時利用 |

### 1.5 ユーザー種別

システムには以下のユーザー種別があります：

| ユーザー種別 | 説明 |
|-------------|------|
| 一般ユーザー | 組織に所属するメンバー。プロジェクト閲覧、デザインセッション参加が可能 |
| 組織管理者 | 組織の管理者。メンバー招待、設定変更が可能 |
| 公開ユーザー | 認証不要。公開ERD画面、公開デザインセッションの閲覧のみ可能 |

### 1.6 対応ブラウザ

推奨ブラウザ：
- Google Chrome（最新版）
- Microsoft Edge（最新版）
- Safari（最新版）
- Firefox（最新版）

---

## 2. ログイン・ログアウト手順

### 2.1 ログイン方法

1. ブラウザでLiam ERDのログインページ（`/login`）にアクセスします
2. ログイン画面が表示されます

**入力項目：**

| 項目 | 入力内容 |
|------|---------|
| メールアドレス | ご登録のメールアドレス |
| パスワード | ご登録のパスワード |

3. 以下のいずれかの方法でログインします：

**方法1：メールアドレスでログイン**
- 「メールアドレス」欄にメールアドレスを入力
- 「パスワード」欄にパスワードを入力
- 「Sign in」ボタンをクリック

**方法2：GitHubアカウントでログイン（推奨）**
- 「Sign in with GitHub」ボタンをクリック
- GitHubの認証画面に遷移します
- GitHubアカウントでログインし、アクセスを許可します

4. 認証に成功すると、「デザインセッション新規作成画面」が表示されます

> **注意**: 初回ログイン時は、自動的にユーザー名に基づいた組織が作成されます。

### 2.2 ログアウト方法

1. 画面右上のユーザーメニューまたはサイドバーをクリックします
2. 表示されるメニューから「ログアウト」を選択します
3. ログアウト処理が完了し、ログイン画面に戻ります
4. 「Logged out successfully」のメッセージが表示されます

### 2.3 パスワードを忘れた場合

現在、パスワードリセット機能はGitHub OAuth認証を使用しているため、GitHubアカウントのパスワードリセット手順に従ってください。

---

## 3. トップページ（TOP画面）

### 3.1 デザインセッション新規作成画面（メインTOP画面）

ログイン後、最初に表示される画面です。ここから新しいデータベース設計セッションを開始できます。

**画面構成：**

| 要素 | 説明 |
|------|------|
| タイトル | "How can I help you with Database Design?" |
| セッションモードセレクター | 5つのモードから選択可能 |
| 最近のセッション一覧 | 過去に作成したセッションへのクイックアクセス |

**セッション開始モード：**

| モード | 説明 | 用途 |
|--------|------|------|
| scratch | ゼロから新規作成 | 新しいデータベース設計を始める場合 |
| github | GitHubリポジトリ連携 | 既存のスキーマファイルを基に設計する場合 |
| upload | ファイルアップロード | ローカルのスキーマファイルを使用する場合 |
| url | URL指定 | 外部URLからスキーマを取得する場合 |
| paste | テキストペースト | スキーマ内容を直接貼り付ける場合 |

### 3.2 サイドバーナビゲーション

画面左側のサイドバーから以下の機能にアクセスできます：

| メニュー | 遷移先 |
|---------|--------|
| New Session | デザインセッション新規作成画面 |
| Projects | プロジェクト一覧画面 |
| Settings | 設定画面 |
| Recent Sessions | 最近のセッション一覧（クイックアクセス） |

---

## 4. 【STEP1】プロジェクト作成・スキーマ登録

> **業務フローでの位置**: GitHubリポジトリと連携し、スキーマファイルを監視対象として登録するステップです。

### 4.1 プロジェクト一覧を確認する

1. サイドバーから「Projects」をクリックします
2. 現在の組織に登録されているプロジェクト一覧が表示されます
3. 各プロジェクトカードには以下の情報が表示されます：
   - プロジェクト名
   - 連携しているGitHubリポジトリ情報
   - 作成日時

### 4.2 新規プロジェクトを作成する

**前提条件：**
- GitHubアカウントでログインしていること
- Liam ERDのGitHub Appがリポジトリにインストールされていること

**手順：**

1. プロジェクト一覧画面で「Add New Project」ボタンをクリックします
2. **Step 1: Import Git Repository**
   - GitHub Installationのドロップダウンからアカウントを選択します
   - 連携するリポジトリを一覧から選択してクリックします
3. **Step 2: Set Watch Schemas**
   - 「スキーマファイルパス」にスキーマファイルのパスを入力します
     - 例: `db/schema.rb`、`prisma/schema.prisma`、`schema.sql`
   - 「スキーマフォーマット」をドロップダウンから選択します

**対応フォーマット：**

| フォーマット | 説明 |
|-------------|------|
| postgres | PostgreSQL DDL（pg_dump出力等） |
| schemarb | Ruby on Rails schema.rb |
| prisma | Prisma schema.prisma |
| tbls | tbls schema.json（MySQL・SQLite・BigQuery対応） |

4. 「Save」ボタンをクリックします
5. プロジェクトが作成され、プロジェクト詳細画面に遷移します

> **注意**: スキーマファイルパスを間違えると、スキーマの取得に失敗します。正しいパスを入力してください。

### 4.3 プロジェクト詳細を確認する

1. プロジェクト一覧から確認したいプロジェクトをクリックします
2. プロジェクト詳細画面（ブランチ詳細画面）が表示されます
3. 以下の操作が可能です：
   - スキーマファイルを選択してER図を表示
   - 「Sessions」タブでデザインセッション一覧を確認
   - ブランチを切り替えて異なるバージョンを確認

---

## 5. 【STEP2-3】デザインセッション機能（AI設計支援）

> **業務フローでの位置**: AIエージェントと対話しながら、要件を分析してスキーマを設計するステップです。

### 5.1 デザインセッションとは

デザインセッションは、LangGraphベースのAIエージェント（Deep Modelingワークフロー）を活用したデータベース設計支援機能です。チャット形式でAIと対話し、以下の処理を自動化できます：

- 要件の分析・構造化
- データベーススキーマの設計
- マイグレーション操作の生成
- テストケースの生成

### 5.2 新規デザインセッションを開始する

**方法1：ゼロから開始（scratch）**

1. 「デザインセッション新規作成画面」で「scratch」タブを選択します
2. 設計したい内容を入力します
3. 送信すると、新しいセッションが作成され、AIとの対話が開始されます

**方法2：既存プロジェクトから開始（github）**

1. 「github」タブを選択します
2. プロジェクトを選択します
3. 関連するスキーマが自動的に読み込まれます
4. 既存スキーマを基に設計を進められます

**方法3：ファイルアップロード（upload）**

1. 「upload」タブを選択します
2. ローカルのスキーマファイルをドラッグ＆ドロップまたは選択します
3. アップロードしたスキーマを基に設計を開始します

### 5.3 AIとの対話で設計を進める

1. チャット入力欄に設計の要件や質問を入力します
2. 「送信」ボタンをクリックまたはEnterキーを押します
3. AIエージェントがリアルタイムでストリーミング応答を返します

**AIエージェントの処理フロー：**

```
ユーザー入力
    ↓
Lead Agent（分類）
    ├─ DBスキーマ設計関連 → PM Agent → DB Agent → QA Agent
    └─ 一般的な質問 → 直接応答
```

**入力例：**
- 「Eコマースサイトのデータベースを設計してください」
- 「ユーザーテーブルに電話番号カラムを追加したい」
- 「注文と商品の関係はどうなっていますか？」

### 5.4 バージョン管理を使用する

デザインセッションでは、スキーマの変更履歴がバージョンとして記録されます。

1. 画面右側の「Versions」パネルでバージョン一覧を確認します
2. 特定のバージョンをクリックすると、その時点のスキーマが表示されます
3. 差分表示で変更箇所を確認できます（追加/更新/削除が色分け表示）

### 5.5 設計結果を確認する

**ER図タブ：**
- 設計中のスキーマがER図として表示されます
- テーブル、カラム、リレーションシップを視覚的に確認できます
- 変更箇所はハイライト表示されます

**Artifactタブ：**
- AIエージェントが分析した要件情報を確認できます
- 生成されたテストケースを確認できます

---

## 6. 【STEP3-4】スキーマ表示・ER図機能

> **業務フローでの位置**: 生成されたスキーマをER図で視覚的に確認し、チームでレビューするステップです。

### 6.1 スキーマ画面でER図を表示する

1. プロジェクト詳細画面（ブランチ詳細画面）からスキーマファイルを選択します
2. スキーマ画面が表示され、ER図が自動生成されます

**ER図の操作：**

| 操作 | 方法 |
|------|------|
| パン（移動） | ドラッグ |
| ズーム | マウスホイール or ピンチ操作 |
| テーブル選択 | ノードをクリック |
| 関連テーブルのハイライト | テーブル選択時に自動ハイライト |

### 6.2 テーブル詳細を確認する

1. ER図上のテーブルノードをクリックします
2. サイドパネルにテーブルの詳細情報が表示されます：
   - カラム一覧（名前、型、制約）
   - インデックス一覧
   - 外部キー関係

### 6.3 サイドバーでテーブル一覧を確認する

1. 画面左側のサイドバーでテーブル一覧を確認できます
2. テーブル名をクリックすると、そのテーブルにフォーカスが移動します
3. 検索機能でテーブルを絞り込むことができます

### 6.4 レイアウトを調整する

- ER図は**ELKアルゴリズム**により自動レイアウトされます
- パネルの境界をドラッグしてサイズを調整できます
- レイアウト設定はCookieに保存され、次回も維持されます

---

## 7. 【STEP4-5】共有・公開機能

> **業務フローでの位置**: チームメンバーと設計を共有し、フィードバックを収集するステップです。

### 7.1 デザインセッションを公開共有する

1. デザインセッション詳細画面で、共有設定アイコンをクリックします
2. 「公開共有を有効にする」をオンにします
3. 公開URLが生成されます
4. URLをコピーしてチームメンバーに共有します

**公開共有の特徴：**
- 認証不要でアクセス可能
- 閲覧のみ可能（編集不可）
- URLは `/public/design_sessions/:id` の形式

### 7.2 公開ERD機能を使用する

認証不要で外部URLのスキーマをER図として表示できます。

**使用方法：**

1. GitHubのスキーマファイルURLを取得します
   - 例: `https://github.com/user/repo/blob/main/db/schema.rb`
2. URLの先頭を `https://liambx.com/erd/p/` に置き換えます
   - 例: `https://liambx.com/erd/p/github.com/user/repo/blob/main/db/schema.rb`
3. 変換したURLにアクセスすると、ER図が表示されます

**対応URL形式：**
- 単一ファイル: `/blob/` を含むURL
- フォルダ: `/tree/` を含むURL（フォルダ内のスキーマファイルを自動検出）

> **注意**: 公開リポジトリのファイルのみ取得可能です。プライベートリポジトリには対応していません。

---

## 8. 組織管理機能

### 8.1 組織とは

組織は、プロジェクトやメンバーを管理する単位です。ユーザーは複数の組織に所属できます。

### 8.2 組織一覧を確認する

1. 画面上部の組織切り替えドロップダウンをクリックします
2. 所属している組織の一覧が表示されます
3. 組織名をクリックして切り替えることができます

### 8.3 新規組織を作成する

1. 組織一覧画面で「Create New Organization」をクリックします
2. 組織新規作成画面が表示されます
3. 「組織名」を入力します
4. 「作成」ボタンをクリックします
5. 組織が作成され、プロジェクト新規作成画面に遷移します

---

## 9. メンバー管理・招待機能

### 9.1 メンバー一覧を確認する

1. サイドバーから「Settings」をクリックします
2. 「Members」タブを選択します
3. 以下のセクションが表示されます：
   - **Organization Members**: 現在のメンバー一覧
   - **Pending Invitations**: 保留中の招待一覧

### 9.2 メンバーを検索する

1. 「Search Members..」入力欄に検索キーワードを入力します
2. メンバー名またはメールアドレスでフィルタリングされます
3. リアルタイムで検索結果が更新されます

### 9.3 新規メンバーを招待する

1. 「Invite」ボタンをクリックします
2. 招待モーダルが表示されます
3. 招待先のメールアドレスを入力します
4. 「送信」ボタンをクリックします
5. 招待メールが送信され、保留中の招待一覧に追加されます

### 9.4 招待を承認する（招待された側）

1. 招待メールに記載されたリンクをクリックします
2. 招待承認画面が表示されます
3. 「承認」ボタンをクリックします
4. 組織に参加し、プロジェクト一覧画面に遷移します

### 9.5 メンバーを削除する

1. メンバー一覧で、削除したいメンバーの削除ボタンをクリックします
2. 確認ダイアログが表示されます
3. 「削除」をクリックします
4. メンバーが組織から削除されます

> **注意**: 自分自身を削除した場合、組織から離脱し、組織一覧画面にリダイレクトされます。

---

## 10. 設定画面機能

### 10.1 設定画面にアクセスする

1. サイドバーから「Settings」をクリックします
2. 設定画面が表示されます
3. 以下のタブで設定を切り替えられます：

| タブ | 説明 |
|------|------|
| General | 組織の一般設定（組織名変更等） |
| Projects | プロジェクト設定（準備中） |
| Members | メンバー管理・招待 |
| Billing | 請求・サブスクリプション設定（準備中） |

### 10.2 一般設定を変更する

1. 「General」タブを選択します
2. 組織名を変更できます
3. 「保存」ボタンをクリックして変更を適用します

---

## 11. 日常業務の流れ

本セクションでは、業務フローに沿った日常業務の流れを説明します。

```
業務フロー概要（再掲）
------------------------------------------------------
【STEP 1】プロジェクト作成・スキーマ登録 → 4章参照
    ↓
【STEP 2】デザインセッション開始 → 5章参照
    ↓
【STEP 3】スキーマ確認・ER図表示 → 6章参照
    ↓
【STEP 4】設計のレビュー・共有 → 7章参照
    ↓
【STEP 5】設計の確定・出力 → 7章参照
------------------------------------------------------
```

### 11.1 【開発者】STEP1: プロジェクト設定

新しいプロジェクトを開始する際の手順です。

1. サイドバーから「Projects」をクリック
2. 「Add New Project」ボタンをクリック
3. GitHubリポジトリを選択
4. スキーマファイルのパスとフォーマットを設定
5. 「Save」をクリックしてプロジェクトを作成

### 11.2 【開発者/DBアーキテクト】STEP2: 設計セッション開始

データベース設計を開始する際の手順です。

1. 「New Session」画面にアクセス
2. 適切なモードを選択（scratch / github / upload等）
3. 必要な情報を入力してセッションを開始
4. AIエージェントとの対話で要件を伝える

### 11.3 【開発者/DBアーキテクト】STEP3: 設計の確認

AIが生成したスキーマを確認する際の手順です。

1. ER図タブでテーブル構造を確認
2. リレーションシップが正しいか確認
3. カラム定義や制約を確認
4. 必要に応じてチャットで修正を依頼

### 11.4 【チーム】STEP4-5: レビューと共有

設計を共有してフィードバックを収集する際の手順です。

1. 公開共有を有効化
2. 公開URLをチームメンバーに共有
3. フィードバックを収集
4. 必要に応じてセッションで修正
5. 最終スキーマを確定

---

## 12. よくある質問と対処法

### 12.1 ログインに関するQ&A

**Q: ログインできません**

A: 以下を確認してください：
- GitHubアカウントでログインする場合、GitHubの認証画面でアクセスを許可していますか？
- ブラウザのCookieが有効になっていますか？
- 別のブラウザまたはシークレットモードで試してください

**Q: GitHubトークンの有効期限が切れたと表示されます**

A: 再度GitHubでログインしてください。システムが自動的にトークンをリフレッシュします。

### 12.2 プロジェクトに関するQ&A

**Q: GitHubリポジトリが一覧に表示されません**

A: 以下を確認してください：
- Liam ERDのGitHub Appがリポジトリにインストールされていますか？
- リポジトリへのアクセス権限がありますか？
- GitHub Appの権限設定を確認してください

**Q: スキーマファイルが見つからないエラーが表示されます**

A: 以下を確認してください：
- スキーマファイルパスが正しいか確認してください
- ブランチ名が正しいか確認してください
- ファイルが実際にリポジトリに存在するか確認してください

### 12.3 デザインセッションに関するQ&A

**Q: AIの応答が途中で止まりました**

A: ページをリロードしてください。セッションの状態は自動保存されており、中断した地点からワークフローを再開できます。

**Q: 生成されたスキーマを修正したい**

A: チャットで修正内容を伝えてください。例：「usersテーブルにemailカラムを追加してください」

---

## 13. トラブルシューティング

### 13.1 エラーメッセージと対処法

| エラーメッセージ | 原因 | 対処法 |
|----------------|------|--------|
| FileNotFound | スキーマファイルが見つからない | ファイルパスとブランチを確認 |
| FormatError - Record not found | スキーマ設定が登録されていない | プロジェクト設定でスキーマパスを登録 |
| Building schema not found | ビルディングスキーマが存在しない | 新しいセッションを作成 |
| Invalid schema format | スキーマフォーマットが不正 | 正しいフォーマットを指定 |
| NetworkError | ネットワーク接続エラー | インターネット接続を確認 |

### 13.2 よくあるトラブルと解決方法

**トラブル：ER図が表示されない**

解決方法：
1. ブラウザをリロードしてください
2. スキーマファイルが正しくパースできているか確認してください
3. エラーメッセージが表示されている場合は、その指示に従ってください
4. ブラウザのキャッシュをクリアしてください

**トラブル：セッションが保存されない**

解決方法：
1. インターネット接続を確認してください
2. ブラウザのCookieが有効になっているか確認してください
3. ページをリロードして再試行してください

**トラブル：メンバー招待が届かない**

解決方法：
1. メールアドレスが正しいか確認してください
2. 迷惑メールフォルダを確認してください
3. 招待を再送信してください

### 13.3 サポートへの連絡方法

問題が解決しない場合は、以下の方法でサポートにお問い合わせください：

- GitHub Issues: https://github.com/liam-hq/liam/issues
- ドキュメントサイト: アプリケーション内の「Docs」メニューから

---

## 改訂履歴

| 版数 | 改訂日 | 改訂内容 |
|-----|--------|---------|
| 1.0 | 2026-02-18 | 初版作成 |

---

*本マニュアルは、Liam ERDのエンドユーザー向け業務運用マニュアルです。*
*システムの更新により、画面や操作方法が変更される場合があります。*
