ponshu-room-lite/CommonSpecification.md

# ぽんるーむ (Pon-Room) - 共通仕様書 v1.0

**作成日**: 2026-01-03
**対象**: AI開発エージェント（Cursor/Antigravity/Claude/Gemini）
**目的**: すべての開発者・AIエージェントが参照する唯一のバイブル

---

## 📋 1. プロジェクト概要

### 1.1 アプリケーション情報
- **アプリ名**: ぽんるーむ (Pon-Room)
- **コンセプト**: 日本酒の「記録・解析・循環」を支えるAIプラットフォーム
- **バージョン**: 1.0.9+47
- **最終更新**: 2026-01-03

### 1.2 ターゲットユーザー
- **B2C (Consumer Mode)**: 一般ユーザー
  - 日本酒体験の記録・診断・共有
  - ゲーミフィケーション（ポイント・バッジ・レベル）
  - 「酒向（しゅこう）カード」による自己表現

- **B2B (Business Mode)**: 飲食店
  - 自店の日本酒メニュー作成（PDF出力）
  - QRコード自動埋め込み
  - インスタ投稿支援

### 1.3 アプリの循環ロジック
```
[飲食店] PDF + QRメニュー作成
    ↓
[客] スキャンして詳細表示・ポイント獲得
    ↓
[客] 自分の記録が貯まる → 酒向カード生成
    ↓
[飲食店] 客の好みを理解してレコメンド
```

---

## 🛠️ 2. 技術スタック

### 2.1 フロントエンド
- **Framework**: Flutter 3.10.1
- **SDK**: Dart 3.10.1
- **対応プラットフォーム**: iOS, Android, Web

### 2.2 バックエンド・データベース
- **Database**: Cloud Firestore (Firebase)
- **Authentication**: Firebase Auth
- **Storage**: Firebase Storage (画像保存)

### 2.3 AI・機械学習
- **Local OCR**: Google ML Kit
  - 用途: ラベルからのテキスト抽出
  - メリット: 無料、高速、オフライン動作

- **LLM Analysis**: Gemini API
  - モデル: `gemini-2.5-flash` / `gemini-3.0-flash`
  - 用途: テキストの構造化、キャッチコピー生成
  - 重要: 画像を直接送らず、OCRテキストのみ送信（トークン節約）

### 2.4 主要パッケージ
```yaml
dependencies:
  # 画像・カメラ
  image_picker: ^1.2.1
  gal: ^2.3.0  # カメラロール保存

  # PDF生成
  pdf: ^3.10.0
  printing: ^5.11.0

  # QRコード
  qr_flutter: ^4.1.0
  mobile_scanner: ^3.5.0  # QRスキャン

  # データベース
  hive: ^2.2.3
  hive_flutter: ^1.1.0

  # AI
  google_generative_ai: ^0.4.7
  google_ml_kit: ^0.16.0  # OCR用
```

---

## 📊 3. 共通データ構造（JSON Schema）

### 3.1 基本方針
- **display_data**: カードUIで表示する最小限の情報（シンプル維持）
- **hidden_specs**: 詳細画面・PDF・分析で使用する情報
- **badges**: ゲーミフィケーション要素
- **gamification**: ポイント・レベル・診断結果
- **user_data**: ユーザーの主観的情報
- **metadata**: システム管理用

### 3.2 SakeItem完全JSON構造

