# 用户卡信息处理系统设计文档

## 1. 系统概述

该系统主要由控制器插件、业务插件和游戏端三部分组成，通过TCP通信实现用户卡信息处理和游戏数据收集。

## 2. 系统架构

### 字符流程图
```
+----------------+    +----------------+    +----------------+
| 控制器插件      |    | 业务插件        |    | 游戏端         |
|                |    |                |    |                |
| - 扫描用户卡    |    | - 处理用户信息  |    | - 接收用户信息  |
| - 读取卡信息    |--->| - 存储本地数据  |<-->| - 发送游戏信息  |
| - 通知业务插件  |    | - 网络请求处理  |    | - 本地备份处理  |
+----------------+    +----------------+    +----------------+
                           |       ^
                           v       |
                      +-----------------+
                      |     服务器       |
                      | - 用户资料数据库 |
                      | - 游戏数据处理   |
                      +-----------------+
```

### mermaid流程图
```mermaid
flowchart LR
    A[控制器插件\n- 扫描用户卡\n- 读取卡信息\n- 通知业务插件] --> B[业务插件\n- 处理用户信息\n- 存储本地数据\n- 网络请求处理]
    B <--> C[游戏端\n- 接收用户信息\n- 发送游戏信息\n- 本地备份处理]
    B <--> D[服务器\n- 用户资料数据库\n- 游戏数据处理]
```

## 3. 系统详细流程

### 3.1 用户卡信息处理流程

#### 流程说明
用户卡信息处理流程描述了从控制器插件扫描用户卡到业务插件向游戏端发送用户信息的完整过程。当控制器插件检测到用户卡扫描信息后，会通知业务插件。业务插件根据网络状态决定从服务器请求用户资料或从本地数据库读取用户信息。如果网络可用，业务插件会请求最新的用户信息并存储到本地；如果网络不可用或请求失败，则从本地SQLite数据库读取历史记录；若本地无记录，则构造默认用户信息。最终，业务插件将完整的用户信息通过TCP（12101端口）发送给游戏端。

#### 字符流程图
```
+----------------+     +----------------+     +----------------+     +----------------+
| 控制器插件      |     | 业务插件        |     | 网络/本地数据库 |     | 游戏端         |
+-------+--------+     +-------+--------+     +-------+--------+     +-------+--------+
        |                      |                      |                      |
        | 扫描到用户卡          |                      |                      |
        +--------------------->+                      |                      |
        |                      |                      |                      |
        |                      | 检查网络状态          |                      |
        |                      +--------------------->+                      |
        |                      |                      |                      |
        |                      | 有网络: 请求用户信息  |                      |
        |                      +--------------------->+                      |
        |                      |                      |                      |
        |                      | 返回用户信息          |                      |
        |                      +<---------------------+                      |
        |                      |                      |                      |
        |                      | 无网络/请求失败:      |                      |
        |                      | 读取本地数据          |                      |
        |                      +--------------------->+                      |
        |                      |                      |                      |
        |                      | 返回本地数据          |                      |
        |                      +<---------------------+                      |
        |                      |                      |                      |
        |                      | 构造用户信息          |                      |
        |                      +-------------------------------------------------+
        |                      |                      |                      |   |
        |                      | TCP(12101)发送用户信息|                      |   |
        |                      +--------------------->+--------------------->+   |
        |                      |                      |                      |   |
        |                      |                      |                      |   |
        |                      |                     本地存储用户信息         <---+
        |                      |                      |                      |
+-------+--------+     +-------+--------+     +-------+--------+     +-------+--------+
```

#### mermaid流程图
```mermaid
sequenceDiagram
    participant 控制器插件
    participant 业务插件
    participant 网络/本地数据库
    participant 游戏端
    
    控制器插件->>业务插件: 扫描到用户卡
    业务插件->>网络/本地数据库: 检查网络状态
    
    alt 有网络
        业务插件->>网络/本地数据库: 请求用户信息
        网络/本地数据库-->>业务插件: 返回用户信息
    else 无网络/请求失败
        业务插件->>网络/本地数据库: 读取本地数据
        网络/本地数据库-->>业务插件: 返回本地数据
    end
    
    业务插件->>业务插件: 构造用户信息
    业务插件->>游戏端: TCP(12101)发送用户信息
    游戏端->>游戏端: 本地存储用户信息
```

### 3.2 游戏信息收集流程

