555 lines
18 KiB
Markdown
555 lines
18 KiB
Markdown
# 🤖 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秒でプロジェクトを理解できます。
|