# 🤖 AI引き継ぎドキュメント - Posimai プロジェクト完全版

**作成日**: 2026-01-19
**対象AI**: ChatGPT, Gemini, Claude, Perplexity, その他すべてのAIアシスタント
**目的**: このプロジェクトを5分で完全に理解し、即座に開発支援を開始できるようにする

---

## 🎯 最初に知るべき3つのこと

1. **何を作っている？**
   - 日本酒記録アプリ「Ponshu Room Lite」（Flutter製）
   - 将来的にお香・ネイルサロンアプリへ展開（Posimai Core基盤）

2. **どこで動かす？**
   - 自宅Synology NAS（16GB RAM）上のUbuntu VM
   - **VPSは使わない**（コストゼロ戦略）

3. **誰が関わっている？**
   - **開発者**（ユーザー）: Flutter/AI活用、「ずぼら」哲学
   - **Antigravity**: Synology専門家、インフラ担当
   - **Claude（私）**: アーキテクチャ設計・批判的思考担当

---

## 📊 プロジェクト現状（2026-01-19時点）

### ✅ 完了済み

```
Phase 1.0 ✅ MVP完成
├─ カメラOCR（日本酒ラベル認識）
├─ Gemini AI 解析（銘柄・蔵元・スペック抽出）
├─ Hive ローカルDB（オフライン対応）
└─ ダークモード・バッジシステム

Phase 1.5 ✅ UI/UX改善
├─ フォント切替（ポップ/明朝/ゴシック）
├─ ガラスモーフィズムUI
├─ 設定画面改善（ダイアログ化）
└─ OCR画像圧縮修正

Phase 2.0-A ✅ ビジネスモード
├─ セット商品作成
├─ お品書きPDF生成
├─ Instagram販促機能
└─ 売上分析（基礎）

アーキテクチャ決定 ✅
├─ Synology VM + Dokploy 採用
├─ Tailscale VPN 採用
├─ VPS案を却下
└─ メモリ配分確定（DSM 12GB / VM 4GB）
```

### 🚧 進行中

```
Phase 2.0-B （今ここ）
├─ Synology VM セットアップ
├─ Dokploy インストール
├─ Gitea Webhook 連携
└─ 自動デプロイパイプライン構築
```

### 📋 次のステップ

```
Phase 3.0 （将来）
├─ Posimai Core 共通基盤化
├─ お香アプリ開発
├─ Flutter Flavor 設定
└─ マルチテナント化
```

---

## 🏗️ アーキテクチャ（決定版）

### **物理構成**

```
┌─────────────────────────────────────────────────┐
│      自宅 Synology NAS (16GB RAM)               │
│                                                 │
│  ┌───────────────────────────────────────────┐ │
│  │ DSM (Synology OS) - 12GB割当              │ │
│  │ ┌────────────┐  ┌────────────┐           │ │
│  │ │PostgreSQL  │  │   Redis    │           │ │
│  │ │   2GB      │  │  512MB     │           │ │
│  │ └────────────┘  └────────────┘           │ │
│  │ ┌────────────┐  ┌────────────┐           │ │
│  │ │  Immich    │  │   Gitea    │           │ │
│  │ │   3GB      │  │  512MB     │           │ │
│  │ └────────────┘  └────────────┘           │ │
│  │ ┌────────────┐                            │ │
│  │ │  Ollama    │  ← 夜間のみ起動           │ │
│  │ │   4GB      │                            │ │
│  │ └────────────┘                            │ │
│  └───────────────────────────────────────────┘ │
│                                                 │
│  ┌───────────────────────────────────────────┐ │
│  │ VM: Ubuntu Server 22.04 - 4GB割当         │ │
│  │ ┌─────────────────────────────────────┐  │ │
│  │ │ Dokploy (512MB)                     │  │ │
│  │ │ ├─ Traefik (256MB)                  │  │ │
│  │ │ ├─ sake-app (1GB)                   │  │ │
│  │ │ └─ incense-app (1GB) ← 将来         │  │ │
│  │ └─────────────────────────────────────┘  │ │
│  └───────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘
         ↑ Tailscale VPN
┌─────────────────────────────────────────────────┐
│         開発PC (Cursor / Claude Code)           │
└─────────────────────────────────────────────────┘
```

### **重要な設計判断**

