snc
@@ -0,0 +1,245 @@
|
||||
---
|
||||
name: creating-visual-explainers
|
||||
description: Generates an illustrated HTML page about any topic and deploys it to surge.sh with a comment widget (text/pin/voice feedback). Triggered by requests like "図解を作って", "図解を生成して", "このトピックを図解して", "図解してデプロイして", "この図解を再デプロイして", or "この図解を削除して".
|
||||
---
|
||||
|
||||
# Creating Visual Explainers
|
||||
|
||||
任意のトピックについて、前提知識がなくても理解できる図解HTMLを生成し、コメント機能（テキスト引用・ピン・音声）付きで surge.sh に公開する。品質基準は「入社したての新卒社会人が読んでも腹落ちする明快さ」だが、この基準は出力には表示しない。
|
||||
|
||||
## 依存
|
||||
|
||||
- `references/base.html` — 図解テンプレート（Tailwind CSS CDN・Lucide Icons CDN・ADS配色を含む「額縁」）
|
||||
- `references/model-answer.html` — 模範回答（品質基準・デザインパターンの実例）。base.htmlと同一の額縁を含む完全なHTMLファイル。widget 未含（デプロイ時に自動注入されるため）
|
||||
- リポジトリルートの `fb-tool-url.txt` / `fb-api-token.txt` — セットアップスキル（`setting-up-comment-tool`）が生成する
|
||||
|
||||
## ワークフロー
|
||||
|
||||
### Step 0: 前提確認
|
||||
|
||||
1. `references/base.html` が存在するか確認する。存在しない場合、以下を伝えて終了:
|
||||
|
||||
> テンプレートファイルが見つかりません。スキルのフォルダ構成が壊れている可能性があります。運営に連絡してください。
|
||||
|
||||
2. リポジトリルート（`.claude` フォルダがある階層）に `fb-tool-url.txt` が存在するか確認する。存在しない場合、以下を伝えて終了:
|
||||
|
||||
> コメントツールのセットアップがまだ完了していません。
|
||||
> 先にチャット欄で「セットアップして」と伝えてください。
|
||||
|
||||
### Step 1: 模範回答の読み込み
|
||||
|
||||
`references/model-answer.html` を読み、以下を把握する:
|
||||
|
||||
- 完成品の品質水準
|
||||
- デザインパターン（色使い・余白・カード・フロー図などの視覚表現）
|
||||
- Tailwind CSSクラスの使い方
|
||||
- Lucide Iconsの使い方
|
||||
- コンテンツの構成・情報量・説明の深さ
|
||||
|
||||
模範回答がデザインガイドラインの代わりになる。パーツ一覧やルールではなく、実物から読み取る。
|
||||
|
||||
### Step 2: テンプレートの読み込み
|
||||
|
||||
`references/base.html` を読み、額縁の構造を把握する:
|
||||
|
||||
- `<!-- CONTENT_START -->` 〜 `<!-- CONTENT_END -->` のプレースホルダー位置
|
||||
- `<!-- TITLE -->`, `<!-- DESCRIPTION -->` のプレースホルダー
|
||||
- ADS配色のTailwind設定
|
||||
- 読み込み済みのCDN（Tailwind CSS・Lucide Icons）
|
||||
|
||||
### Step 3: ウェブで情報収集
|
||||
|
||||
トピックについてウェブ検索を行い、正確かつ最新の情報を収集する。
|
||||
|
||||
検索は **2〜3回** に絞る。以下の観点でクエリを組み立てる:
|
||||
|
||||
1. **正確な定義**: トピックの公式な定義、公式ドキュメントの説明
|
||||
2. **最新動向**: 直近の変更点、アップデート、現在のベストプラクティス
|
||||
3. **具体例**: 実際の使われ方、初心者に伝わるたとえに使える事例
|
||||
|
||||
検索結果から以下を整理し、Step 4 の参考情報とする:
|
||||
|
||||
- トピックの正確な定義（検索結果を優先。AIの学習データだけに頼らない）
|
||||
- 最近変わった点があれば、それを明記する
|
||||
- たとえ話に使えそうな事例や数字
|
||||
- **出典URL**: 図解に採用した情報のソースURLを控えておく（Step 4 でインライン出典に使う）
|
||||
|
||||
### Step 4: コンテンツ生成
|
||||
|
||||
Step 3 で収集した情報をもとに、図解HTMLを生成する。検索結果で得た定義・事実・具体例を優先的に採用する。
|
||||
|
||||
模範回答のデザインを参考にしつつ、Tailwindの語彙で自由にレイアウトを組む。模範回答のパターンに合うものはそのまま使い、合わないものはTailwindクラスでその場で作る。テンプレートの定義済みパーツに縛られない。
|
||||
|
||||
### Step 5: ファイル作成
|
||||
|
||||
1. `output/` ディレクトリがなければ作成する
|
||||
2. トピックに関連する短い英単語のスラッグを決める（例: `api-basics`, `git-rebase`）
|
||||
3. `references/base.html` を `output/{スラッグ}.html` にコピーする
|
||||
4. コピーしたファイル内のプレースホルダーをすべて置換する:
|
||||
- `<!-- TITLE -->` → 図解のタイトル
|
||||
- `<!-- DESCRIPTION -->` → 内容を要約した1文
|
||||
- `<!-- CONTENT_START -->` 〜 `<!-- CONTENT_END -->` → Step 4で生成したコンテンツ
|
||||
5. ファイルを保存する（ブラウザで開くのは Step 6 のデプロイ後に行う。ローカルでは開かない）
|
||||
|
||||
### Step 6: 公開
|
||||
|
||||
ファイル保存後、公開する前にまず Node.js の有無を確認する。
|
||||
|
||||
```bash
|
||||
node --version
|
||||
```
|
||||
|
||||
バージョン番号が表示された → そのまま「公開の実行」に進む。
|
||||
|
||||
`command not found` と表示された → `references/node-install-guide.md` の手順に従ってNode.jsのインストールを案内する。
|
||||
|
||||
#### 公開の実行
|
||||
|
||||
以下のスクリプトを**実行する**（中身を読む必要はない）。コメントウィジェットの埋め込みはこのスクリプトが自動で行う。
|
||||
|
||||
**macOS / Git Bash（Windows）の場合:**
|
||||
|
||||
```bash
|
||||
bash .claude/skills/creating-visual-explainers/scripts/deploy-diagram.sh output/{スラッグ}.html [スラッグ]
|
||||
```
|
||||
|
||||
**Windows（PowerShell）で bash が使えない場合:**
|
||||
|
||||
```powershell
|
||||
$fbUrl = (Get-Content fb-tool-url.txt).Trim()
|
||||
$apiToken = (Get-Content fb-api-token.txt).Trim()
|
||||
$snippet = "<script src=`"$fbUrl/widget.js`" data-token=`"$apiToken`"></script>"
|
||||
$dir = "$env:TEMP\diagram-deploy"
|
||||
New-Item -ItemType Directory -Force $dir | Out-Null
|
||||
# (?s)^(.*)</body> は貪欲マッチのため「最後の </body>」だけを置換する
|
||||
# （本文中にコード例として </body> があっても多重注入しない。bash 版と同じ挙動）
|
||||
(Get-Content output/{スラッグ}.html -Raw) -replace '(?s)^(.*)</body>', ('$1' + $snippet + '</body>') | Set-Content "$dir\index.html"
|
||||
Set-Content "$dir\robots.txt" "User-agent: *`nDisallow: /"
|
||||
npx --yes surge $dir --domain diagram-[スラッグ].surge.sh
|
||||
Add-Content deploy-history.log "$(Get-Date -Format 'yyyy-MM-dd HH:mm:ss') | https://diagram-[スラッグ].surge.sh"
|
||||
```
|
||||
|
||||
スラッグにはトピックに関連する短い英単語を指定する（例: `git-rebase`, `api-basics`）。
|
||||
|
||||
#### 初回の場合（Surge未登録）
|
||||
|
||||
ターミナルにメールアドレスとパスワードの入力を求められる。以下を伝える:
|
||||
|
||||
> 初回のみアカウント登録が必要です。
|
||||
> メールアドレスを入力して Enter → パスワードを決めて入力して Enter。
|
||||
> 確認メールが届いたらリンクをクリックすれば登録完了です。
|
||||
> 次回以降はこの手順は不要です。
|
||||
|
||||
#### エラーが出た場合
|
||||
|
||||
エラーメッセージをそのまま見せず、**何が起きていて何をすれば解決するか**を、専門用語を避けて平易に説明する。
|
||||
|
||||
よくあるエラーと対応:
|
||||
|
||||
- **`npx: command not found`** — Node.js がまだ入っていない。`references/node-install-guide.md` の手順を案内する
|
||||
- **`surge: not found` / surge関連エラー** — `npm install -g surge` を実行してから再度試す
|
||||
- **認証エラー / `Login required`** — `npx surge login` を実行してメールアドレスとパスワードを入力する
|
||||
- **`fb-tool-url.txt が見つかりません`** — セットアップが未完了。チャット欄で「セットアップして」と伝えるよう案内する
|
||||
- **その他** — エラーの内容を読み、「何が問題で」「次に何をすればいいか」を平易に説明する
|
||||
|
||||
### 図解の再デプロイ
|
||||
|
||||
ユーザーが「この図解を再デプロイして」と依頼した場合（内容の修正後や、公開済み図解にコメント機能を付け直すとき）:
|
||||
|
||||
1. 対象の HTML を特定する（直近に編集した `output/{スラッグ}.html`。不明ならリポジトリルートの `deploy-history.log` から URL を確認し、ドメインの `diagram-` 以降がスラッグ）
|
||||
2. 「公開の実行」と同じコマンドを、**同じスラッグ**で再実行する（同じ URL に上書き公開される）
|
||||
|
||||
### 図解の削除
|
||||
|
||||
ユーザーが「この図解を削除して」と依頼した場合:
|
||||
|
||||
1. リポジトリルートの `deploy-history.log` を読み、直近のデプロイURLを特定する
|
||||
- ログが存在しない場合 → ユーザーに削除したいURLを聞く
|
||||
2. `npx surge teardown [ドメイン]` を実行する
|
||||
3. 削除完了をユーザーに伝える
|
||||
|
||||
### Step 7: 完了報告
|
||||
|
||||
#### 公開に成功した場合
|
||||
|
||||
```
|
||||
完成・公開完了: 【図解のタイトル】
|
||||
|
||||
（図解の内容を1〜2文で要約）
|
||||
|
||||
公開URL:
|
||||
https://diagram-スラッグ.surge.sh
|
||||
|
||||
図解の主なポイント:
|
||||
- （主要トピックを3〜5個）
|
||||
|
||||
コメントの付け方:
|
||||
ページ右端のボタンから、テキスト選択・ピン・音声（マイクに向かって喋る）の
|
||||
3通りでフィードバックできます。
|
||||
|
||||
この図解を削除したいとき:
|
||||
チャット欄で「この図解を削除して」と伝えてください。
|
||||
```
|
||||
|
||||
#### 公開できなかった場合
|
||||
|
||||
```
|
||||
完成: 【図解のタイトル】
|
||||
|
||||
（図解の内容を1〜2文で要約）
|
||||
|
||||
ファイルの保存先:
|
||||
output/{スラッグ}.html（ブラウザにドラッグ＆ドロップすると表示できます）
|
||||
|
||||
図解の主なポイント:
|
||||
- （主要トピックを3〜5個）
|
||||
|
||||
URLで共有したいとき:
|
||||
チャット欄で「この図解を公開して」と伝えてください。
|
||||
```
|
||||
|
||||
## 守ること（禁止事項）
|
||||
|
||||
- **見出し（`h1`〜`h4`）を必ず入れる** — 音声コメントはページ内の見出しを手がかりにピンを配置する。見出しが1つも無いHTMLでは音声フィードバックがエラーになる
|
||||
- **React・shadcn/ui を使わない** — 静的な図解にJSフレームワークは不要。AIの出力を制限し、モデルによる品質差も限定的にしてしまう
|
||||
- **絵文字を使わない** — OS依存で表示が変わる。アイコンはLucide Iconsを使う
|
||||
- **インタラクティブ要素を入れない** — トグル、フェードイン、アニメーション、フォーム、クリックで開閉する要素は一切禁止
|
||||
- **`<style>` タグを追加しない** — スタイリングはTailwind CSSクラスで行う。インラインの `style` 属性も避ける
|
||||
- **`<script>` を追加しない** — テンプレートに含まれるもの以外のJavaScriptは禁止。widget.js の埋め込みはデプロイスクリプトが自動で行うため、SKILL の範囲外
|
||||
- **外部リソースを追加しない** — テンプレートに含まれるCDN以外の外部読み込み（画像URL・フォント・追加CDN）は禁止
|
||||
- **テンプレートの額縁構造を変更しない** — `<head>`・CDN読み込み・meta タグはそのまま維持する
|
||||
- **PDF印刷で消える表現を使わない** — `bg-clip-text text-transparent` によるグラデーション文字はPDF出力時に透明のまま消える。テンプレートの print CSS でフォールバックを入れているが、グラデーション文字を使った場合はPDF出力で色が単色（`#2563EB`）に変わる点を意識すること
|
||||
|
||||
## コンテンツ生成の指針
|
||||
|
||||
- **概論 → 各論** — いきなり詳細に入らない。全体像を見せてから個別の話に入る
|
||||
- **専門用語は初出で必ず解説** — 「API（Application Programming Interface＝ソフトウェア同士がやり取りするための窓口）」のように、括弧書きで平易に説明する
|
||||
- **たとえ話で身近な体験に結びつける** — レストランの注文、郵便配達、信号機など、技術を知らない人でもイメージできる例を使う
|
||||
- **簡潔にまとめすぎない** — 理解に必要な情報量は削らない。腹落ちするまで丁寧に説明する
|
||||
- **図を早く見せる** — 見出しから最初のビジュアルまでに、テキストは最大2段落（各2〜3行）。それ以上の説明が必要な場合は、図を先に見せてから図の後にテキストで補足する（図→説明の順）。「説明してから図を見せる」より「図を見せてから説明する」方が、同じ文量でも「読まされている感」がなくなる。テキストで述べたたとえ話（ゲーム、レストラン等）も、テキストだけで済まさずミニビジュアル化を検討する
|
||||
- **「見たことがあるもの」は説明するのではなく見せる** — 図解の中で読者がすでに体験しているもの（アプリの画面、ツールのUI、Webサイト）に言及するとき、テキストで「〜という画面が表示されます」と書く代わりに、その画面自体をTailwind CSSで再現して配置する。「天気アプリの画面」なら天気アプリのモックアップを、「チャット画面」ならチャットUIを、「ターミナル」ならターミナルウィンドウを見せる。読者の「見たことある！」という記憶が発火する瞬間が、テキスト説明より圧倒的に理解を深める
|
||||
- **ビジュアルには2つの役割がある** — 図解に使うビジュアルは「構造を示す図」と「体験を再現する図」の2種類。どちらか一方ではなく、両方を組み合わせて使う:
|
||||
- **構造パターン（仕組みを頭で理解する図）** — 知識の種類に応じて選ぶ:
|
||||
- **「Xとは何か」(定義)** → アナロジー図: 身近なたとえの登場人物を配置し、矢印で関係を示す。主役を中央に大きく
|
||||
- **「Xはどう動くか」(プロセス)** → ステップフロー: 番号つき横並び（モバイルは縦）。各ステップにアイコン＋一言。色はステップごとに変える
|
||||
- **「XとYの違い」(比較)** → 左右対比: 2カラムで並べ、同じ観点を同じ行に揃える。✗/✓ や赤/緑で差を一目で伝える
|
||||
- **「Xの具体例」(事例)** → カードグリッド: 2列のカードにアイコン＋タイトル＋説明。カード内で「表の顔」と「裏の仕組み」を分けると深みが出る
|
||||
- **「Xのすごさ」(数値)** → 数字カード: 3カラムに大きな数字。text-3xl font-black で存在感を出し、色を各数字で変える
|
||||
- **「Xの構造・中身」(階層)** → 入れ子ブロック: 外側の大きなブロック内に構成要素を配置。ボーダーや背景色の濃淡で階層を表現
|
||||
- **「Xの誤解」(訂正)** → 誤解→正解カード: 赤ヘッダーに誤解、本文に緑で正解。✗と✓の対比
|
||||
- **「Xの変遷」(時系列)** → タイムライン: 左にボーダーライン、各時点に年号・ラベル・要約。色のグラデーションで時代の変化を表現
|
||||
- **体験再現パターン（読者の「見たことある」記憶と結びつける図）** — 読者が実際に触れたことのある画面をTailwind CSSで再現する。「あなたが見ているもの」「〜の画面では」「実際に使うとき」のような文脈が出てきたら、テキスト説明ではなくこちらを使う:
|
||||
- **チャットUI** — 吹き出し形式の対話画面。暗い背景＋ユーザー吹き出し（右寄せ）＋AI吹き出し（左寄せ）＋入力欄モック
|
||||
- **エディタUI** — タイトルバー（赤黄緑ボタン）＋サイドバー（ファイルツリー）＋コードペイン。AIチャットパネルを加えた3ペインも可
|
||||
- **ターミナルUI** — タイトルバー（赤黄緑ボタン）＋プロンプト（$）＋コマンド＋出力。コードブロックとの違いはウィンドウ枠がある点
|
||||
- **ブラウザUI** — タイトルバー（赤黄緑ボタン）＋アドレスバー＋ページ内容
|
||||
- **アプリ画面** — 上記に当てはまらないアプリ（天気予報、地図、決済画面など）。角丸カード内にアイコン＋数値＋ラベルでミニ画面を再現
|
||||
- 共通ルール: 中身はリアルすぎず要点が伝わるミニマルな内容にする。特定ブランドのロゴや名称は使わず汎用的な表現にする。Tailwind CSSクラスのみで構成する
|
||||
- **冒頭にヒーロー＋一枚絵サマリー** — タイトルで「何の図解か」を伝えたあと、そのままトピックの核心を1枚の図で見せる。ヒーローの説明文を図への導入（「ひとことで言えば──」のような引き）にし、図の直後に各論への橋渡し（「ここからひとつずつ解説していきます」）を置く。ヒーロー → 一言の答え → 図 → 各論が一本の流れになること。一枚絵サマリーの構成:
|
||||
- **一言の答え**: トピックの核心を1文で太字表示（カード冒頭）。読者が「なるほど」と思える定義を先に読ませ、そのあとの図で視覚的に裏付ける
|
||||
- **コア図解**: 一言の答えを図にしたもの。アイコン＋矢印＋ラベルで表現
|
||||
- **身近な接点**: 読者がすでに体験している具体例を、アイコン＋一言のピルで2〜4個並べる
|
||||
- **読者のレベルに言及しない** — 「初心者向け」「入門」「未経験者でもわかる」のように読者を特定のレベルにラベリングする表現をタイトル・見出し・本文に入れない。「わかりやすく説明する」のは図解の品質であって、読者のレベルではない。たとえ話や専門用語の解説で自然に噛み砕けば、ラベルなしで誰にでも伝わる
|
||||
- **ヒーローバッジはトピックカテゴリ** — タイトル上のバッジには、トピックのカテゴリを入れる（テクノロジー、ビジネス、開発ツール、デザイン、マーケティングなど）。「初心者向け」「入門」など読者のレベルを示すラベルは入れない
|
||||
- **インライン出典** — 検索結果から採用した事実・定義・数字のすぐ近くに、出典リンクをさりげなく添える。本文の読みやすさを損なわないよう `text-xs text-ads-dim` で小さく薄く表示し、リンクテキストはURLそのままではなく「出典: ○○公式ドキュメント」のようにページ内容がわかる名前にする。段落末やカード下部など、視線の流れを邪魔しない位置に置く
|
||||
- **日本語で** — 英語メインのトピックでも、図解は日本語で書く
|
||||
@@ -0,0 +1,83 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="ja">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<meta name="robots" content="noindex, nofollow, noarchive, nosnippet, noimageindex">
|
||||
<meta name="googlebot" content="noindex, nofollow">
|
||||
<meta property="og:title" content="<!-- TITLE -->">
|
||||
<meta property="og:description" content="<!-- DESCRIPTION -->">
|
||||
<meta property="og:type" content="article">
|
||||
<title><!-- TITLE --></title>
|
||||
<link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><rect width='100' height='100' rx='20' fill='%23FFFFFF'/><rect x='8' y='8' width='84' height='84' rx='14' fill='none' stroke='%233B82F6' stroke-width='4'/><circle cx='32' cy='40' r='10' fill='%233B82F6' opacity='0.8'/><circle cx='68' cy='40' r='10' fill='%2360A5FA' opacity='0.8'/><rect x='25' y='62' width='50' height='6' rx='3' fill='%2394A3B8' opacity='0.6'/><rect x='30' y='74' width='40' height='6' rx='3' fill='%2394A3B8' opacity='0.3'/></svg>">
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
||||
<link href="https://fonts.googleapis.com/css2?family=Noto+Sans+JP:wght@400;500;700;900&display=swap" rel="stylesheet">
|
||||
<script src="https://cdn.tailwindcss.com"></script>
|
||||
<script>
|
||||
tailwind.config = {
|
||||
theme: {
|
||||
extend: {
|
||||
colors: {
|
||||
ads: {
|
||||
bg: '#FFFFFF',
|
||||
surface: '#F8FAFC',
|
||||
hover: '#F1F5F9',
|
||||
border: '#E2E8F0',
|
||||
accent: '#3B82F6',
|
||||
'accent-light': '#2563EB',
|
||||
text: '#1E293B',
|
||||
muted: '#64748B',
|
||||
dim: '#94A3B8',
|
||||
positive: '#10B981',
|
||||
negative: '#EF4444',
|
||||
warning: '#F59E0B',
|
||||
}
|
||||
},
|
||||
fontFamily: {
|
||||
sans: ['"Noto Sans JP"', '"Hiragino Sans"', '"Hiragino Kaku Gothic ProN"', '"Yu Gothic UI"', '"Meiryo"', 'sans-serif'],
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
</script>
|
||||
<style>
|
||||
@media print {
|
||||
.no-print { display: none !important; }
|
||||
body { border-top: none !important; }
|
||||
.rounded-xl { break-inside: avoid; }
|
||||
.md\:flex-row { flex-direction: row !important; }
|
||||
.md\:hidden { display: none !important; }
|
||||
.hidden.md\:block { display: block !important; }
|
||||
.md\:grid-cols-2 { grid-template-columns: repeat(2, minmax(0, 1fr)) !important; }
|
||||
.sm\:grid-cols-3 { grid-template-columns: repeat(3, minmax(0, 1fr)) !important; }
|
||||
.md\:mb-20 { margin-bottom: 5rem !important; }
|
||||
.md\:py-16 { padding-top: 4rem !important; padding-bottom: 4rem !important; }
|
||||
.bg-clip-text.text-transparent {
|
||||
-webkit-background-clip: initial !important;
|
||||
background-clip: initial !important;
|
||||
color: #2563EB !important;
|
||||
-webkit-text-fill-color: #2563EB !important;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body class="bg-ads-bg text-slate-600 antialiased leading-relaxed border-t-4 border-ads-accent">
|
||||
<div class="no-print max-w-3xl mx-auto px-5 pt-2 flex justify-end">
|
||||
<button onclick="window.print()" class="flex items-center gap-1.5 text-xs text-ads-dim hover:text-ads-accent transition-colors cursor-pointer">
|
||||
<i data-lucide="download" class="w-3.5 h-3.5"></i>
|
||||
PDF
|
||||
</button>
|
||||
</div>
|
||||
<main class="max-w-3xl mx-auto px-5 py-10 md:py-16">
|
||||
<!-- CONTENT_START -->
|
||||
|
||||
<!-- CONTENT_END -->
|
||||
</main>
|
||||
<footer class="max-w-3xl mx-auto px-5 pb-10 pt-6 border-t border-ads-border/30">
|
||||
<p class="text-xs text-ads-dim text-center">AI-Driven School の図解ツールで作成</p>
|
||||
</footer>
|
||||
<script src="https://unpkg.com/lucide@latest"></script>
|
||||
<script>lucide.createIcons();</script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,968 @@
|
||||
<!-- このファイルの<head>はreferences/base.htmlと同一に保つ。base.html変更時は必ずこちらも更新する -->
|
||||
<!DOCTYPE html>
|
||||
<html lang="ja">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<meta name="robots" content="noindex, nofollow, noarchive, nosnippet, noimageindex">
|
||||
<meta name="googlebot" content="noindex, nofollow">
|
||||
<meta property="og:title" content="APIの仕組み">
|
||||
<meta property="og:description" content="APIの仕組みを、身近な例とビジュアルでわかりやすく図解します。">
|
||||
<meta property="og:type" content="article">
|
||||
<title>APIの仕組み</title>
|
||||
<link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><rect width='100' height='100' rx='20' fill='%23FFFFFF'/><rect x='8' y='8' width='84' height='84' rx='14' fill='none' stroke='%233B82F6' stroke-width='4'/><circle cx='32' cy='40' r='10' fill='%233B82F6' opacity='0.8'/><circle cx='68' cy='40' r='10' fill='%2360A5FA' opacity='0.8'/><rect x='25' y='62' width='50' height='6' rx='3' fill='%2394A3B8' opacity='0.6'/><rect x='30' y='74' width='40' height='6' rx='3' fill='%2394A3B8' opacity='0.3'/></svg>">
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
||||
<link href="https://fonts.googleapis.com/css2?family=Noto+Sans+JP:wght@400;500;700;900&display=swap" rel="stylesheet">
|
||||
<script src="https://cdn.tailwindcss.com"></script>
|
||||
<script>
|
||||
tailwind.config = {
|
||||
theme: {
|
||||
extend: {
|
||||
colors: {
|
||||
ads: {
|
||||
bg: '#FFFFFF',
|
||||
surface: '#F8FAFC',
|
||||
hover: '#F1F5F9',
|
||||
border: '#E2E8F0',
|
||||
accent: '#3B82F6',
|
||||
'accent-light': '#2563EB',
|
||||
text: '#1E293B',
|
||||
muted: '#64748B',
|
||||
dim: '#94A3B8',
|
||||
positive: '#10B981',
|
||||
negative: '#EF4444',
|
||||
warning: '#F59E0B',
|
||||
}
|
||||
},
|
||||
fontFamily: {
|
||||
sans: ['"Noto Sans JP"', '"Hiragino Sans"', '"Hiragino Kaku Gothic ProN"', '"Yu Gothic UI"', '"Meiryo"', 'sans-serif'],
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
</script>
|
||||
<style>
|
||||
@media print {
|
||||
.no-print { display: none !important; }
|
||||
body { border-top: none !important; }
|
||||
.rounded-xl { break-inside: avoid; }
|
||||
.md\:flex-row { flex-direction: row !important; }
|
||||
.md\:hidden { display: none !important; }
|
||||
.hidden.md\:block { display: block !important; }
|
||||
.md\:grid-cols-2 { grid-template-columns: repeat(2, minmax(0, 1fr)) !important; }
|
||||
.sm\:grid-cols-3 { grid-template-columns: repeat(3, minmax(0, 1fr)) !important; }
|
||||
.md\:mb-20 { margin-bottom: 5rem !important; }
|
||||
.md\:py-16 { padding-top: 4rem !important; padding-bottom: 4rem !important; }
|
||||
.bg-clip-text.text-transparent {
|
||||
-webkit-background-clip: initial !important;
|
||||
background-clip: initial !important;
|
||||
color: #2563EB !important;
|
||||
-webkit-text-fill-color: #2563EB !important;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body class="bg-ads-bg text-slate-600 antialiased leading-relaxed border-t-4 border-ads-accent">
|
||||
<div class="no-print max-w-3xl mx-auto px-5 pt-2 flex justify-end">
|
||||
<button onclick="window.print()" class="flex items-center gap-1.5 text-xs text-ads-dim hover:text-ads-accent transition-colors cursor-pointer">
|
||||
<i data-lucide="download" class="w-3.5 h-3.5"></i>
|
||||
PDF
|
||||
</button>
|
||||
</div>
|
||||
<main class="max-w-3xl mx-auto px-5 py-10 md:py-16">
|
||||
<!-- CONTENT_START -->
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- HERO -->
|
||||
<!-- ============================================================ -->
|
||||
<div class="text-center mb-8 md:mb-10">
|
||||
<div class="inline-flex items-center gap-2 bg-ads-accent/10 text-ads-accent-light px-4 py-1.5 rounded-full text-sm font-medium mb-6">
|
||||
<i data-lucide="cpu" class="w-4 h-4"></i>
|
||||
テクノロジー
|
||||
</div>
|
||||
<h1 class="text-3xl md:text-5xl font-black text-slate-900 tracking-tight mb-6">
|
||||
<span class="bg-gradient-to-r from-blue-600 to-cyan-600 bg-clip-text text-transparent">API</span>の仕組み
|
||||
</h1>
|
||||
<p class="text-lg text-ads-muted max-w-xl mx-auto leading-relaxed">
|
||||
「APIって何？」と聞かれて、うまく答えられない。<br>
|
||||
ひとことで言うと ──
|
||||
</p>
|
||||
</div>
|
||||
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- ONE-PAGE SUMMARY -->
|
||||
<!-- ============================================================ -->
|
||||
<div class="bg-ads-surface border border-ads-border rounded-2xl p-6 md:p-10 mb-6">
|
||||
<div class="text-center mb-8 md:mb-10">
|
||||
<p class="text-xl md:text-2xl font-black text-slate-900 mb-2">
|
||||
API = ソフトウェアの<span class="text-ads-accent-light">「注文窓口」</span>
|
||||
</p>
|
||||
<p class="text-sm text-ads-muted">
|
||||
中身を知らなくても、決まった形で頼めば結果が届く
|
||||
</p>
|
||||
</div>
|
||||
|
||||
<!-- Core flow: App → API → Server -->
|
||||
<div class="flex flex-col md:flex-row items-center justify-center gap-2 md:gap-0 mb-8">
|
||||
<!-- App -->
|
||||
<div class="flex flex-col items-center w-36 p-3">
|
||||
<div class="w-14 h-14 rounded-xl bg-blue-500/10 border border-blue-500/20 flex items-center justify-center mb-2.5">
|
||||
<i data-lucide="smartphone" class="w-7 h-7 text-blue-600"></i>
|
||||
</div>
|
||||
<div class="font-bold text-slate-900 text-sm">あなたのアプリ</div>
|
||||
<div class="text-[11px] text-blue-600/70 mt-0.5">「天気を教えて」</div>
|
||||
</div>
|
||||
|
||||
<!-- Arrow 1: Request -->
|
||||
<div class="flex items-center justify-center md:w-16 py-1 md:py-0">
|
||||
<div class="flex flex-col items-center gap-0.5">
|
||||
<span class="text-[9px] font-medium text-ads-accent tracking-wider">リクエスト</span>
|
||||
<i data-lucide="arrow-right" class="w-5 h-5 text-ads-accent hidden md:block"></i>
|
||||
<i data-lucide="arrow-down" class="w-5 h-5 text-ads-accent md:hidden"></i>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- API (centerpiece — visually prominent) -->
|
||||
<div class="flex flex-col items-center w-40 p-4 bg-ads-accent/5 border-2 border-ads-accent/20 rounded-2xl">
|
||||
<div class="w-16 h-16 rounded-2xl bg-ads-accent/15 border-2 border-ads-accent/30 flex items-center justify-center mb-2.5">
|
||||
<i data-lucide="arrow-left-right" class="w-8 h-8 text-ads-accent-light"></i>
|
||||
</div>
|
||||
<div class="font-bold text-ads-accent-light text-base">API</div>
|
||||
<div class="text-[11px] text-ads-muted mt-0.5 mb-2">注文を届け、結果を返す</div>
|
||||
<div class="text-[10px] text-ads-muted bg-white rounded-lg px-2.5 py-1 border border-ads-border/50">レストランのウェイター役</div>
|
||||
</div>
|
||||
|
||||
<!-- Arrow 2: Forward to server -->
|
||||
<div class="flex items-center justify-center md:w-16 py-1 md:py-0">
|
||||
<div class="flex flex-col items-center gap-0.5">
|
||||
<span class="text-[9px] font-medium text-ads-accent tracking-wider">依頼</span>
|
||||
<i data-lucide="arrow-right" class="w-5 h-5 text-ads-accent hidden md:block"></i>
|
||||
<i data-lucide="arrow-down" class="w-5 h-5 text-ads-accent md:hidden"></i>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Server -->
|
||||
<div class="flex flex-col items-center w-36 p-3">
|
||||
<div class="w-14 h-14 rounded-xl bg-emerald-500/10 border border-emerald-500/20 flex items-center justify-center mb-2.5">
|
||||
<i data-lucide="server" class="w-7 h-7 text-emerald-600"></i>
|
||||
</div>
|
||||
<div class="font-bold text-slate-900 text-sm">サービス</div>
|
||||
<div class="text-[11px] text-emerald-600/70 mt-0.5">処理して結果を返す</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Return flow -->
|
||||
<div class="flex justify-center mb-8">
|
||||
<div class="flex items-center gap-2 text-xs text-emerald-600 bg-emerald-500/5 border border-emerald-500/15 rounded-full px-4 py-1.5">
|
||||
<i data-lucide="corner-down-left" class="w-3.5 h-3.5"></i>
|
||||
結果（レスポンス）があなたのアプリに届く
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Divider with label -->
|
||||
<div class="flex items-center gap-4 mb-6">
|
||||
<div class="flex-1 border-t border-ads-border/50"></div>
|
||||
<div class="text-[11px] text-ads-dim font-medium">あなたも毎日使っている</div>
|
||||
<div class="flex-1 border-t border-ads-border/50"></div>
|
||||
</div>
|
||||
|
||||
<!-- Everyday examples as pills -->
|
||||
<div class="flex flex-wrap justify-center gap-2 mb-8">
|
||||
<div class="flex items-center gap-1.5 bg-white border border-ads-border rounded-full px-3.5 py-1.5 text-xs text-slate-700">
|
||||
<i data-lucide="cloud" class="w-3.5 h-3.5 text-cyan-500"></i>
|
||||
天気予報
|
||||
</div>
|
||||
<div class="flex items-center gap-1.5 bg-white border border-ads-border rounded-full px-3.5 py-1.5 text-xs text-slate-700">
|
||||
<i data-lucide="log-in" class="w-3.5 h-3.5 text-blue-500"></i>
|
||||
Googleログイン
|
||||
</div>
|
||||
<div class="flex items-center gap-1.5 bg-white border border-ads-border rounded-full px-3.5 py-1.5 text-xs text-slate-700">
|
||||
<i data-lucide="credit-card" class="w-3.5 h-3.5 text-emerald-500"></i>
|
||||
オンライン決済
|
||||
</div>
|
||||
<div class="flex items-center gap-1.5 bg-white border border-ads-border rounded-full px-3.5 py-1.5 text-xs text-slate-700">
|
||||
<i data-lucide="map-pin" class="w-3.5 h-3.5 text-red-500"></i>
|
||||
地図・ナビ
|
||||
</div>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
<p class="text-center text-ads-muted mb-16 md:mb-20">
|
||||
ここから先で、この仕組みをひとつずつ丁寧に解説していきます。
|
||||
</p>
|
||||
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- SECTION 1: そもそもAPIって何？ -->
|
||||
<!-- ============================================================ -->
|
||||
<section class="mb-16 md:mb-20">
|
||||
<div class="flex items-center gap-3 mb-8">
|
||||
<div class="flex items-center justify-center w-10 h-10 rounded-lg bg-blue-500/10 flex-shrink-0">
|
||||
<i data-lucide="help-circle" class="w-5 h-5 text-blue-600"></i>
|
||||
</div>
|
||||
<h2 class="text-xl md:text-2xl font-bold text-slate-900">そもそもAPIって何？</h2>
|
||||
</div>
|
||||
|
||||
<p class="mb-6 leading-relaxed">
|
||||
API（エーピーアイ）は <strong class="text-slate-900">Application Programming Interface</strong>（アプリケーション・プログラミング・インターフェース）の略称です。正式名称を聞いても「何のこと？」と思いますよね。
|
||||
</p>
|
||||
|
||||
<p class="mb-6 leading-relaxed">
|
||||
まずは日常のたとえで考えてみましょう。レストランに行った場面を想像してください。
|
||||
</p>
|
||||
|
||||
<p class="mb-8 leading-relaxed">
|
||||
あなた（お客さん）は、厨房に直接入って料理を作ることはできません。厨房のルールも、調理器具の使い方も知りません。でも、<strong class="text-slate-900">ウェイターに「パスタをください」と注文すれば、厨房で作られた料理があなたのテーブルに届きます。</strong>厨房の中で何が起きているかを知る必要はありません。
|
||||
</p>
|
||||
|
||||
<!-- レストラン比喩フロー図 -->
|
||||
<div class="bg-ads-surface border border-ads-border rounded-xl p-6 md:p-8 mb-8">
|
||||
<h3 class="text-lg font-bold text-slate-900 text-center mb-8">レストランで考えるAPIの役割</h3>
|
||||
|
||||
<div class="flex flex-col md:flex-row items-center justify-center gap-4 md:gap-0">
|
||||
<!-- あなた（お客さん） -->
|
||||
<div class="w-44 bg-blue-500/10 border border-blue-500/20 rounded-xl p-5 text-center">
|
||||
<div class="w-12 h-12 rounded-full bg-blue-500/20 flex items-center justify-center mx-auto mb-3">
|
||||
<i data-lucide="user" class="w-6 h-6 text-blue-600"></i>
|
||||
</div>
|
||||
<div class="font-bold text-blue-700 mb-1">あなた</div>
|
||||
<div class="text-xs text-blue-600/70">お客さん</div>
|
||||
<div class="text-xs text-ads-muted mt-3 bg-slate-100/80 rounded-lg px-3 py-1.5">「パスタください」</div>
|
||||
</div>
|
||||
|
||||
<!-- 矢印 1 -->
|
||||
<div class="flex items-center justify-center md:w-16 py-2 md:py-0">
|
||||
<div class="flex flex-col items-center gap-1">
|
||||
<span class="text-[10px] text-ads-muted">注文</span>
|
||||
<i data-lucide="arrow-right" class="w-5 h-5 text-ads-accent hidden md:block"></i>
|
||||
<i data-lucide="arrow-down" class="w-5 h-5 text-ads-accent md:hidden"></i>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- API（ウェイター） -->
|
||||
<div class="w-44 bg-ads-accent/10 border-2 border-ads-accent/30 rounded-xl p-5 text-center">
|
||||
<div class="w-12 h-12 rounded-full bg-ads-accent/20 flex items-center justify-center mx-auto mb-3">
|
||||
<i data-lucide="message-square" class="w-6 h-6 text-ads-accent-light"></i>
|
||||
</div>
|
||||
<div class="font-bold text-ads-accent-light mb-1">API</div>
|
||||
<div class="text-xs text-ads-accent/70">ウェイター</div>
|
||||
<div class="text-xs text-ads-muted mt-3 bg-slate-100/80 rounded-lg px-3 py-1.5">注文を伝え、料理を届ける</div>
|
||||
</div>
|
||||
|
||||
<!-- 矢印 2 -->
|
||||
<div class="flex items-center justify-center md:w-16 py-2 md:py-0">
|
||||
<div class="flex flex-col items-center gap-1">
|
||||
<span class="text-[10px] text-ads-muted">依頼</span>
|
||||
<i data-lucide="arrow-right" class="w-5 h-5 text-ads-accent hidden md:block"></i>
|
||||
<i data-lucide="arrow-down" class="w-5 h-5 text-ads-accent md:hidden"></i>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- サーバー（厨房） -->
|
||||
<div class="w-44 bg-emerald-500/10 border border-emerald-500/20 rounded-xl p-5 text-center">
|
||||
<div class="w-12 h-12 rounded-full bg-emerald-500/20 flex items-center justify-center mx-auto mb-3">
|
||||
<i data-lucide="server" class="w-6 h-6 text-emerald-600"></i>
|
||||
</div>
|
||||
<div class="font-bold text-emerald-700 mb-1">サーバー</div>
|
||||
<div class="text-xs text-emerald-600/70">厨房</div>
|
||||
<div class="text-xs text-ads-muted mt-3 bg-slate-100/80 rounded-lg px-3 py-1.5">パスタを作って渡す</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="flex justify-center mt-6">
|
||||
<div class="flex items-center gap-2 text-ads-muted text-sm">
|
||||
<i data-lucide="corner-down-left" class="w-4 h-4"></i>
|
||||
料理（レスポンス）があなたのテーブルに届く
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<p class="mb-6 leading-relaxed">
|
||||
この比喩がAPIの本質をほぼ言い当てています。あなた（アプリ）は、厨房（サーバー）の中で何が起きているかを知る必要がありません。ウェイター（API）に決まった形式で注文を伝えれば、結果が返ってくる。これがAPIです。
|
||||
</p>
|
||||
|
||||
<!-- ポイントボックス -->
|
||||
<div class="bg-ads-accent/5 border border-ads-accent/20 rounded-xl p-5">
|
||||
<div class="flex items-start gap-3">
|
||||
<div class="flex items-center justify-center w-8 h-8 rounded-lg bg-ads-accent/10 flex-shrink-0 mt-0.5">
|
||||
<i data-lucide="lightbulb" class="w-4 h-4 text-ads-accent-light"></i>
|
||||
</div>
|
||||
<div>
|
||||
<p class="font-bold text-ads-accent-light mb-1">ここがポイント</p>
|
||||
<p class="text-ads-muted leading-relaxed">
|
||||
APIは<strong class="text-slate-800">「仲介役」</strong>です。相手の内部構造を知らなくても、<strong class="text-slate-800">決まったルールで話しかければ結果が返ってくる</strong>。これがAPIの本質です。この「決まったルール」のことを、エンジニアは「インターフェース（Interface）」と呼びます。
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- SECTION 2: もう少し正確に言うと -->
|
||||
<!-- ============================================================ -->
|
||||
<section class="mb-16 md:mb-20">
|
||||
<div class="flex items-center gap-3 mb-8">
|
||||
<div class="flex items-center justify-center w-10 h-10 rounded-lg bg-purple-500/10 flex-shrink-0">
|
||||
<i data-lucide="search" class="w-5 h-5 text-purple-600"></i>
|
||||
</div>
|
||||
<h2 class="text-xl md:text-2xl font-bold text-slate-900">もう少し正確に言うと</h2>
|
||||
</div>
|
||||
|
||||
<p class="mb-6 leading-relaxed">
|
||||
レストランのたとえで、ざっくりとしたイメージはつかめましたか？ ここからもう少しだけ正確に説明します。
|
||||
</p>
|
||||
|
||||
<p class="mb-8 leading-relaxed">
|
||||
APIとは、ひとことで言えば<strong class="text-slate-900">「ソフトウェア同士が会話するための窓口」</strong>です。あなたが使っているアプリの裏側で、別のサービスのデータや機能を借りてくるための「取り決め」と考えてください。
|
||||
</p>
|
||||
|
||||
<div class="bg-ads-surface border border-ads-border rounded-xl p-6 mb-8 text-center">
|
||||
<div class="text-xs text-ads-dim font-medium tracking-widest uppercase mb-3">技術的な定義</div>
|
||||
<p class="text-lg md:text-xl font-bold text-slate-900 leading-relaxed">
|
||||
API = あるソフトウェアの機能を、<br class="hidden md:block">
|
||||
別のソフトウェアから使えるようにする仕組み
|
||||
</p>
|
||||
<p class="text-xs text-ads-dim mt-3">出典: <a href="https://developer.mozilla.org/ja/docs/Learn/JavaScript/Client-side_web_APIs/Introduction" class="underline decoration-ads-dim/30 hover:text-ads-accent transition-colors">MDN Web Docs — Web API の紹介</a></p>
|
||||
</div>
|
||||
|
||||
<p class="mb-8 leading-relaxed">
|
||||
これだけだとまだ抽象的に感じるかもしれません。では、<strong class="text-slate-900">APIがある世界とない世界</strong>を比べてみましょう。
|
||||
</p>
|
||||
|
||||
<!-- Before / After 比較 -->
|
||||
<div class="grid grid-cols-1 md:grid-cols-2 gap-4">
|
||||
<!-- Before -->
|
||||
<div class="bg-red-500/5 border border-red-500/20 rounded-xl p-6">
|
||||
<div class="inline-flex items-center gap-1.5 bg-red-500/10 text-red-600 px-3 py-1 rounded-full text-xs font-bold tracking-wide mb-5">
|
||||
<i data-lucide="x-circle" class="w-3.5 h-3.5"></i>
|
||||
BEFORE — APIがない世界
|
||||
</div>
|
||||
<ul class="space-y-3">
|
||||
<li class="flex items-start gap-2.5">
|
||||
<i data-lucide="x" class="w-4 h-4 text-red-600 mt-1 flex-shrink-0"></i>
|
||||
<span>天気情報が欲しければ、<strong class="text-red-700">自分で気象観測の仕組み</strong>を構築する</span>
|
||||
</li>
|
||||
<li class="flex items-start gap-2.5">
|
||||
<i data-lucide="x" class="w-4 h-4 text-red-600 mt-1 flex-shrink-0"></i>
|
||||
<span>決済機能が欲しければ、<strong class="text-red-700">クレジットカード処理を自前で開発</strong>する</span>
|
||||
</li>
|
||||
<li class="flex items-start gap-2.5">
|
||||
<i data-lucide="x" class="w-4 h-4 text-red-600 mt-1 flex-shrink-0"></i>
|
||||
<span>地図を表示したければ、<strong class="text-red-700">地図データを自分で作成・更新</strong>する</span>
|
||||
</li>
|
||||
<li class="flex items-start gap-2.5">
|
||||
<i data-lucide="x" class="w-4 h-4 text-red-600 mt-1 flex-shrink-0"></i>
|
||||
<span>ユーザー認証は<strong class="text-red-700">パスワード管理からセキュリティ対策まで全部自前</strong></span>
|
||||
</li>
|
||||
</ul>
|
||||
<div class="mt-5 pt-4 border-t border-red-500/10 text-sm text-red-700/70 flex items-center gap-2">
|
||||
<i data-lucide="alert-circle" class="w-4 h-4"></i>
|
||||
膨大な開発コストと時間。バグのリスクも高い。
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- After -->
|
||||
<div class="bg-emerald-500/5 border border-emerald-500/20 rounded-xl p-6">
|
||||
<div class="inline-flex items-center gap-1.5 bg-emerald-500/10 text-emerald-600 px-3 py-1 rounded-full text-xs font-bold tracking-wide mb-5">
|
||||
<i data-lucide="check-circle" class="w-3.5 h-3.5"></i>
|
||||
AFTER — APIがある世界
|
||||
</div>
|
||||
<ul class="space-y-3">
|
||||
<li class="flex items-start gap-2.5">
|
||||
<i data-lucide="check" class="w-4 h-4 text-emerald-600 mt-1 flex-shrink-0"></i>
|
||||
<span>天気情報は<strong class="text-emerald-700">天気予報APIに問い合わせるだけ</strong>で取得できる</span>
|
||||
</li>
|
||||
<li class="flex items-start gap-2.5">
|
||||
<i data-lucide="check" class="w-4 h-4 text-emerald-600 mt-1 flex-shrink-0"></i>
|
||||
<span>決済は<strong class="text-emerald-700">Stripe APIに任せれば数行のコード</strong>で完成</span>
|
||||
</li>
|
||||
<li class="flex items-start gap-2.5">
|
||||
<i data-lucide="check" class="w-4 h-4 text-emerald-600 mt-1 flex-shrink-0"></i>
|
||||
<span>地図は<strong class="text-emerald-700">Google Maps APIで高品質な地図を即表示</strong>できる</span>
|
||||
</li>
|
||||
<li class="flex items-start gap-2.5">
|
||||
<i data-lucide="check" class="w-4 h-4 text-emerald-600 mt-1 flex-shrink-0"></i>
|
||||
<span>ログインは<strong class="text-emerald-700">GoogleやAppleのAPIで安全に認証</strong>できる</span>
|
||||
</li>
|
||||
</ul>
|
||||
<div class="mt-5 pt-4 border-t border-emerald-500/10 text-sm text-emerald-700/70 flex items-center gap-2">
|
||||
<i data-lucide="zap" class="w-4 h-4"></i>
|
||||
「自分が本当に作るべきもの」に集中できる。
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- SECTION 3: APIの仕組み -->
|
||||
<!-- ============================================================ -->
|
||||
<section class="mb-16 md:mb-20">
|
||||
<div class="flex items-center gap-3 mb-8">
|
||||
<div class="flex items-center justify-center w-10 h-10 rounded-lg bg-cyan-500/10 flex-shrink-0">
|
||||
<i data-lucide="settings" class="w-5 h-5 text-cyan-600"></i>
|
||||
</div>
|
||||
<h2 class="text-xl md:text-2xl font-bold text-slate-900">APIの仕組み — リクエストとレスポンス</h2>
|
||||
</div>
|
||||
|
||||
<p class="mb-6 leading-relaxed">
|
||||
APIでのやり取りは、実はとてもシンプルです。基本は<strong class="text-slate-900">「聞く（リクエスト）」</strong>と<strong class="text-slate-900">「答える（レスポンス）」</strong>の2つだけ。
|
||||
</p>
|
||||
|
||||
<p class="mb-8 leading-relaxed">
|
||||
リクエスト（Request）とは、「こういう情報をください」「この処理をしてください」とAPIに送るメッセージのことです。レスポンス（Response）は、APIがその要求に対して返す結果です。この2つのやり取りを分解すると、4つのステップになります。
|
||||
</p>
|
||||
|
||||
<!-- 4ステップフロー図 -->
|
||||
<div class="bg-ads-surface border border-ads-border rounded-xl p-6 md:p-8 mb-8">
|
||||
<h3 class="text-lg font-bold text-slate-900 text-center mb-8">APIリクエスト〜レスポンスの流れ</h3>
|
||||
|
||||
<div class="flex flex-col md:flex-row items-stretch justify-center gap-3 md:gap-0">
|
||||
<div class="flex-1 bg-blue-500/10 border border-blue-500/20 rounded-xl p-4 text-center">
|
||||
<div class="w-8 h-8 rounded-full bg-blue-500 text-white text-sm font-bold flex items-center justify-center mx-auto mb-3">1</div>
|
||||
<i data-lucide="send" class="w-6 h-6 text-blue-600 mx-auto mb-2"></i>
|
||||
<div class="font-bold text-blue-700 text-sm mb-1">リクエスト送信</div>
|
||||
<div class="text-xs text-ads-muted leading-relaxed">あなたのアプリが<br>「こういう情報ください」<br>とAPIに送る</div>
|
||||
</div>
|
||||
|
||||
<div class="flex items-center justify-center md:w-10 py-1 md:py-0">
|
||||
<i data-lucide="chevron-right" class="w-5 h-5 text-ads-dim hidden md:block"></i>
|
||||
<i data-lucide="chevron-down" class="w-5 h-5 text-ads-dim md:hidden"></i>
|
||||
</div>
|
||||
|
||||
<div class="flex-1 bg-purple-500/10 border border-purple-500/20 rounded-xl p-4 text-center">
|
||||
<div class="w-8 h-8 rounded-full bg-purple-500 text-white text-sm font-bold flex items-center justify-center mx-auto mb-3">2</div>
|
||||
<i data-lucide="shield" class="w-6 h-6 text-purple-600 mx-auto mb-2"></i>
|
||||
<div class="font-bold text-purple-700 text-sm mb-1">APIが受け取る</div>
|
||||
<div class="text-xs text-ads-muted leading-relaxed">リクエストの内容を<br>チェック・認証する<br>（門番の役割）</div>
|
||||
</div>
|
||||
|
||||
<div class="flex items-center justify-center md:w-10 py-1 md:py-0">
|
||||
<i data-lucide="chevron-right" class="w-5 h-5 text-ads-dim hidden md:block"></i>
|
||||
<i data-lucide="chevron-down" class="w-5 h-5 text-ads-dim md:hidden"></i>
|
||||
</div>
|
||||
|
||||
<div class="flex-1 bg-emerald-500/10 border border-emerald-500/20 rounded-xl p-4 text-center">
|
||||
<div class="w-8 h-8 rounded-full bg-emerald-500 text-white text-sm font-bold flex items-center justify-center mx-auto mb-3">3</div>
|
||||
<i data-lucide="database" class="w-6 h-6 text-emerald-600 mx-auto mb-2"></i>
|
||||
<div class="font-bold text-emerald-700 text-sm mb-1">サーバーが処理</div>
|
||||
<div class="text-xs text-ads-muted leading-relaxed">データベース検索や<br>計算など、実際の<br>処理を実行する</div>
|
||||
</div>
|
||||
|
||||
<div class="flex items-center justify-center md:w-10 py-1 md:py-0">
|
||||
<i data-lucide="chevron-right" class="w-5 h-5 text-ads-dim hidden md:block"></i>
|
||||
<i data-lucide="chevron-down" class="w-5 h-5 text-ads-dim md:hidden"></i>
|
||||
</div>
|
||||
|
||||
<div class="flex-1 bg-amber-500/10 border border-amber-500/20 rounded-xl p-4 text-center">
|
||||
<div class="w-8 h-8 rounded-full bg-amber-500 text-white text-sm font-bold flex items-center justify-center mx-auto mb-3">4</div>
|
||||
<i data-lucide="reply" class="w-6 h-6 text-amber-600 mx-auto mb-2"></i>
|
||||
<div class="font-bold text-amber-700 text-sm mb-1">レスポンス返却</div>
|
||||
<div class="text-xs text-ads-muted leading-relaxed">処理結果をあなたの<br>アプリに返す<br>（料理が届く瞬間）</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<p class="mb-6 leading-relaxed">
|
||||
言葉だけだとまだピンとこないかもしれません。では、実際のコードで見てみましょう。たとえば、天気予報APIから東京の天気を取得するコードは、たったこれだけです。
|
||||
</p>
|
||||
|
||||
<!-- コード例: JavaScript -->
|
||||
<div class="mb-6">
|
||||
<div class="flex items-center gap-2 bg-slate-800 border border-slate-700/50 rounded-t-xl px-4 py-2.5 text-xs text-ads-muted">
|
||||
<i data-lucide="code" class="w-3.5 h-3.5"></i>
|
||||
JavaScript — 天気予報APIの呼び出し例
|
||||
</div>
|
||||
<pre class="bg-slate-950 border border-slate-700/50 border-t-0 rounded-b-xl p-5 overflow-x-auto text-sm leading-loose"><code><span class="text-slate-500">// 1. APIにリクエストを送る（「東京の天気を教えて」と聞く）</span>
|
||||
<span class="text-purple-400">const</span> response <span class="text-slate-400">=</span> <span class="text-purple-400">await</span> <span class="text-blue-400">fetch</span>(<span class="text-emerald-400">"https://api.weather.example.com/current?city=tokyo"</span>);
|
||||
|
||||
<span class="text-slate-500">// 2. レスポンスをJSON形式（データの構造）に変換する</span>
|
||||
<span class="text-purple-400">const</span> data <span class="text-slate-400">=</span> <span class="text-purple-400">await</span> response.<span class="text-blue-400">json</span>();
|
||||
|
||||
<span class="text-slate-500">// 3. 必要なデータを取り出して使う</span>
|
||||
console.<span class="text-blue-400">log</span>(data.temperature); <span class="text-slate-500">// → "22°C"</span>
|
||||
console.<span class="text-blue-400">log</span>(data.condition); <span class="text-slate-500">// → "晴れ"</span>
|
||||
console.<span class="text-blue-400">log</span>(data.humidity); <span class="text-slate-500">// → "65%"</span></code></pre>
|
||||
</div>
|
||||
|
||||
<!-- コード解説 -->
|
||||
<div class="bg-ads-surface border border-ads-border rounded-xl p-5 mb-8">
|
||||
<h4 class="text-sm font-bold text-slate-900 mb-4 flex items-center gap-2">
|
||||
<i data-lucide="file-text" class="w-4 h-4 text-ads-accent"></i>
|
||||
コードの解説（1行ずつ読み解く）
|
||||
</h4>
|
||||
<div class="space-y-4 text-sm">
|
||||
<div class="flex items-start gap-3">
|
||||
<span class="text-xs font-mono bg-blue-500/10 text-blue-600 px-2 py-0.5 rounded flex-shrink-0 mt-0.5">1</span>
|
||||
<span class="leading-relaxed"><code class="text-emerald-700 text-xs bg-slate-100 px-1.5 py-0.5 rounded">fetch()</code> は「指定したURLに問い合わせる」命令。URLの末尾にある <code class="text-emerald-700 text-xs bg-slate-100 px-1.5 py-0.5 rounded">?city=tokyo</code> が「東京の情報が欲しい」というリクエストの中身です。レストランのたとえで言えば「パスタください」にあたる部分。</span>
|
||||
</div>
|
||||
<div class="flex items-start gap-3">
|
||||
<span class="text-xs font-mono bg-purple-500/10 text-purple-600 px-2 py-0.5 rounded flex-shrink-0 mt-0.5">2</span>
|
||||
<span class="leading-relaxed">返ってきたデータは機械向けの生データなので、<code class="text-emerald-700 text-xs bg-slate-100 px-1.5 py-0.5 rounded">.json()</code> で人間が読みやすい形（JSON = JavaScript Object Notation）に変換します。JSONは「名前: 値」の組み合わせでデータを表現する書式で、Web業界で最も広く使われています。</span>
|
||||
</div>
|
||||
<div class="flex items-start gap-3">
|
||||
<span class="text-xs font-mono bg-emerald-500/10 text-emerald-600 px-2 py-0.5 rounded flex-shrink-0 mt-0.5">3</span>
|
||||
<span class="leading-relaxed">変換したデータから <code class="text-emerald-700 text-xs bg-slate-100 px-1.5 py-0.5 rounded">data.temperature</code> のように、ドット（.）で区切って欲しい情報を名前で取り出します。辞書で単語を引くのに似ています。</span>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<p class="mb-4 leading-relaxed">
|
||||
ターミナル（コマンドを入力する黒い画面）からもAPIを試せます。<code class="text-emerald-700 text-xs bg-slate-100 px-1.5 py-0.5 rounded">curl</code>（カール）というコマンドを使うと、たった1行でAPIにリクエストを送れます。
|
||||
</p>
|
||||
|
||||
<!-- ターミナルUIモックアップ: curl -->
|
||||
<div class="mb-8 rounded-xl overflow-hidden border border-slate-700/50">
|
||||
<div class="flex items-center gap-3 bg-slate-800 px-4 py-2.5">
|
||||
<div class="flex gap-1.5">
|
||||
<div class="w-3 h-3 rounded-full bg-red-500/80"></div>
|
||||
<div class="w-3 h-3 rounded-full bg-yellow-500/80"></div>
|
||||
<div class="w-3 h-3 rounded-full bg-green-500/80"></div>
|
||||
</div>
|
||||
<div class="flex items-center gap-1.5 text-xs text-slate-400">
|
||||
<i data-lucide="terminal" class="w-3.5 h-3.5"></i>
|
||||
ターミナル — curlコマンドでAPIを叩く
|
||||
</div>
|
||||
</div>
|
||||
<pre class="bg-slate-950 p-5 overflow-x-auto text-sm leading-loose"><code><span class="text-emerald-400">$</span> curl https://api.weather.example.com/current?city=tokyo
|
||||
|
||||
<span class="text-slate-500"># 返ってくるレスポンス（JSON形式）</span>
|
||||
{
|
||||
<span class="text-blue-400">"city"</span>: <span class="text-emerald-400">"東京"</span>,
|
||||
<span class="text-blue-400">"temperature"</span>: <span class="text-amber-400">"22°C"</span>,
|
||||
<span class="text-blue-400">"condition"</span>: <span class="text-emerald-400">"晴れ"</span>,
|
||||
<span class="text-blue-400">"humidity"</span>: <span class="text-amber-400">"65%"</span>
|
||||
}</code></pre>
|
||||
</div>
|
||||
|
||||
<div class="bg-amber-500/5 border border-amber-500/20 rounded-xl p-5">
|
||||
<div class="flex items-start gap-3">
|
||||
<div class="flex items-center justify-center w-8 h-8 rounded-lg bg-amber-500/10 flex-shrink-0 mt-0.5">
|
||||
<i data-lucide="info" class="w-4 h-4 text-amber-600"></i>
|
||||
</div>
|
||||
<div>
|
||||
<p class="font-bold text-amber-700 mb-1">ちょっと補足: URLの構造</p>
|
||||
<p class="text-ads-muted leading-relaxed text-sm">
|
||||
<code class="text-emerald-700 text-xs bg-slate-100 px-1.5 py-0.5 rounded">https://api.weather.example.com/current?city=tokyo</code> のURLは、大きく3つの部分に分かれます。<strong class="text-slate-800">api.weather.example.com</strong> がAPIの住所（ベースURL）、<strong class="text-slate-800">/current</strong> が「何を」（現在の天気）、<strong class="text-slate-800">?city=tokyo</strong> が「どこの」（東京）というパラメータです。レストランで例えると「〇〇レストランの（住所）、メインメニューから（何を）、パスタを（詳細）」に対応します。
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<p class="mt-8 mb-6 leading-relaxed">
|
||||
では、このAPIのレスポンスが実際のアプリではどう表示されるのでしょうか？ あなたが見ている天気アプリの画面を覗いてみましょう。
|
||||
</p>
|
||||
|
||||
<!-- ブラウザUIモックアップ -->
|
||||
<div class="rounded-xl overflow-hidden border border-slate-700/50 mb-8">
|
||||
<div class="flex items-center gap-3 bg-slate-800 px-4 py-2.5">
|
||||
<div class="flex gap-1.5">
|
||||
<div class="w-3 h-3 rounded-full bg-red-500/80"></div>
|
||||
<div class="w-3 h-3 rounded-full bg-yellow-500/80"></div>
|
||||
<div class="w-3 h-3 rounded-full bg-green-500/80"></div>
|
||||
</div>
|
||||
<div class="flex-1 bg-slate-700/50 rounded-lg px-3 py-1 text-xs text-slate-400 flex items-center gap-1.5">
|
||||
<i data-lucide="lock" class="w-3 h-3 text-emerald-400"></i>
|
||||
weather-app.example.com
|
||||
</div>
|
||||
</div>
|
||||
<div class="bg-gradient-to-b from-sky-100 to-sky-50 p-6 md:p-8">
|
||||
<div class="text-center">
|
||||
<div class="text-xs text-sky-600/70 font-medium mb-1">現在地: 東京</div>
|
||||
<div class="flex items-center justify-center gap-2 mb-2">
|
||||
<i data-lucide="sun" class="w-10 h-10 text-amber-500"></i>
|
||||
<span class="text-4xl font-black text-sky-900">22°C</span>
|
||||
</div>
|
||||
<div class="text-sm text-sky-700 font-medium mb-4">晴れ</div>
|
||||
<div class="flex justify-center gap-6 text-xs text-sky-600/80">
|
||||
<div class="flex items-center gap-1"><i data-lucide="droplets" class="w-3.5 h-3.5"></i> 65%</div>
|
||||
<div class="flex items-center gap-1"><i data-lucide="wind" class="w-3.5 h-3.5"></i> 3m/s</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="bg-ads-accent/5 border border-ads-accent/20 rounded-xl p-5">
|
||||
<div class="flex items-start gap-3">
|
||||
<div class="flex items-center justify-center w-8 h-8 rounded-lg bg-ads-accent/10 flex-shrink-0 mt-0.5">
|
||||
<i data-lucide="lightbulb" class="w-4 h-4 text-ads-accent-light"></i>
|
||||
</div>
|
||||
<div>
|
||||
<p class="font-bold text-ads-accent-light mb-1">APIの結果 → アプリの画面</p>
|
||||
<p class="text-ads-muted leading-relaxed">
|
||||
上の天気アプリは、裏側で <code class="text-emerald-700 text-xs bg-slate-100 px-1.5 py-0.5 rounded">temperature: "22°C"</code> や <code class="text-emerald-700 text-xs bg-slate-100 px-1.5 py-0.5 rounded">condition: "晴れ"</code> というAPIレスポンスを受け取り、見やすいデザインに変換して表示しています。<strong class="text-slate-800">あなたが普段見ているきれいな画面の裏側では、こうしたAPIのやり取りが行われている</strong>のです。
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- SECTION 4: 身近なAPIの例 -->
|
||||
<!-- ============================================================ -->
|
||||
<section class="mb-16 md:mb-20">
|
||||
<div class="flex items-center gap-3 mb-8">
|
||||
<div class="flex items-center justify-center w-10 h-10 rounded-lg bg-amber-500/10 flex-shrink-0">
|
||||
<i data-lucide="smartphone" class="w-5 h-5 text-amber-600"></i>
|
||||
</div>
|
||||
<h2 class="text-xl md:text-2xl font-bold text-slate-900">身近なAPIの例 — 実はあなたも毎日使っている</h2>
|
||||
</div>
|
||||
|
||||
<p class="mb-8 leading-relaxed">
|
||||
「API」と聞くとプログラマーの専門用語に聞こえるかもしれません。しかし、あなたがスマホで何気なくやっている日常の操作の裏側では、たくさんのAPIが動いています。<strong class="text-slate-900">「あなたが見ている画面」の裏側で、APIが何をしているのか</strong>を図解します。
|
||||
</p>
|
||||
|
||||
<div class="grid grid-cols-1 md:grid-cols-2 gap-4">
|
||||
<!-- 天気予報アプリ -->
|
||||
<div class="bg-ads-surface border border-ads-border rounded-xl overflow-hidden">
|
||||
<div class="bg-gradient-to-b from-sky-100 to-sky-50 p-5">
|
||||
<div class="text-center">
|
||||
<div class="text-[10px] text-sky-600/60 font-medium mb-0.5">東京</div>
|
||||
<div class="flex items-center justify-center gap-1.5 mb-1">
|
||||
<i data-lucide="sun" class="w-7 h-7 text-amber-500"></i>
|
||||
<span class="text-2xl font-black text-sky-900">22°C</span>
|
||||
</div>
|
||||
<div class="text-xs text-sky-700 font-medium mb-2">晴れ</div>
|
||||
<div class="flex justify-center gap-4 text-[10px] text-sky-600/70">
|
||||
<div class="flex items-center gap-0.5"><i data-lucide="droplets" class="w-3 h-3"></i> 65%</div>
|
||||
<div class="flex items-center gap-0.5"><i data-lucide="wind" class="w-3 h-3"></i> 3m/s</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="p-5 pt-4">
|
||||
<h3 class="font-bold text-slate-900 text-sm mb-2 flex items-center gap-2">
|
||||
<i data-lucide="cloud" class="w-4 h-4 text-cyan-600"></i> 天気予報アプリ
|
||||
</h3>
|
||||
<div class="text-xs text-cyan-600 font-medium mb-1">裏側でAPIがやっていること</div>
|
||||
<p class="text-sm text-ads-muted leading-relaxed">気象庁のサーバーに「東京の最新天気データをください」とリクエストを送り、気温・天候・湿度・風速などのデータをJSON形式で受け取っている</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Googleログイン -->
|
||||
<div class="bg-ads-surface border border-ads-border rounded-xl overflow-hidden">
|
||||
<div class="bg-white p-5 flex flex-col items-center justify-center">
|
||||
<div class="text-xs text-ads-muted mb-3">アカウントにログイン</div>
|
||||
<div class="flex items-center gap-2.5 border border-ads-border rounded-lg px-5 py-2.5 bg-white hover:bg-ads-hover transition-colors">
|
||||
<div class="w-5 h-5 rounded-full bg-gradient-to-br from-blue-500 via-red-500 to-yellow-500 flex items-center justify-center">
|
||||
<span class="text-[8px] font-black text-white">G</span>
|
||||
</div>
|
||||
<span class="text-sm font-medium text-slate-700">Google でログイン</span>
|
||||
</div>
|
||||
<div class="flex items-center gap-3 mt-3">
|
||||
<div class="flex-1 border-t border-ads-border/50"></div>
|
||||
<span class="text-[10px] text-ads-dim">または</span>
|
||||
<div class="flex-1 border-t border-ads-border/50"></div>
|
||||
</div>
|
||||
<div class="w-full mt-2 bg-ads-surface border border-ads-border/50 rounded-lg px-3 py-1.5 text-xs text-ads-dim">メールアドレスで登録</div>
|
||||
</div>
|
||||
<div class="p-5 pt-4">
|
||||
<h3 class="font-bold text-slate-900 text-sm mb-2 flex items-center gap-2">
|
||||
<i data-lucide="log-in" class="w-4 h-4 text-blue-600"></i> 「Googleでログイン」ボタン
|
||||
</h3>
|
||||
<div class="text-xs text-blue-600 font-medium mb-1">裏側でAPIがやっていること</div>
|
||||
<p class="text-sm text-ads-muted leading-relaxed">GoogleのOAuth API（オーオース = 認可の仕組み）に「このユーザーの身元を確認してください」と問い合わせ、認証トークン（本人確認済みの証）を受け取っている</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- オンライン決済 -->
|
||||
<div class="bg-ads-surface border border-ads-border rounded-xl overflow-hidden">
|
||||
<div class="bg-gradient-to-b from-emerald-50 to-white p-5 text-center">
|
||||
<div class="w-10 h-10 rounded-full bg-emerald-500/15 flex items-center justify-center mx-auto mb-2">
|
||||
<i data-lucide="check" class="w-6 h-6 text-emerald-600"></i>
|
||||
</div>
|
||||
<div class="text-sm font-bold text-emerald-700 mb-1">お支払い完了</div>
|
||||
<div class="text-xl font-black text-slate-900 mb-1">¥1,980</div>
|
||||
<div class="text-[10px] text-ads-dim">VISA **** 4242</div>
|
||||
</div>
|
||||
<div class="p-5 pt-4">
|
||||
<h3 class="font-bold text-slate-900 text-sm mb-2 flex items-center gap-2">
|
||||
<i data-lucide="credit-card" class="w-4 h-4 text-emerald-600"></i> オンライン決済
|
||||
</h3>
|
||||
<div class="text-xs text-emerald-600 font-medium mb-1">裏側でAPIがやっていること</div>
|
||||
<p class="text-sm text-ads-muted leading-relaxed">Stripe等の決済APIが、クレジットカード会社のサーバーと暗号化通信を行い、与信確認（この人は支払える？）→ 決済処理 → 結果通知を実行している</p>
|
||||
<p class="text-[10px] text-ads-dim mt-2">出典: <a href="https://docs.stripe.com/api" class="underline decoration-ads-dim/30 hover:text-ads-accent transition-colors">Stripe API 公式ドキュメント</a></p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- 地図・ナビ -->
|
||||
<div class="bg-ads-surface border border-ads-border rounded-xl overflow-hidden">
|
||||
<div class="bg-emerald-50/50 p-5">
|
||||
<div class="relative bg-emerald-100/80 rounded-lg p-4 h-28 flex flex-col justify-between">
|
||||
<div class="flex items-center gap-1.5">
|
||||
<div class="w-4 h-4 rounded-full bg-blue-500 border-2 border-white flex items-center justify-center">
|
||||
<div class="w-1.5 h-1.5 bg-white rounded-full"></div>
|
||||
</div>
|
||||
<span class="text-[10px] text-blue-700 font-medium">現在地</span>
|
||||
</div>
|
||||
<div class="border-l-2 border-dashed border-blue-400/60 ml-2 h-6"></div>
|
||||
<div class="flex items-center justify-between">
|
||||
<div class="flex items-center gap-1.5">
|
||||
<i data-lucide="map-pin" class="w-4 h-4 text-red-500"></i>
|
||||
<span class="text-[10px] text-red-700 font-medium">東京駅</span>
|
||||
</div>
|
||||
<div class="bg-white rounded-full px-2 py-0.5 text-[10px] font-bold text-blue-700 border border-blue-200">12分</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="p-5 pt-4">
|
||||
<h3 class="font-bold text-slate-900 text-sm mb-2 flex items-center gap-2">
|
||||
<i data-lucide="map-pin" class="w-4 h-4 text-red-600"></i> 地図・ナビアプリ
|
||||
</h3>
|
||||
<div class="text-xs text-red-600 font-medium mb-1">裏側でAPIがやっていること</div>
|
||||
<p class="text-sm text-ads-muted leading-relaxed">Google Maps APIが地図画像の取得、現在の交通情報の取得、経路計算をそれぞれ別のAPIに問い合わせ、統合して表示している</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="mt-8 bg-ads-accent/5 border border-ads-accent/20 rounded-xl p-5">
|
||||
<div class="flex items-start gap-3">
|
||||
<div class="flex items-center justify-center w-8 h-8 rounded-lg bg-ads-accent/10 flex-shrink-0 mt-0.5">
|
||||
<i data-lucide="lightbulb" class="w-4 h-4 text-ads-accent-light"></i>
|
||||
</div>
|
||||
<div>
|
||||
<p class="font-bold text-ads-accent-light mb-1">気づきましたか？</p>
|
||||
<p class="text-ads-muted leading-relaxed text-sm">
|
||||
上の4つの例に共通しているのは、<strong class="text-slate-800">あなたがAPIの存在を意識していない</strong>ということです。天気を確認するとき「今からAPIを呼ぶぞ」とは思いませんよね。優れたAPIは、ユーザーにその存在を感じさせません。まるで空気のように、裏側で静かに仕事をしているのです。
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- SECTION 5: APIを使うとどう嬉しいか -->
|
||||
<!-- ============================================================ -->
|
||||
<section class="mb-16 md:mb-20">
|
||||
<div class="flex items-center gap-3 mb-8">
|
||||
<div class="flex items-center justify-center w-10 h-10 rounded-lg bg-emerald-500/10 flex-shrink-0">
|
||||
<i data-lucide="trending-up" class="w-5 h-5 text-emerald-600"></i>
|
||||
</div>
|
||||
<h2 class="text-xl md:text-2xl font-bold text-slate-900">APIを使うとどう嬉しいか</h2>
|
||||
</div>
|
||||
|
||||
<p class="mb-8 leading-relaxed">
|
||||
ここまで読んで「APIは便利そうだ」と感じてもらえたと思います。では、開発者の視点から見たとき、APIを使うことで<strong class="text-slate-900">具体的にどのくらいの効果</strong>があるのか。数字と一緒に見てみましょう。
|
||||
</p>
|
||||
|
||||
<div class="grid grid-cols-1 sm:grid-cols-3 gap-4 mb-10">
|
||||
<div class="bg-ads-surface border border-ads-border rounded-xl p-6 text-center">
|
||||
<div class="text-3xl md:text-4xl font-black text-ads-accent leading-tight mb-2">50回+</div>
|
||||
<div class="text-sm text-ads-muted">あなたが1日に<br>APIを使っている回数</div>
|
||||
</div>
|
||||
<div class="bg-ads-surface border border-ads-border rounded-xl p-6 text-center">
|
||||
<div class="text-3xl md:text-4xl font-black text-emerald-600 leading-tight mb-2">24,000+</div>
|
||||
<div class="text-sm text-ads-muted">世界で公開されている<br>APIの数</div>
|
||||
<p class="text-[10px] text-ads-dim mt-2">出典: <a href="https://www.programmableweb.com/" class="underline decoration-ads-dim/30 hover:text-ads-accent transition-colors">ProgrammableWeb</a></p>
|
||||
</div>
|
||||
<div class="bg-ads-surface border border-ads-border rounded-xl p-6 text-center">
|
||||
<div class="text-3xl md:text-4xl font-black text-amber-600 leading-tight mb-2">0.2秒</div>
|
||||
<div class="text-sm text-ads-muted">多くのAPIの<br>平均応答時間</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="grid grid-cols-1 md:grid-cols-2 gap-4">
|
||||
<div class="flex gap-4 bg-ads-surface border border-ads-border rounded-xl p-5">
|
||||
<div class="w-10 h-10 rounded-lg bg-amber-500/10 flex items-center justify-center flex-shrink-0">
|
||||
<i data-lucide="zap" class="w-5 h-5 text-amber-600"></i>
|
||||
</div>
|
||||
<div>
|
||||
<h3 class="font-bold text-slate-900 mb-2">開発スピードが上がる</h3>
|
||||
<p class="text-sm text-ads-muted leading-relaxed">決済、認証、地図、翻訳...。これらをゼロから作ると何ヶ月もかかりますが、APIを使えば数日〜数時間で実装できます。車を作りたいとき、エンジンから設計する必要はないのです。</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="flex gap-4 bg-ads-surface border border-ads-border rounded-xl p-5">
|
||||
<div class="w-10 h-10 rounded-lg bg-blue-500/10 flex items-center justify-center flex-shrink-0">
|
||||
<i data-lucide="shield" class="w-5 h-5 text-blue-600"></i>
|
||||
</div>
|
||||
<div>
|
||||
<h3 class="font-bold text-slate-900 mb-2">品質が担保される</h3>
|
||||
<p class="text-sm text-ads-muted leading-relaxed">Google Maps、Stripe、AWSなど、各分野の専門企業が何千人体制で開発・運用しているAPIの品質は、個人や小さなチームで再現できるレベルではありません。その品質を「借りる」ことができます。</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="flex gap-4 bg-ads-surface border border-ads-border rounded-xl p-5">
|
||||
<div class="w-10 h-10 rounded-lg bg-purple-500/10 flex items-center justify-center flex-shrink-0">
|
||||
<i data-lucide="refresh-cw" class="w-5 h-5 text-purple-600"></i>
|
||||
</div>
|
||||
<div>
|
||||
<h3 class="font-bold text-slate-900 mb-2">保守の手間が減る</h3>
|
||||
<p class="text-sm text-ads-muted leading-relaxed">API提供元がバグ修正・機能改善・セキュリティ更新を継続的に行ってくれます。あなたはAPIを「使うだけ」。自分でゼロから作った機能は、自分でずっと面倒を見続ける必要があります。</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="flex gap-4 bg-ads-surface border border-ads-border rounded-xl p-5">
|
||||
<div class="w-10 h-10 rounded-lg bg-emerald-500/10 flex items-center justify-center flex-shrink-0">
|
||||
<i data-lucide="layers" class="w-5 h-5 text-emerald-600"></i>
|
||||
</div>
|
||||
<div>
|
||||
<h3 class="font-bold text-slate-900 mb-2">レゴのように拡張できる</h3>
|
||||
<p class="text-sm text-ads-muted leading-relaxed">APIはレゴブロックのように組み合わせられます。たとえば「翻訳API + 音声合成API」を組み合わせれば、多言語音声読み上げ機能が作れます。1つのAPIだけでは実現できない価値が、組み合わせで生まれるのです。</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- SECTION 6: よくある誤解 -->
|
||||
<!-- ============================================================ -->
|
||||
<section class="mb-16 md:mb-20">
|
||||
<div class="flex items-center gap-3 mb-8">
|
||||
<div class="flex items-center justify-center w-10 h-10 rounded-lg bg-red-500/10 flex-shrink-0">
|
||||
<i data-lucide="alert-circle" class="w-5 h-5 text-red-600"></i>
|
||||
</div>
|
||||
<h2 class="text-xl md:text-2xl font-bold text-slate-900">よくある誤解</h2>
|
||||
</div>
|
||||
|
||||
<p class="mb-8 leading-relaxed">
|
||||
APIについて学び始めると、多くの人が同じところでつまずきます。ここでは、初学者が陥りがちな3つの誤解を取り上げて、正しい理解に修正します。
|
||||
</p>
|
||||
|
||||
<div class="space-y-4">
|
||||
<div class="bg-ads-surface border border-ads-border rounded-xl overflow-hidden">
|
||||
<div class="flex items-center gap-3 px-6 py-4 bg-red-500/5 border-b border-ads-border/50">
|
||||
<div class="w-6 h-6 rounded-full bg-red-500/10 flex items-center justify-center flex-shrink-0">
|
||||
<i data-lucide="x" class="w-3.5 h-3.5 text-red-600"></i>
|
||||
</div>
|
||||
<h3 class="font-bold text-red-700 text-sm">誤解: 「APIはプログラマーだけが使うもの」</h3>
|
||||
</div>
|
||||
<div class="px-6 py-5">
|
||||
<div class="flex items-start gap-3">
|
||||
<div class="w-6 h-6 rounded-full bg-emerald-500/10 flex items-center justify-center flex-shrink-0 mt-0.5">
|
||||
<i data-lucide="check" class="w-3.5 h-3.5 text-emerald-600"></i>
|
||||
</div>
|
||||
<div>
|
||||
<p class="text-sm font-bold text-emerald-700 mb-2">実際は:</p>
|
||||
<p class="text-sm text-ads-muted leading-relaxed">
|
||||
あなたも毎日APIを使っています。朝、天気アプリを開く。SNSにログインする。電子マネーで買い物する。これらの操作はすべて、裏側でAPIが動いています。プログラマーが「APIを使う」のは、この仕組みのコードを書いている側にいるだけの話。<strong class="text-slate-800">気づかないうちにAPIの恩恵を毎日受けている</strong>のです。
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="bg-ads-surface border border-ads-border rounded-xl overflow-hidden">
|
||||
<div class="flex items-center gap-3 px-6 py-4 bg-red-500/5 border-b border-ads-border/50">
|
||||
<div class="w-6 h-6 rounded-full bg-red-500/10 flex items-center justify-center flex-shrink-0">
|
||||
<i data-lucide="x" class="w-3.5 h-3.5 text-red-600"></i>
|
||||
</div>
|
||||
<h3 class="font-bold text-red-700 text-sm">誤解: 「APIって難しい技術でしょ？」</h3>
|
||||
</div>
|
||||
<div class="px-6 py-5">
|
||||
<div class="flex items-start gap-3">
|
||||
<div class="w-6 h-6 rounded-full bg-emerald-500/10 flex items-center justify-center flex-shrink-0 mt-0.5">
|
||||
<i data-lucide="check" class="w-3.5 h-3.5 text-emerald-600"></i>
|
||||
</div>
|
||||
<div>
|
||||
<p class="text-sm font-bold text-emerald-700 mb-2">実際は:</p>
|
||||
<p class="text-sm text-ads-muted leading-relaxed">
|
||||
APIの概念自体は「注文して結果を受け取る」というシンプルな仕組みです。レストランで注文できるなら、APIの概念は理解できます。先ほどのコード例のように、実際のプログラムも数行で書けることがほとんどです。難しいのはAPIそのものではなく、<strong class="text-slate-800">「APIで何を作るか」を考える部分</strong>。道具はシンプル、使いこなすセンスが問われるということです。
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="bg-ads-surface border border-ads-border rounded-xl overflow-hidden">
|
||||
<div class="flex items-center gap-3 px-6 py-4 bg-red-500/5 border-b border-ads-border/50">
|
||||
<div class="w-6 h-6 rounded-full bg-red-500/10 flex items-center justify-center flex-shrink-0">
|
||||
<i data-lucide="x" class="w-3.5 h-3.5 text-red-600"></i>
|
||||
</div>
|
||||
<h3 class="font-bold text-red-700 text-sm">誤解: 「APIを使うと個人情報が漏れそうで怖い」</h3>
|
||||
</div>
|
||||
<div class="px-6 py-5">
|
||||
<div class="flex items-start gap-3">
|
||||
<div class="w-6 h-6 rounded-full bg-emerald-500/10 flex items-center justify-center flex-shrink-0 mt-0.5">
|
||||
<i data-lucide="check" class="w-3.5 h-3.5 text-emerald-600"></i>
|
||||
</div>
|
||||
<div>
|
||||
<p class="text-sm font-bold text-emerald-700 mb-2">実際は:</p>
|
||||
<p class="text-sm text-ads-muted leading-relaxed">
|
||||
適切に設計されたAPIは、<strong class="text-slate-800">必要最小限の情報だけ</strong>をやり取りします。たとえば銀行のAPIが口座残高を返す際、パスワードや暗証番号は一切含まれません。APIはデータの「窓口」であり、<strong class="text-slate-800">「何の情報を公開し、何を隠すか」を厳密に制御</strong>できます。むしろ、データベースに直接触るよりもAPIを介した方が安全なのです。レストランのたとえで言えば、お客さんが直接厨房に入るより、ウェイターを通した方が厨房の秩序が保たれるのと同じです。
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
|
||||
<!-- ============================================================ -->
|
||||
<!-- SECTION 7: まとめ -->
|
||||
<!-- ============================================================ -->
|
||||
<section>
|
||||
<div class="flex items-center gap-3 mb-8">
|
||||
<div class="flex items-center justify-center w-10 h-10 rounded-lg bg-ads-accent/10 flex-shrink-0">
|
||||
<i data-lucide="check-circle" class="w-5 h-5 text-ads-accent-light"></i>
|
||||
</div>
|
||||
<h2 class="text-xl md:text-2xl font-bold text-slate-900">まとめ — 覚えておきたい3つのこと</h2>
|
||||
</div>
|
||||
|
||||
<p class="mb-8 leading-relaxed">
|
||||
長い図解を読んでいただきありがとうございます。最後に、この記事で伝えたかったことを3つに絞ってまとめます。
|
||||
</p>
|
||||
|
||||
<div class="space-y-4 mb-10">
|
||||
<div class="bg-ads-surface border border-ads-border rounded-xl p-6 border-l-4 border-l-blue-500">
|
||||
<div class="flex items-start gap-4">
|
||||
<div class="text-2xl font-black text-blue-500 leading-none flex-shrink-0 mt-1">01</div>
|
||||
<div>
|
||||
<h3 class="font-bold text-slate-900 mb-2">APIは「ソフトウェアの窓口」</h3>
|
||||
<p class="text-sm text-ads-muted leading-relaxed">
|
||||
レストランのウェイターのように、あなた（アプリ）とサーバーの間を取り持つ仲介役。相手の内部構造を知らなくても、決まったルール（インターフェース）で話しかければ結果が返ってきます。
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="bg-ads-surface border border-ads-border rounded-xl p-6 border-l-4 border-l-emerald-500">
|
||||
<div class="flex items-start gap-4">
|
||||
<div class="text-2xl font-black text-emerald-500 leading-none flex-shrink-0 mt-1">02</div>
|
||||
<div>
|
||||
<h3 class="font-bold text-slate-900 mb-2">あなたはすでにAPIユーザー</h3>
|
||||
<p class="text-sm text-ads-muted leading-relaxed">
|
||||
天気予報、SNSログイン、地図検索、オンライン決済。気づかないうちに、あなたの日常はAPIに支えられています。APIは特別な人だけのものではなく、全員の生活を支える仕組みです。
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="bg-ads-surface border border-ads-border rounded-xl p-6 border-l-4 border-l-amber-500">
|
||||
<div class="flex items-start gap-4">
|
||||
<div class="text-2xl font-black text-amber-500 leading-none flex-shrink-0 mt-1">03</div>
|
||||
<div>
|
||||
<h3 class="font-bold text-slate-900 mb-2">APIで「車輪の再発明」がなくなる</h3>
|
||||
<p class="text-sm text-ads-muted leading-relaxed">
|
||||
すでにある優れた機能をAPIで借りることで、自分は「自分にしか作れない部分」に集中できます。開発スピードが上がり、品質も上がり、保守の手間も減る。これがAPIの最大の恩恵です。
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="text-center bg-gradient-to-b from-ads-accent/5 to-transparent border border-ads-accent/10 rounded-xl p-8 md:p-10">
|
||||
<i data-lucide="globe" class="w-8 h-8 text-ads-accent mx-auto mb-4"></i>
|
||||
<p class="text-lg font-bold text-slate-900 mb-3">APIは「知っている」だけで世界が広がる概念です。</p>
|
||||
<p class="text-ads-muted max-w-lg mx-auto leading-relaxed">
|
||||
次にアプリを使うとき、「この裏側でどんなAPIが動いているんだろう？」と想像してみてください。天気予報の数字も、ログインボタンも、決済完了の画面も、すべてAPIが繋いでいます。テクノロジーの見え方が、少しだけ変わるはずです。
|
||||
</p>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- CONTENT_END -->
|
||||
</main>
|
||||
<footer class="max-w-3xl mx-auto px-5 pb-10 pt-6 border-t border-ads-border/30">
|
||||
<p class="text-xs text-ads-dim text-center">AI-Driven School の図解ツールで作成</p>
|
||||
</footer>
|
||||
<script src="https://unpkg.com/lucide@latest"></script>
|
||||
<script>lucide.createIcons();</script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,68 @@
|
||||
# Node.js インストールガイド
|
||||
|
||||
図解の公開ステップやセットアップの前提確認で Node.js が未インストールだった場合に参照する。
|
||||
|
||||
## 説明と許可
|
||||
|
||||
以下をユーザーに伝え、インストールの許可を求める:
|
||||
|
||||
> 図解の作成は完了しました。`output/` フォルダ内の HTML ファイルをブラウザにドラッグ＆ドロップすれば、今すぐ確認できます。
|
||||
>
|
||||
> URLで公開するには「Node.js」のインストールが必要です。
|
||||
> Node.js は、パソコン上でプログラムを動かすための土台で、世界中で使われている安全な道具です。
|
||||
> **README にも記載の通り、AI-Driven School 運営が確認済みですので安心してください。**
|
||||
>
|
||||
> 今からインストールしてもよいですか？
|
||||
|
||||
ユーザーが許可しなかった場合 → ファイルの確認方法（生成された HTML ファイルをブラウザで開く）を伝えて終了。
|
||||
|
||||
## macOS の場合
|
||||
|
||||
インストーラーをダウンロードする:
|
||||
|
||||
```bash
|
||||
PKG_NAME=$(curl -sL https://nodejs.org/dist/latest-lts/ | grep -o 'node-v[0-9.]*\.pkg' | head -1) && curl -fsSL "https://nodejs.org/dist/latest-lts/${PKG_NAME}" -o /tmp/node-install.pkg && echo "ダウンロード完了: ${PKG_NAME}"
|
||||
```
|
||||
|
||||
ダウンロード完了後、インストールを実行する**前に**以下を伝える:
|
||||
|
||||
> インストールのために、パソコンのパスワードの入力が必要です。
|
||||
> これはパソコンにログインするときに使っているパスワードです。
|
||||
> 画面下のターミナル欄にパスワードを入力して Enter を押してください。
|
||||
> 入力中の文字は画面に表示されませんが、正常な動作です。
|
||||
|
||||
```bash
|
||||
sudo installer -pkg /tmp/node-install.pkg -target / && rm /tmp/node-install.pkg
|
||||
```
|
||||
|
||||
## Windows の場合
|
||||
|
||||
インストールを実行する**前に**以下を伝える:
|
||||
|
||||
> インストール中に「このアプリがデバイスに変更を加えることを許可しますか？」という確認画面が表示されることがあります。
|
||||
> 「はい」を押してください。
|
||||
|
||||
```powershell
|
||||
winget install OpenJS.NodeJS.LTS --accept-package-agreements --accept-source-agreements
|
||||
```
|
||||
|
||||
インストール完了後、現在のターミナルで Node.js を使えるようにする:
|
||||
|
||||
```powershell
|
||||
$env:Path = [System.Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("Path","User")
|
||||
```
|
||||
|
||||
winget が使えない場合（「winget は認識されていません」と表示された場合）:
|
||||
|
||||
```powershell
|
||||
$msi = (Invoke-WebRequest -Uri "https://nodejs.org/dist/latest-lts/" -UseBasicParsing).Links.href | Where-Object { $_ -match "x64\.msi$" } | Select-Object -First 1; Invoke-WebRequest -Uri "https://nodejs.org/dist/latest-lts/$msi" -OutFile "$env:TEMP\node-install.msi" -UseBasicParsing; Start-Process msiexec.exe -ArgumentList "/i `"$env:TEMP\node-install.msi`"" -Verb RunAs -Wait; Remove-Item "$env:TEMP\node-install.msi"
|
||||
```
|
||||
|
||||
## インストール完了の確認
|
||||
|
||||
```bash
|
||||
node --version
|
||||
```
|
||||
|
||||
バージョン番号が表示された → インストール成功。
|
||||
エラーが出た → Cursor を再起動してからもう一度試すよう案内する。
|
||||
@@ -0,0 +1,125 @@
|
||||
#!/bin/bash
|
||||
# 図解 HTML にコメントウィジェットの script タグを注入して surge.sh に公開する。
|
||||
#
|
||||
# 使い方: deploy-diagram.sh <HTMLファイル> [スラッグ]
|
||||
#
|
||||
# ウィジェットの配信元 URL とトークンは、セットアップスキルが
|
||||
# リポジトリルートに生成する fb-tool-url.txt / fb-api-token.txt から読む。
|
||||
set -e
|
||||
|
||||
HTML_FILE="${1:?使い方: deploy-diagram.sh <HTMLファイル> [スラッグ]}"
|
||||
SLUG="${2:-}"
|
||||
|
||||
GREEN='\033[0;32m'
|
||||
YELLOW='\033[1;33m'
|
||||
RED='\033[0;31m'
|
||||
NC='\033[0m'
|
||||
|
||||
if ! command -v node &>/dev/null; then
|
||||
echo -e "${RED}エラー: Node.js がインストールされていません${NC}" >&2
|
||||
echo "Node.js をインストールしてから、もう一度試してください。" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [ ! -f "$HTML_FILE" ]; then
|
||||
echo -e "${RED}エラー: $HTML_FILE が見つかりません${NC}" >&2
|
||||
echo "先に図解を生成してください。" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [ -n "$SLUG" ]; then
|
||||
DOMAIN="diagram-${SLUG}.surge.sh"
|
||||
else
|
||||
DOMAIN="diagram-$(date +%y%m%d%H%M).surge.sh"
|
||||
fi
|
||||
|
||||
# このスクリプトは <ルート>/.claude/skills/creating-visual-explainers/scripts/ に置かれる前提。
|
||||
# 4階層上 = このスキル一式が置かれているリポジトリのルート
|
||||
ROOT_DIR="$(cd "$(dirname "$0")/../../../.." && pwd)"
|
||||
|
||||
FB_URL_FILE="$ROOT_DIR/fb-tool-url.txt"
|
||||
if [ ! -f "$FB_URL_FILE" ]; then
|
||||
echo -e "${RED}エラー: fb-tool-url.txt が見つかりません${NC}" >&2
|
||||
echo "チャット欄で「セットアップして」と伝えてください。" >&2
|
||||
exit 1
|
||||
fi
|
||||
FB_URL=$(cat "$FB_URL_FILE")
|
||||
|
||||
FB_TOKEN_FILE="$ROOT_DIR/fb-api-token.txt"
|
||||
if [ ! -f "$FB_TOKEN_FILE" ]; then
|
||||
echo -e "${RED}エラー: fb-api-token.txt が見つかりません${NC}" >&2
|
||||
echo "セットアップが完了していない可能性があります。チャット欄で「セットアップして」と伝えてください。" >&2
|
||||
exit 1
|
||||
fi
|
||||
API_TOKEN=$(cat "$FB_TOKEN_FILE")
|
||||
|
||||
if [[ ! "$FB_URL" =~ ^https:// ]]; then
|
||||
echo -e "${RED}エラー: fb-tool-url.txt の URL が https:// で始まっていません${NC}" >&2
|
||||
exit 1
|
||||
fi
|
||||
if [[ "$FB_URL" =~ [\\|\&$'\n'] ]]; then
|
||||
echo -e "${RED}エラー: fb-tool-url.txt に不正な文字が含まれています${NC}" >&2
|
||||
exit 1
|
||||
fi
|
||||
if [[ "$API_TOKEN" =~ [\\|\&$'\n'\ ] ]]; then
|
||||
echo -e "${RED}エラー: fb-api-token.txt に不正な文字が含まれています${NC}" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if ! grep -q '</body>' "$HTML_FILE"; then
|
||||
echo -e "${RED}エラー: $HTML_FILE に </body> タグが見つかりません${NC}" >&2
|
||||
echo "HTML ファイルの構造が壊れている可能性があります。" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
TEMP_DIR=$(mktemp -d)
|
||||
trap 'rm -rf "$TEMP_DIR"' EXIT
|
||||
|
||||
SNIPPET="<script src=\"${FB_URL}/widget.js\" data-token=\"${API_TOKEN}\"></script></body>"
|
||||
|
||||
# 最後の </body> だけを置換する。図解の題材が HTML やコードだと本文中にも
|
||||
# </body> が現れうるため、一括置換すると script タグが複数挿し込まれて壊れる。
|
||||
awk -v snippet="$SNIPPET" '
|
||||
{ line[NR] = $0; if (index($0, "</body>")) last = NR }
|
||||
END {
|
||||
for (i = 1; i <= NR; i++) {
|
||||
if (i == last) {
|
||||
# 該当行の最後の </body> を置換する（sub は先頭一致なので位置を自力で求める）
|
||||
s = line[i]; pos = 0; from = 1
|
||||
while ((p = index(substr(s, from), "</body>")) > 0) {
|
||||
pos = from + p - 1
|
||||
from = pos + 7
|
||||
}
|
||||
printf "%s%s%s\n", substr(s, 1, pos - 1), snippet, substr(s, pos + 7)
|
||||
} else {
|
||||
print line[i]
|
||||
}
|
||||
}
|
||||
}
|
||||
' "$HTML_FILE" > "$TEMP_DIR/index.html"
|
||||
|
||||
printf "User-agent: *\nDisallow: /\n" > "$TEMP_DIR/robots.txt"
|
||||
|
||||
echo -e "${YELLOW}公開中...${NC}"
|
||||
npx --yes surge "$TEMP_DIR" --domain "$DOMAIN"
|
||||
|
||||
touch "$ROOT_DIR/deploy-history.log"
|
||||
echo "$(date '+%Y-%m-%d %H:%M:%S') | https://${DOMAIN}" >> "$ROOT_DIR/deploy-history.log"
|
||||
|
||||
echo ""
|
||||
echo -e "${GREEN}完了！${NC}"
|
||||
echo "URL: https://${DOMAIN}"
|
||||
|
||||
if [[ "$OSTYPE" == "darwin"* ]]; then
|
||||
echo "https://${DOMAIN}" | pbcopy
|
||||
echo -e "${GREEN}URLをクリップボードにコピーしました${NC}"
|
||||
open "https://${DOMAIN}"
|
||||
elif command -v clip.exe &>/dev/null; then
|
||||
echo -n "https://${DOMAIN}" | clip.exe
|
||||
echo -e "${GREEN}URLをクリップボードにコピーしました${NC}"
|
||||
start "https://${DOMAIN}" 2>/dev/null || true
|
||||
elif command -v xdg-open &>/dev/null; then
|
||||
xdg-open "https://${DOMAIN}"
|
||||
fi
|
||||
|
||||
echo -e "${YELLOW}削除するとき: npx surge teardown ${DOMAIN}${NC}"
|
||||
@@ -0,0 +1,294 @@
|
||||
---
|
||||
name: setting-up-comment-tool
|
||||
description: 音声図解コメントツールの初期セットアップ（Vercel・Neon・Gemini APIキー）を対話的にガイドするスキル。「セットアップして」「セットアップの続きをして」「コメントツールをセットアップして」「フィードバック機能を設定して」「音声図解コメントツールを使えるようにして」と依頼された際、および「コメントが保存されません」などセットアップ起因のトラブル調査を求められた際に使用する。
|
||||
---
|
||||
|
||||
# Setting Up Comment Tool
|
||||
|
||||
図解に対するコメント機能（テキスト引用・ピン・音声）を使えるようにする初期セットアップ。Vercel（ホスティング）・Neon Postgres（データベース）・Gemini APIキー（音声解析）の設定を対話的にガイドする。
|
||||
|
||||
**実行するのは1回だけ。** セットアップ完了後は、図解を作ってsurge.shにデプロイするだけで自動的にコメント機能が付く。
|
||||
|
||||
## 用語の定義
|
||||
|
||||
- **ツールフォルダ**: このツール本体（`package.json` の name が `voice-diagram-comment-tool` のフォルダ）。`npm` / `vercel` コマンドはすべてここで実行する
|
||||
- **リポジトリルート**: `.claude` フォルダがある階層。`fb-tool-url.txt` / `fb-api-token.txt` はここに保存する（デプロイスクリプトがここから読むため）
|
||||
|
||||
## Step 0: ツールフォルダの特定
|
||||
|
||||
1. ワークスペースのルートに `package.json` があり、name が `voice-diagram-comment-tool` なら、ルートがツールフォルダ（単体利用）
|
||||
2. なければ、ワークスペース内から name が `voice-diagram-comment-tool` の `package.json` を探す（別リポジトリに組み込んだ利用。フォルダ名は通常 `voice-diagram-comment`）
|
||||
3. 見つからない場合、以下を伝えて終了:
|
||||
|
||||
> ツール本体のフォルダが見つかりません。「voice-diagram-comment」（音声図解コメントツール）フォルダがこのリポジトリ内にあるか確認してください。
|
||||
|
||||
## 前提確認
|
||||
|
||||
### Node.js
|
||||
|
||||
```bash
|
||||
node --version
|
||||
```
|
||||
|
||||
バージョン番号が表示された → 次に進む。
|
||||
`command not found` → `.claude/skills/creating-visual-explainers/references/node-install-guide.md` の手順でインストールを案内する。
|
||||
|
||||
### Vercel CLI
|
||||
|
||||
```bash
|
||||
vercel --version
|
||||
```
|
||||
|
||||
バージョン番号が表示された → 次に進む。
|
||||
`command not found` → 以下を実行:
|
||||
|
||||
```bash
|
||||
npm install -g vercel
|
||||
```
|
||||
|
||||
## ワークフロー
|
||||
|
||||
以降のコマンドは、明記がない限り**ツールフォルダで実行する**。
|
||||
|
||||
### Step 1: 依存関係のインストール
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
### Step 2: Vercelにログイン
|
||||
|
||||
```bash
|
||||
vercel login
|
||||
```
|
||||
|
||||
ブラウザが開く。以下を伝える:
|
||||
|
||||
> ブラウザでVercelのログイン画面が開きます。
|
||||
> アカウントを持っていない場合は「Sign Up」から無料アカウントを作成してください。
|
||||
> メールアドレスまたはGitHubアカウントで登録できます。
|
||||
> ログインが完了したら、ターミナルに戻ってください。
|
||||
|
||||
### Step 3: Vercelに初回デプロイ
|
||||
|
||||
先にデプロイしてVercelプロジェクトを作成する（環境変数の設定にはプロジェクトが必要なため）。
|
||||
|
||||
自動命名に任せると名前の衝突などで不正になることがある。最初にプロジェクト名を明示してリンクする:
|
||||
|
||||
```bash
|
||||
vercel link --yes --project voice-diagram-comment-tool
|
||||
```
|
||||
|
||||
（同名プロジェクトが既にある等でエラーになったら、`voice-comment-tool-2` のように名前を変えて再実行する）
|
||||
|
||||
続いて本番デプロイ:
|
||||
|
||||
```bash
|
||||
vercel --yes --prod
|
||||
```
|
||||
|
||||
デプロイが完了すると以下の2つのURLが出力される。両方を控えておく:
|
||||
|
||||
- **Inspect URL**: `https://vercel.com/{slug}/{project}/...` 形式（Step 6 で使う）
|
||||
- **Production URL**: `https://xxx.vercel.app` 形式（最終的なツールURL）
|
||||
|
||||
この時点では環境変数が未設定なのでツールはまだ動かない。そのまま次に進む。
|
||||
|
||||
### Step 4: APIトークンの生成と設定
|
||||
|
||||
APIを保護するためのトークンを生成し、Vercelの環境変数に設定する。
|
||||
|
||||
```bash
|
||||
openssl rand -hex 16
|
||||
```
|
||||
|
||||
**Windows（PowerShell）の場合:**
|
||||
|
||||
```powershell
|
||||
[System.Guid]::NewGuid().ToString("N")
|
||||
```
|
||||
|
||||
表示された文字列がトークン。これを環境変数として設定する:
|
||||
|
||||
```bash
|
||||
echo "生成したトークン" | vercel env add API_TOKEN production
|
||||
```
|
||||
|
||||
「生成したトークン」は実際に生成した値に置き換える。`vercel env add` が対話式プロンプトを出さずに値を受け取るよう、パイプで渡す。
|
||||
|
||||
同じトークンを**リポジトリルート**の `fb-api-token.txt` に保存する（1行、トークンのみ）。
|
||||
|
||||
### Step 5: Gemini APIキーの設定
|
||||
|
||||
音声フィードバック（喋った内容をAIが聞き取って図解にピンを配置する機能）に使うAPIキーを設定する。
|
||||
|
||||
ユーザーに以下を案内する:
|
||||
|
||||
> 音声フィードバックには Google の Gemini というAIを使います。無料のAPIキーを発行しましょう。
|
||||
>
|
||||
> 1. ブラウザで https://aistudio.google.com/apikey を開く
|
||||
> 2. Googleアカウントでログイン
|
||||
> 3. 「APIキーを作成」（Create API key）をクリック
|
||||
> 4. 表示されたキー（`AIza...` で始まる文字列）をコピー
|
||||
> 5. コピーしたキーをこのチャット欄に貼り付けてください
|
||||
>
|
||||
> 無料枠の範囲で使えます。クレジットカードの登録は不要です。
|
||||
|
||||
キーを受け取ったら設定する:
|
||||
|
||||
```bash
|
||||
echo "受け取ったAPIキー" | vercel env add GEMINI_API_KEY production
|
||||
```
|
||||
|
||||
**注意**: 受け取ったAPIキーは環境変数の設定にだけ使う。ファイルに書き出したり、チャットの返答で復唱したりしない。
|
||||
|
||||
### Step 6: データベースの追加
|
||||
|
||||
Step 3 の Inspect URL からデプロイID部分（末尾のランダム文字列）を削り、`/stores` を付けて Storage ページの直接URLを組み立てる。
|
||||
|
||||
例: Inspect URL が `https://vercel.com/your-projects/voice-diagram-comment-tool/abc123xyz` なら
|
||||
→ `https://vercel.com/your-projects/voice-diagram-comment-tool/stores`
|
||||
|
||||
ユーザーにブラウザでの操作を案内する。以下の `{StorageページURL}` を組み立てたURLに置き換えて伝える:
|
||||
|
||||
> コメントを保存するデータベースを追加します。ブラウザで以下のURLを開いてください。
|
||||
>
|
||||
> {StorageページURL}
|
||||
>
|
||||
> ページが開いたら、以下の操作をしてください。
|
||||
>
|
||||
> 1. 「Create Database」をクリック
|
||||
> 2. 「Neon Postgres」を選択
|
||||
> 3. プランは「Free」を選択（無料、クレジットカード不要）
|
||||
> 4. 「Create」をクリック
|
||||
> 5. 次の画面で:
|
||||
> - 「Search Projects」からプロジェクトを選択
|
||||
> - 「Custom Prefix」の欄を `DATABASE` に変更
|
||||
> - 「Connect」をクリック
|
||||
>
|
||||
> 完了したら教えてください。
|
||||
|
||||
### Step 7: 環境変数の取得とマイグレーション
|
||||
|
||||
```bash
|
||||
vercel env pull .env.local
|
||||
```
|
||||
|
||||
テーブルを作成:
|
||||
|
||||
```bash
|
||||
npm run db:migrate
|
||||
```
|
||||
|
||||
`Migration complete.` と表示されれば成功。
|
||||
|
||||
### Step 8: 再デプロイ
|
||||
|
||||
環境変数を反映するため、もう一度デプロイする。
|
||||
|
||||
```bash
|
||||
vercel --prod
|
||||
```
|
||||
|
||||
### Step 9: URLを保存する
|
||||
|
||||
ツールの**固定URL**（`https://プロジェクト名.vercel.app` 形式。通常は `https://voice-diagram-comment-tool.vercel.app`）を、**リポジトリルート**の `fb-tool-url.txt` に書き出す。URLのみを1行で保存する。
|
||||
|
||||
**注意**: `vercel --prod` の出力に表示されるランダム文字列入りのURL（例: `https://voice-diagram-comment-tool-a1b2c3-xxx.vercel.app`）は保存しない。デプロイ固有URLはVercelの保護機能により外部から読めないことがある。
|
||||
|
||||
保存したら、公開ページから widget.js に到達できることを確認する:
|
||||
|
||||
```bash
|
||||
curl -s -o /dev/null -w "%{http_code}" "$(cat fb-tool-url.txt)/widget.js"
|
||||
```
|
||||
|
||||
**Windows（PowerShell）の場合:**
|
||||
|
||||
```powershell
|
||||
(Invoke-WebRequest "$((Get-Content fb-tool-url.txt).Trim())/widget.js").StatusCode
|
||||
```
|
||||
|
||||
`200` ならOK。`404` や `401` が返る場合は、Vercelダッシュボードのプロジェクト → Settings → Domains に表示されているドメインを確認し、そのURLで `fb-tool-url.txt` を保存し直して再確認する。
|
||||
|
||||
### Step 10: 音声解析APIの通し検証
|
||||
|
||||
widget.js は静的ファイルなので、これだけではAPI（サーバーレス関数）が動いている保証にならない。無音の音声データを実際に `/api/voice-analyze` へ送り、Gemini まで通ることを確認する。
|
||||
|
||||
まず、16kHz・モノラル・1秒の無音WAVを生成してbase64化し、リクエストボディを組み立てる（**リポジトリルート**で実行）:
|
||||
|
||||
```bash
|
||||
node -e '
|
||||
const sr = 16000, dataLen = sr * 2; // 16bit mono 1秒
|
||||
const b = Buffer.alloc(44 + dataLen);
|
||||
b.write("RIFF", 0); b.writeUInt32LE(36 + dataLen, 4); b.write("WAVE", 8);
|
||||
b.write("fmt ", 12); b.writeUInt32LE(16, 16); b.writeUInt16LE(1, 20); b.writeUInt16LE(1, 22);
|
||||
b.writeUInt32LE(sr, 24); b.writeUInt32LE(sr * 2, 28); b.writeUInt16LE(2, 32); b.writeUInt16LE(16, 34);
|
||||
b.write("data", 36); b.writeUInt32LE(dataLen, 40);
|
||||
const body = {
|
||||
audioBase64: b.toString("base64"),
|
||||
mimeType: "audio/wav",
|
||||
targets: [{ index: 0, text: "テスト", heading: "テスト", isHeading: true }],
|
||||
};
|
||||
require("fs").writeFileSync("/tmp/fb-voice-check.json", JSON.stringify(body));
|
||||
'
|
||||
```
|
||||
|
||||
**Windows（PowerShell）の場合**: 上と同じ `node -e` スクリプトを実行し、出力先だけ `$env:TEMP + "\\fb-voice-check.json"` に読み替える（`node -e` はWindowsでも動く）。
|
||||
|
||||
続いて、APIトークンを付けてPOSTする:
|
||||
|
||||
```bash
|
||||
curl -s -w "\n%{http_code}" -X POST "$(cat fb-tool-url.txt)/api/voice-analyze" \
|
||||
-H "Authorization: Bearer $(cat fb-api-token.txt)" \
|
||||
-H "Content-Type: application/json" \
|
||||
--data @/tmp/fb-voice-check.json
|
||||
```
|
||||
|
||||
結果の判定:
|
||||
|
||||
- **HTTP 200 で `{"results":[]}`**（無音なので空配列）→ 音声解析まで通しで動いている。セットアップ成功
|
||||
- **HTTP 404** → APIルートがデプロイされていない。Vercelのビルド設定の問題（エラー対応の「音声の解析に失敗しました」を参照）
|
||||
- **`Gemini エラー` を含む応答** → Geminiのモデル名またはAPIキーの問題（エラー対応の「Gemini エラー (404)」を参照）
|
||||
- **HTTP 403** → `fb-api-token.txt` の値と Vercel の `API_TOKEN` が食い違っている。Step 4 をやり直す
|
||||
|
||||
### Step 11: 完了報告
|
||||
|
||||
リポジトリルートに `fb-tool-url.txt` と `fb-api-token.txt` があることを確認し、以下を伝える:
|
||||
|
||||
```
|
||||
セットアップ完了
|
||||
|
||||
あなたのコメントツール URL:
|
||||
https://xxx.vercel.app
|
||||
|
||||
以降「図解を作って」と伝えるだけで、コメント機能付きの図解が公開されます。
|
||||
|
||||
公開した図解では、3通りの方法でフィードバックできます:
|
||||
- テキストをマウスで選択してコメント
|
||||
- 好きな場所にピンを刺してコメント
|
||||
- マイクに向かって喋るだけ（AIが該当箇所にピンを自動配置）
|
||||
|
||||
APIはトークンで保護されています。図解のデプロイ時に自動で埋め込まれるため、
|
||||
追加の操作は不要です。
|
||||
```
|
||||
|
||||
`fb-tool-url.txt` / `fb-api-token.txt` / `.env.local` はGitにコミットしない（このフォルダの `.gitignore` で除外済み。別リポジトリに組み込んでいる場合は、そのリポジトリの `.gitignore` にも追加するよう案内する）。
|
||||
|
||||
## エラー対応
|
||||
|
||||
エラーメッセージをそのまま見せず、何が起きていて何をすれば解決するかを平易に説明する。
|
||||
|
||||
- **`vercel: command not found`** → `npm install -g vercel` を実行
|
||||
- **`DATABASE_URL is not set`** → Step 6のデータベース追加が完了しているか確認。完了していれば `vercel env pull .env.local` を再実行
|
||||
- **マイグレーション失敗** → ツールフォルダの `.env.local` に `DATABASE_URL` が含まれているか確認
|
||||
- **音声フィードバックで「GEMINI_API_KEY が未設定です」** → Step 5が完了しているか `vercel env ls` で確認し、設定後に `vercel --prod` で再デプロイ
|
||||
- **「音声の解析に失敗しました」** → まず `/api/voice-analyze` が404を返していないか確認する（`curl -s -o /dev/null -w "%{http_code}" -X POST "$(cat fb-tool-url.txt)/api/voice-analyze"` — 404以外＝APIは存在する）。404ならAPIルートがデプロイされていない。原因はVercelのビルド設定: `vercel.json` に `buildCommand` を直接書くとVercelがNext.jsを認識できず、APIが生成されない。ツールフォルダの `vercel.json` が `{"framework": "nextjs"}` のみで、`package.json` に `vercel-build` スクリプトがあることを確認し、`vercel --prod` で再デプロイする
|
||||
- **「Gemini エラー (404)」** → 指定中のGeminiモデルが新規APIキーでは利用不可になっている（例: `gemini-2.5-flash` は新規ユーザーに提供終了）。`echo "gemini-flash-latest" | vercel env add GEMINI_MODEL production` で環境変数を設定し、`vercel --prod` で再デプロイする（ツールが最新版なら既定値が `gemini-flash-latest` のためこのエラーは起きない）
|
||||
- **「コメントが保存されません」と相談された** → 順に切り分ける: ①Step 9の到達確認（widget.js が200か）②`vercel env ls` で `DATABASE_URL` と `API_TOKEN` が production にあるか ③マイグレーション済みか（`vercel env pull .env.local` → `npm run db:migrate`）④環境変数を後から足した場合は `vercel --prod` で再デプロイしたか
|
||||
|
||||
## 依存
|
||||
|
||||
- ツールフォルダの `package.json` — 依存関係と `db:migrate` スクリプト
|
||||
- ツールフォルダの `scripts/migrate.ts` — DBマイグレーションスクリプト
|
||||
- `.claude/skills/creating-visual-explainers/references/node-install-guide.md` — Node.jsインストール手順
|
||||
- `.claude/skills/creating-visual-explainers/scripts/deploy-diagram.sh` — `fb-tool-url.txt` / `fb-api-token.txt` の読み取り側
|
||||
Reference in New Issue
Block a user