# Kylin Game Data

Kylin 游戏数据存储包 -- 存档/同步/冲突解决/历史记录。

## 功能特性

- **存档管理**：按 user_id + game_id 维度存储，data 字段为 JSON 格式
- **数据同步**：客户端到服务端的增量同步
- **冲突解决**：支持 server_wins / client_wins / manual 三种策略
- **历史记录**：完整的存档变更历史，支持回溯
- **数据校验**：SHA256 校验和，确保数据完整性
- **频率控制**：防止客户端过于频繁的同步请求

## 安装

```bash
composer require kylin/game-data
```

## 配置发布

```bash
php artisan vendor:publish --tag=kylin-game-data-config
php artisan vendor:publish --tag=kylin-game-data-migrations
php artisan migrate
```

## 使用示例

### Facade

```php
use Kylin\GameData\Facades\KylinGameData;

// 获取存档
$save = KylinGameData::getSave($userId, $gameId);

// 保存数据
$save = KylinGameData::saveData($userId, $gameId, $data, $version);

// 删除存档
KylinGameData::deleteSave($userId, $gameId);

// 获取历史
$histories = KylinGameData::getHistory($userId, $gameId, 20);
```

### 数据同步服务

```php
use Kylin\GameData\Services\GameDataSyncService;

$syncService = app(GameDataSyncService::class);

// 客户端同步到服务端
$save = $syncService->syncFromClient($userId, $gameId, $data, $clientVersion);

// 计算校验和
$checksum = $syncService->calculateChecksum($data);

// 冲突解决
$resolvedData = $syncService->resolveConflict($serverData, $clientData);
```

### API 路由

所有路由均需通过 `kylin.game` 中间件认证（X-App-Id + HMAC 签名）。

| 方法 | 路径 | 说明 |
|------|------|------|
| GET    | /api/kylin/game-data/{appId} | 获取游戏数据 |
| POST   | /api/kylin/game-data/{appId}/sync | 同步游戏数据 |
| GET    | /api/kylin/game-data/{appId}/history | 存档历史 |
| DELETE | /api/kylin/game-data/{appId} | 删除存档 |

### 冲突解决策略

| 策略 | 说明 |
|------|------|
| server_wins | 保留服务端数据（默认） |
| client_wins | 采用客户端数据 |
| manual | 抛出冲突异常，等待手动解决 |

### 数据存储格式

按 `user_id + game_id` 维度存储，`data` 字段为 JSON 格式，每款游戏自定义 schema：

```json
{
    "user_id": 1,
    "game_id": 2,
    "data": {
        "level": 10,
        "gold": 5000,
        "inventory": [...],
        "progress": {...}
    },
    "version": 5,
    "client_version": 5,
    "checksum": "sha256_hash..."
}
```

## 依赖

- PHP ^8.5
- Laravel ^13.0
- kylin/core
- kylin/user
- kylin/game

## 许可证

私有软件，未经授权禁止使用。
