card/docs/AI_CONTEXT.md

# AI Context Document - ai.card プロジェクト

> **重要**: このドキュメントは、将来のAI開発者（Claude Code等）が迅速にプロジェクトを理解し、作業を継続できるよう設計されています。

## 🎯 プロジェクト概要

**ai.card** は、atprotoベースの分散型カードゲームです。ユーザーがデータを所有し、世界で一人だけが持てるuniqueカードが存在する革新的なシステムです。

### 中核思想
- **存在子理論**: 世界の最小単位（ai）の探求がテーマ
- **yui system**: 現実の個人とゲーム要素の1:1紐付け
- **データ主権**: atproto PDSでユーザーがカードデータを所有
- **現実の反映**: ゲームがプレイヤーの現実と連動

## 🏗️ システム構成

```
[iOS App] ←→ [Web App] ←→ [FastAPI API] ←→ [PostgreSQL]
                                ↕
                         [atproto PDS]
                                ↕
                         [ai.verse(将来)]
```

### 技術スタック（2025年6月1日現在）
- **Backend**: Python 3.11 + FastAPI + PostgreSQL + Docker
- **Frontend**: React 18 + TypeScript + Vite + Framer Motion
- **Mobile**: SwiftUI + Combine + iOS 16.0+
- **Identity**: atproto DID + JWT
- **Infrastructure**: Docker Compose + Cloudflare Tunnel + Supabase

## 💎 uniqueカードシステム（最重要概念）

### 概念
```
通常のガチャ → キラカード(0.1%) → uniqueカード(0.0001%)
                     ↑表              ↑隠し機能
                 ユーザーの目標      偶然の幸運
```

### 実装
- **確率**: 0.0001%（10万分の1）
- **唯一性**: カードID 0-15の各種類につき、世界で1人のみ所有可能
- **検証**: `unique_card_registry`テーブル + atproto PDS両方でチェック
- **エフェクト**: 虹色オーラ + パーティクル + 特別UI

### データフロー
```
ガチャ実行 → レアリティ判定 → unique可能性チェック → 
atomic操作で確保 → DB保存 → atproto PDS同期 → アニメーション表示
```

## 🔐 atproto統合

### 認証フロー
```
ユーザー: ハンドル + アプリパスワード
    ↓
atproto PDS認証
    ↓
JWT発行 → セッション管理
    ↓
API呼び出し認証
```

### データ同期
```
カード取得 → DB保存 → atproto collection record作成
    ↓
レキシコン: ai.card.collection
    ↓
ユーザーPDSにデータ保存（ユーザーがデータ所有）
```

## 📁 重要なファイル構造

### Backend（最重要）
```
api/app/
├── models/card.py              # カードデータ定義
├── services/gacha.py           # ガチャロジック（uniqueカード生成）
├── services/atproto.py         # atproto統合
├── services/card_sync.py       # PDS同期
├── repositories/card.py        # カードデータアクセス
├── routes/auth.py              # 認証API
├── routes/cards.py             # カードAPI
└── db/models.py                # データベースモデル
```

### Frontend
```
web/src/
├── components/Card.tsx         # カード表示（エフェクト付き）
├── components/GachaAnimation.tsx # ガチャ演出
├── services/auth.ts            # 認証管理
└── services/api.ts             # API通信

ios/AiCard/AiCard/
├── Views/GachaView.swift       # ガチャ画面
├── Views/CardView.swift        # カード表示
├── Services/APIClient.swift    # API通信
└── Services/AuthManager.swift  # 認証管理
```

## 🎮 ゲーム仕様

### カードマスター（16種類）
```json
{
  "0": {"name": "アイ", "color": "fff700", "description": "世界の最小単位"},
  "1": {"name": "夢幻", "color": "b19cd9", "description": "意識が物質を作る"},
  ...
  "15": {"name": "世界", "color": "54a0ff", "description": "存在と世界は同じもの"}
}
```

### レアリティ確率
```
Normal: 99.789%      → グレー系
Rare: 0.1%           → ブルー系
Super Rare: 0.01%    → パープル系
Kira: 0.1%           → ゴールド系（スパークル）
Unique: 0.0001%      → マゼンタ系（オーラ）
```

## 🚀 開発環境セットアップ

