168 lines
5.0 KiB
Markdown
168 lines
5.0 KiB
Markdown
# ai.card 開発ガイド (Claude Code用)
|
||
|
||
## プロジェクト概要
|
||
**ai.card** - atproto基盤のカードゲームシステム。iOS/Web/APIで構成され、ユーザーデータ主権を実現。
|
||
|
||
## 現在の状態 (2025/01/06)
|
||
- ✅ MCP Server実装完了
|
||
- ✅ SQLiteデータベース稼働中
|
||
- ✅ 基本的なガチャ・カード管理機能
|
||
- 🔧 atproto連携は一時無効化
|
||
- 📱 iOS/Web実装待ち
|
||
|
||
## 開発環境セットアップ
|
||
|
||
### 必要なもの
|
||
- Python 3.13
|
||
- Node.js (Web開発用)
|
||
- Docker (PostgreSQL用、オプション)
|
||
- Xcode (iOS開発用)
|
||
|
||
### 初回セットアップ
|
||
```bash
|
||
# 1. プロジェクトディレクトリ
|
||
cd /Users/syui/ai/gpt/card
|
||
|
||
# 2. 仮想環境構築
|
||
./setup_venv.sh
|
||
|
||
# 3. データベース初期化
|
||
cd api
|
||
~/.config/syui/ai/card/venv/bin/python init_db.py
|
||
|
||
# 4. サーバー起動
|
||
cd ..
|
||
./start_server.sh
|
||
```
|
||
|
||
## 開発時の作業分担提案
|
||
|
||
### ai.gptプロジェクトで起動 (MCP/バックエンド作業)
|
||
**適している作業:**
|
||
- MCPサーバー機能の追加・修正
|
||
- データベーススキーマ変更
|
||
- API エンドポイント追加
|
||
- バックエンドロジック実装
|
||
|
||
**起動方法:**
|
||
```bash
|
||
cd /Users/syui/ai/gpt
|
||
# Claude Codeをここで起動
|
||
# ai.card/api/ を編集対象にする
|
||
```
|
||
|
||
### ai.cardプロジェクトで起動 (フロントエンド作業)
|
||
**適している作業:**
|
||
- iOS アプリ開発 (Swift/SwiftUI)
|
||
- Web フロントエンド開発 (React/TypeScript)
|
||
- UI/UX デザイン実装
|
||
- クライアント側ロジック
|
||
|
||
**起動方法:**
|
||
```bash
|
||
cd /Users/syui/ai/gpt/card
|
||
# Claude Codeをここで起動
|
||
# ios/ または web/ を編集対象にする
|
||
```
|
||
|
||
## ディレクトリ構造
|
||
```
|
||
ai.card/
|
||
├── api/ # バックエンド (Python/FastAPI)
|
||
│ ├── app/
|
||
│ │ ├── main.py # エントリポイント
|
||
│ │ ├── mcp_server.py # MCPサーバー実装
|
||
│ │ ├── models/ # データモデル
|
||
│ │ ├── routes/ # APIルート
|
||
│ │ └── services/ # ビジネスロジック
|
||
│ └── requirements.txt
|
||
├── ios/ # iOSアプリ (Swift)
|
||
│ └── AiCard/
|
||
├── web/ # Webフロントエンド (React)
|
||
│ └── src/
|
||
├── docs/ # ドキュメント
|
||
├── setup_venv.sh # 環境構築スクリプト
|
||
└── start_server.sh # サーバー起動スクリプト
|
||
```
|
||
|
||
## 主要な技術スタック
|
||
|
||
### バックエンド
|
||
- **言語**: Python 3.13
|
||
- **フレームワーク**: FastAPI + fastapi-mcp
|
||
- **データベース**: SQLite (開発) / PostgreSQL (本番予定)
|
||
- **ORM**: SQLAlchemy 2.0
|
||
|
||
### フロントエンド
|
||
- **iOS**: Swift 5.9 + SwiftUI
|
||
- **Web**: React + TypeScript + Vite
|
||
- **スタイリング**: CSS Modules
|
||
|
||
## 現在の課題と制約
|
||
|
||
### 依存関係の問題
|
||
1. **atproto**: `SessionString` APIが変更されたため一部機能無効化
|
||
2. **supabase**: httpxバージョン競合で無効化
|
||
3. **PostgreSQL**: ネイティブ拡張のコンパイル問題でSQLite使用中
|
||
|
||
### 回避策
|
||
- atproto機能はモック実装で代替
|
||
- データベースはSQLiteで開発継続
|
||
- 本番環境ではDockerでPostgreSQL使用予定
|
||
|
||
## API仕様
|
||
|
||
### MCP Tools (9個)
|
||
1. **get_user_cards(did: str)** - ユーザーのカード一覧取得
|
||
2. **draw_card(did: str, is_paid: bool)** - ガチャでカード取得
|
||
3. **get_card_details(card_id: int)** - カード詳細情報
|
||
4. **analyze_card_collection(did: str)** - コレクション分析
|
||
5. **get_unique_registry()** - ユニークカード登録状況
|
||
6. **sync_cards_atproto(did: str)** - atproto同期（無効化中）
|
||
7. **get_gacha_stats()** - ガチャ統計情報
|
||
|
||
### REST API
|
||
- `/api/v1/cards/*` - カード管理
|
||
- `/api/v1/auth/*` - 認証（モック実装）
|
||
- `/api/v1/sync/*` - 同期機能
|
||
|
||
## 今後の開発予定
|
||
|
||
### Phase 1: 基盤強化
|
||
- [ ] PostgreSQL移行（Docker利用）
|
||
- [ ] atproto最新版対応
|
||
- [ ] テストコード追加
|
||
|
||
### Phase 2: クライアント実装
|
||
- [ ] iOS アプリ基本機能
|
||
- [ ] Web フロントエンド
|
||
- [ ] リアルタイムガチャ演出
|
||
|
||
### Phase 3: 本格運用
|
||
- [ ] Cloudflare デプロイ
|
||
- [ ] ユーザーデータ主権実装
|
||
- [ ] ai.verse連携
|
||
|
||
## 注意事項
|
||
- サーバーは`--reload`モードで起動中（ファイル変更で自動再起動）
|
||
- データベースは `~/.config/syui/ai/card/aicard.db`
|
||
- 仮想環境は `~/.config/syui/ai/card/venv/`
|
||
- エラーログはターミナルに出力される
|
||
|
||
## デバッグ用コマンド
|
||
```bash
|
||
# データベース確認
|
||
sqlite3 ~/.config/syui/ai/card/aicard.db ".tables"
|
||
|
||
# API動作確認
|
||
curl http://localhost:8000/health
|
||
curl "http://localhost:8000/get_gacha_stats"
|
||
|
||
# ログ確認
|
||
tail -f /var/log/aicard.log # 未実装
|
||
```
|
||
|
||
## 参考リンク
|
||
- [AI エコシステム統合設計書](/Users/syui/ai/gpt/CLAUDE.md)
|
||
- [MCP統合作業報告](./docs/MCP_INTEGRATION_SUMMARY.md)
|
||
- [API仕様書](http://localhost:8000/docs) ※サーバー起動時のみ |