# 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) ※サーバー起動時のみ