機能仕様書

📊 現在の実装ステータス（2025/01/31 結果表示最適化）

✅ 実装済み機能

基本診断機能（7つの質問）
100種類のクラブデータベース
収益化機能（Amazon/楽天アフィリエイトリンク生成 + 検索フォールバック）
モジュール型アーキテクチャへの移行（Service/Component分離）
🎯 診断結果3段階表示（2025/01/31 NEW）
- STAGE 1: サマリー - ベストマッチのクラブを大きく表示
- STAGE 2: 比較表 - TOP3を横並びで簡潔に比較
- STAGE 3: 詳細 - アコーディオンで各クラブの詳細表示
- ユーザー入力値を折りたたみ可能に（アコーディオン）
- レスポンシブ対応（モバイル: 縦積み、デスクトップ: 横並び）
- スムーズなアニメーション（fadeIn, slideIn, hover effects）
- 性能バーにグラデーション・プログレスアニメーション
- テストスイート作成（result-display-test.html）
UI/UX改善（2025/01/30）
- CTAボタンの視認性向上（白背景・高コントラスト化）
- 🎯 ヒーローセクションCTA導線最適化（優先度1）
  - プライマリCTAを1つに絞り込み（「無料で診断を始める」）
  - セカンダリCTAを控えめなテキストリンクに変更
  - ボタンサイズ・視覚的階層の明確化
  - モバイル最適化（縦積みレイアウト、プライマリCTA優先表示）
  - 診断履歴リンクをヘッダーナビに追加
  - 微細なパルスアニメーションでCTA注目度向上
- モバイルナビにクラブ一覧リンク追加
- バリデーションエラーの視覚的フィードバック強化
- 進捗バーのデザイン改善（太く・グラデーション化）
- 選択肢のアニメーションフィードバック追加
- サイドバーの表示ブレークポイント最適化（xl以上で表示）
- スケルトンローディング追加
- 🆕 ローディング表示改善（Issue 2-2）
  - 背景を薄くし、親しみやすい明るいオーバーレイに変更
  - ゴルフボールをモチーフにしたアニメーションに変更
  - ローディングメッセージをランダム表示（複数パターン）
  - 擬似プログレスバーで進捗感を可視化
- 🆕 診断質問の説明機能（ツールチップ）
- 🆕 各質問に「分からない」オプション追加
- 🆕 ヘルプアイコンによる詳細説明表示
- ✅ 入力エラーフィードバック強化（1-3対応）
  - リアルタイムバリデーション（blur/inputイベント）
  - 赤枠・背景色変更・シェイクアニメーション
  - アイコン付きエラーメッセージ（スライドイン）
  - 入力ヒント表示（有効範囲の明示）
  - プレースホルダー改善（例示付き）
  - エラー時の自動フォーカス・スムーズスクロール
  - ARIA対応（アクセシビリティ向上）
  - バリデーションテストスイート作成
コードリファクタリング（2025/01/30-31）
- 存在しないJSファイル参照を削除（404エラー解消）
- StateManagerにupdateHistory()メソッド追加
- Service Workerのキャッシュリスト更新
- clubs.htmlのインラインJSをモジュール化（clubs.js）
- 共通ユーティリティモジュール作成（helpers.js）
- ユニットテストスイート追加（unit-tests.js）
- 結果表示コンポーネント分離（2025/01/31）
  - Accordion.js（汎用折りたたみUI）
  - ComparisonTable.js（TOP3比較表）
  - ResultSummary.js（ベストマッチサマリー）
  - ResultDisplay.js（3段階統合表示）

1. システム概要

サービス概要

ゴルフアイアン適性診断は、ユーザーの身体特性、技術レベル、スイング特性を総合的に分析し、最適なアイアンクラブとシャフトの組み合わせを推奨するWebアプリケーションです。

主要特徴

科学的データに基づく診断アルゴリズム
100種類の豊富なクラブデータベース（実装済み ✓）
主要メーカー20社以上をカバー（実装済み ✓）
レスポンシブ対応（スマホ・タブレット・PC）
PWA対応によるオフライン機能
多言語対応（日本語・英語）
Enterキーでの選択機能（実装済み ✓）

システム指標

8 診断質問数

5分平均診断時間

100 クラブデータ数

20+ 対応メーカー数

2. コア機能

2.1 適性診断機能

機能概要

ユーザーの入力情報を基に、最適なアイアンクラブを診断・推奨する機能