```json
{
  "display_data": {
    "name": "獺祭 純米大吟醸 磨き二割三分",
    "catch_phrase": "華やかな香りと洗練された味わい",
    "image_path": "path/to/image.jpg",
    "rating": 4.5
  },

  "hidden_specs": {
    "brewery": "旭酒造株式会社",
    "prefecture": "山口県",
    "type": "純米大吟醸",
    "alcohol_content": 16.0,
    "polishing_ratio": 23,
    "sake_meter_value": 4.0,
    "rice_variety": "山田錦",
    "yeast": "自社酵母",
    "manufacturing_year_month": "2024.10",
    "qr_code_url": "https://pon-room.app/sake/abc123"
  },

  "badges": {
    "is_recommended": false,
    "is_seasonal": false,
    "season_tag": "春限定"
  },

  "gamification": {
    "pon_points": 10,
    "sake_mbti_type": "フルーティー・モダン型",
    "rarity_level": "レア"
  },

  "user_data": {
    "is_favorite": false,
    "is_wishlist": false,
    "tags": ["甘口", "フルーティー", "冷酒向き"],
    "memo": "お祝い事にぴったり。冷やして飲むのがおすすめ。",
    "drink_location": "○○レストラン",
    "companion": "△△さん",
    "purchase_location": "××酒販店",
    "price": 5000
  },

  "metadata": {
    "created_at": "2026-01-03T12:34:56Z",
    "updated_at": "2026-01-03T12:34:56Z",
    "app_type": "sake",
    "app_mode": "consumer",
    "version": "1.0",
    "scanned_count": 0
  }
}
```

---

## 🎨 4. UI構成ルール

### 4.1 タブ構成（5タブ制）

| タブ | Consumer Mode (B2C) | Business Mode (B2B) |
|------|---------------------|---------------------|
| **タブ1** | 日本酒カードリスト（自分の記録） | 日本酒カードリスト（店舗在庫） |
| **タブ2** | QRスキャン・AR情報表示 | PDFメニュー作成・QR埋め込み |
| **タブ3** | AIソムリエ・酒向カード診断 | インスタ投稿支援（AI文章生成） |
| **タブ4** | 酒蔵マップ（聖地巡礼） | 店舗設定・在庫管理 |
| **タブ5** | マイページ（レベル・バッジ・設定） | アナリティクス（スキャン統計） |

### 4.2 カード表示ルール（重要）

**表示項目（display_dataのみ）:**
- 銘柄名 (`display_data.name`)
- 画像 (`display_data.image_path`)
- 評価 (`display_data.rating`) - 星表示
- バッジ (`badges`) - 店長推奨・季節限定アイコン

**非表示項目（詳細画面でのみ使用）:**
- `hidden_specs` の全項目
- `user_data` の詳細情報

**理由:** シンプルなUIを維持し、挫折を防ぐ

### 4.3 詳細画面の表示項目

**全て表示:**
- `display_data` 全項目
- `hidden_specs` 全項目（スペック表として）
- `badges` （アイコン付き）
- `user_data` 全項目

### 4.4 PDF出力の表示項目

**主要項目:**
- `display_data.name`, `image_path`
- `hidden_specs` の以下:
  - type, alcohol_content, polishing_ratio
  - sake_meter_value, brewery, prefecture
- `badges` （アイコン付き）
- QRコード（`hidden_specs.qr_code_url` から生成）

---

## 🤖 5. AI解析フロー（Hybrid Analysis）

### 5.1 撮影から保存まで

```
1. 撮影
   ├─ ImagePicker or Camera パッケージ
   └─ カメラロール自動保存（gal パッケージ使用）★重要

2. OCR（テキスト抽出）
   ├─ Google ML Kit（ローカル・無料）
   ├─ 画像 → 全テキスト抽出
   └─ 抽出テキストのみを次へ

3. AI解析（構造化）
   ├─ 抽出テキストを Gemini API へ送信
   ├─ プロンプト: 「JSONフォーマットで返して」
   └─ 上記のJSON構造で回答を取得

4. 保存
   ├─ Hive（ローカル）に即座保存
   └─ Firebase（クラウド）に同期（将来実装）
```

### 5.2 AI解析プロンプト例

```
あなたは日本酒のラベル解析の専門家です。
以下のOCRテキストから、日本酒の情報を抽出してJSON形式で回答してください。

【OCRテキスト】
{ocrText}

【出力ルール】
1. display_data: 銘柄名と魅力的なキャッチコピー（あなたが生成）
2. hidden_specs: 詳細スペック（読み取れた範囲で）
3. 読み取れない項目はnullにする
4. JSONのみを返す（```jsonなどのマークダウン記法は不要）
5. キャッチコピーは20文字以内で簡潔に

