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種類）

{
  "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. 基本起動

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）

# 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エンドポイント追加

# 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. データベーステーブル追加

# 1. db/models.pyに新しいモデル
class NewModel(Base):
    __tablename__ = "new_table"
    # フィールド定義

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

3. atproto新機能追加

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

🎨 UI/UXパターン

カードエフェクト実装

// Web（React + Framer Motion）
<motion.div
  className={`card ${getRarityClass()}`}
  animate={isRevealing ? { rotateY: 0 } : {}}
  transition={{ duration: 0.8 }}
>

// 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の起動状態確認

ログ確認

# 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開発者は、この順序で読むことで迅速にプロジェクトを理解し、作業を開始できます。