# Ponshu Room Lite - AI Master Roadmap & Context

> **For All AI Assistants**: このドキュメントはプロジェクトの現状、ルール、および将来のロードマップを共有するためのマスタードキュメントです。作業を開始する前に必ず確認してください。

---

## 1. プロジェクト概要
**Ponshu Room Lite** は、日本酒のラベルを撮影するだけでAI（Gemini 2.0 Flash）が詳細情報を解析・記録するFlutterアプリです。

- **ターゲット**: 個人ユーザー（日本酒愛好家）〜 知人配布レベル
- **主要機能**: AIラベル解析、テイスティングノート記録、PDFメニュー生成、バックアップ
- **技術スタック**: Flutter, Riverpod, Hive (NoSQL), Google Gemini API
- **現状バージョン**: **v1.0.15+26** (2026-02-11) - 配布準備完了段階

---

## 2. 現在のステータス (v1.0.15)
### ✅ 完了済みの重要実装
1.  **AI解析の一貫性確保**:
    *   `gemini_service.dart`: Temperature 0.2
    *   `analysis_cache_service.dart`: 画像ハッシュキャッシュ + **銘柄名ベースキャッシュ** (v1.0.15)
2.  **UI/UXの統一**:
    *   **AppColors ThemeExtension** による完全なテーマ管理 (ハードコード色排除)
    *   `ErrorRetryWidget` による統一エラーハンドリング
    *   ダイアログ、ボトムナビの挙動統一
    *   **新規開拓おすすめセクション**: ソムリエタブに実装済み（v1.1.0予定の前倒し実装）
3.  **セキュリティ**:
    *   `secrets.local.dart` の `.gitignore` 対応
    *   **Synology Proxy Server**: 構築用コードと手順書 (`docs/SYNOLOGY_PROXY_SETUP.md`) 完備

### ⚠️ 残存する技術的負債
1.  **Synology Proxyの永続化未対応**:
    *   現在のレート制限は In-Memory 実装のため、コンテナ再起動でリセットされる。
    *   Redis またはファイルベースの永続化が必要。
2.  **プロジェクト構成の乱立**:
    *   `ponshu_room_lite - コピー` 等のバックアップフォルダが散乱。Git管理されているためこれらは削除推奨（セキュリティ・混乱防止）。
3.  **巨大クラス**: `lib/screens/sake_detail_screen.dart` (~800行) → 分割は進んだが監視が必要。 `camera_screen.dart` (967行) も分割対象。
4.  **デバッグプリント残存**: `debugPrint` が200件以上残っている。リリースビルドには出ないが、`kDebugMode` で囲む等の整理が必要。
5.  **Pro版ビルド手順未整備**: `IS_PRO_VERSION` フラグの利用方法がドキュメント化されていない。

---

## 3. 次ステップ推奨タスク (Roadmap)

### 🔹 v1.0.16: 品質改善とリファクタリング (High Priority)
このバージョンは**コードベースの健全化**に集中します。

1.  **`sake_detail_screen.dart` の分割** (工数: 4h)
    *   目的: 可読性と保守性の向上
    *   方針: `lib/screens/sake_detail/` フォルダを作成し、セクションごとにWidget化する
    *   分割案:
        *   `BasicInfoSection`
        *   `TasteChartSection`
        *   `SakenowaSection`
        *   `TastingNotesSection`

2.  **テストコードの導入** (工数: 3h)
    *   目的: リグレッション防止
    *   対象:
        *   Unit Tests: `SakeItem` モデルの JSON 変換、`LevelCalculator`
        *   Service Tests: `GeminiService` (Mock使用)、`AnalysisCacheService`

3.  **残存ハードコード色の修正**
    *   `lib/widgets/onboarding_dialog.dart`: `Colors.grey` (2箇所) を `appColors` に置換
    *   `pending_analysis_screen.dart`: エラー赤を `appColors.error`、成功緑を `appColors.success` に置換（カメラUIの白は維持）

### 🔹 v1.1.0: 機能拡張 (Medium Priority)
1.  **チャート手動編集機能**
    *   AIの解析結果（5軸チャート）をユーザーが手動で微調整できる機能