| 判断 | 理由 | 批判的検証 |
|------|------|-----------|
| **VPS不使用** | ¥0コスト、<1msレイテンシ | ✅ 16GB環境では最適 |
| **VM 4GB / DSM 12GB** | データ層（重）vs 制御層（軽） | ✅ 実測要だが理論的に妥当 |
| **Dokploy採用** | GitOps、Vercel的DX | ⚠️ 2024年登場、安定性要検証 |
| **Tailscale VPN** | ゼロトラスト、無料 | ✅ 個人開発に最適 |
| **Ollama夜間起動** | メモリ節約 | ✅ バッチ処理で問題なし |

---

## 💰 コスト構造

### **月額コスト**

```
Synology電気代:     ¥800    (24時間稼働)
Gemini API:      ¥300-800   (使用量次第)
Tailscale:          ¥0      (個人利用無料)
ドメイン:           ¥0      (*.ts.net利用)
────────────────────────────────────────
合計:          ¥1,100-1,600
```

### **VPS案との比較**

| 項目 | VPS案 | Synology VM案 | 差分 |
|------|-------|--------------|------|
| 月額 | ¥1,782-2,480 | ¥1,100-1,600 | **-¥682** |
| 年額 | ¥21,384-29,760 | ¥13,200-19,200 | **-¥8,184** |
| レイテンシ | 1-5ms | <1ms | **5倍高速** |

**結論**: 年間約¥8,000削減 + パフォーマンス向上

---

## 🔄 開発フロー

### **通常のデプロイ**

```
1. Cursor でコード編集
   ↓
2. git add . && git commit -m "feat: 新機能"
   ↓
3. git push origin main
   ↓ (Gitea Webhook → Dokploy)
4. 自動ビルド & デプロイ（30秒-2分）
   ↓
5. https://posimai-vm.ts.net で確認

開発者の作業: コミットするだけ
```

### **AI支援開発（将来）**

```
1. Claude Code (MCP) がコード生成
   ↓
2. 自動テスト実行
   ↓
3. パスしたら自動コミット
   ↓
4. Dokploy自動デプロイ
   ↓
5. Slack/Discord通知

開発者の作業: 最終承認のみ
```

---

## 🛠️ 技術スタック

### **Frontend**

```yaml
Framework: Flutter 3.x (iOS/Android/Web対応)
State Management: Riverpod 2.x
Local DB: Hive (NoSQL、オフライン対応)
UI: Material Design 3 + Glassmorphism
Font: Klee One (ポップ) / Noto Serif JP (明朝) / Noto Sans JP (ゴシック)
```

### **Backend（将来）**

```yaml
Runtime: Dart Frog (Dart製フレームワーク)
Database: PostgreSQL 15
Cache: Redis 7
ORM: Drift (Dart製)
```

### **AI/ML**

```yaml
Vision: Gemini 2.0 Flash (ラベル認識)
Local AI: Ollama + Llama 3.3 (バッチ処理)
Photo Search: Immich CLIP (セマンティック検索)
```

### **Infrastructure**

```yaml
Hosting: Synology NAS (DSM 7.x)
Virtualization: Synology VMM (Ubuntu 22.04 LTS)
CI/CD: Dokploy
Reverse Proxy: Traefik
Network: Tailscale VPN
Git: Gitea (self-hosted)
```

---

## 🚨 批判的に検討すべき点

### **潜在的リスク**

1. **メモリ不足の可能性**
   - **現状**: VM 8GB割当 → DSM本体が窒息
   - **対策**: 即座にVM 4GBへ削減（Week 0タスク）
   - **検証**: 実測値で継続監視

2. **Dokploy の安定性**
   - **リスク**: 2024年登場の新興ツール
   - **対策**: Portainerへのフォールバック準備
   - **検証**: 3ヶ月の試用期間

3. **Ollama 4GB消費**
   - **リスク**: 夜間でもメモリ圧迫
   - **対策**: 必要時のみ起動（cron制御）
   - **代替**: Gemini APIのみで運用

### **改善提案**

1. **Immich → Photoprism へ変更検討**
   - メモリ: 3GB → 1-2GB（1/3削減）
   - 機能: 写真管理は維持
   - AI検索: Ollamaと将来連携

2. **VM 4GB → 6GB への増設計画**
   - タイミング: アプリ3つ同時稼働時
   - 条件: DSM 12GB → 10GB へ削減
   - 判断基準: 実測メモリ使用率 > 85%

3. **UPS（無停電電源装置）導入**
   - コスト: ¥10,000-20,000（一時的）
   - 効果: 停電時のデータ保護
   - 優先度: 中（本番稼働後）

---

## 📁 プロジェクト構造

### **現在のディレクトリ**