【出力フォーマット】
{JSON構造をここに記載}
```

### 5.3 コスト最適化のポイント

**❌ NG: 画像を直接Geminiに送信**
- 高トークン消費
- エラー発生率が高い

**✅ OK: OCRテキストのみ送信**
- トークン消費70-90%削減
- 安定した動作
- 後から再解析が不要

---

## 🎮 6. ゲーミフィケーション機能

### 6.1 ポンポイント（仮称）

**獲得条件:**
- 日本酒を記録: +5pt
- QRスキャン: +10pt
- 酒蔵訪問: +30pt（位置情報連動）
- 評価・レビュー投稿: +3pt

**レベルシステム:**
```
0-49pt: 利き酒初心者
50-149pt: 日本酒愛好家
150-299pt: 酒豪
300-499pt: 利き酒師
500pt+: 酒マスター
```

### 6.2 酒向（しゅこう）カード

**概要:** MBTIライクな自己診断カード

**診断軸（レーダーチャート）:**
1. 甘口 ←→ 辛口
2. 濃醇 ←→ 淡麗
3. フルーティー ←→ 米の旨味
4. 冷酒 ←→ 熱燗

**表示項目:**
- 診断タイプ（例: フルーティー・モダン型）
- レーダーチャート
- 好きな銘柄TOP3
- AIの一言コメント

**用途:**
- 店員に見せて好みを伝える
- SNSシェア（画像として保存）

---

## 📱 7. QR循環ロジック

### 7.1 BtoB: PDFメニュー作成時

```
1. 飲食店が店舗在庫を登録
2. PDFメニュー生成時、各銘柄にQRコード埋め込み
3. QRコード内容: https://pon-room.app/sake/{sakeId}
4. 印刷して店内に設置
```

### 7.2 BtoC: QRスキャン時

```
1. 客がアプリでQRスキャン
2. 銘柄詳細をAR風に表示（オーバーレイ）
3. 「記録する」ボタンで自分のリストに追加
4. ポンポイント+10pt獲得
5. 酒蔵リンクへの誘導
```

### 7.3 循環の価値

- **客**: スキャンする度にポイントが貯まる
- **店**: 客の興味データが蓄積（アナリティクス）
- **蔵元**: ECサイトへの誘導で売上向上

---

## 🎓 8. オンボーディング（使い方ガイド）

### 8.1 初回起動時

**4ステップガイド:**
1. ようこそ！日本酒の記録を始めよう
2. カメラで撮影するだけでAIが自動解析
3. お気に入りを記録して自分だけのコレクションを
4. 飲食店の方はBusinessモードへ切り替え可能

### 8.2 再表示機能

- 各画面右上の「？」アイコン
- タップでガイドを再表示

### 8.3 Businessモード専用ガイド

**3ステップ（モード切り替え時のみ表示）:**
1. 店舗情報を設定しましょう
2. メニューを作成してPDF出力
3. QRコードで客とつながる

---

## 🚀 9. 開発優先順位（Phase別）

### Phase 0: 基盤整備 ✅
- [x] CommonSpecification.md 作成
- [ ] SakeItemモデルの拡張

### Phase 1: 安心の確保（1-2時間）
- [ ] カメラロール保存実装（gal）
- [ ] iOS/Android権限設定
- [ ] 撮影後の自動保存フロー

### Phase 2: BtoB機能完成（4-6時間）
- [ ] PDF + printing 実装
- [ ] モックアップ厳密再現
- [ ] QRコード埋め込み
- [ ] レイアウト定数化

### Phase 3: AI最適化（3-4時間）
- [ ] Google ML Kit 導入
- [ ] OCRテキスト抽出
- [ ] Gemini APIへのテキスト送信切り替え

### Phase 4: ゲーミフィケーション（後回しOK）
- [ ] ポンポイントシステム
- [ ] 酒向カード生成
- [ ] QRスキャン機能

---

## 📐 10. レイアウト定数（PDF用）

```dart
class PDFLayoutConstants {
  // 余白
  static const double pageMargin = 24.0;
  static const double sectionSpacing = 20.0;
  static const double itemSpacing = 12.0;

