422 lines
16 KiB
Markdown
422 lines
16 KiB
Markdown
# Posimai Project — マスターアーキテクチャドキュメント
|
||
|
||
最終更新: 2026-03-11
|
||
対象: Claude Code / Cursor / Antigravity / Gemini / 全 AI エージェント
|
||
|
||
このドキュメントはプロジェクトの現状・課題・ロードマップを一元管理します。
|
||
実装の前に必ずこのファイルを読んでください。
|
||
|
||
---
|
||
|
||
## 0. Gemini 最新回答への批判的レビュー（2026-03-11）
|
||
|
||
Gemini が「Gemini 3.1 Flash-Lite（2026-03-03リリース）」「Gemini 3.1 Pro（2026-02-19リリース）」
|
||
と具体的な日付を断言しているが、**AI が自身のバージョンに関してハルシネーションを起こす
|
||
典型的なパターン** であり、鵜呑みにしてはならない。
|
||
|
||
| Gemini の主張 | 判定 | 理由 |
|
||
|---|---|---|
|
||
| "Gemini 3.1 Flash-Lite を 2026-03-03 に正式リリース" | 要検証 | Claude の知識カットオフ（2025年8月）以降の情報。公式確認必須 |
|
||
| "DeepSeek V3.2 は推測だったと認める" | 評価する | 自己訂正は誠実 |
|
||
| Docker Compose 設計案を提示 | 方向性は正しい | ただし不完全（後述） |
|
||
| Ollama の導入 | 有効な提案 | RAM 要件の言及が不足 |
|
||
|
||
**AI モデルのバージョン情報は必ず公式で確認すること:**
|
||
- Google AI Studio (aistudio.google.com) でモデル一覧を確認
|
||
- DeepSeek 公式 API ドキュメントで最新版を確認
|
||
|
||
**Gemini の docker-compose.yml の問題点:**
|
||
- nginx（リバースプロキシ）がない → ポートが直接露出する
|
||
- Gitea がない → すでに動いているなら Compose で管理すべき
|
||
- ネットワーク定義がない
|
||
- restart ポリシーがない（NAS 再起動後にコンテナが自動起動しない）
|
||
- Ollama の GPU/メモリ設定がない
|
||
- secrets 管理が平文環境変数のみ（DB パスワード等）
|
||
|
||
---
|
||
|
||
## 1. プロジェクト全体像
|
||
|
||
### 1.1 所有者プロフィール
|
||
- 非エンジニア（コードを読める、書けない）
|
||
- AI エージェントへのプロンプト設計が得意
|
||
- クラウド依存なし・Synology ファーストが絶対条件
|
||
- コスト最小化・利用回数の上限を気にしたくない
|
||
|
||
### 1.2 現在のアプリ一覧（全 9 本）
|
||
|
||
| アプリ | ディレクトリ | 種別 | Synology 依存 | 状態 |
|
||
|--------|-------------|------|--------------|------|
|
||
| posimai-brain | `posimai-brain/` | SPA (Vanilla JS) | Yes（記事 API） | 稼働中 |
|
||
| posimai-feed | `posimai-feed/` | SPA (Vanilla JS) | Yes（フィード API） | 稼働中 |
|
||
| posimai-events | `posimai-events/` | 静的 (Vanilla JS) | 部分的 | 稼働中 |
|
||
| posimai-hotels | `posimai-hotels/` | 静的 (Vanilla JS) | 部分的 | 稼働中 |
|
||
| posimai-maps | `posimai-maps/` | 静的 (Vanilla JS) | 部分的 | 稼働中 |
|
||
| posimai-reader | `posimai-reader/` | 静的 (Vanilla JS) | No | 稼働中 |
|
||
| posimai-together | `posimai-together/` | 静的 (Vanilla JS) | No | 稼働中 |
|
||
| posimai-dashboard | `posimai-dashboard/` | Next.js (App Router) | 不明 | 稼働中 |
|
||
| posimai-analytics | `posimai-analytics/` | Next.js (App Router) | 不明 | 稼働中 |
|
||
|
||
### 1.3 アプリ種別の正確な分類
|
||
|
||
```
|
||
純粋な静的アプリ（Synologyなしでも全機能動作）
|
||
→ reader, together
|
||
→ データはコード内 or 不要
|
||
|
||
データ参照型（Synologyが落ちてもUIは動く・データだけ取れない）
|
||
→ events, hotels, maps
|
||
→ Synology から定期取得、localStorage キャッシュあり
|
||
|
||
SPA + バックエンド依存（Synologyが必須）
|
||
→ brain, feed
|
||
→ Synology FastAPI が主データソース
|
||
|
||
Next.js（サーバーサイド処理あり）
|
||
→ dashboard（Basic Auth あり）, analytics
|
||
→ Vercel Edge で動作、Synology 依存は設計次第
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 現在のインフラ構成（確認済み・2026-03-11）
|
||
|
||
```
|
||
[開発者PC（Windows 11）]
|
||
├ VS Code + Claude Code / Cursor
|
||
├ c:/Users/maita/posimai-project/ (ローカル作業)
|
||
└ git push → Gitea(primary) + GitHub(mirror)
|
||
|
||
[Synology NAS「Mai_SVR」（自宅・常時稼働）]
|
||
├ 物理 RAM: 16 GB（現在 4.11 GB 使用中）
|
||
├ DSM: 7.3.2-86009 Update 1
|
||
├ Virtual Machine Manager
|
||
│ └ Posimai_lab（VM）: CPU 2コア、RAM 4GB、ディスク 100GB
|
||
│ ※ VM 内の詳細は未確認（OS 不明）
|
||
└ Container Manager（Docker Compose）
|
||
└── プロジェクト: posimai_lab（/volume1/docker/posimai_lab）
|
||
├── gitea (gitea/gitea:1.21) ← 稼働中 ✓
|
||
├── gitea_db (postgres:15) ← 稼働中 ✓ ※Gitea + API 共用
|
||
├── mcp_server (node:20-slim) ← 稼働中 ✓ AI エージェント連携
|
||
├── posimai_api (node:20-slim) ← 稼働中 ✓ 記事API・Geminiプロキシ
|
||
└── ai_proxy (python:3.11-slim) ← 停止中 → 削除可
|
||
|
||
外部アクセス: Tailscale（posimai-lab.tail72e846.ts.net）
|
||
内部ポート: Gitea:3000, API:8090
|
||
|
||
[GitHub（クラウド）]
|
||
└ private mirror（Vercel webhook用）
|
||
|
||
[Vercel（クラウド）]
|
||
└ 全9アプリをホスト（静的ファイル配信 / Next.js SSR）
|
||
```
|
||
|
||
### 2.1 posimai_api の詳細（確認済み）
|
||
|
||
- **言語**: Node.js（Python/FastAPI ではなかった）
|
||
- **役割**: 記事保存・要約・Gemini API プロキシ
|
||
- **DB**: PostgreSQL（gitea_db と同一インスタンス、同一ユーザー共用）
|
||
- **認証**: API キー方式（pk_maita_ / pk_partner_ / pk_musume_）
|
||
- **CORS 許可**: posimai-brain, posimai-reader, posimai-feed
|
||
- **アクセス方法**: Tailscale 経由 HTTPS または 内部 HTTP:8090
|
||
|
||
### 2.2 現状の問題点（優先度順）
|
||
|
||
**問題1: シークレット管理 — 高優先**
|
||
- docker-compose.yml に DB パスワード・API キーが平文記載
|
||
- git commit するとパスワードが Gitea/GitHub に残る
|
||
- 対策: `.env` ファイルに分離、docker-compose.yml から変数参照に変更
|
||
|
||
**問題2: DB ユーザーの共用 — 中優先**
|
||
- Gitea と posimai_api が同一 postgres ユーザー（gitea）を使用
|
||
- 対策: posimai_api 専用ユーザー/DB を作成する
|
||
|
||
**問題3: posimai_api が HTTP のみ — 中優先**
|
||
- nginx がないため HTTPS 化されていない（Tailscale 経由なら許容範囲）
|
||
- 対策: nginx コンテナ追加（必要と判断したとき）
|
||
|
||
**問題4: アクセントカラーの不統一 — 低優先**
|
||
- Brain/Feed/Reader: `#818CF8`（Indigo）
|
||
- その他・テンプレート: `#6EE7B7`（Teal）
|
||
- 対策: 新規アプリは Teal 固定。既存は次回大改修時に統一。
|
||
|
||
---
|
||
|
||
## 3. デプロイパイプライン（確立済み）
|
||
|
||
```
|
||
コード変更
|
||
↓
|
||
git add . && git commit -m "feat: ..."
|
||
↓
|
||
npm run deploy
|
||
= git push gitea main && git push github main
|
||
↓ ↓
|
||
Gitea（自宅Synology） GitHub（private mirror）
|
||
（プライマリ・ソースof真実） ↓
|
||
Vercel webhook
|
||
↓
|
||
https://[app-id].vercel.app
|
||
```
|
||
|
||
**絶対に守るルール:**
|
||
- `vercel --prod` 直接実行 → 禁止（GitHub push で自動デプロイ）
|
||
- `git push origin` → 禁止（gitea と github の2リモートを使う）
|
||
- デプロイは `npm run deploy` のみ
|
||
|
||
---
|
||
|
||
## 4. 新アプリ作成の自動化（確立済み）
|
||
|
||
```bash
|
||
bash scripts/new-app.sh <app-id> "<表示名>" "<説明>"
|
||
```
|
||
|
||
1. `_template/` をコピー（プレースホルダー置換）
|
||
2. Git 初期化 + 初回コミット
|
||
3. Gitea API でリポジトリ作成 → push
|
||
4. GitHub CLI でリポジトリ作成 → push
|
||
5. Vercel で GitHub 連携
|
||
6. git post-commit フック設置
|
||
|
||
---
|
||
|
||
## 5. テンプレート仕様（`_template/`）
|
||
|
||
### 5.1 デザインシステム（変更禁止トークン）
|
||
|
||
```css
|
||
--bg: #0D0D0D /* ページ背景 */
|
||
--surface: #1A1A1A /* カード */
|
||
--surface2: #252525 /* ネスト要素 */
|
||
--border: #2D2D2D /* ボーダー */
|
||
--text: #F3F4F6 /* 主テキスト */
|
||
--text2: #9CA3AF /* 副テキスト */
|
||
--text3: #6B7280 /* 弱テキスト */
|
||
--accent: #6EE7B7 /* Posimai Teal（アプリごとに1行変更可） */
|
||
--radius: 12px
|
||
```
|
||
|
||
- フォント: Inter (300/400/500/600)
|
||
- アイコン: Lucide のみ（stroke 1.5〜2.0）
|
||
- 絵文字: **絶対禁止**
|
||
- カラフルな配色: **禁止**
|
||
- バッジ: emerald（完了）/ amber（進行中）/ zinc（予定）の3色のみ
|
||
|
||
### 5.2 テンプレートの現在の機能（Phase 1 実装済み）
|
||
|
||
```
|
||
_template/index.html に含まれるもの:
|
||
├ header（52px glassmorphism）
|
||
│ ├ PC展開時: ページタイトルのみ（アプリ名はサイドバーに）
|
||
│ └ モバイル/折りたたみ時: アプリ名 + ハンバーガー
|
||
├ sidebar
|
||
│ ├ accordion ナビセクション（折りたたみ対応）
|
||
│ ├ nav-count バッジ（数値表示）
|
||
│ └ フッター（アバター + ユーザー名 + 設定歯車）
|
||
├ settings-panel（右スライドアウト）
|
||
│ ├ トグルスイッチ
|
||
│ ├ API キー入力
|
||
│ └ データ削除ボタン
|
||
├ main content
|
||
│ ├ card / list-item / empty-state
|
||
│ ├ btn-primary / btn-ghost / btn-danger
|
||
│ └ badge-stable / badge-progress / badge-planned
|
||
└ toast 通知
|
||
```
|
||
|
||
### 5.3 テンプレート Phase 2 候補（優先度付き）
|
||
|
||
| 優先度 | 機能 | 判断根拠 |
|
||
|--------|------|---------|
|
||
| 中 | SWR API クライアント（オプションファイル） | API ありアプリ専用。デフォルト OFF |
|
||
| 中 | Pull to Refresh（モバイル） | PWA の基本 UX |
|
||
| 低 | コマンドパレット（Cmd+K） | パワーユーザー向け |
|
||
| 低 | BroadcastChannel（タブ同期） | 必要なアプリで個別実装 |
|
||
| 低 | PWA Share Target | manifest.json のコメントサンプルとして |
|
||
|
||
---
|
||
|
||
## 6. AI エージェント役割分担
|
||
|
||
| エージェント | 主な用途 | 得意なこと |
|
||
|---|---|---|
|
||
| **Claude Code** | 設計・実装・アーキテクチャ判断 | CLAUDE.md / LEARNINGS.md の遵守 |
|
||
| **Cursor** | 日常的な小改修・インライン編集 | IDE 内での素早い修正 |
|
||
| **Antigravity** | 自律エージェント実験 | 複数ファイル横断変更 |
|
||
| **Gemini** | レビュー・大コンテキスト分析 | プロジェクト全体の俯瞰 |
|
||
|
||
**注意**: Gemini はモデルバージョン・リリース日・具体的な数値を
|
||
ハルシネーションする傾向がある。重要な技術情報は公式で確認すること。
|
||
|
||
---
|
||
|
||
## 7. AI モデル戦略（コストゼロ・上限なし優先）
|
||
|
||
### 7.1 基本方針
|
||
|
||
「最新モデルを追いかけず、無料枠を確実に使い切る」
|
||
|
||
### 7.2 推奨スタック（2026年3月時点での合理的な選択）
|
||
|
||
| 役割 | モデル | 費用 | 上限 |
|
||
|------|--------|------|------|
|
||
| メイン（解析・生成） | Gemini Flash 最新版 | 無料枠 | 1分あたり RPM あり |
|
||
| コード論理検証 | DeepSeek V3 最新版 | 有料（格安） | 実質無制限 |
|
||
| 完全ローカル（上限なし） | Ollama on Synology | 0円 | なし（RAM 依存） |
|
||
|
||
**重要**: モデル名・料金は Google AI Studio および DeepSeek 公式で必ず確認すること。
|
||
本ドキュメントに特定バージョンを記載しない理由は、AI によるハルシネーションを防ぐため。
|
||
|
||
### 7.3 Ollama on Synology の実現可能性
|
||
|
||
| Synology モデル | RAM | 動作可能なモデル |
|
||
|----------------|-----|----------------|
|
||
| 4GB | Llama 3.2 3B（要確認） | 簡単な要約・コード補完 |
|
||
| 8GB+ | Llama 3.1 8B, Gemma 3 9B | 記事分析・コード生成 |
|
||
| 16GB+ | Mistral Nemo 12B 等 | ほぼ全用途をカバー |
|
||
|
||
→ Synology の RAM 容量を確認してから検討
|
||
|
||
---
|
||
|
||
## 8. Synology Docker 目標アーキテクチャ
|
||
|
||
### 8.1 現状（確認済み）
|
||
```
|
||
Container Manager / posimai_lab プロジェクト（稼働中）
|
||
├ gitea ✓ Docker 化済み
|
||
├ gitea_db ✓ PostgreSQL 稼働中（Gitea + API 共用）
|
||
├ mcp_server ✓ MCP サーバー稼働中
|
||
├ posimai_api ✓ Node.js API 稼働中（記事・Gemini プロキシ）
|
||
└ ai_proxy × 停止中 → 削除可
|
||
|
||
主な改善余地: シークレット管理 / nginx / DB 分離
|
||
```
|
||
|
||
### 8.2 目標構成（Container Manager / docker-compose）
|
||
|
||
```yaml
|
||
# posimai-synology/docker-compose.yml（設計案）
|
||
|
||
services:
|
||
|
||
nginx:
|
||
image: nginx:alpine
|
||
ports:
|
||
- "80:80"
|
||
- "443:443"
|
||
volumes:
|
||
- ./nginx/conf.d:/etc/nginx/conf.d:ro
|
||
- ./nginx/certs:/etc/nginx/certs:ro
|
||
restart: unless-stopped
|
||
depends_on:
|
||
- posimai-api
|
||
|
||
posimai-api:
|
||
build: ./api
|
||
environment:
|
||
- DATABASE_URL=postgresql://posimai:${DB_PASS}@postgres:5432/posimai
|
||
- GEMINI_API_KEY=${GEMINI_API_KEY}
|
||
restart: unless-stopped
|
||
depends_on:
|
||
postgres:
|
||
condition: service_healthy
|
||
|
||
postgres:
|
||
image: postgres:16-alpine
|
||
environment:
|
||
- POSTGRES_USER=posimai
|
||
- POSTGRES_PASSWORD=${DB_PASS}
|
||
- POSTGRES_DB=posimai
|
||
volumes:
|
||
- postgres_data:/var/lib/postgresql/data
|
||
healthcheck:
|
||
test: ["CMD-SHELL", "pg_isready -U posimai"]
|
||
interval: 10s
|
||
timeout: 5s
|
||
retries: 5
|
||
restart: unless-stopped
|
||
|
||
# Gitea（既にDockerなら統合、直インストールなら後回し）
|
||
# gitea:
|
||
# image: gitea/gitea:latest
|
||
# ...
|
||
|
||
# オプション: ローカル LLM（RAM 8GB以上推奨）
|
||
# ollama:
|
||
# image: ollama/ollama
|
||
# volumes:
|
||
# - ollama_data:/root/.ollama
|
||
# restart: unless-stopped
|
||
|
||
volumes:
|
||
postgres_data:
|
||
# ollama_data:
|
||
```
|
||
|
||
**env ファイル（`.env`、gitignore 必須）:**
|
||
```
|
||
DB_PASS=xxxxxxxxxx
|
||
GEMINI_API_KEY=xxxxxxxxxx
|
||
```
|
||
|
||
### 8.3 nginx ルーティング設計（案）
|
||
|
||
```nginx
|
||
# /api → posimai-api:8000
|
||
# /git → gitea:3000（任意）
|
||
# Tailscale IP または特定ポートでのみ公開
|
||
```
|
||
|
||
### 8.4 実装ステップ（優先度順）
|
||
|
||
| 優先度 | タスク | 前提条件 |
|
||
|--------|--------|---------|
|
||
| 1 (高) | ai_proxy コンテナ削除 | すぐ実施可 |
|
||
| 2 (高) | docker-compose.yml の `.env` 分離 | シークレット管理改善 |
|
||
| 3 (中) | nginx 追加（HTTPS / リバースプロキシ） | Tailscale 運用継続なら低優先でも可 |
|
||
| 4 (中) | posimai_api 専用 DB ユーザー作成 | Gitea との DB ユーザー分離 |
|
||
| 5 (低) | Ollama 追加 | VM RAM を 8GB に増やしてから |
|
||
|
||
---
|
||
|
||
## 9. 未解決事項（要確認）
|
||
|
||
| 確認項目 | 判明状況 |
|
||
|---------|---------|
|
||
| Synology の RAM 容量 | ✓ 物理 16GB（VM に 4GB 割当）|
|
||
| FastAPI / Python | ✓ 不使用。Node.js (posimai_api) が担当 |
|
||
| データの保存形式 | ✓ PostgreSQL（gitea_db コンテナ）|
|
||
| Synology への外部アクセス | ✓ Tailscale（posimai-lab.tail72e846.ts.net）|
|
||
| Gitea は Docker か | ✓ Docker 化済み |
|
||
| VM（Posimai_lab）の OS・用途 | 未確認（SSH / VNC で確認要）|
|
||
| mcp_server の具体的な動作 | 未確認（どの AI エージェントが使っているか）|
|
||
|
||
---
|
||
|
||
## 10. 絶対に守るルール（全 AI 共通）
|
||
|
||
1. **デプロイは `npm run deploy` のみ**（`vercel --prod` 禁止）
|
||
2. **絵文字禁止**（コード・UI・コメントすべて）
|
||
3. **アイコンは Lucide のみ**
|
||
4. **デザイントークン変更禁止**（--accent 1行のみ例外）
|
||
5. **`git push origin` 禁止**（gitea と github の2リモートのみ）
|
||
6. **AI のバージョン断言は鵜呑みにしない**（公式確認必須）
|
||
7. **Synology への直接インストール禁止**（今後は全て Docker 経由）
|
||
|
||
---
|
||
|
||
## 参照ファイル一覧
|
||
|
||
| ファイル | 内容 |
|
||
|---------|------|
|
||
| `CLAUDE.md` | AI 向けプロジェクトルール（最優先） |
|
||
| `AGENTS.md` | CLAUDE.md の Cursor/Windsurf 向けコピー |
|
||
| `LEARNINGS.md` | 過去のトラブル・解決策・設計判断ログ |
|
||
| `docs/master-architecture.md` | **このファイル** |
|
||
| `docs/template-features-analysis.md` | テンプレート機能優先度分析 |
|
||
| `docs/gemini-review-prompt.md` | Gemini へのレビュー依頼プロンプト |
|
||
| `_template/index.html` | PWA テンプレート（Phase 1 実装済み） |
|
||
| `scripts/new-app.sh` | 新アプリ作成自動化スクリプト |
|