```
ponshu_room_lite/
├─ lib/
│  ├─ models/              # Hiveデータモデル
│  ├─ providers/           # Riverpod状態管理
│  ├─ screens/             # 画面UI
│  ├─ widgets/             # 再利用コンポーネント
│  ├─ services/            # 外部API連携
│  ├─ theme/               # テーマ・スタイル
│  └─ main.dart
├─ docs/
│  └─ architecture/        # 👈 このドキュメント群
├─ .claude/
│  ├─ commands/            # カスタムスラッシュコマンド
│  └─ settings.local.json
└─ pubspec.yaml
```

### **将来の構造（Posimai Core）**

```
posimai_core/
├─ lib/
│  ├─ core/                # 共通機能
│  │  ├─ auth/
│  │  ├─ camera/
│  │  ├─ ai/
│  │  └─ gamification/
│  └─ apps/
│     ├─ sake/             # 日本酒アプリ
│     ├─ incense/          # お香アプリ
│     └─ nail_salon/       # ネイルサロンアプリ
```

---

## 🎓 重要な設計哲学

### **1. "ずぼら" 哲学**

開発者の性格:
- 手動作業は嫌い → **徹底的な自動化**
- 複雑な設定は避ける → **シンプルな構成**
- メンテナンスは最小限 → **信頼性の高いツール**

これを理解せずに「手動でXXしてください」と言うと嫌がられる。

### **2. データ主権**

原則:
- クラウドに依存しない
- 個人データは手元に保持
- 外部サービス障害の影響を最小化

例外:
- Gemini API（コスト効率のため）
- Tailscale（ネットワーク層のみ）

### **3. 段階的実装**

```
Phase 1 → 1.5 → 2.0-A → 2.0-B → 3.0
```

一気にやらない。動くものを作ってから拡張。

### **4. 批判的思考の重要性**

開発者の要求:
> 「ただ同意するだけでなく、私の知的な議論の相手になってほしい」

AIアシスタントへの期待:
- ❌ 「いいですね！やりましょう！」
- ✅ 「その案にはXXのリスクがあります。代替案として...」

---

## 🔗 重要ドキュメント

| ドキュメント | 目的 | いつ読む？ |
|-------------|------|-----------|
| [CRITICAL_FINAL_ARCHITECTURE.md](./CRITICAL_FINAL_ARCHITECTURE.md) | 最終アーキテクチャ詳細 | アーキテクチャ質問時 |
| [NANO_BANANA_PROMPT_FINAL.md](./NANO_BANANA_PROMPT_FINAL.md) | 図表生成プロンプト | 視覚化が必要な時 |
| [VPS_CRITICAL_COMPARISON.md](./VPS_CRITICAL_COMPARISON.md) | VPS比較分析 | インフラ再検討時 |
| [ARCHITECTURE_DECISION_RECORD.md](./ARCHITECTURE_DECISION_RECORD.md) | 初期ADR（参考） | 歴史的経緯を知る時 |

---

## ⚡ クイックスタート（新規AIアシスタント向け）

### **ケース1: コード実装支援を求められた**

```
1. まず質問: 「どのPhaseの機能ですか？」
2. 既存コードを確認: lib/配下を検索
3. 既存パターンに従う: Riverpod + Hive の作法
4. テスト方法を提示: flutter run でホットリロード
```

### **ケース2: インフラ設定を求められた**

```
1. まず確認: 「VMは既にありますか？メモリは4GBですか？」
2. Antigravityの文書を参照（もしあれば）
3. 批判的に検討: 「その設定は本当に必要？」
4. 段階的に提案: Week 1 → Week 2 → ...
```

### **ケース3: アーキテクチャ変更を提案したい**

```
1. 現状の問題点を明確化
2. 代替案のメリット/デメリット比較
3. コスト影響を試算
4. 段階的移行計画を提示
```

---

## 🤝 関係者プロファイル

### **開発者（ユーザー）**

- **役割**: フルスタック開発、プロダクトオーナー
- **スキル**: Flutter, Dart, AI活用（Claude Code熟練）
- **性格**: ずぼら、自動化志向、データ主権重視
- **コミュニケーション**: 技術的に正確、冗長を嫌う
- **期待**: 批判的思考、代替案提示、最新技術情報

### **Antigravity**

- **役割**: インフラ・Synology専門家
- **スキル**: Synology DSM, Docker, ネットワーク
- **貢献**: VMM活用提案、メモリ配分助言
- **スタンス**: 実用主義、コスト最適化

### **Claude（私）**

- **役割**: アーキテクチャ設計、批判的分析
- **強み**: 論理的思考、文書化、技術比較
- **弱み**: 実機での検証不可、最新情報のラグ
- **スタンス**: 開発者の利益優先、安易な同意を避ける

