add claude
This commit is contained in:
285
docs/AI_CONTEXT.md
Normal file
285
docs/AI_CONTEXT.md
Normal file
@ -0,0 +1,285 @@
|
||||
# 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開発者は、この順序で読むことで迅速にプロジェクトを理解し、作業を開始できます。
|
||||
Reference in New Issue
Block a user