card/README.md

# ai.card

🎴 atproto基盤カードゲームシステム × 🧠 ai.gpt AI統合

## 概要

ai.cardは、ユーザーがデータを所有する分散型カードゲームです。
- 🤖 **AI統合**: ai.gpt MCPサーバー経由でAI機能拡張
- 🔗 **atproto連携**: 分散SNSとのデータ同期
- 📱 **クロスプラットフォーム**: iOS/Web統合クライアント
- 🎯 **yui-system**: 個人の唯一性を保証するユニークカード実装

## アーキテクチャ

### 基本構成（ai.card独立動作）
```
iOS/Web Client
    ↓ HTTP API
ai.card API Server (port 8000) 🎴 基本カードゲーム
    ↓
SQLite/PostgreSQL + atproto PDS
```

### AI拡張構成（オプション）
```
iOS/Web Client
    ↓ HTTP API (基本機能)
ai.card API Server (port 8000) 🎴 カードゲーム
    ↓
SQLite/PostgreSQL + atproto PDS

iOS/Web Client (AI機能のみ)
    ↓ HTTP API (AI拡張)
ai.gpt MCP Server (port 8001) 🧠 AI分析・統計
    ↓ HTTP Client
ai.card MCP Server (port 8000)
```

**設計思想**: ai.cardは完全に独立して動作し、ai.gptは必要に応じてai.cardと連携するオプション機能

## 技術スタック

### バックエンド
- **ai.card API**: Python/FastAPI（独立動作）
- **MCP統合**: オプションでai.gpt連携
- **データベース**: SQLite (開発) / PostgreSQL (本番)
- **認証**: atproto OAuth 2.1 + レガシーアプリパスワード

### フロントエンド
- **Web**: React + TypeScript + Vite
- **iOS**: Swift/SwiftUI + Combine
- **基本機能**: ガチャ・コレクション・統計（ai.card単体）
- **AI拡張**: コレクション分析・AI統計（ai.gpt連携時のみ）

## プロジェクト構造

```
ai.card/
├── api/                    # FastAPI + MCP Server
│   ├── app/
│   │   ├── main.py        # エントリポイント
│   │   ├── mcp_server.py  # MCP統合サーバー
│   │   ├── models/        # データモデル
│   │   ├── routes/        # REST API
│   │   └── services/      # ビジネスロジック
│   └── requirements.txt
├── web/                   # React Web Client
│   ├── src/
│   │   ├── components/    # UI コンポーネント
│   │   ├── services/      # API クライアント (ai.gpt経由)
│   │   └── styles/        # CSS スタイル
│   └── package.json
├── ios/                   # iOS SwiftUI App
│   └── AiCard/
│       ├── Models/        # データモデル + AI統合
│       ├── Services/      # API クライアント (ai.gpt経由)
│       └── Views/         # SwiftUI ビュー
├── docs/                  # ドキュメント
└── scripts/               # 環境セットアップ
```

## 🧠 AI機能

### コレクション分析
- **AIによる自動分析**: レアリティ分布・コレクション評価
- **個人化推奨**: ユーザーの収集パターンに基づく提案
- **スコアリング**: 総合的なコレクション価値算出

### ガチャ統計
- **リアルタイム統計**: 全体・個人のガチャ成功率
- **トレンド分析**: 時系列での引き運分析
- **活動履歴**: 最近のガチャ結果表示

## セットアップ

### 基本セットアップ（ai.card単体）

#### 1. ai.card サーバー起動
```bash
# 自動セットアップ
./setup_venv.sh

# サーバー起動
./start_server.sh
# → http://localhost:8000 で起動
```

#### 2. Web クライアント起動
```bash
cd web
npm install
npm run dev
# → http://localhost:5173 で起動（基本機能利用可能）
```

#### 3. iOS 開発
```bash
# Xcodeでプロジェクトを開く
open ios/AiCard/AiCard.xcodeproj
# → 基本機能（ガチャ・コレクション・統計）利用可能
```

### AI拡張セットアップ（オプション）

#### 4. ai.gpt サーバー起動（AI機能用）
```bash
# ai.gptプロジェクトで実行
cd ../
aigpt server --port 8001
# → http://localhost:8001 で起動
# → AI分析・統計機能が利用可能に
```

## 🔐 atproto OAuth認証（実装完了）

### OAuth 2.1 + DPoP認証システム

#### 認証フロー
1. **ユーザー認証**: Blueskyハンドル入力 (例: syui.ai)
2. **OAuth認証**: BrowserOAuthClient による認証リダイレクト
3. **セッション管理**: DPoP保護されたトークンでセキュア認証
4. **Handle表示**: DIDからHandleの自動解決

#### 実装詳細
```typescript
// OAuth設定
const oauthClient = await BrowserOAuthClient.load({
  clientId: clientId,
  handleResolver: 'https://bsky.social',
});

// 認証実行（重要: transition:genericスコープが必須）
const authUrl = await this.oauthClient.authorize(handle, {
  scope: 'atproto transition:generic',  // カスタムコレクション用
});

// セッション取得
const result = await oauthClient.init();
const agent = new Agent(result.session);  // 公式推奨方法
```

#### カスタムコレクション対応
- **コレクション**: `ai.card.box` 
- **必要スコープ**: `transition:generic`（カスタムレコードタイプ用）
- **レコード例**: 
```json
{
  "$type": "ai.card.box",
  "cards": [...],
  "total_cards": 25,
  "updated_at": "2025-01-06T..."
}
```