入力項目

基本情報: 身長、体重、年齢（実装済み ✓）
ゴルフ経験: 初心者、アマチュア、中級者、上級者（実装済み ✓）
スイング特性: スイングスピード（ゆっくり、標準、速い）（実装済み ✓）
ミス傾向: スライス、フック、トップ、ダフリ（実装済み ✓）
弾道の高さ: 低い、中程度、高い（実装済み ✓）
重視ポイント: 飛距離、正確性、操作性、やさしさ（実装済み ✓）
予算: 5万円以下、5-10万円、10-15万円、15万円以上（実装済み ✓）

出力項目

ユーザー入力値の詳細表示（実装済み ✓）
ゴルファータイプ診断（実装済み ✓）
診断サマリーと根拠（実装済み ✓）
推奨アイアンセット（上位3位まで）（実装済み ✓）
適合度スコア（100点満点）（実装済み ✓）
詳細な推奨理由（実装済み ✓）
シャフト推奨（実装済み ✓）
レーダーチャート表示（実装済み ✓）
各クラブの特性表示（プログレスバー付き）（実装済み ✓）
価格情報・購入リンク（Amazon、楽天）（実装済み ✓）
個別クラブシェア機能（実装済み ✓）

2.2 結果保存・履歴機能

機能概要

診断結果の保存、履歴管理機能を提供

実装済み機能 ✓

診断結果のローカル保存
診断履歴の一覧表示
最近の診断表示（サイドバー）
履歴から結果の再表示
最大10件の履歴保持

未実装機能

クラウド保存（Supabase連携）
PDFエクスポート機能
過去診断との比較機能

2.3 結果共有機能

機能概要

診断結果を他者と共有するための機能

共有方法

SNSシェア（Twitter）（実装済み ✓）
SNSシェア（Facebook）（実装済み ✓）
SNSシェア（LINE）（実装済み ✓）
URLコピー（実装済み ✓）
メール送信（未実装）
QRコード生成（未実装）

2.4 診断質問の説明機能（ツールチップ）✓

機能概要

各診断質問に詳細な説明を表示し、ユーザーが正確に回答できるようサポート

実装済み機能 ✓

全質問にヘルプアイコン（?）を配置
ホバー/タップで詳細説明を表示するツールチップ
スイングスピードにドライバー飛距離の目安を併記
ミス傾向の用語説明（スライス、フックなど）
各質問に「分からない」オプションを追加
モバイル対応（タップで開閉、画面外はみ出し防止）
多言語対応（日本語・英語）
視認性の高いダークテーマツールチップデザイン

技術仕様

コンポーネント: Tooltip.js
スタイリング: CSS（グラデーション、シャドウ、アニメーション）
HTML属性: data-help-key, data-help-text
イベント: mouseenter, mouseleave, click
位置計算: 動的配置（上下左右の空きを判定）

ユーザビリティ向上

初心者が専門用語を理解しやすくなる
判断基準が不明確な質問に具体例を提示
「分からない」選択で診断を進められる
ツールチップ外クリックで自動的に閉じる

2.5 高度診断結果表示機能 ✓

機能概要

ユーザーの入力値を整理し、科学的根拠に基づく詳細な診断結果を提供

実装済み機能 ✓

ユーザープロフィール一覧表示
ゴルファータイプ自動判定
同タイプのプロゴルファー表示（実装済み ✓）
診断ポイントの詳細説明
各クラブの詳細推奨理由
シャフト推奨とセットアップ提案
プログレスバー付き性能表示
個別クラブシェア機能

2.5 ユーザビリティ強化機能 ✓

機能概要

よりスムーズな診断体験を提供するための操作性改善

実装済み機能 ✓

Enterキーでの選択・次へ進む機能
キーボードナビゲーション対応
100種類のクラブデータベース
豊富なブランド・シリーズカバー

2.6 アイアンクラブ一覧機能 ✓

機能概要

100種類以上のアイアンクラブを検索・フィルタリングできる専用ページ機能

実装済み機能 ✓