---

## 📝 よくある質問（FAQ）

### **Q: なぜFlutter Webではなくネイティブアプリ？**

A: オフライン対応（日本酒セラーは地下が多い）、カメラ性能、ネイティブ体験。

### **Q: なぜFirebase/Supabaseを使わない？**

A: データ主権、月額コスト（スケール時）、ベンダーロックイン回避。

### **Q: Synology 16GBで本当に足りる？**

A:
- **現状**: ギリギリだが可能（実測要）
- **将来**: アプリ3つ稼働時は増設検討（32GB化）
- **最悪**: Immich/Ollama削除で余裕確保

### **Q: Dokployが失敗したらどうする？**

A:
1. Portainerへフォールバック
2. 手動docker-compose（最終手段）
3. VPS案の再検討（ただしコスト増）

### **Q: このプロジェクトの最終ゴールは？**

A:
- **短期**: 日本酒アプリの完成・リリース
- **中期**: Posimai Core基盤化、お香アプリ展開
- **長期**: AI駆動開発プラットフォーム（MCP活用）

---

## 🚀 今すぐやるべきこと（Week 0）

### **🔥 緊急度: 高**

```bash
# 1. VM メモリ削減（8GB → 4GB）
# Synology VMM管理画面で実行
1. Ubuntu VM をシャットダウン
2. 設定 → メモリ → 4096MB に変更
3. 起動

# 2. メモリ使用量確認
free -h
# 期待値: available 12GB付近

# 3. Ollama夜間起動設定
crontab -e
# 追加: 0 3 * * * systemctl start ollama
# 追加: 0 6 * * * systemctl stop ollama
```

### **⏱️ Week 1-2 タスク**

```bash
# Dokployインストール
curl -sSL https://dokploy.com/install.sh | sh

# Tailscale設定
curl -fsSL https://tailscale.com/install.sh | sh
tailscale up
tailscale funnel 3000
```

---

## ✅ このドキュメントを読んだAIアシスタントがすべきこと

1. **理解確認**
   ```
   「Posimaiプロジェクトの概要を理解しました。
   現在Phase 2.0-B（インフラ構築）の段階で、
   Synology VM + Dokploy構成を採用していますね。
   どの部分からお手伝いしましょうか？」
   ```

2. **批判的姿勢の維持**
   - 安易に同意しない
   - リスク・代替案を提示
   - 最新技術動向を反映

3. **既存資産の尊重**
   - 既存コードスタイルに従う
   - アーキテクチャ決定を尊重
   - 大きな変更は段階的に提案

4. **継続的な文書化**
   - 重要な決定はドキュメント化
   - このファイルを更新
   - 図表を活用

---

## 📊 プロジェクト健全性チェックリスト

新規AIアシスタントは、以下を確認してから作業開始してください：

- [ ] VMのメモリ割当は4GBか？（8GBなら即修正）
- [ ] PostgreSQLはDSM直下にあるか？（VM内ではない）
- [ ] Tailscaleはインストール済みか？
- [ ] Giteaは稼働しているか？
- [ ] Dokployはまだ未導入か？（導入済みなら設定確認）
- [ ] 開発者の「ずぼら」哲学を理解したか？
- [ ] 批判的思考の重要性を認識したか？

---

**最終更新**: 2026-01-19
**バージョン**: 1.0
**次回レビュー**: 2026-04-19
**作成者**: Claude (Sonnet 4.5) + 開発者 + Antigravity

---

## 🎁 ボーナス: コピペ用サマリー

他AIに素早く状況を伝えたい時は、以下をコピペしてください：

```
【プロジェクト】Ponshu Room Lite（日本酒記録Flutter App）
【現在地】Phase 2.0-B（インフラ構築中）
【構成】Synology NAS (16GB) → Ubuntu VM (4GB) → Dokploy
【データ層】PostgreSQL/Immich/Ollama（DSM直下、12GB）
【制御層】Dokploy/Traefik/Apps（VM内、4GB）
【ネットワーク】Tailscale VPN（ゼロトラスト）
【月額コスト】¥1,100-1,600（VPS不使用）
【レイテンシ】<1ms（同一物理マシン）
【開発者性格】ずぼら、自動化志向、批判的思考を求める
【緊急タスク】VM メモリ 8GB→4GB 削減
【詳細】docs/architecture/AI_HANDOFF_DOCUMENT.md 参照
```

このサマリーを貼れば、他AIは30秒でプロジェクトを理解できます。