# Location Interaction System - evaluation_value Based Implementation

## 概要

LocationモデルのDestinationにuse_qr_codeフラグとevaluation_valueフィールドを使用した、拡張されたロケーションインタラクションシステムを実装しました。

## システム構成

### 1. Locationモデル拡張

**ファイル**: `rog/models.py`

- `evaluation_value` フィールドを使用してインタラクションタイプを決定
- 値の意味:
  - `"0"` または `null`: 通常ポイント
  - `"1"`: 写真撮影 + 買い物ポイント
  - `"2"`: QRコードスキャン + クイズ回答

### 2. ビジネスロジック

**ファイル**: `rog/location_interaction.py`

```python
# インタラクションタイプ定数
INTERACTION_TYPE_NORMAL = "0"      # 通常ポイント
INTERACTION_TYPE_PHOTO = "1"       # 写真撮影ポイント
INTERACTION_TYPE_QR_QUIZ = "2"     # QRコード + クイズポイント

# 主要関数
- get_interaction_type(location): ロケーションのインタラクションタイプを判定
- validate_interaction_requirements(location, request_data): 必要なデータの検証
- get_point_calculation(location, interaction_result): ポイント計算
```

### 3. チェックインAPI

**ファイル**: `rog/location_checkin_view.py`

**エンドポイント**: `POST /api/location-checkin/`

**リクエスト形式**:
```json
{
    "location_id": 123,
    "latitude": 35.1234,
    "longitude": 136.5678,
    "photo": "base64_encoded_image_data",      // evaluation_value="1"の場合必須
    "qr_code_data": "{\"quiz_id\": 1, \"correct_answer\": \"答え\"}", // evaluation_value="2"の場合必須
    "quiz_answer": "ユーザーの回答"              // evaluation_value="2"の場合必須
}
```

**レスポンス形式**:
```json
{
    "success": true,
    "checkin_id": 456,
    "points_awarded": 10,
    "point_type": "photo_shopping",
    "message": "写真撮影が完了しました。買い物ポイントを獲得！",
    "location_name": "ロケーション名",
    "interaction_type": "1",
    "interaction_result": {
        "photo_saved": true,
        "photo_filename": "checkin_123_20250103_143022.jpg"
    }
}
```

### 4. APIデータ拡張

**ファイル**: `rog/serializers.py`

LocationSerializerを拡張して、以下の情報を追加:
- `interaction_type`: インタラクションタイプ ("0", "1", "2")
- `requires_photo`: 写真撮影が必要かどうか
- `requires_qr_code`: QRコードスキャンが必要かどうか
- `interaction_instructions`: ユーザー向け指示メッセージ

### 5. テスト用Webインターフェース

**ファイル**: `templates/location_checkin_test.html`

**アクセス**: `/api/location-checkin-test/`

機能:
- ロケーション一覧の表示
- evaluation_valueに基づく要件の表示
- 写真アップロード (evaluation_value="1")
- QRデータ・クイズ入力 (evaluation_value="2")
- チェックイン実行とテスト

## 使用方法

### 1. 通常ポイント (evaluation_value="0")

```javascript
const data = {
    location_id: 123,
    latitude: 35.1234,
    longitude: 136.5678
};

fetch('/api/location-checkin/', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify(data)
});
```

### 2. 写真撮影ポイント (evaluation_value="1")

```javascript
const data = {
    location_id: 123,
    latitude: 35.1234,
    longitude: 136.5678,
    photo: "base64_encoded_image_data"  // 写真必須
};
```

### 3. QRコード + クイズポイント (evaluation_value="2")

```javascript
const data = {
    location_id: 123,
    latitude: 35.1234,
    longitude: 136.5678,
    qr_code_data: '{"quiz_id": 1, "correct_answer": "岐阜城"}',  // QRコードデータ
    quiz_answer: "岐阜城"  // ユーザーの回答
};
```

## ポイント計算システム

### 基本ポイント
- 通常ポイント: 10ポイント
- 写真撮影ポイント: 15ポイント
- QRコード + クイズポイント: 20ポイント (正解時)

### ボーナスポイント
- クイズ正解ボーナス: +5ポイント
- 写真保存成功ボーナス: +2ポイント

## エラーハンドリング

### 検証エラー
- 必須フィールド不足
- 距離制限外
- 写真データ不正
- QRコードデータ不正

### 処理エラー
- 写真保存失敗
- データベースエラー
- ネットワークエラー

## セキュリティ考慮事項

1. **認証**: `@login_required`デコレータでユーザー認証必須
2. **CSRF**: `@csrf_exempt`だが、トークン検証推奨
3. **距離検証**: Haversine公式による正確な距離計算
4. **データ検証**: 入力データの厳密な検証

## データベース影響

### 新規追加なし
- 既存の`evaluation_value`フィールドを活用
- `Useractions`テーブルでチェックイン記録

### 推奨される追加フィールド (今後の拡張)
- `Location.checkin_radius`: チェックイン許可範囲
- `Location.use_qr_code`: QRコード使用フラグ
- `Location.quiz_data`: クイズデータ

## 今後の拡張予定

1. **写真検証**: AI による撮影内容検証
2. **QRコード生成**: 動的QRコード生成システム
3. **ゲーミフィケーション**: バッジ・称号システム
4. **リアルタイム**: WebSocket による即座反映
5. **統計**: インタラクション統計・分析

## テスト手順

1. テストページにアクセス: `/api/location-checkin-test/`
2. evaluation_valueが異なるロケーションを選択
3. 各インタラクションタイプでチェックイン実行
4. レスポンスの確認

## 関連ファイル

- `rog/models.py`: Locationモデル定義
- `rog/serializers.py`: LocationSerializer拡張
- `rog/location_interaction.py`: ビジネスロジック
- `rog/location_checkin_view.py`: チェックインAPI
- `rog/urls.py`: URL設定
- `templates/location_checkin_test.html`: テストインターフェース

---

この実装により、evaluation_valueに基づく柔軟なロケーションインタラクションシステムが完成しました。各ロケーションで異なるユーザー体験を提供し、ゲーミフィケーション要素を追加することで、より魅力的なロゲイニング体験を実現します。