#### 流程说明
游戏信息收集流程描述了业务插件如何通过TCP监听接收游戏端发送的消息并进行处理的过程。业务插件监听TCP（12103端口）以接收来自游戏端的信息。根据接收到的消息类型（由标识头区分），业务插件会进行不同的处理：如果是游戏结束消息（标识头为"game-over"），业务插件会更新对应Player的状态，之后接收到该Player的游戏信息将不再与用户卡关联；如果是游戏业务信息，业务插件会尝试通过网络将数据发送到服务器，若网络不可用或发送失败，则将数据存储到本地SQLite数据库中以便稍后同步。

#### 字符流程图
```
+----------------+     +----------------+     +----------------+
| 游戏端         |     | 业务插件        |     | 服务器/本地存储 |
+-------+--------+     +-------+--------+     +-------+--------+
        |                      |                      |
        | TCP(12103)发送游戏信息|                      |
        +--------------------->+                      |
        |                      |                      |
        |                      | 检查消息类型          |                    
        |                      +-----------------+    |
        |                      |                 |    |
        |                      | 游戏结束消息     |    |
        |                      |-----------------+    |
        |                      | 更新Player状态   |    |
        |                      +-----------------+    |
        |                      |                 |    |
        |                      | 游戏业务信息     |    |
        |                      |-----------------+    |
        |                      | 检查网络状态     |    |
        |                      +--------------------->+
        |                      |                      |
        |                      | 有网络: 发送到服务器  |
        |                      +--------------------->+
        |                      |                      |
        |                      | 响应结果             |
        |                      +<---------------------+
        |                      |                      |
        |                      | 无网络/发送失败:      |
        |                      | 存储到本地SQLite     |
        |                      +--------------------->+
        |                      |                      |
+-------+--------+     +-------+--------+     +-------+--------+
```

#### mermaid流程图
```mermaid
sequenceDiagram
    participant 游戏端
    participant 业务插件
    participant 服务器/本地存储
    
    游戏端->>业务插件: TCP(12103)发送游戏信息
    
    alt 游戏结束消息
        业务插件->>业务插件: 更新Player状态
    else 游戏业务信息
        业务插件->>业务插件: 检查网络状态
        alt 有网络
            业务插件->>服务器/本地存储: 发送到服务器
            服务器/本地存储-->>业务插件: 响应结果
        else 无网络/发送失败
            业务插件->>服务器/本地存储: 存储到本地SQLite
        end
    end
```

### 3.3 游戏信息发送失败处理流程

#### 流程说明
游戏信息发送失败处理流程描述了当游戏端无法直接将游戏信息发送给业务插件时的备份处理机制。当游戏端向业务插件发送信息超时或无响应时，游戏端会将这些数据存储到特定目录中的文件系统，采用一条数据一个文件的方式。业务插件会定期检查该目录，读取这些文件中的数据，处理（如重新发送到服务器或记录到本地数据库）后再删除这些文件。这种机制确保了即使在业务插件暂时不可用的情况下，游戏数据也不会丢失，提高了系统的可靠性和容错性。

#### 字符流程图
```
+----------------+     +----------------+     +----------------+
| 游戏端         |     | 文件系统        |     | 业务插件        |
+-------+--------+     +-------+--------+     +-------+--------+
        |                      |                      |
        | 信息发送超时/无响应   |                      |
        +-----------------+    |                      |
        |                |     |                      |
        | 创建数据文件    |     |                      |
        |----------------+     |                      |
        | 将数据写入文件  |     |                      |
        +--------------------->+                      |
        |                      |                      |
        |                      |  业务插件定期检查目录 |
        |                      +<---------------------+
        |                      |                      |
        |                      |  读取数据文件        |
        |                      +--------------------->+
        |                      |                      |
        |                      |  处理数据(重发/记录)  |
        |                      +<---------------------+
        |                      |                      |
        |                      |  处理完成后删除文件   |
        |                      +<---------------------+
        |                      |                      |
+-------+--------+     +-------+--------+     +-------+--------+
```

#### mermaid流程图
```mermaid
sequenceDiagram
    participant 游戏端
    participant 文件系统
    participant 业务插件
    
    游戏端->>游戏端: 信息发送超时/无响应
    游戏端->>游戏端: 创建数据文件
    游戏端->>文件系统: 将数据写入文件
    业务插件->>文件系统: 定期检查目录
    文件系统->>业务插件: 读取数据文件
    业务插件->>业务插件: 处理数据(重发/记录)
    业务插件->>文件系统: 处理完成后删除文件
```

## 4. 信息结构

### 4.1 发送给游戏的用户信息JSON结构

```json
{
  "result": true,         // 操作结果
  "errMsg": "",           // 错误信息
  "statusCode": 0,        // 状态码（0=成功，1=未绑定，2=无网）
  "tag": "user-info",     // 标识标签，区分不同类型的信息
  "data": {
    "playerIndex": 1,      // player索引
    "cardId": "123456",    // 卡ID
    "cardSn": "789012",    // 卡序列号
    "userName": "张三",    // 用户名称
    "userAvatar": "http://example.com/avatar.jpg" // 用户头像
  }
}
```

