# 図解＋フィードバックツール

わからない言葉やしくみを AI に伝えるだけで、初めて聞く人にもわかるように噛み砕いた図解ページを自動で作り、フィードバック機能付きで公開できるツールです。

- **前提知識がなくても読める** — 専門用語は出てきた場所で必ずわかりやすく解説されます
- **文字の壁にならない** — カード・ステップ図・比較表など、目で見てわかる構成です
- **テキストを選んでコメント** — 公開した図解で、気になる箇所をマウスで選択するとコメント入力欄が出ます
- **優先度が色でわかる** — Must（赤）・Better（黄）・Want（緑）の 3 段階で重要度を伝えられます
- **セットアップは 1 回だけ** — 一度設定すれば、以降は図解を公開するたびにフィードバック機能が自動で付きます
- **無料で使える** — Vercel と Surge の無料プランだけで動きます

## しくみ

```
  「○○を図解して」と AI に依頼
    │
    ▼
  AI が図解 HTML を output/ に生成
    │
    ▼
  deploy-diagram.sh が自動で実行
    ├─ fb-tool-url.txt から FB ツール URL を取得
    ├─ </body> の直前に widget.js の <script> を注入
    └─ Surge にデプロイ
    │
    ▼
  公開 URL をブラウザで開く（FB 機能付き）
    ├─ widget.js    … 画面右のサイドバー・コメント入力・ハイライト表示
    └─ /api/comments … コメントの保存・取得
         │
         ▼
  Neon Postgres（無料DB）
    └─ comments テーブル … コメントデータを永続化
```

## セキュリティについて

API はトークンで保護されています。セットアップ時に自動で生成・設定されるため、追加の操作は不要です。

- コメント API（`/api/comments`）とページ取得 API（`/api/fetch-page`）はトークンなしではアクセスできません
- 図解のデプロイ時に、トークンが自動で埋め込まれます
- `fb-api-token.txt` はトークンを保存するファイルです。Git にはコミットされません

## セットアップ

初回だけ必要な設定です。AI が順番に案内してくれます。

```
  ① Node.js を確認
        ↓
  ② Vercel CLI をインストール
        ↓
  ③ 依存関係をインストール
        ↓
  ④ Vercel にログイン
        ↓
  ⑤ API トークンを生成
        ↓
  ⑥ Vercel にデプロイ
        ↓
  ⑦ データベースを追加（ブラウザで操作）
        ↓
  ⑧ マイグレーション実行
        ↓
  ⑨ 完了（fb-tool-url.txt と fb-api-token.txt が生成される）
```

### やり方

Cursor のチャット欄で次のように伝えてください。

```
セットアップして
```

AI がステップごとに案内してくれます。

### 必要なもの

| 必要なもの | 説明 | 費用 |
|-----------|------|------|
| Node.js | パソコン上でプログラムを動かすための土台。AI が自動でインストールを案内します | 無料 |
| Vercel アカウント | フィードバックツールを動かすサーバー。メールアドレスで登録できます | 無料（Hobby プラン） |
| Neon Postgres | コメントデータを保存するデータベース。Vercel の画面から追加します | 無料 |
| Surge アカウント | 図解を公開するサービス。初回にメールアドレスとパスワードで登録します | 無料 |

クレジットカードの登録は不要です。

## 使い方

### 図解を作る

Cursor のチャット欄に、知りたいことを書いて送信します。

```
APIについて図解して
```

AI が図解を作り、フィードバック機能付きで自動デプロイします。

### コメントを付ける

```
  ① 図解ページで気になるテキストをマウスで選択
        ↓
  ② ポップアップが表示される
        ↓
  ③ 優先度を選ぶ（Must / Better / Want）
        ↓
  ④ コメントを入力して「送信」
```

初回だけ名前の入力を求められます（次回以降は自動で記憶されます）。

### 優先度の意味

| 優先度 | 色 | 使いどころ |
|--------|-----|-----------|
| Must | 赤 | 必ず直すべき箇所（事実の間違い、重大なわかりにくさ） |
| Better | 黄 | 直すとよくなる箇所（表現の改善、構成の入れ替え） |
| Want | 緑 | 余裕があれば対応（細かい表現、好みの範囲） |

### コメントを確認する

画面右端の小さなボタンをクリックすると、サイドバーが開きます。

- **未解決 / 解決済 / すべて** のフィルタで絞り込めます
- コメントカードをクリックすると、本文の該当箇所にジャンプします
- 本文のハイライトをクリックすると、サイドバーの対応カードにジャンプします

### コメントを管理する

