1
0

fix reamde

This commit is contained in:
2025-06-09 01:50:47 +09:00
parent b68c7b5e61
commit 87b528338a

586
README.md
View File

@@ -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連携**: 分散IDDID認証とデータ同期
- **データベース**: 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の安全性と高速性
- **データ主権**: ユーザーがデータを完全所有
- **分散型**: 中央集権に依存しない設計
- **型安全**: コンパイル時エラー検出
- **並行処理**: 非同期I/O最適化
## 🚀 クイックスタート
### 前提条件
```bash
# Rust 1.70+
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# データベース(どちらか選択)
# SQLite開発用・推奨
sqlite3 --version
# PostgreSQL本番用
psql --version
### データフロー
```
ユーザー → ai.bot mention → カード生成 → atproto collection → ユーザー所有
↑ ↓
← iOS app表示 ← ai.card API ←
```
### セットアップ
## 移行計画
```bash
# 1. プロジェクトクローン
cd /Users/syui/ai/ai/card/api-rs
### Phase 1: 独立化
- **iOS移植**: Claude担当予定
- **Web UI**: React実装
- **API独立**: ai.botからの分離
# 2. 依存関係インストール
cargo build
### Phase 2: データ主権実装
- **atproto collection**: カードデータをユーザー所有に
- **OAuth 2.1**: 不正防止機能実装
- **画像ファイル**: Cloudflare Pages最適化
# 3. 環境設定
cp .env.example .env
vim .env
### Phase 3: ゲーム機能拡張
- **ガチャシステム**: 確率・レアリティ管理
- **トレード機能**: ユーザー間カード交換
- **デッキ構築**: カードゲーム戦略要素
# 4. データベース初期化
cargo run -- migrate
## yui system適用
# 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/
├── main.rs # エントリーポイント
├── config.rs # 設定管理
├── error.rs # エラーハンドリング
── database.rs # データベース抽象化
├── 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 # 依存関係定義
/Users/syui/ai/gpt/card/
├── api/ # FastAPI + MCP server
├── web/ # React Web UI
├── ios/ # SwiftUI iOS app
── docs/ # 開発ドキュメント
```
## 🗄️ データベース設計
### 主要テーブル
```sql
-- ユーザー管理
users (did, handle, created_at, updated_at)
-- カードマスターデータ
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)
-- ユニークカード登録
unique_card_registry (unique_id, card_id, owner_did, obtained_at)
-- ガチャ履歴
draw_history (id, user_did, card_id, status, cp, is_paid, drawn_at)
-- ガチャプール
gacha_pools (id, name, description, is_active, pickup_card_ids)
```
### カードレアリティ
| レアリティ | 確率 | 倍率 |
|------------|------|------|
| Normal | 60% | 1.0x |
| Rare | 25% | 1.5x |
| SuperRare | 10% | 2.0x |
| Kira | 4% | 3.0x |
| Unique | 1% | 5.0x |
## 🔌 API エンドポイント
### 認証API
```http
POST /api/v1/auth/login
Content-Type: application/json
{
"identifier": "user.handle.or.did",
"password": "password"
}
Response:
{
"access_token": "jwt_token",
"token_type": "Bearer",
"expires_in": 3600,
"user": {
"did": "did:plc:...",
"handle": "user.handle"
}
}
```
### カードAPI
```http
# カード一覧取得
GET /api/v1/cards/collection?did=did:plc:xxx&limit=20&offset=0
# ガチャ実行
POST /api/v1/cards/draw
{
"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 エコシステム統合プロジェクト
## MCPツールai.gpt連携
### カード管理
- **card_get_user_cards**: ユーザーカード取得
- **card_draw_card**: ガチャ実行
- **card_analyze_collection**: コレクション分析
- **card_check_daily_limit**: 日次制限確認
- **card_get_card_stats**: カード統計情報
- **card_manage_deck**: デッキ管理
## 開発状況
### 完成済み機能
-**基本カード生成**: ai.bot統合での1日1回取得
-**atproto連携**: mention機能
-**MCP統合**: ai.gptからの操作
### 開発中機能
- 🔧 **iOS app**: SwiftUI実装
- 🔧 **Web UI**: React実装
- 🔧 **独立API**: FastAPI server
### 将来機能
- 📋 **OAuth 2.1**: 不正防止強化
- 📋 **画像最適化**: Cloudflare Pages
- 📋 **ゲーム拡張**: トレード・デッキ戦略
## ai.botからの移行詳細
### 現在のai.bot実装
- **Rust製**: seahorse CLI framework
- **atproto連携**: mention機能でカード配布
- **日次制限**: 1アカウント1日1回取得
- **自動生成**: AI絵画Leonardo.AI + Stable Diffusion
### 独立化の理由
- **iOS展開**: モバイルアプリでの独立した体験
- **ゲーム拡張**: デッキ構築・バトル機能の追加
- **データ主権**: ユーザーによる完全なデータ所有
- **スケーラビリティ**: サーバー負荷分散
## 技術的課題と解決策
### データ改ざん防止
- **短期**: MCP serverによる検証
- **中期**: OAuth 2.1 scope実装待ち
- **長期**: ブロックチェーン的整合性チェック
### スケーラビリティ
- **画像配信**: Cloudflare Pages活用
- **API負荷**: FastAPIによる高速処理
- **データ保存**: atproto分散ストレージ
### ユーザー体験
- **直感的UI**: iOS/Webでの統一UX
- **リアルタイム更新**: WebSocketでの即座反映
- **オフライン対応**: ローカルキャッシュ機能
## ai.game連携構想
### Play-to-Work統合
- **カードゲームプレイ → 業務成果変換**: ai.gameデバイスでの労働ゲーム化
- **デッキ構築戦略 → 企業戦略思考**: カード組み合わせが戦略思考を鍛練
- **トレード交渉 → ビジネススキル**: 他プレイヤーとの交渉が実務能力向上
### メタバース展開
- **ai.verse統合**: 3D世界でのカードバトル
- **アバター連動**: 所有カードがキャラクター能力に影響
- **配信コンテンツ**: カードゲームが配信可能なエンターテイメント