  // フォントサイズ
  static const double titleFontSize = 24.0;
  static const double headingFontSize = 14.0;
  static const double bodyFontSize = 11.0;
  static const double labelFontSize = 9.0;

  // 線の太さ
  static const double borderWidthThin = 0.5;
  static const double borderWidthMedium = 1.0;
  static const double borderWidthThick = 2.0;

  // 色（posimaiカラー）
  static final PdfColor borderColor = PdfColor.fromHex('#E2E8F0');
  static final PdfColor labelColor = PdfColor.fromHex('#64748B');
  static final PdfColor accentColor = PdfColor.fromHex('#376495');
}
```

---

## 🔐 11. セキュリティ・プライバシー

### 11.1 データ保存場所

**✅ ローカル保存:**
- Hive DB: アプリ専用ディレクトリ
- 写真: カメラロール（ユーザー端末）

**✅ 外部送信（一時的、保存されない）:**
- Gemini API: OCRテキストのみ（画像は送らない）

**❌ 外部送信なし:**
- 個人情報の無断クラウド保存
- サードパーティへのデータ販売

### 11.2 将来のFirebase連携

- ユーザーが明示的に「同期」を選択した場合のみ
- 画像はFirebase Storageへ
- テキストデータはFirestoreへ

---

## 🎯 12. 量産対応（ワイン・ビールアプリへの展開）

### 12.1 拡張方法

`metadata.app_type` を変更するだけで転用可能:
- `sake` → 日本酒
- `wine` → ワイン
- `beer` → クラフトビール
- `whisky` → ウイスキー

### 12.2 共通化できる機能

- 撮影・OCR・AI解析フロー
- ポイントシステム
- PDF出力・QR循環
- マイページ・設定

### 12.3 差分化が必要な箇所

- JSONの `hidden_specs` フィールド
  - ワイン: ぶどう品種、産地、ヴィンテージ
  - ビール: ホップ、モルト、IBU値
- キャッチコピーのトーン

---

## 📝 13. AIエージェントへの指示

### 13.1 開発時の鉄則

1. **この仕様書を最優先のルール（バイブル）として参照せよ**
2. **display_data と hidden_specs を明確に分離せよ**
3. **カードUIはシンプルに保ち、display_dataのみ使用せよ**
4. **挫折防止のため、段階的に実装せよ（Phase順守）**
5. **モックアップがある場合は1px単位で厳密再現せよ**

### 13.2 コード生成時の注意

- null安全性を徹底
- エラーハンドリングを統一
- デバッグログを適切に配置
- コメントは日本語で簡潔に

### 13.3 質問・提案時のルール

- 仕様書と矛盾する提案をする場合は理由を明記
- 新機能追加時はPhaseを提案
- データ構造変更時はJSON例を提示

---

## 📞 14. サポート・連絡先

**プロジェクトオーナー**: posimai
**開発支援AI**: Claude (Anthropic), Gemini (Google AI), ChatGPT (OpenAI)
**バージョン管理**: Git (GitHub)
**CI/CD**: Vercel (Web), Firebase Hosting

---

## 🎉 15. 最後に

この仕様書は「挫折しない日本酒アプリ開発」のために、複数のAIの知恵を結集して作成されました。

**重要な心構え:**
- シンプルから始める
- データは豊富に持つが、表示は最小限に
- ユーザーが「楽しい」と感じる体験を最優先に

**Let's build the best sake app together! 🍶✨**

---

**End of CommonSpecification.md v1.0**