目的¶

PathCollectorを、対象Webサイト上の行動を端末横断で時系列記録し、個人情報を意味付きマスクしたうえで保存し、MCP経由で検索・取得・解析できる画面なしのサービスとして実装する。

最上位ゴールは「Web行動記録」であり、GA4/GSCの代替ではなく、DOM状態・DOM変化・ユーザー操作・遷移・エラーを後から解析可能な形で保持すること。

担当ワーカー¶

Claude Code（主担当）
推奨モデル: Sonnet

MVPスコープ¶

1. Collector SDK¶

• TypeScript + rrweb
• PC / macOS / iPhone / iPad / Android対応
• Chrome / Edge / Firefox / Safari / iOS Safari / iOS Chrome / Android Chrome
• 初期DOMスナップショット
• DOM追加・削除・属性・テキスト変更
• click / tap / input / change / submit / scroll / navigation / focus / blur
• visibilitychange / pagehide / orientationchange / online / offline
• JavaScript error / unhandled rejection
• SPA遷移対応
• touchend・pointerup・clickの重複排除、モバイル操作をtapへ正規化
• 5秒、50イベント、256KB、visibilitychange、pagehideでflush
• 終了時はsendBeacon優先、失敗時fetch keepalive

2. プライバシー¶

• クライアント側とサーバー側の二段階マスキング
• [MASKED_NAME] / [MASKED_EMAIL] / [MASKED_PHONE] / [MASKED_ADDRESS] / [MASKED_CARD_NUMBER] / [MASKED_PASSWORD] / [MASKED_TOKEN] 等
• input type、name、id、autocomplete、aria-label、周辺ラベル、CSS selector、正規表現による検出
• hidden input value、password、script/style本文、認証情報を保存しない
• data-pc-mask、data-pc-ignore対応
• URL query/fragment内の機微情報除去
• 生のPIIをログへ出力しない
• ブラウザフィンガープリント禁止
• IPを行動分析DBへ保存しない

3. 同意・オプトアウト¶

• ConsentState: unknown / granted / denied / essential_only
• consentMode: explicit / implicit
• optOut / optIn / isOptedOut
• オプトアウト時は録画停止、未送信バッファ破棄、visitor/session ID削除
• pc_opt_outをファーストパーティCookieまたはlocalStorageへ保存

4. API¶

Collector API:

• POST /v1/collect
• POST /v1/consent
• POST /v1/opt-out
• GET /v1/sdk/config/{write_key}

Analysis API:

• GET /v1/projects/{project_id}/sessions
• GET /v1/projects/{project_id}/sessions/{session_id}
• GET /v1/projects/{project_id}/sessions/{session_id}/timeline
• POST /v1/projects/{project_id}/analysis/pages
• POST /v1/projects/{project_id}/analysis/events
• POST /v1/projects/{project_id}/analysis/paths
• POST /v1/projects/{project_id}/analysis/funnel
• POST /v1/projects/{project_id}/analysis/dropoffs
• POST /v1/projects/{project_id}/analysis/scroll-depth

Privacy API:

• DELETE /v1/projects/{project_id}/sessions/{session_id}
• DELETE /v1/projects/{project_id}/visitors/{visitor_id}

System API:

• GET /health
• GET /ready
• GET /metrics

5. MCP Server¶

画面なし。MCPを主要操作面とする。
実装ツール:

• pathcollector_search_sessions
• pathcollector_get_session
• pathcollector_get_web_behavior
• pathcollector_get_timeline
• pathcollector_summarize_web_behavior
• pathcollector_get_page_metrics
• pathcollector_analyze_paths
• pathcollector_analyze_funnel
• pathcollector_analyze_dropoffs
• pathcollector_get_errors
• pathcollector_delete_session
• pathcollector_delete_visitor
• pathcollector_get_schema
• pathcollector_health

通常はrrweb生イベントではなく正規化済みuser_actionsを返す。生DOM取得はraw_events:read scope保有時のみ許可する。

6. DB¶

PostgreSQL 16以上。
最低限のテーブル:

• organizations
• projects
• project_domains
• api_credentials
• privacy_rules
• anonymous_visitors
• sessions
• page_views
• event_batches
• raw_events
• user_actions
• action_effects
• privacy_findings
• daily_metrics
• deletion_requests
• audit_logs

主識別単位はsession_id、補助識別単位はvisitor_id。複数端末をまたぐ人物統合は行わない。

7. 操作と画面変化の関連付け¶

ユーザー操作後2秒以内に発生したDOM変更をaction_effect候補として関連付ける。
記録項目:

• added_node_count
• removed_node_count
• changed_attribute_count
• changed_text_count
• navigation_occurred
• validation_error_occurred
• javascript_error_occurred
• affected_selectors

技術スタック¶

• pnpm workspace
• Node.js + TypeScript
• Fastify
• rrweb
• PostgreSQL 16
• Drizzle ORM推奨
• Zod
• MCP TypeScript SDK
• Vitest
• Playwright
• Docker Compose
• Nginx
• JSON構造化ログ

リポジトリ構成¶

pathcollector/
├─ apps/api
├─ apps/mcp
├─ apps/worker
├─ apps/collector-sdk
├─ packages/database
├─ packages/domain
├─ packages/privacy
├─ packages/schemas
├─ packages/logger
├─ packages/config
├─ migrations
├─ tests/integration
├─ tests/e2e
├─ tests/privacy
├─ docs/api
├─ docs/mcp
└─ docker-compose.yml

実装順序¶

Phase 1:

1. リポジトリ初期化
2. PostgreSQLスキーマとmigration
3. プロジェクト/APIキー登録CLI
4. Collector SDK
5. rrweb取得
6. クライアントマスキング
7. /v1/collect
8. サーバー再マスキング
9. raw_events保存

Phase 2:

1. visitor/session/page_view生成
2. click/tap/scroll/navigation/error正規化
3. user_actions保存
4. action_effects生成
5. TTL削除

Phase 3:

1. MCP認証
2. セッション検索
3. Web行動タイムライン
4. ページ指標
5. パス/ファネル/離脱分析
6. 削除ツール

Phase 4:

1. E2E
2. PII漏えいテスト
3. レート制限
4. metrics
5. バックアップ・復元手順
6. API/MCPドキュメント

必須受入条件¶

• Docker Composeで起動できる
• /health と /ready が正常
• テストサイトへ1タグで設置可能
• Windows Chrome、macOS Safari、iPhone Safari、iPhone Chrome、Android Chromeで計測可能
• タップが重複せず1操作として保存される
• DOMスナップショット・DOM変更・スクロール・遷移・エラーを記録できる
• SPA遷移を記録できる
• 入力値を保存せず、入力行為とフィールド種別のみ記録できる
• email、電話番号、氏名、password、tokenが保存前にマスクされる
• data-pc-ignore配下が保存されない
• 同意拒否・オプトアウト時に送信しない
• MCPからWeb行動を時系列取得できる
• MCPから「入口、閲覧順、スクロール、操作、DOM変化、離脱点、エラー直前行動」を取得できる
• 権限外project_idを参照できない
• TTL削除が稼働する
• 削除操作が監査ログへ記録される
• READMEに導入、起動、設定、テスト、MCP接続方法を記載

完了定義¶

対象サイトへJavaScriptタグを設置することで、PC・iPhone・Android・タブレット上のWeb行動を取得し、個人情報をマスクした状態で時系列保存し、MCP経由で検索・取得・解析できること。

開発上の制約¶

• 管理画面は作らない
• セッションリプレイUIは作らない
• ヒートマップUIは作らない
• 生PIIを一切永続化しない
• 問題発生時は原因、影響、暫定対応