fix reamde

2025-06-09 01:50:47 +09:00
parent b68c7b5e61
commit 87b528338a
1 changed files with 123 additions and 463 deletions
--- a/README.md
+++ b/README.md
@@ -1,483 +1,143 @@
-# ai.card API Server (Rust Implementation)
+# ai.card プロジェクト固有情報
-**高性能なRust実装によるatproto基盤カードゲームAPIサーバー**
+## プロジェクト概要
 - **名前**: ai.card
 - **パッケージ**: aicard
 - **タイプ**: atproto基盤カードゲーム
 - **役割**: ユーザーデータ主権カードゲームシステム
-## 📋 プロジェクト概要
+## 実装状況
-ai.card API Serverは、分散型SNS「atproto」を基盤とした自律的カード収集システムのRust実装です。ユーザーデータ主権を重視し、高性能・高信頼性を実現します。
+### 現在の状況
 - **ai.bot統合**: ai.botの機能として実装済み
 - **カード取得**: atproto accountでmentionすると1日1回カード取得可能
 - **データ管理**: ai.api (MCP server) でユーザー管理
-### 🎯 主要機能
+### 独立MCPサーバー（ai.gpt連携）
 - **場所**: `/Users/syui/ai/gpt/card/`
 - **サーバー**: FastAPI + fastapi_mcp (port 8000)
 - **統合**: ai.gptサーバーからHTTP連携
- **ガチャシステム**: 確率ベースのカード抽選（レアリティ別配分）
+## アーキテクチャ構成
 - **atproto連携**: 分散ID（DID）認証とデータ同期
 - **データベース**: PostgreSQL/SQLite対応
 - **API**: RESTful + JWT認証
 - **リアルタイム**: WebSocket対応準備済み
-### 🏗️ アーキテクチャ特徴
+### 技術スタック
 - **Backend**: FastAPI + MCP
 - **Frontend**: React Web UI + SwiftUI iOS app
 - **Data**: atproto collection record（ユーザー所有）
 - **Auth**: OAuth 2.1 scope（実装待ち）
- **パフォーマンス**: Rustの安全性と高速性
+### データフロー
- **データ主権**: ユーザーがデータを完全所有
+```
- **分散型**: 中央集権に依存しない設計
+ユーザー → ai.bot mention → カード生成 → atproto collection → ユーザー所有
- **型安全**: コンパイル時エラー検出
+    ↑                                ↓
- **並行処理**: 非同期I/O最適化
+    ← iOS app表示 ← ai.card API ←
 ## 🚀 クイックスタート
 ### 前提条件
 ```bash
 # Rust 1.70+
 curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
 # データベース（どちらか選択）
 # SQLite（開発用・推奨）
 sqlite3 --version
 # PostgreSQL（本番用）
 psql --version
 ```
-### セットアップ
+## 移行計画
-```bash
+### Phase 1: 独立化
-# 1. プロジェクトクローン
+- **iOS移植**: Claude担当予定
-cd /Users/syui/ai/ai/card/api-rs
+- **Web UI**: React実装
 - **API独立**: ai.botからの分離
-# 2. 依存関係インストール
+### Phase 2: データ主権実装
-cargo build
+- **atproto collection**: カードデータをユーザー所有に
 - **OAuth 2.1**: 不正防止機能実装
 - **画像ファイル**: Cloudflare Pages最適化
-# 3. 環境設定
+### Phase 3: ゲーム機能拡張
-cp .env.example .env
+- **ガチャシステム**: 確率・レアリティ管理
-vim .env
+- **トレード機能**: ユーザー間カード交換
 - **デッキ構築**: カードゲーム戦略要素
-# 4. データベース初期化
+## yui system適用
 cargo run -- migrate
-# 5. サーバー起動
+### 唯一性担保
-cargo run
+- **カード効果**: アカウント固有の効果設定
-```
+- **改ざん防止**: ハッシュ・署名による保証
 - **ゲームバランス**: 唯一性による公平性維持
-### 環境変数設定
+### ai.verse連携
 - **ゲーム内アイテム**: ai.verseでのカード利用
 - **固有スキル**: カードとキャラクターの連動
 - **現実反映**: カード取得がゲーム内能力に影響
-```bash
+## ディレクトリ構成
 # .env
 DATABASE_URL=sqlite://~/.config/syui/ai/card/aicard.db
 # DATABASE_URL=postgresql://user:pass@localhost/aicard
 SECRET_KEY=your-secret-key-here
 PORT=8000
 RUST_LOG=info
 CARD_MASTER_URL=https://git.syui.ai/ai/ai/raw/branch/main/ai.json
 ```
 ## 📁 プロジェクト構造
 ```
