ponshu-room-lite/docs/gamification_specification.md

Gamification & Guide Specification

Version: 1.0 Date: 2026-01-16 Status: Initial Draft

---

1. Feature Overview

ユーザーのモチベーション向上と機能理解を促進するための「ゲーミフィケーション」および「ユーザーガイド」機能の仕様を定義します。

---

2. Gamification Mechanics

A. Level & Titles (レベルと称号)

• 獲得ロジック: 日本酒登録数に応じてEXP獲得。1登録 = 1EXP (将来的に拡張予定)。
• レベルテーブル:
  • Lv.1 (0 EXP): 見習い (Apprentice)
  • Lv.2 (10 EXP): 歩き飲み (Wanderer)
  • Lv.5 (50 EXP): 嗜み人 (Enthusiast)
  • Lv.10 (100 EXP): 呑兵衛 (Drinker)
  • Lv.20 (200 EXP): 酒豪 (Heavy Drinker)
  • Lv.30 (300 EXP): 利き酒師 (Kikisake-shi)
  • Lv.50 (500 EXP): 日本酒伝道師 (Evangelist)
  • Lv.100 (1000 EXP): ポンシュマスター (Ponshu Master)

B. Badges (バッジ)

• 東北制覇 (Tohoku Conqueror): 青森、岩手、宮城、秋田、山形、福島すべての県の酒を登録。
• 辛口党 (Dry Lover): 日本酒度+5以上の酒を10本登録。
• (Note: 現在はUIのみ実装。自動解除ロジックは今回実装スコープ外だが、ガイド画面で条件を表示する)

C. AI Sommelier (AIソムリエ)

• 診断ロジック: 登録された全日本酒の味覚パラメータ（香り、甘さ、酸味、苦味、ボディ）の平均値を算出。
• 表示: 5軸レーダーチャートと固有の称号。
• シェア: スクリーンショットによる画像シェア機能。

---

3. User Guide Implementation (Hybrid Model)

A. Coach Marks (初回のみ)

ユーザーが初めて特定画面にアクセスした際に表示されるスポットライト型チュートリアル。

• Package: tutorial_coach_mark
• Triggers:
  • Camera Screen: 「ここをタップして日本酒をスキャン！(+10 EXP)」
  • Profile Screen (Soul): 「ここでレベルと称号を確認！」「バッジを集めよう」
  • Sommelier Screen: 「あなたの好みをAIが分析します」
• Persistence: Hive (UserProfile) に hasSeen{Screen}Tutorial フラグを保存。

B. Persistent Guide Screen (常設ガイド)

いつでも仕様を確認できる専用画面。

• Access: マイページ (SoulScreen) -> 「📖 ガイド・ヘルプ」ボタン
• Content:
  1. レベル＆EXP: レベル一覧表、EXP獲得条件。
  2. バッジ: 獲得条件一覧と現在の進捗 (e.g., "7/10本").
  3. AIソムリエ: 味覚チャートの見方。
  4. 基本操作: 登録、メニュー作成、PDF出力の手順。

---

4. Technical Architecture

Data Model (UserProfile Update)

@HiveField(16, defaultValue: false)
bool hasSeenCameraTutorial;

@HiveField(17, defaultValue: false)
bool hasSeenProfileTutorial;

@HiveField(18, defaultValue: false)
bool hasSeenSommelierTutorial;

UI Components

• GuideScreen.dart: ヘルプコンテンツを表示するスクロール可能な画面。
• _buildSection(): 共通のセクションビルダ。
• _buildLevelTable(): データ駆動のレベル表。

---

5. Implementation Steps

1. Coach Marks: tutorial_coach_mark 導入、Hiveフィールド追加、各画面に実装。
2. Guide Screen: ガイド画面UI実装、ロジック（レベル表、バッジ進捗）実装。
3. Navigation: マイページにボタン配置。