14 KiB

Raw Blame History

ぽんるーむ (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 主要パッケージ

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構造

{
  "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ライクな自己診断カード

診断軸（レーダーチャート）:

甘口 ←→ 辛口
濃醇 ←→ 淡麗
フルーティー ←→ 米の旨味
冷酒 ←→ 熱燗

表示項目:

診断タイプ（例: フルーティー・モダン型）
レーダーチャート
好きな銘柄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ステップガイド:

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

8.2 再表示機能

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

8.3 Businessモード専用ガイド

3ステップ（モード切り替え時のみ表示）:

店舗情報を設定しましょう
メニューを作成してPDF出力
QRコードで客とつながる

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

Phase 0: 基盤整備 ✅

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用）

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 開発時の鉄則

この仕様書を最優先のルール（バイブル）として参照せよ
display_data と hidden_specs を明確に分離せよ
カードUIはシンプルに保ち、display_dataのみ使用せよ
挫折防止のため、段階的に実装せよ（Phase順守）
モックアップがある場合は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

14 KiB Raw Blame History Unescape Escape