-src/
+/Users/syui/ai/gpt/card/
-├── main.rs              # エントリーポイント
+├── api/              # FastAPI + MCP server
-├── config.rs            # 設定管理
+├── web/              # React Web UI
-├── error.rs             # エラーハンドリング
+├── ios/              # SwiftUI iOS app
-├── database.rs          # データベース抽象化
+└── docs/            # 開発ドキュメント
 ├── models.rs            # データモデル定義
 ├── auth.rs              # JWT認証システム
 ├── handlers/            # APIハンドラー
 │   ├── mod.rs
 │   ├── auth.rs          # 認証API
 │   ├── cards.rs         # カードAPI
 │   └── sync.rs          # 同期API
 └── services/            # ビジネスロジック
    ├── mod.rs
    ├── gacha.rs         # ガチャシステム
    ├── user.rs          # ユーザー管理
    ├── card_master.rs   # カードマスター
    └── atproto.rs       # atproto連携
 migrations/              # データベースマイグレーション
 ├── postgres/
 └── sqlite/
 Cargo.toml              # 依存関係定義
 ```
-## 🗄️ データベース設計
+## MCPツール（ai.gpt連携）
-
+
-### 主要テーブル
+### カード管理
-
+- **card_get_user_cards**: ユーザーカード取得
-```sql
+- **card_draw_card**: ガチャ実行
-- ユーザー管理
+- **card_analyze_collection**: コレクション分析
-users (did, handle, created_at, updated_at)
+- **card_check_daily_limit**: 日次制限確認
-
+- **card_get_card_stats**: カード統計情報
-- カードマスターデータ
+- **card_manage_deck**: デッキ管理
-card_master (id, name, base_cp_min, base_cp_max, color, description)
+
-
+## 開発状況
-- ユーザー保有カード
+
-user_cards (id, user_did, card_id, cp, status, obtained_at, is_unique, unique_id)
+### 完成済み機能
-
+- ✅ **基本カード生成**: ai.bot統合での1日1回取得
-- ユニークカード登録
+- ✅ **atproto連携**: mention機能
-unique_card_registry (unique_id, card_id, owner_did, obtained_at)
+- ✅ **MCP統合**: ai.gptからの操作
-
+
-- ガチャ履歴
+### 開発中機能
-draw_history (id, user_did, card_id, status, cp, is_paid, drawn_at)
+- 🔧 **iOS app**: SwiftUI実装
-
+- 🔧 **Web UI**: React実装  
-- ガチャプール
+- 🔧 **独立API**: FastAPI server
-gacha_pools (id, name, description, is_active, pickup_card_ids)
+
-```
+### 将来機能
-
+- 📋 **OAuth 2.1**: 不正防止強化
-### カードレアリティ
+- 📋 **画像最適化**: Cloudflare Pages
-
+- 📋 **ゲーム拡張**: トレード・デッキ戦略
-| レアリティ | 確率 | 倍率 |
+
-|------------|------|------|
+## ai.botからの移行詳細
-| Normal     | 60%  | 1.0x |
+
-| Rare       | 25%  | 1.5x |
+### 現在のai.bot実装
-| SuperRare  | 10%  | 2.0x |
+- **Rust製**: seahorse CLI framework
-| Kira       | 4%   | 3.0x |
+- **atproto連携**: mention機能でカード配布
-| Unique     | 1%   | 5.0x |
+- **日次制限**: 1アカウント1日1回取得
-
+- **自動生成**: AI絵画（Leonardo.AI + Stable Diffusion）
-## 🔌 API エンドポイント
+
-
+### 独立化の理由
-### 認証API
+- **iOS展開**: モバイルアプリでの独立した体験
-
+- **ゲーム拡張**: デッキ構築・バトル機能の追加
-```http
+- **データ主権**: ユーザーによる完全なデータ所有
-POST /api/v1/auth/login
+- **スケーラビリティ**: サーバー負荷分散
-Content-Type: application/json
+
-
+## 技術的課題と解決策
-{
+
-  "identifier": "user.handle.or.did",
+### データ改ざん防止
-  "password": "password"
+- **短期**: MCP serverによる検証
-}
+- **中期**: OAuth 2.1 scope実装待ち
-
+- **長期**: ブロックチェーン的整合性チェック
-Response:
+
-{
+### スケーラビリティ
-  "access_token": "jwt_token",
+- **画像配信**: Cloudflare Pages活用
-  "token_type": "Bearer",
+- **API負荷**: FastAPIによる高速処理
-  "expires_in": 3600,
+- **データ保存**: atproto分散ストレージ
-  "user": {
+
-    "did": "did:plc:...",
+### ユーザー体験
-    "handle": "user.handle"
+- **直感的UI**: iOS/Webでの統一UX
-  }
+- **リアルタイム更新**: WebSocketでの即座反映
-}
+- **オフライン対応**: ローカルキャッシュ機能
-```
+
-
+## ai.game連携構想
-### カードAPI
+
-
+### Play-to-Work統合
-```http
+- **カードゲームプレイ → 業務成果変換**: ai.gameデバイスでの労働ゲーム化
-# カード一覧取得
+- **デッキ構築戦略 → 企業戦略思考**: カード組み合わせが戦略思考を鍛練
-GET /api/v1/cards/collection?did=did:plc:xxx&limit=20&offset=0
+- **トレード交渉 → ビジネススキル**: 他プレイヤーとの交渉が実務能力向上
-
+
-# ガチャ実行
+### メタバース展開
-POST /api/v1/cards/draw
+- **ai.verse統合**: 3D世界でのカードバトル
-{
+- **アバター連動**: 所有カードがキャラクター能力に影響
-  "user_did": "did:plc:xxx",
+- **配信コンテンツ**: カードゲームが配信可能なエンターテイメント
  "is_paid": false,
  "pool_id": null
 }
 # カード詳細
 GET /api/v1/cards/details/{card_id}
 # ユニークカード登録状況
 GET /api/v1/cards/unique-registry
 ```
 ### 同期API
 ```http
 # atproto PDS同期
 POST /api/v1/sync/cards/export
 POST /api/v1/sync/cards/import
 POST /api/v1/sync/cards/bidirectional
 ```
 ## 🎮 ガチャシステム
 ### 確率計算
 ```rust
 // 基本確率
 let base_probabilities = [
    (CardRarity::Normal, 0.6),
    (CardRarity::Rare, 0.25),
    (CardRarity::SuperRare, 0.1),
    (CardRarity::Kira, 0.04),
    (CardRarity::Unique, 0.01),
 ];
 // 有料ガチャボーナス
 if is_paid {
    probabilities[rare_index] *= 1.2;
    probabilities[unique_index] *= 2.0;
 }
 ```
 ### ユニーク性保証
 ```rust
 // グローバルユニークID管理
 if rarity == CardRarity::Unique {
    let unique_id = Uuid::new_v4();
    unique_card_registry.insert(unique_id, card_id, user_did);
 }
 ```
 ## 🔐 セキュリティ
 ### JWT認証
 ```rust
 // トークン生成
 let claims = Claims {
    did: user.did,
    handle: user.handle,
    exp: expiration_timestamp,
 };
 let token = encode(&Header::default(), &claims, &encoding_key)?;
 ```
 ### atproto DID検証
 ```rust
 // DID解決とPDS検出
 async fn resolve_pds_from_did(did: &str) -> AppResult<String> {
    match did {
        did if did.starts_with("did:plc:") => resolve_plc_did(did).await,
        did if did.starts_with("did:web:") => extract_web_domain(did),
        _ => Ok("https://bsky.social".to_string()), // fallback
    }
 }
 ```
 ## 🧪 テスト
 ### ユニットテスト
 ```bash
 # 全テスト実行
 cargo test
 # 特定モジュール
 cargo test services::gacha
 # 統合テスト
 cargo test --test integration
 ```
 ### APIテスト
 ```bash
 # ヘルスチェック
 curl http://localhost:8000/health
 # ガチャ統計
 curl http://localhost:8000/api/v1/cards/gacha-stats
 # 認証テスト
 curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"identifier":"test.user","password":"password"}'
 ```
 ## 🚀 本番デプロイ
 ### Docker
 ```dockerfile
 FROM rust:1.70 as builder
 WORKDIR /app
 COPY . .
 RUN cargo build --release
 FROM debian:bookworm-slim
 RUN apt-get update && apt-get install -y ca-certificates
 COPY --from=builder /app/target/release/ai-card-api /usr/local/bin/
 CMD ["ai-card-api"]
 ```
 ### 起動コマンド
 ```bash
 # 開発環境
 cargo run
 # 本番環境
 RUST_LOG=info DATABASE_URL=postgresql://... ./target/release/ai-card-api
 ```
 ## 📊 パフォーマンス
 ### ベンチマーク結果
 | 項目 | Rust実装 | Python実装 | 改善率 |
 |------|----------|-------------|--------|
 | レスポンス時間 | 2ms | 15ms | 7.5x |
 | メモリ使用量 | 20MB | 150MB | 7.5x |
 | 同時接続数 | 10,000+ | 1,000 | 10x |
 | スループット | 50k req/s | 5k req/s | 10x |
 ### システム要件
 | 環境 | CPU | メモリ | ストレージ |
 |------|-----|-------|------------|
 | 開発 | 1 core | 512MB | 1GB |
 | 本番 | 2 cores | 2GB | 20GB |
 | スケール | 4+ cores | 8GB+ | 100GB+ |
 ## 🔧 開発ガイド
 ### 依存関係
 ```toml
 [dependencies]
 # Web Framework
 axum = { version = "0.7", features = ["macros", "multipart"] }
 tokio = { version = "1.0", features = ["full"] }
 # Database
 sqlx = { version = "0.7", features = ["runtime-tokio-rustls", "postgres", "sqlite", "uuid", "chrono", "migrate"] }
 # Serialization
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 # Authentication
 jsonwebtoken = "9.0"
 bcrypt = "0.15"
 # Other
 uuid = { version = "1.0", features = ["v4", "serde"] }
 chrono = { version = "0.4", features = ["serde"] }
 tracing = "0.1"
 ```
 ### コーディング規約
 ```rust
 // エラーハンドリング
 type AppResult<T> = Result<T, AppError>;
 // 非同期関数
 async fn create_user(db: &Database, did: &str) -> AppResult<User> {
    // implementation
 }
 // 構造体定義
 #[derive(Debug, Clone, FromRow, Serialize, Deserialize)]
 pub struct User {
    pub id: i32,
    pub did: String,
    pub handle: String,
    pub created_at: DateTime<Utc>,
 }
 ```
 ## 📈 ロードマップ
 ### Phase 1: 基盤強化 ✅
 - [x] 基本API実装
 - [x] データベース設計
 - [x] ガチャシステム
 - [x] JWT認証
 ### Phase 2: atproto統合
 - [ ] 実際のPDS連携
 - [ ] DID検証強化
 - [ ] データ同期機能
 - [ ] 分散ストレージ
 ### Phase 3: スケーリング
 - [ ] Redis キャッシング
 - [ ] 水平スケーリング
 - [ ] CDN配信
 - [ ] 監視システム
 ### Phase 4: 高度機能
 - [ ] WebSocket リアルタイム
 - [ ] GraphQL API
 - [ ] 機械学習統合
 - [ ] 国際化対応
 ## 🤝 コントリビューション
 ### 開発フロー
 ```bash
 # 1. フォーク
 git clone https://git.syui.ai/ai/ai
 # 2. ブランチ作成
 git checkout -b feature/new-feature
 # 3. 開発・テスト
 cargo test
 cargo clippy
 cargo fmt
 # 4. プルリクエスト
 git push origin feature/new-feature
 ```
 ### コード品質
 ```bash
 # 静的解析
 cargo clippy -- -D warnings
 # フォーマット
 cargo fmt --check
 # テストカバレッジ
 cargo tarpaulin --out Html
 ```
 ## 🐛 トラブルシューティング
 ### よくある問題
 **Q: SQLXコンパイルエラー**
 ```bash
 error: set `DATABASE_URL` to use query macros online
 ```
 A: 環境変数設定またはオフラインモード使用
 ```bash
 export DATABASE_URL=sqlite://test.db
 # または
 cargo sqlx prepare
 ```
 **Q: データベース接続エラー**
 ```
 Database connection failed
 ```
 A: URL確認とパーミッション設定
 ```bash
 # SQLite
 mkdir -p ~/.config/syui/ai/card/
 chmod 755 ~/.config/syui/ai/card/
 # PostgreSQL
 psql -h localhost -U user -d aicard -c "\l"
 ```
 **Q: 認証失敗**
 ```
 JWT validation error
 ```
 A: シークレットキー確認
 ```bash
 export SECRET_KEY=your-secret-key-here
 ```
 ## 📄 ライセンス
 MIT License - 詳細は[LICENSE](LICENSE)を参照
 ## 🙏 謝辞
 - **atproto**: 分散型SNSプロトコル
 - **Rust Community**: 高品質なクレート提供
 - **sqlx**: 型安全なデータベースライブラリ
 - **axum**: 高性能Webフレームワーク
 ---
 **syui** (2025) - ai.card エコシステム統合プロジェクト