#### 確認方法
```bash
# atproto レコード確認
curl -sL "https://bsky.social/xrpc/com.atproto.repo.listRecords?repo=syui.ai&collection=ai.card.box"
```

### データ主権の実現
- **ユーザーがデータを所有**: atproto networkでレコード管理
- **分散型アーキテクチャ**: 中央集権的サーバーに依存しない
- **相互運用性**: 他のatproto対応アプリとのデータ共有可能

## 使い方

### Web アプリケーション

#### 基本機能（ai.card単体）
1. **ガチャ**: 通常/プレミアムガチャでカード取得
2. **コレクション**: 保有カード一覧・詳細表示
3. **📊 統計**: ガチャ統計・レアリティ分布

#### AI拡張機能（ai.gpt連携時）
4. **🧠 AI分析**: コレクション分析・推奨システム
5. **📊 統計 (AI強化)**: 高度な統計・トレンド分析

### iOS アプリケーション
- Web版と同等の機能をネイティブUIで提供
- SwiftUI + Combine による reactive UI
- ai.card独立動作 + オプションでai.gpt AI機能

## API エンドポイント

### ai.card 直接API（基本機能）
| エンドポイント | 説明 | メソッド |
|---------------|------|---------|
| `/api/v1/cards/draw` | ガチャ実行 | POST |
| `/api/v1/cards/user/{did}` | カード一覧取得 | GET |
| `/api/v1/cards/{id}` | カード詳細 | GET |
| `/api/v1/cards/stats` | ガチャ統計 | GET |
| `/api/v1/cards/unique` | ユニークカード | GET |
| `/api/v1/health` | システム状態 | GET |

### ai.gpt MCP Tools（AI拡張機能）
| エンドポイント | 説明 | パラメータ |
|---------------|------|-----------|
| `/card_analyze_collection` | AI分析 | did |
| `/card_get_gacha_stats` | AI統計 | - |

### 依存関係
- **ai.card**: 完全独立動作（依存なし）
- **ai.gpt**: ai.cardに依存（オプション機能として）

## 開発状況

### ✅ 完成済み
- [x] **MCP Server統合**: ai.card独立サーバー + ai.gpt連携
- [x] **SQLite基盤**: カード・ガチャ・ユーザー管理
- [x] **AI機能**: コレクション分析・ガチャ統計
- [x] **Web UI**: React SPA + AI機能タブ
- [x] **iOS基盤**: SwiftUI + ai.gpt連携APIクライアント
- [x] **OAuth 2.1認証**: atproto OAuth + DPoP認証実装完了
- [x] **atproto データバックアップ**: ai.card.boxコレクションへの保存機能

### 🚧 進行中
- [ ] **atproto データ復元**: ai.card.boxからローカルへの復元機能
- [ ] **ユニークカード**: yui-system実装
- [ ] **リアルタイム機能**: WebSocket対応

### 🎯 今後の予定

#### 次回作業項目（優先度高）
- [ ] **atproto データ復元機能**: ai.card.boxからローカルSQLiteへの復元
- [ ] **CardBox コンポーネント**: atproto レコード表示UI
- [ ] **同期機能**: ローカル ↔ atproto 双方向同期
- [ ] **iOS OAuth対応**: SwiftUIでのatproto認証実装

#### 将来的な拡張
- [ ] **本番デプロイ**: Cloudflare + PostgreSQL
- [ ] **ai.verse統合**: 3Dメタバース連携
- [ ] **分散SNS**: atproto PDS自動投稿
- [ ] **マルチユーザー対応**: 他ユーザーのコレクション閲覧

## トラブルシューティング

### OAuth認証エラー

#### `Missing required scope: transition:generic`
```typescript
// 解決方法: スコープに transition:generic を追加
const authUrl = await this.oauthClient.authorize(handle, {
  scope: 'atproto transition:generic',  // ✅ 正しい
  // scope: 'atproto',  // ❌ 不十分
});
```

#### Handle が "unknown" と表示される
```typescript
// 原因: BrowserOAuthClient の使用方法が間違っている
// 解決方法: sessionオブジェクトを直接Agentに渡す
const agent = new Agent(result.session);  // ✅ 公式推奨
// new Agent({service: '...', fetch: session.dpopFetch});  // ❌ 非推奨
```

#### カスタムコレクションへの書き込みエラー
```bash
# 確認: OAuth スコープが正しく設定されているか
# ブラウザコンソールで確認:
console.log(atprotoOAuthService.getSession());
# → scope: "atproto transition:generic" が含まれているか確認
```

### ai.gpt連携エラー
```bash
# ai.gptサーバーが起動しているか確認
curl http://localhost:8001/health

# ai.cardサーバーが起動しているか確認
curl http://localhost:8000/health
```

### データベースエラー
```bash
# データベース初期化
cd api
~/.config/syui/ai/card/venv/bin/python init_db.py
```

### atproto データ確認
```bash
# バックアップされたレコードを確認
curl -sL "https://bsky.social/xrpc/com.atproto.repo.listRecords?repo={YOUR_HANDLE}&collection=ai.card.box"

# レコード詳細取得
curl -sL "https://bsky.social/xrpc/com.atproto.repo.getRecord?repo={YOUR_HANDLE}&collection=ai.card.box&rkey=self"
```

## 貢献

ai.card は ai.gpt エコシステムの一部として開発されています。
- [ai.gpt 統合設計書](../CLAUDE.md)
- [MCP統合作業報告](./docs/MCP_INTEGRATION_SUMMARY.md)
- [AI統合ガイド](../docs/AI_CARD_INTEGRATION.md)