専用ページ（clubs.html）を新設
サイドバー・ヘッダーナビゲーションからのアクセス
上部固定の大型検索バー（クラブ名/ブランド/特徴の検索）
フィルターUI刷新（PC: サイドバー、モバイル: ドロワー）
難易度・タイプ・ブランド・価格帯のフィルタリング
ソート機能（価格: 安い順/高い順、評価順、新着順）
詳細なクラブスペック表示（タイプ、素材、価格等）
5段階評価表示（許容性、飛距離、打感、操作性）
Amazon・楽天市場への直接リンク
レスポンシブ対応（モバイル・タブレット・PC）
「もっと見る」ボタン + 自動読み込み（無限スクロール）による段階的表示（12件ずつ）
検索結果件数と表示件数の表示（例: 120件 / 表示中24件）
適用中の条件をチップで表示（ワンクリック解除）

2.7 購入サポート機能

機能概要

推奨クラブの購入をサポートする機能

実装済み機能 ✓

Amazon・楽天市場への直接リンク
価格表示とコスト情報
個別クラブのシェア機能

未実装機能

価格比較機能
在庫確認
試打予約リンク

3. 診断アルゴリズム

アルゴリズム概要

多変量解析と重み付けスコアリングを組み合わせた独自のマッチングアルゴリズムを採用

診断フロー（V1.2強化版）

データ前処理: 入力データの正規化と欠損値処理
プロファイル生成: ユーザープロファイルの数値化
ゴルファータイプ判定: 経験・志向に基づくタイプ分類
多項目スコア計算: 経験・スピード・ミス・体格・予算など統合分析
詳細理由生成: 各推奨理由の自動文章生成
シャフト推奨: スイング特性に基づくシャフト提案
ランキング生成: 総合適合度によるランキング
結果可視化: プログレスバー・チャートでの表示

スコアリングシステム

身体適合性 25% 身長・体重に基づくクラブ長・重量適合

技術レベル適合性 30% 経験・技術レベルに応じた寛容性

スイング特性適合性 25% スイングスピード・弾道への適合

ミス傾向対策 15% ミス改善効果の期待値

志向・予算適合性 5% ブランド志向・予算との適合

4. データ構造

クラブデータベース構造

clubs.json

{
  "id": "string",
  "manufacturer": "string",
  "model": "string",
  "category": "game_improvement|players|players_distance",
  "construction": "cavity|muscle|hollow",
  "target_handicap": "0-5|5-15|15-30|30+",
  "price_range": "low|medium|high",
  "weight": "number",
  "lie_angle": "number",
  "loft_7iron": "number",
  "shaft_options": ["steel", "carbon"],
  "features": {
    "forgiveness": "1-10",
    "workability": "1-10",
    "distance": "1-10",
    "feel": "1-10"
  },
  "specifications": {
    "head_size": "compact|mid|large",
    "sole_width": "narrow|medium|wide",
    "offset": "minimal|moderate|strong"
  }
}

診断結果データ構造

{
  "diagnosis_id": "string",
  "user_profile": {
    "gender": "male|female",
    "height": "number",
    "weight": "number",
    "experience": "string",
    "handicap": "number",
    "swing_speed": "slow|average|fast",
    "ball_height": "low|medium|high",
    "miss_tendency": ["slice", "hook", "top", "fat"],
    "priority": "distance|accuracy|forgiveness|feel",
    "budget": "low|medium|high",
    "preferred_brands": ["string"],
    "appearance": "traditional|modern|no_preference"
  },
  "recommendations": [
    {
      "rank": "number",
      "club": "object",
      "score": "number",
      "reasons": ["string"],
      "shaft_recommendation": "string"
    }
  ],
  "created_at": "datetime"
}

5. 技術スタック

フロントエンド

HTML5: セマンティックマークアップ
CSS3: Grid/Flexbox レスポンシブデザイン（実装済み ✓）
JavaScript (ES6+): Vanilla JS, モジュール設計（実装済み ✓）
TailwindCSS: ユーティリティファーストCSS（実装済み ✓）
Chart.js: レーダーチャート表示（実装済み ✓）
PWA: Service Worker, Web App Manifest（部分実装）

バックエンド・データベース

ローカルストレージ: 診断結果・履歴保存（実装済み ✓）
Supabase: 認証・データベース・API（計画中）
PostgreSQL: リレーショナルデータベース（計画中）
Row Level Security: データアクセス制御（計画中）

ホスティング・インフラ

GitHub Pages: 静的サイトホスティング
CDN: コンテンツ配信最適化
HTTPS: SSL/TLS暗号化

開発・運用ツール

Git/GitHub: バージョン管理・CI/CD
GitHub Actions: 自動デプロイ
Google Analytics: アクセス解析
Google Search Console: SEO管理

