仕様・API
サービス概要（プレゼン用）
価値・柱・スタックの圧縮サマリー。
Swipe LP — プレゼン用サマリー
用途: 社内外の説明・デモ・投資家向けのたたき台。仕様の正本は docs/spec/ の各ファイル。数値・HTTP・キー形式の最終確認は必ず spec。
1. 一言で
スワイプ操作で読み進める、スマートフォン向けLPを管理画面で作り、埋め込みJS・ホスト型URL（/p/{id}）・ZIPで配信し、ステップ単位で分析するシステム（作成するLPがSP前提。管理画面そのものの端末とは切り離す）。
マーケサイト / には 組み込みデモLP（灯り珈琲・5ステップ）があり、API不要でスワイプ体験できる。
2. 価値・狙い
| 観点 | 内容 |
|---|---|
| 優先順位 | まず社内での制作・配信・分析。外販に耐えるマルチテナントと課金の置き場は最初から持つ。 |
| 制作物 | 作成するLPはスマートフォン向け（レイアウト・操作はSP前提。PCで見ることはあっても主設計はSP）。 |
| 体験 | 縦/横・通常/全画面などスワイプとビューポートを swipe オブジェクトで表現し、ランタイムで統一。 |
| 配信の自由度 | 自サイト埋め込み、ホスト型 /p/{id}、任意静的ホスティングへのZIP（相対パス完結）。file:// 直開きは推奨しない。 |
| AI制作 | LPナレッジから 文案提案（同期）・画像ジョブ（非同期）・参考URL解析。ストーリーボード一括。 |
| 計測 | ファネルに効く lp_view / step_view / 滞在 / CTA・ホットスポット・動画・スワイプ をイベント化。LP別ダッシュボード＋効果測定ハブ。期間フィルタ（7/30/90日）。 |
| 単一ソース | 編集・プレビュー・埋め込み・ZIPは同じLP定義JSONを消費し、二重実装を避ける。 |
3. 誰が・どう使うか（ストーリー）
| 役割 | 行うこと |
|---|---|
| 制作者 | Workspace 上でLPを作成し、ステップ（画像/動画）・CTA・ホットスポットをJSONとして編集。公開すると公開ID（lpId）で取得可能に。 |
| サイト運用者 | 埋め込み: runtime.js を読み、コンテナに data-swipe-lp-id / data-swipe-lp-api-base 等を指定。ZIP: index.html + lp.json + assets/ をホスティングに配置。 |
| 分析担当 | 計測キーを付与した公開ビューから POST /v1/analytics/events でイベントが届く想定で、ダッシュボード（MVP指標は後述）を見る。 |
4. LP定義JSONの骨子（v0.1）
単一JSONが正本。schemaVersion（現状 "0.1"）で互換管理。
| ルート | 役割 |
|---|---|
id | 公開LP ID（埋め込み・計測・GET /v1/public/lp/{lpId}）。ULID推奨。 |
revision | 更新の識別。サーバ返却の revision と原則同一。 |
meta | title 必須、locale（省略時 ja-JP）、description 任意。 |
swipe | direction: vertical | horizontal · viewport: default | fullscreen。 |
steps[] | 1件以上。配列順が表示順。 |
各ステップ: id（公開後も不変。並べ替えしてもID維持・削除IDは再利用しない）、type: image | video、media（src は相対パスが正）、cta（ステップごと。非表示は null）、hotspots[]（正規化矩形 rect 0〜1）。
ホットスポット: 画像上のタップ領域。CTAボタンとは別系統で、分析でも cta_click と hotspot_click を分離。
メディア: ZIPでは assets/... 相対。将来、CDN絶対URLはオプション拡張の余地あり（v0.1では相対が主）。
詳細・例は spec/lp-definition-v0.1.md。
5. 配信の3経路
5.1 埋め込みJS
- スクリプト例:
https://{配信元}/swipe-lp/v0/runtime.js（defer推奨）。メジャー互換破壊時のみパスを上げる想定。 - マウント先は1つのルート要素。
data-swipe-lp-id・data-swipe-lp-api-baseが必須。data-swipe-lp-public-keyは計測する場合に使用。省略時は計測なし。 - ランタイムは
GET {apiBase}/v1/public/lp/{lpId}で定義を取得し、分析はPOST {apiBase}/v1/analytics/events（後述）。 - 代替として
window.SwipeLP.mount(selector, { lpId, apiBase, publicKey?, surface? })でも初期化可能。
5.2 ホスト型公開URL
GET https://{site-origin}/p/{publicId}— SSR・OGメタ付き。- 公開時に live 計測キーがあれば 当ページからも計測（
GET /v1/public/lp/{id}のpublicKey）。 - 非公開は 410。詳細は embed-and-zip-v0.1.md §4。
5.3 ZIP配布
解凍ルートに置く固定名（マニフェスト別名は使わない）:
| ファイル | 役割 |
|---|---|
index.html | エントリ。ランタイムと lp.json を読み込み。 |
lp.json | LP定義（スキーマ v0.1）。 |
swipe-lp.runtime.v0.js | ビューア（ファイル名固定）。埋め込みと同一バンドル可。 |
assets/ | メディア。lp.json の media.src と整合。 |
swipe-lp.config.json | 任意。surface: zip、apiBase、publicKey、analytics.enabled 等。 |
完全オフライン閲覧は、apiBase なし／analytics.enabled: false でイベント送信なしにできる。相対パス完結のため、顧客の静的サーバやS3等にそのまま配置しやすい。
6. 公開HTTP API（ランタイムが触る部分）
ベースURLは末尾スラッシュなし。パスは /v1/...。JSON、Content-Type: application/json。
| エンドポイント | 認証 | 役割 |
|---|---|---|
GET /v1/public/lp/{lpId} | 不要 | 公開中のLP定義を返す。404 不存在、410 非公開。 |
POST /v1/analytics/events | X-SwipeLP-Key 必須 | イベントバッチ。204/202 受理。 |
CORS: 公開LPの GET は任意オリジン可。計測POSTは X-SwipeLP-Key を許可ヘッダに含めてプリフライト対応。
エラー形式（推奨）: { "error": { "code", "message" } }。例: invalid_request、invalid_key、key_lp_mismatch、not_found、gone、rate_limited 等。詳細は spec/api-v0.1.md。
計測POSTの制約: events は 1〜100件/リクエスト。超過は 400。サーバは キーに紐づく lpId と各イベントの lpId が一致することを検証（不一致は 403）。eventId 重複は冪等に捨ててよい（推奨）。
7. 分析イベント（設計の要点）
7.1 共通エンベロープ
各イベントに eventId（UUID）、name、occurredAt（ISO8601 UTC）、sessionId（匿名・端末単位）、surface（embed | zip | preview）、lpId、revision。任意で context（userAgent、viewport 等）。
7.2 主要イベント（抜粋）
| 名前 | 意味の概要 |
|---|---|
lp_view | その sessionId で初めてLPを表示。 |
step_view | ステップが十分見えた（閾値: 表示率 ≥ 0.5 が 連続100ms）。 |
step_dwell | 閾値以上で見えていた時間を、ステップ離脱時に送信。 |
cta_click / hotspot_click | ステップID・インデックス。ホットスポットは hotspotId 追加。 |
swipe_next / swipe_prev | 遷移元・先のステップとインデックス。 |
video_play / video_progress / video_complete | 動画ステップ用（video_progress は 25/50/75% 等、spec準拠）。 |
ペイロードは payload にネスト推奨（実装はフラットでも可）。全文は spec/analytics-events-v0.1.md。
7.3 MVPダッシュボードで見せる指標（確定）
- LPあたり: ユニーク
sessionId数（lp_viewベース） - ステップあたり:
step_view数、step_dwell平均・合計 - コンバージョン寄り:
cta_click+hotspot_click数
8. 計測キー（publicKey）の考え方
- 目的: 匿名の計測POSTを許可しつつ、どのLP向けのトラフィックかを識別し、漏洩時に失効できるようにする。
- 形式（確定）:
pk_{live|test}_{opaque}。クライアントに平文で置くため、サーバは ハッシュのみ保存（例:HMAC-SHA256(secret_pepper, 全文)）。 - 検証: 形式・DB照合・ボディ内の
lpIdとキーの紐づき（MVPは LP単位発行を推奨して影響範囲を限定）。 - 管理画面では平文は一度だけ表示などの運用前提。詳細は spec/api-v0.1.md。
9. 管理API（v0.1 実装・バックオフィス）
日常操作: ログインユーザーの JWT（httpOnly）＋ワークスペース ACL（owner / editor / viewer）。
ブートストラップ: 環境変数 ADMIN_TOKEN を Authorization: Bearer … または X-Admin-Token で送る（CI・緊急用）。
| メソッド | パス | 内容 |
|---|---|---|
POST | /v1/manage/workspaces | Workspace 作成 { name, slug } |
GET | /v1/manage/workspaces | 一覧 |
POST | /v1/manage/workspaces/{id}/landing-pages | LP 作成（public_id は ULID 自動） |
GET | /v1/manage/workspaces/{id}/landing-pages | LP 一覧 |
PATCH | /v1/manage/workspaces/{ws}/landing-pages/{lp} | definition 更新（definition.id は変更不可） |
POST | /v1/manage/workspaces/{ws}/landing-pages/{lp}/publish | 公開 |
POST | /v1/manage/workspaces/{ws}/landing-pages/{lp}/keys | 計測キー発行（平文はレスで一度だけ） |
POST | /v1/manage/workspaces/{ws}/landing-pages/{lp}/ai/writing-suggestions | AI文案提案（同期） |
POST | /v1/manage/workspaces/{ws}/landing-pages/{lp}/ai/image-jobs | AI画像ジョブ |
GET | /v1/manage/workspaces/{ws}/landing-pages/{lp}/analytics/summary?days= | LP集計（期間フィルタ可） |
開発シードのデモキー例（demo LP 用）: pk_live_swipelp_seed_demo_0001 — 実装は spec/stack.md を参照。
管理コンソール（競合型UIに寄せた導線）: 左ナビで サイト制作（ワークスペース・LP）と 効果測定（LP横断の集計一覧）に分離。画面要素と未実装の対応は spec/product-ui-parity.md。
10. 技術スタックと通信
| 領域 | 内容 |
|---|---|
| 構成 | npm workspaces モノレポ |
| 管理UI | apps/web — Next.js 14 App Router、Tailwind |
| API | apps/api — Python 3.12、FastAPI、SQLAlchemy 2 |
| 閲覧 | packages/viewer — 埋め込み/ZIP向けランタイム（TypeScript） |
| DB | PostgreSQL 16 |
| オブジェクト | S3互換（開発: MinIO。本番は R2/S3 + CDN 前提） |
| プロキシ | 既存 nginx-proxy + acme-companion 等で HTTPS（sslip.io 等での検証ドキュメントあり） |
ブラウザ → サーバ: ユーザー操作は主に Next と同一オリジン。/api/* は Next の rewrite で内部 api（API_INTERNAL_URL）へ。公開LPの /v1/public/* や計測は FastAPI 側の契約どおり。
本番に近い動作確認: docker compose と deploy/nginx-proxy-sslip.md。
11. 認証・マルチテナント・課金
- 認証: 「誰が」「どの Workspace に属するか」をドメインで表現。ログイン手段はアダプタで差し替え。MVPはメール＋パスワードやマジックリンク等から。SSO/OIDC は同じ境界に後から載せる。
- Workspace: メンバー・権限（Owner / Admin / Editor / Viewer 等）は実装時に確定。LP・資産・集計キーは Workspace に紐づく。
- 課金: MVPでは Stripe 等は実装しない。Workspace に
plan・billing_status・trial_ends_at等の nullable フィールドを持ち、社内運用では手動でも可。
12. AI機能
- 文案提案（実装済）: CTA・メタ・ナレッジ・ステップ補足・ストーリーボード。同期 API。→ ai-writing-v0.1.md
- 画像生成（実装済）: 非同期ジョブ、一括・RAG・参考URL。→ ai-lp-image-jobs-v0.1.md
- 動画生成: 未実装。方針は ai-features.md。
- 原則: APIキーはサーバのみ。画像はジョブ＋ストレージ。文案は現状同期。
13. MVPの境界（話の整理用）
- やる: スワイプLPの制作・公開、埋め込み/ホストURL/ZIP配信、ステップ分析、Workspace、計測キー、AI文案・画像、管理API。
- まだやらない: 本番課金フロー（フィールドのみ）。動画AI・ヒートマップ可視化。
14. デモ・質疑で使えるフレーズ
- 「LPは1つのJSON定義で、埋め込みもZIPも同じランタイム。」
- 「ZIPは相対パスだけなので、顧客の静的ホスティングにそのまま載せられる。」
- 「
step.idは公開後も変えないので、長期の分析比較がしやすい。」 - 「ホットスポットとCTAはイベントが分かれるので、バナー型とボタン型の効果を分けられる。」
- 「
step_viewは『半分以上が100ms見えた』など、仕様で閾値が決まっている。」 - 「計測キーはクライアントに出るので、LP単位発行や失効でリスクを抑える設計。」
- 「TOPのデモは組み込みLPで、picsum や API に依存しない。」
- 「AI文案はストーリーボードまで一括。演出指示として画像生成に渡せる。」
15. 正本ドキュメント（詳細はこちら）
| 内容 | パス |
|---|---|
| MVP全体像 | spec/mvp.md |
| LP定義スキーマ v0.1 | spec/lp-definition-v0.1.md |
| 分析イベント v0.1 | spec/analytics-events-v0.1.md |
| 埋め込み・ZIP v0.1 | spec/embed-and-zip-v0.1.md |
| 公開API・計測キー v0.1 | spec/api-v0.1.md |
| 技術スタック・管理API | spec/stack.md |
| AI文案 v0.1 | spec/ai-writing-v0.1.md |
| AI画像 v0.1 | spec/ai-lp-image-jobs-v0.1.md |
| 製品ガイド | product/getting-started.md |
| Docker・プロキシ | deploy/nginx-proxy-sslip.md |
| 意思決定ログ | decisions/log.md |
本ファイルはプレゼン向け要約である。契約・HTTP・キー形式の最終確認は必ず上記 spec を参照すること。