| 操作 | できること |
|------|-----------|
| 返信 | コメントにスレッド形式で返信 |
| 解決 | 対応済みのコメントを解決済みにする（再開もできます） |
| 編集 | 自分のコメントの内容・優先度を変更 |
| 削除 | 自分のコメントを削除 |
| 優先度変更 | 自分のコメントのバッジをクリックで Must → Better → Want を切り替え |

### コメントをダウンロードする

サイドバーのヘッダーにあるボタンでエクスポートできます。

- **JSON** — プログラムで処理したいとき
- **MD** — Markdown 形式。優先度ごとに分類されて出力されます

### 図解の削除

チャット欄で「この図解を削除して」と伝えてください。AI がデプロイ履歴から URL を特定し、削除を実行します。

## 以前の図解ツールとの違い

以前は「図解ツール」と「フィードバックツール」が別々のフォルダでした。

| | 旧（別々のツール） | 新（このツール） |
|---|---|---|
| フォルダ | 図解ツール + fb-tool-v2 の 2 つ | 図解コメントツールの 1 つだけ |
| FB 機能 | 図解ツールの base.html に手動で widget を埋め込み | デプロイ時に自動注入（base.html はクリーン） |
| 再 DL 時 | base.html が上書きされて widget 設定が消える | fb-tool-url.txt で管理。base.html に影響なし |
| セットアップ | 図解ツール側で base.html を編集する手順が必要 | 「セットアップして」だけで完了 |

旧図解ツールをすでに使っている場合は、このフォルダに切り替えるだけで移行できます。`output/` 内の既存の図解はそのまま使えます（再デプロイすれば FB 機能が自動で付きます）。

## フォルダの中身

```
図解コメントツール/
├── .claude/skills/
│   ├── creating-visual-explainers/  ← 図解生成スキル
│   │   ├── SKILL.md
│   │   ├── references/
│   │   │   ├── base.html           ← 図解テンプレート（widget なし）
│   │   │   ├── model-answer.html   ← 模範回答
│   │   │   └── node-install-guide.md
│   │   └── scripts/
│   │       └── deploy-diagram.sh   ← デプロイ＋widget 注入
│   └── setup-fb-tool/               ← セットアップスキル
│       ├── SKILL.md
│       └── references/
│           └── node-install-guide.md
├── output/                           ← 図解の保存先
├── public/
│   └── widget.js                     ← フィードバック UI 本体
├── src/
│   ├── app/api/comments/             ← コメント CRUD API
│   └── lib/
│       ├── db.ts                     ← データベース接続
│       └── types.ts                  ← 型定義
├── scripts/
│   └── migrate.ts                    ← DB テーブル作成
├── fb-tool-url.txt                   ← セットアップ完了後に生成
├── fb-api-token.txt                  ← API トークン（セットアップ完了後に生成）
├── deploy-history.log                ← 図解デプロイ履歴
├── package.json
└── README.md                         ← この説明書
```

| ファイル / フォルダ | 説明 | 触る必要 |
|---|---|---|
| `output/` | 図解の保存先 | 見るだけ |
| `public/widget.js` | フィードバック UI 本体 | なし |
| `src/app/api/comments/` | コメントの CRUD API | なし |
| `scripts/migrate.ts` | DB テーブル作成スクリプト（セットアップ時に 1 回だけ実行） | なし |
| `fb-tool-url.txt` | FB ツールの URL（セットアップ完了後に自動生成） | なし |
| `fb-api-token.txt` | API トークン（セットアップ完了後に自動生成） | なし |
| `deploy-history.log` | 図解の公開履歴（自動生成） | なし |

あなたが直接触る必要があるファイルはありません。
セットアップも図解の作成も、AI がすべて案内してくれます。

## 困ったとき

### 「セットアップして」と言っても反応しない

このフォルダ（`図解コメントツール`）を Cursor で開いているか確認してください。
フォルダの中の個別ファイルではなく、フォルダごと開く必要があります。

### Vercel へのデプロイが失敗する

チャット欄で「デプロイが失敗しました」と伝えてください。AI がエラーの内容を読み取り、対処法を案内してくれます。

### コメントが保存されない

データベースのセットアップが完了しているか確認してください。
チャット欄で「コメントが保存されません」と伝えると、AI が原因を調べてくれます。

### フィードバック欄が図解に表示されない

セットアップが完了していれば、新しく作る図解には自動で付きます。
すでに公開済みの図解には反映されないので、再デプロイしてください。

### その他のトラブル

何が起きても、まずはチャット欄で AI に状況を伝えてください。
AI がエラーの内容を読み取り、次にやるべきことを教えてくれます。

---

Mac / Windows どちらでも使えます。AI-Driven School 運営が動作確認済みです。