6. ユーザーインターフェース

UIデザイン原則

シンプル: 直感的で分かりやすいインターフェース
レスポンシブ: すべてのデバイスで最適表示
アクセシブル: WCAG 2.1準拠のアクセシビリティ
高速: 3秒以内のページ読み込み時間

画面仕様

デスクトップ (1200px以上)

3カラムレイアウト
サイドナビゲーション
リアルタイムプレビュー

タブレット (768px-1199px)

2カラムレイアウト
折りたたみメニュー
タッチ最適化

スマートフォン (767px以下)

1カラムレイアウト
ハンバーガーメニュー
スワイプ操作対応

7. パフォーマンス仕様

パフォーマンス目標

First Contentful Paint < 1.5秒

Largest Contentful Paint < 2.5秒

Cumulative Layout Shift < 0.1

Time to Interactive < 3.0秒

最適化手法

画像最適化: WebP形式、遅延読み込み
CSS最適化: クリティカルCSS、minification
JavaScript最適化: コード分割、tree shaking
キャッシュ戦略: Service Worker、CDN活用
リソース圧縮: Gzip/Brotli圧縮

8. セキュリティ

セキュリティ対策

データ保護

HTTPS通信の強制
個人情報の暗号化保存
Row Level Security (RLS)
定期的なバックアップ

アクセス制御

認証システム（Supabase Auth）
JWT トークン認証
セッション管理
不正アクセス検知

脆弱性対策

XSS (Cross-Site Scripting) 対策
CSRF (Cross-Site Request Forgery) 対策
SQL インジェクション対策
定期的なセキュリティ監査

プライバシー保護

個人情報保護法準拠
GDPR 準拠（将来対応）
データ削除権の保証
第三者提供の制限

9. 外部連携

アフィリエイト連携

A8.net

ゴルフショップ・メーカーとの提携
成果報酬型広告
購入トラッキング

Amazon Associates

Amazon商品へのリンク
在庫確認API連携
価格情報取得

分析・マーケティング

Google Analytics 4

ユーザー行動分析
コンバージョン追跡
カスタムイベント計測

Google Tag Manager

タグ管理の一元化
イベントトラッキング
A/Bテスト支援

📊 アフィリエイト計測仕様 (全アプリ共通 GTM連携)

1. 概要

目的: 全アプリ（ゴルフ診断、パズル等）のアフィリエイトリンククリックを横断的に計測し、アプリ別・商品別の収益性を分析する
GTMコンテナID: GTM-TXQGZRF9
GA4測定ID: G-ZDPNYD2875

2. HTML実装ルール（開発者向け）

アフィリエイトリンク（<a>タグ）には、以下のクラスと属性が必須です。

属性/クラス	必須	値の例	説明
`class`	必須	`js-track-affiliate`	GTM発火用トリガー識別子
`data-platform`	必須	`Amazon`, `Rakuten`	リンク先のプラットフォーム名
`data-item-name`	必須	`Stealth Iron`, `ナンプレ本`	商品名（分析の主軸）
`data-link-type`	任意	`database_link`, `fallback_search`	正規リンク/検索フォールバック識別

3. GTM設定内容

トリガー: Click Element が CSSセレクタ .js-track-affiliate, .js-track-affiliate * に一致
GA4送信パラメータ:
- service_name: URLから自動取得（{{Auto - Service Name}}）
- item_name: data-item-name (統合変数)
- platform: data-platform
- link_source: data-link-type

SNS・共有

ソーシャルメディア

Twitter API（結果投稿）
Facebook Graph API
LINE Messaging API

📋 未実装機能一覧

優先度：高（2025年Q1-Q2実装予定）

1. データ管理・保存機能

クラウド保存（Supabase連携）
- ユーザー認証システム
- 診断結果のクラウド同期
- 複数デバイス間でのデータ共有
PDFエクスポート機能
- 診断結果の印刷用フォーマット
- ショップへの持参用レポート
- 詳細スペックシート生成
過去診断との比較機能
- スイング改善の経過追跡
- 推奨クラブの変化分析
- 成長グラフ表示

2. 購入支援機能

価格比較機能
- 複数ECサイトの価格追跡
- 価格変動アラート
- 最安値ショップ表示
在庫確認システム
- リアルタイム在庫表示
- 取寄せ可否情報
- 納期目安表示
試打予約機能
- 近隣ショップ検索
- 試打可能店舗マップ
- 予約カレンダー連携