#### 4.1.1 请求服务器查询玩家资料
	请求写入排行榜
```json
{
  "tag": "update-user-info",     // 标识标签，区分不同类型的信息
  "data": {
    "cardId": "123456",    // 卡ID
	"score": 10000 //积分
  }
}
```
	回复
```json
{
 "result": true,         // 操作结果
  "errMsg": "",           // 错误信息
  "statusCode": 0,        // 状态码（0=成功，1=未绑定，2=无网）
  "tag": "",     // 标识标签，区分不同类型的信息
  "data":{}
}
```

	请求查询玩家信息
```json
{
  "tag": "select-user-info",     // 标识标签，区分不同类型的信息
  "data": {
    "cardId": "123456",    // 卡ID	
  }
}
```
	回复
```json
{
  "result": true,         // 操作结果
  "errMsg": "",           // 错误信息
  "statusCode": 0,        // 状态码（0=成功，1=未绑定，2=无网）
  "tag": "user-info",     // 标识标签，区分不同类型的信息
  "data": {
    "playerIndex": 1,      // player索引
    "cardId": "123456",    // 卡ID
    "cardSn": "789012",    // 卡序列号
    "userName": "张三",    // 用户名称
    "userAvatar": "http://example.com/avatar.jpg" // 用户头像
    ...
  }
}
```

### 4.2 游戏结束消息JSON结构

```json
{
  "result": true,         // 操作结果
  "errMsg": "",           // 错误信息
  "statusCode": 0,        // 状态码（0=成功，非0=失败）
  "tag": "game-over",     // 标识标签
  "data": {
    "playerIndex": 1,      // player索引
    "cardId": "123456",    // 卡ID
    "timestamp": 1634567890 // 时间戳
  }
}
```

### 4.3 游戏业务信息JSON结构

```json
{
  "result": true,          // 操作结果
  "errMsg": "",            // 错误信息
  "statusCode": 0,         // 状态码（0=成功，非0=失败）
  "tag": "game-data",      // 标识标签
  "data": {
    "playerIndex": 1,      // player索引
    "cardId": "123456",    // 卡ID
    "gameData": {          // 游戏数据（根据具体业务定义）
      // 具体业务数据
    },
    "timestamp": 1634567890 // 时间戳
  }
}
```

## 5. 通信端口说明

- **12101端口**：游戏端监听，业务端发送消息
- **12103端口**：业务端监听，游戏端发送消息

## 6. 数据持久化

### 6.1 SQLite数据结构

#### 用户信息表
```sql
CREATE TABLE user_info (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  card_id TEXT NOT NULL,
  card_sn TEXT NOT NULL,
  user_name TEXT,
  user_avatar TEXT,
  last_updated INTEGER,
  UNIQUE(card_id, card_sn)
);
```

#### 游戏数据表
```sql
CREATE TABLE game_data (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  card_id TEXT NOT NULL,
  player_index INTEGER NOT NULL,
  data_type TEXT NOT NULL,
  data_content TEXT NOT NULL,
  timestamp INTEGER NOT NULL,
  is_synced INTEGER DEFAULT 0
);
```

### 6.2 文件存储结构

游戏数据文件命名格式：`game_data_{timestamp}_{playerIndex}_{cardId}.json`

## 7. 注意事项

### 7.1 数据安全与隐私

- 用户卡信息应进行加密存储
- 本地数据应设置访问权限限制
- 网络传输过程采用HTTPS或加密通道

### 7.2 数据同步机制

- 本地数据与服务器数据定期同步机制
- 冲突解决策略（以服务器数据为准或采用时间戳）
- 同步频率设置（定时/事件触发）

### 7.3 错误处理与恢复

- 网络恢复后的数据自动上传机制
- 重试策略（指数退避算法）
- 错误日志记录与报警机制
- 异常情况下的回滚机制

### 7.4 性能优化

- SQLite查询优化
- 批量数据处理
- 队列机制避免并发问题
- 异步处理大量数据

### 7.5 本地存储管理

- 定期清理过期数据
- 存储空间监控
- 数据备份机制
- 存储空间不足时的处理策略

### 7.6 监控与日志

- 关键操作日志记录
- 系统状态监控
- 异常情况报警机制

## 8. 系统扩展性考虑

- 支持多种类型用户卡的可扩展接口
- 业务消息类型的可扩展设计
- 版本兼容性处理机制
- 插件化架构设计
- 配置化管理