2.  **Pro機能の実装**
    *   QRスキャン連携
    *   Instagram投稿生成
    *   アナリティクスダッシュボード

### 🔹 運用環境の整備 (User Action Required)
1.  **Synology Proxy構築**
    *   目的: APIキーを隠蔽し、ユーザーごとの利用制限(Quota)を管理する
    *   参照: [`docs/SYNOLOGY_PROXY_SETUP.md`](./docs/SYNOLOGY_PROXY_SETUP.md)
    *   ツール: `tools/proxy/` (server.js, package.json, Dockerfile)
2.  **配布用APK生成**
    *   `flutter build apk --release`

---

## 4. 開発ルール (Strict Rules)

### UI/Design

#### 原則: AppColors を使用すること
```dart
final appColors = Theme.of(context).extension<AppColors>()!;
color: appColors.textPrimary    // ✅ OK
color: appColors.error          // ✅ OK (エラー表示)
color: appColors.success        // ✅ OK (成功表示)
color: Colors.red               // ❌ NG
color: Colors.black             // ❌ NG (例外を除く)
```

#### ⚠️ ハードコード色の例外一覧（変更禁止）

以下の箇所は意図的にハードコードされています。**AIエージェントはこれらを appColors に置き換えてはいけません。**

| ファイル | 色 | 理由 |
|---------|-----|------|
| `lib/screens/camera_screen.dart` (全体) | `Colors.white / Colors.black / Colors.white54` など | カメラビューファインダーはテーマに関係なく視認性確保が必須。黒背景に白テキストは固定要件 |
| `lib/screens/pending_analysis_screen.dart:387` | `Colors.grey.shade400` (disabledBackgroundColor) | Material Design の disabled ボタン標準色。変えると UX が壊れる |
| `lib/screens/pending_analysis_screen.dart:341` | `Colors.grey.shade300` (プレースホルダー背景) | 画像未選択状態のプレースホルダー標準色 |
| `lib/screens/main_screen.dart:65` | `Colors.grey.shade400` (Pro機能アイコン) | ロック中の機能が無効化されていることを示す意図的な灰色 |
| 各所の `boxShadow` | `Colors.black.withValues(alpha: ...)` | シャドウは黒固定が自然。テーマ依存にする必要なし |
| `lib/screens/features/sommelier_screen.dart` カードシャドウ | `Colors.black.withValues(alpha: ...)` | 同上 |

#### ✅ 変更対象のハードコード色（v1.0.16 タスク）

| ファイル | 変更前 | 変更後 |
|---------|--------|--------|
| `lib/widgets/onboarding_dialog.dart:113` | `Colors.grey` | `appColors.textSecondary` |
| `lib/widgets/onboarding_dialog.dart:136` | `Colors.grey[300]` | `appColors.textSecondary` |
| `lib/screens/pending_analysis_screen.dart` (エラーテキスト) | `Colors.red` | `appColors.error` |
| `lib/screens/pending_analysis_screen.dart` (成功アイコン) | `Colors.green.shade400` | `appColors.success` |

*   **Washi Theme**: 和紙のような質感を重視。ダークモード対応は必須。

### State Management
*   **Riverpod**: `ConsumerWidget` / `ConsumerStatefulWidget` を使用。
*   ロジックはUIから分離し、Notifier/Providerに記述する。

### AI Integration
*   **Gemini Service**: 直接呼び出しではなく、必ず `GeminiService` を経由。
*   **Caching**: AI呼び出し前に必ずキャッシュを確認するロジックが含まれているか確認（現在はService内で自動化済み）。

---

## 5. 主要ドキュメントリンク
*   [`task.md`](./task.md): 直近のタスク管理
*   [`implementation_plan.md`](./implementation_plan.md): 最新の実装計画
*   [`lib/theme/app_colors.dart`](./lib/theme/app_colors.dart): カラーパレット定義
*   [`docs/SYNOLOGY_PROXY_SETUP.md`](./docs/SYNOLOGY_PROXY_SETUP.md): Proxy構築手順

---
**Last Updated**: 2026-02-13 (v1.0.15+26)