3. コミュニケーション機能

メール送信機能
- 診断結果のメール送信
- 友人への共有
- プロショップへの相談メール
QRコード生成
- 診断結果の即時共有
- ショップでの簡単表示
- イベント・展示会での活用

優先度：中（2025年Q3-Q4実装予定）

4. 高度な診断機能

ウェッジ・ユーティリティ診断
- アプローチ特性分析
- バンカー適性診断
- 距離別ウェッジ推奨
AIチャットボット
- 診断補助AI
- クラブ選択相談
- FAQ自動応答
スイング動画解析
- 動画アップロード機能
- AI姿勢分析
- 改善ポイント提案

5. ユーザーエンゲージメント

レビュー・評価システム
- 推奨クラブの実使用レビュー
- 5段階評価システム
- 写真付きレビュー
コミュニティ機能
- ユーザー間の情報交換
- クラブ交換会情報
- ゴルフ仲間マッチング

優先度：低（2026年以降検討）

6. 先進技術機能

AR/VR機能
- ARクラブ試着
- VRスイング体験
- 3Dクラブビューワー
機械学習強化
- 個人最適化アルゴリズム
- 予測精度向上
- トレンド分析
IoT連携
- スマートクラブ連携
- スイングセンサー統合
- 練習データ自動取得

実装に関する注意事項

GitHub Pages（静的サイト）の制約により、バックエンド機能は外部サービス連携が必要
Supabase、Firebase等のBaaSを活用した実装を検討
ユーザーデータ保護とプライバシー対策を最優先
段階的な機能追加により、安定性を維持

11. 今後の機能拡張予定

フェーズ2（2025年Q1-Q2）

ウェッジ・ユーティリティ診断機能追加
AI チャットボット導入
ユーザーレビュー・評価機能
パーソナライズド推奨機能強化

フェーズ3（2025年Q3-Q4）

モバイルアプリ開発（iOS/Android）
ARクラブ試着機能
スイング動画解析機能
プロフィッター予約システム

フェーズ4（2026年）

機械学習による診断精度向上
VRクラブ体験機能
ゴルフコース連携
国際展開（アジア・欧米）

技術進化計画

AI/ML: TensorFlow.js による機械学習モデル導入
リアルタイム: WebRTC によるライブ相談機能
3D/AR: Three.js による3Dクラブ表示
エッジ: Edge Computing による高速化

目次

📊 現在の実装ステータス（2025/01/31 結果表示最適化）

✅ 実装済み機能

1. システム概要

サービス概要

主要特徴

システム指標

2. コア機能

2.1 適性診断機能

機能概要

入力項目

出力項目

2.2 結果保存・履歴機能

機能概要

実装済み機能 ✓

未実装機能

2.3 結果共有機能

機能概要

共有方法

2.4 診断質問の説明機能（ツールチップ）✓

機能概要

実装済み機能 ✓

技術仕様

ユーザビリティ向上

2.5 高度診断結果表示機能 ✓

機能概要

実装済み機能 ✓

2.5 ユーザビリティ強化機能 ✓

機能概要

実装済み機能 ✓

2.6 アイアンクラブ一覧機能 ✓

機能概要

実装済み機能 ✓

2.7 購入サポート機能

機能概要

実装済み機能 ✓

未実装機能

3. 診断アルゴリズム

アルゴリズム概要

診断フロー（V1.2強化版）

スコアリングシステム

4. データ構造

クラブデータベース構造

clubs.json

診断結果データ構造

5. 技術スタック

フロントエンド

バックエンド・データベース

ホスティング・インフラ

開発・運用ツール

6. ユーザーインターフェース

UIデザイン原則

画面仕様

デスクトップ (1200px以上)

タブレット (768px-1199px)

スマートフォン (767px以下)

7. パフォーマンス仕様

パフォーマンス目標

最適化手法

8. セキュリティ

セキュリティ対策

データ保護

アクセス制御

脆弱性対策

プライバシー保護

9. 外部連携

アフィリエイト連携

A8.net

Amazon Associates

分析・マーケティング

Google Analytics 4

Google Tag Manager

📊 アフィリエイト計測仕様 (全アプリ共通 GTM連携)

1. 概要

2. HTML実装ルール（開発者向け）

3. GTM設定内容

SNS・共有

ソーシャルメディア

📋 未実装機能一覧