511 lines
14 KiB
Markdown
511 lines
14 KiB
Markdown
# ぽんるーむ (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**
|