### 1. 基本起動
```bash
git clone [repository]
cd ai.card

# Docker環境起動
docker-compose up -d

# データベース初期化
docker-compose exec api python init_db.py

# Web開発サーバー
cd web && npm install && npm run dev

# iOS（Xcodeで開く）
open ios/AiCard/AiCard.xcodeproj
```

### 2. 環境変数設定（.env）
```bash
# PostgreSQL
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/aicard

# atproto（テスト用）
ATPROTO_HANDLE=test.bsky.social
ATPROTO_PASSWORD=your-app-password

# JWT
SECRET_KEY=your-secret-key
```

### 3. atprotoアカウント準備
1. Blueskyアカウント作成
2. アプリパスワード生成（https://bsky.app/settings/app-passwords）
3. 環境変数に設定

## 🔧 よくある実装パターン

### 1. 新しいAPIエンドポイント追加
```python
# 1. routes/に新しいルート定義
@router.post("/new-endpoint")
async def new_endpoint(db: AsyncSession = Depends(get_db)):
    # ロジック

# 2. main.pyにルーター追加
app.include_router(new_router, prefix=settings.api_v1_prefix)
```

### 2. データベーステーブル追加
```python
# 1. db/models.pyに新しいモデル
class NewModel(Base):
    __tablename__ = "new_table"
    # フィールド定義

# 2. Alembicマイグレーション
alembic revision --autogenerate -m "add new table"
alembic upgrade head
```

### 3. atproto新機能追加
```python
# services/atproto.pyに新しいメソッド
async def new_atproto_feature(self, did: str, data: dict):
    # atproto SDK使用
    return self.client.some_new_api(data)
```

## 🎨 UI/UXパターン

### カードエフェクト実装
```typescript
// Web（React + Framer Motion）
<motion.div
  className={`card ${getRarityClass()}`}
  animate={isRevealing ? { rotateY: 0 } : {}}
  transition={{ duration: 0.8 }}
>
```

```swift
// iOS（SwiftUI）
CardView(card: card)
    .rotation3DEffect(.degrees(isRevealing ? 0 : 180), axis: (0, 1, 0))
    .animation(.easeInOut(duration: 0.8), value: isRevealing)
```

## ⚠️ 重要な注意点

### 1. uniqueカードの整合性
- **必須**: atomic操作でのunique確保
- **必須**: DB + atproto PDS両方での検証
- **注意**: レース条件の回避

### 2. atproto連携
- **メインパスワード禁止**: 必ずアプリパスワード使用
- **セッション管理**: JWTトークンの適切な管理
- **エラーハンドリング**: atproto PDS接続失敗時の処理

### 3. 確率システム
- **透明性**: 確率は隠さず設定ファイルで管理
- **公平性**: サーバーサイドでの確率計算必須
- **監査**: ガチャ履歴の完全記録

## 🔮 将来の拡張ポイント

### Phase 1: 運用安定化
- 統合テスト自動化
- モニタリング・アラート
- パフォーマンス最適化

### Phase 2: 機能拡張
- カード交換システム
- プッシュ通知
- リアルタイム同期

### Phase 3: エコシステム統合
- ai.gpt連携（AI人格とカード連動）
- ai.verse連携（3Dゲーム世界でunique skill）
- 分散SNS連携

## 📋 デバッグ・トラブルシューティング

### よくある問題
1. **ガチャでカードが生成されない**
   → `services/gacha.py`のエラーログ確認

2. **atproto認証失敗**
   → アプリパスワードとハンドルの確認

3. **uniqueカード重複**
   → `unique_card_registry`テーブルの整合性チェック

4. **データベース接続失敗**
   → Docker Composeの起動状態確認

### ログ確認
```bash
# API ログ
docker-compose logs -f api

# データベース状態
docker-compose exec postgres psql -U postgres -d aicard -c "SELECT * FROM unique_card_registry;"
```

---

## 📚 推奨読み込み順序（AI向け）

1. **このドキュメント全体** - プロジェクト概要把握
2. **CLAUDE.md** - 哲学・思想の理解
3. **IMPLEMENTATION_SUMMARY.md** - 具体的実装詳細
4. **API.md** - APIエンドポイント仕様
5. **DATABASE.md** - データベース設計
6. **ATPROTO.md** - atproto連携詳細

新しいAI開発者は、この順序で読むことで迅速にプロジェクトを理解し、作業を開始できます。