card/claude.md

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開発用)

初回セットアップ

# 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 エンドポイント追加
• バックエンドロジック実装

起動方法:

cd /Users/syui/ai/gpt
# Claude Codeをここで起動
# ai.card/api/ を編集対象にする

ai.cardプロジェクトで起動 (フロントエンド作業)

適している作業:

• iOS アプリ開発 (Swift/SwiftUI)
• Web フロントエンド開発 (React/TypeScript)
• UI/UX デザイン実装
• クライアント側ロジック

起動方法:

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/
• エラーログはターミナルに出力される

デバッグ用コマンド

# データベース確認
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 エコシステム統合設計書
• MCP統合作業報告
• API仕様書 ※サーバー起動時のみ