# TSGame 跨平台项目说明文档

## 项目概述

TSGame 是一个跨平台的棋牌游戏应用，支持Android、iOS、HarmonyOS等主流移动平台。主要实现了聚友棋牌、进贤聚友棋牌等多个地方特色棋牌游戏。项目采用WebView混合开发模式，通过统一的JS Bridge接口实现跨平台功能。

### 支持平台
- **Android**: API 21+ (Android 5.0+)
- **iOS**: iOS 11.0+
- **HarmonyOS**: API 8+ (HarmonyOS 3.0+)

### 基本信息
- **应用标识**: `com.jx.jyhd` (可根据平台调整)
- **应用名称**: 进贤聚友棋牌（支持多种地方棋牌名称配置）
- **当前版本**: 3.6.3
- **架构模式**: WebView + JS Bridge 混合开发

## 跨平台技术架构

### 整体架构设计
```
┌─────────────────────────────────────────────────────┐
│                   H5游戏前端                          │
│              (HTML5 + CSS3 + JavaScript)           │
└─────────────────────────────────────────────────────┘
                            │
┌─────────────────────────────────────────────────────┐
│                 JS Bridge 通信层                      │
│            (统一的跨平台API接口定义)                    │
└─────────────────────────────────────────────────────┘
                            │
┌─────────────┬─────────────┬─────────────┬─────────────┐
│   Android   │     iOS     │ HarmonyOS   │   其他平台    │
│   Native    │   Native    │   Native    │   Native    │
└─────────────┴─────────────┴─────────────┴─────────────┘
```

### 核心设计原则
1. **统一接口**: 所有平台实现相同的JS Bridge API接口
2. **功能对等**: 确保各平台功能基本一致
3. **性能优化**: 针对不同平台特性进行优化
4. **用户体验**: 遵循各平台的设计规范

## 项目功能特性

### 核心功能模块
1. **多地方棋牌游戏支持**
   - 崇仁聚友棋牌
   - 进贤聚友棋牌
   - 广州聚友棋牌
   - 慈溪聚友棋牌
   - 东乡棋牌等多个地方特色游戏

2. **WebView游戏引擎**
   - Android: 腾讯X5 WebView内核
   - iOS: WKWebView
   - HarmonyOS: Web组件
   - 支持HTML5游戏运行
   - 自定义JS桥接功能

3. **社交分享功能**
   - 微信好友/朋友圈分享
   - QQ分享（Android）
   - 系统分享（iOS/HarmonyOS）
   - 抖音分享（Intent/URL Scheme方式）

4. **位置服务**
   - Android: 高德地图SDK
   - iOS: 高德地图SDK + CoreLocation
   - HarmonyOS: 华为地图服务
   - GPS/网络定位支持

5. **语音功能**
   - 声网Agora音频SDK（全平台支持）
   - 实时语音通话
   - 录音功能

6. **版本管理**
   - 应用自动更新
   - 游戏资源热更新
   - 配置文件动态加载

## 跨平台项目目录结构

### 通用项目结构
```
tsgame_multiplatform/
├── shared/                        # 共享资源
│   ├── webview/                   # H5游戏资源
│   │   ├── assets/               # 静态资源
│   │   ├── js/                   # JavaScript文件
│   │   ├── css/                  # 样式文件
│   │   └── index.html           # 游戏入口页面
│   ├── bridge/                   # JS Bridge接口定义
│   │   ├── bridge-api.js        # 统一API接口
│   │   └── bridge-types.ts      # TypeScript类型定义
│   └── config/                   # 配置文件
│       ├── game-config.json     # 游戏配置
│       └── platform-config.json # 平台配置
├── android/                      # Android平台实现
│   ├── app/
│   │   ├── src/main/java/       # Java/Kotlin源码
│   │   ├── src/main/assets/     # 资源文件
│   │   └── build.gradle         # 构建配置
│   └── libs/                    # 第三方库
├── ios/                          # iOS平台实现
│   ├── TSGame/
│   │   ├── Classes/             # OC/Swift源码
│   │   ├── Resources/           # 资源文件
│   │   └── Info.plist          # 应用配置
│   └── Podfile                  # 依赖管理
├── harmonyos/                    # HarmonyOS平台实现
│   ├── entry/
│   │   ├── src/main/ets/       # ArkTS源码
│   │   ├── src/main/resources/ # 资源文件
│   │   └── build-profile.json5 # 构建配置
│   └── oh-package.json5        # 依赖管理
├── docs/                         # 项目文档
│   ├── platform-guides/        # 平台开发指南
│   ├── api-reference/          # API参考文档
│   └── deployment/             # 部署指南
└── tools/                       # 开发工具
    ├── build-scripts/          # 构建脚本
    └── test-tools/             # 测试工具
```

### 平台特定代码包结构

#### Android (Java/Kotlin)
```
com.jx.jyhd/
├── activity/                    # 活动页面
│   ├── MainActivity            # 主入口
│   ├── WebViewActivity         # WebView容器
│   └── SplashActivity          # 启动页
├── bridge/                     # JS Bridge实现
│   ├── BridgeWebView          # WebView扩展
│   ├── BridgeHandler          # 方法处理器
│   └── BridgeManager          # 桥接管理器
├── service/                    # 业务服务
│   ├── AuthService            # 认证服务
│   ├── ShareService           # 分享服务
│   └── LocationService        # 定位服务
└── utils/                      # 工具类
    ├── NetworkUtils           # 网络工具
    └── StorageUtils           # 存储工具
```

#### iOS (Objective-C/Swift)
```
TSGame/
├── Controllers/                # 控制器
│   ├── TSMainViewController   # 主控制器
│   ├── TSWebViewController    # WebView控制器
│   └── TSSplashViewController # 启动页控制器
├── Bridge/                     # JS Bridge实现
│   ├── TSBridgeWebView        # WebView扩展
│   ├── TSBridgeHandler        # 方法处理器
│   └── TSBridgeManager        # 桥接管理器
├── Services/                   # 业务服务
│   ├── TSAuthService          # 认证服务
│   ├── TSShareService         # 分享服务
│   └── TSLocationService      # 定位服务
└── Utils/                      # 工具类
    ├── TSNetworkUtils         # 网络工具
    └── TSStorageUtils         # 存储工具
```

#### HarmonyOS (ArkTS)
```
src/main/ets/
├── entryability/              # 应用入口
│   └── EntryAbility.ts       # 主Ability
├── pages/                     # 页面
│   ├── Index.ets             # 主页面
│   ├── WebView.ets           # WebView页面
│   └── Splash.ets            # 启动页
├── bridge/                    # JS Bridge实现
│   ├── BridgeWebView.ets     # WebView扩展
│   ├── BridgeHandler.ets     # 方法处理器
│   └── BridgeManager.ets     # 桥接管理器
├── services/                  # 业务服务
│   ├── AuthService.ets       # 认证服务
│   ├── ShareService.ets      # 分享服务
│   └── LocationService.ets   # 定位服务
└── utils/                     # 工具类
    ├── NetworkUtils.ets      # 网络工具
    └── StorageUtils.ets      # 存储工具
```

## 跨平台应用启动流程

### 统一启动流程设计
```
应用启动
    ↓
平台初始化 (原生代码)
    ↓
权限检查与申请
    ↓
配置文件加载
    ↓
JS Bridge初始化
    ↓
WebView组件加载
    ↓
H5游戏资源加载
    ↓
游戏启动完成
```

### 平台特定启动流程

#### Android启动流程
1. **应用启动入口**
   ```
   AndroidManifest.xml → SplashActivity → MainActivity → WebViewActivity
   ```

2. **初始化阶段** (`SplashActivity.onCreate`)
   ```java
   1. 权限检查和存储权限申请
   2. 设置全屏显示和屏幕常亮
   3. 初始化日志系统
   4. 友盟统计初始化
   5. 微信API初始化
   6. 获取当前Activity信息
   ```

#### iOS启动流程
1. **应用启动入口**
   ```
   Info.plist → AppDelegate → TSMainViewController → TSWebViewController
   ```

2. **初始化阶段** (`AppDelegate.didFinishLaunchingWithOptions`)
   ```objc
   1. 权限检查和申请
   2. 状态栏和导航栏配置
   3. 日志系统初始化
   4. 统计SDK初始化
   5. 微信API初始化
   6. 根视图控制器设置
   ```

#### HarmonyOS启动流程
1. **应用启动入口**
   ```
   module.json5 → EntryAbility → Index.ets → WebView.ets
   ```

2. **初始化阶段** (`EntryAbility.onCreate`)
   ```typescript
   1. 权限检查和申请
   2. 窗口属性配置
   3. 日志系统初始化
   4. 分析服务初始化
   5. 第三方SDK初始化
   6. 主页面加载
   ```

### 配置加载流程（通用）
```javascript
// 第一阶段：本地配置加载
1. 从本地存储读取游戏配置参数:
   - gamestart: 游戏启动目录
   - gamedir: 游戏父目录  
   - gameconfig: 游戏配置URL
   - agent: 代理ID
   - channel: 渠道号
   - market: 市场来源

// 第二阶段：版本检查
1. 检查是否首次安装
2. 从assets/bundle复制初始游戏资源
3. 检查本地版本与服务器版本
4. 决定是否需要更新游戏资源

// 第三阶段：资源更新
if (需要应用更新) {
    // 跳转到应用商店或下载APK/IPA
} else if (需要游戏资源更新) {
    下载游戏ZIP包 -> 解压到本地 -> 更新配置
} else {
    直接启动游戏
}

// 第四阶段：游戏启动
1. 初始化H5数据 (app_data.js)
2. 写入游戏配置参数到JS文件
3. 启动主游戏WebView页面
4. 完成启动流程
```

### 关键配置文件

#### version.json (版本配置)
```json
{
    "version": 1,
    "gameid": "game001",
    "name": "游戏名称",
    "platform": "all"
}
```

#### app_data.js (运行时配置)
```javascript
var app_version = 1;
var app_gameconfig = 'config_url';
var app_gamedir = 'game_directory';
var app_gamestart = 'start_file';
var app_agent = 'agent_id';
var app_channel = 'channel_id';
var app_market = 'market_id';
var app_platform = 'android|ios|harmonyos';
    下载游戏ZIP包 -> 解压到本地 -> 更新配置
} else {
    直接启动游戏
}
```

#### 第六阶段：游戏启动
```java
1. 初始化H5数据 (app_data.js)
2. 写入游戏配置参数到JS文件
3. 启动主游戏WebView页面
4. 完成启动流程
```

## WebView与原生交互API

项目使用自定义的JS桥接框架实现WebView与原生Android之间的双向通信。主要基于 `BridgeWebView` 实现。

### API快速参考表

| 功能分类 | API名称 | 调用方向 | 主要用途 |
|---------|---------|----------|----------|
| **认证登录** | `accreditlogin` | JS→Native | 触发微信/QQ登录 |
| | `sharelogin` | Native→JS | 登录结果回调 |
| **社交分享** | `friendsSharetypeUrlToptitleDescript` | JS→Native | 微信/抖音分享 |
| | `sharesuccess` | Native→JS | 分享结果回调 |
| **设备信息** | `getphoneInfo` | JS→Native | 获取设备基本信息 |
| | `getbattery` | JS→Native | 获取电池电量 |
| | `getwifiLevel` | JS→Native | 获取WiFi信号强度 |
| | `getnetwork` | JS→Native | 获取网络连接状态 |
| | `getTime` | JS→Native | 获取系统时间 |
| **多媒体** | `getphoto` | JS↔Native | 图片下载处理 |
| | `opensaoma` | JS→Native | 二维码扫描 |
| | `opencamera` | JS→Native | 拍照功能 |
| **音频** | `prepareaudio` | JS→Native | 录音准备 |
| | `mediaTypeAudio` | JS→Native | 音频播放 |
| | `voicePlaying` | JS→Native | 语音动画 |
| **音视频通话** | `createRoom` | JS→Native | 创建音视频房间 |
| | `exitRoom` | JS→Native | 退出音视频房间 |
| **定位服务** | `startlocation` | JS→Native | 开始定位 |
| | `getlocationinfo` | JS→Native | 获取位置信息 |
| | `locationinfo` | Native→JS | 定位结果回调 |
| **系统交互** | `vibrator` | JS→Native | 手机震动 |
| | `orientation` | JS→Native | 屏幕方向控制 |
| | `finsh` | JS→Native | 退出应用 |
| | `notification` | JS→Native | 系统通知 |
| **摇一摇** | `startshake` | JS→Native | 开始摇一摇监听 |
| | `stopshake` | JS→Native | 停止摇一摇 |
| | `shake` | Native→JS | 摇一摇事件回调 |
| **页面操作** | `OpenurlTitleData` | JS→Native | 打开新WebView页面 |
| | `browser` | JS→Native | 系统浏览器打开链接 |
| | `backgameData` | JS→Native | 返回并传递数据 |
| **复制粘贴** | `gameCopytext` | JS→Native | 复制文本到剪贴板 |
| | `gamepastetext` | JS→Native | 获取剪贴板内容 |
| **电话状态** | `getphonestate` | JS→Native | 获取电话状态 |
| | `phoneStateChanged` | Native→JS | 电话状态变化 |
| **应用管理** | `getGameinstall` | JS→Native | 检查应用安装状态 |
| | `getmarketname` | JS→Native | 获取市场来源 |
| **前后台** | `appservice` | Native→JS | 前后台状态通知 |

### 核心组件

#### 1. 桥接框架核心类
- **`BridgeWebView`**: 继承自腾讯X5 WebView，实现JS桥接功能
- **`BridgeHandler`**: 处理JS调用原生的接口
- **`CallBackFunction`**: 原生向JS回调的接口
- **`Message`**: 消息传递的数据模型

#### 2. JS桥接原理
```javascript
// JS端调用原生方法
WebViewJavascriptBridge.callHandler('handlerName', data, function(response) {
    console.log('Response from native:', response);
});

// JS端注册方法供原生调用
WebViewJavascriptBridge.registerHandler('jsHandlerName', function(data, responseCallback) {
    responseCallback('Response from JS');
});
```

```java
// 原生端注册方法供JS调用
x5webview.registerHandler("handlerName", new BridgeHandler() {
    @Override
    public void handler(String data, CallBackFunction function) {
        // 处理JS传来的数据
        function.onCallBack("Response from native");
    }
});

// 原生端调用JS方法
x5webview.callHandler("jsHandlerName", data, new CallBackFunction() {
    @Override
    public void onCallBack(String data) {
        // 处理JS的回调数据
    }
});
```

### 完整API接口详细说明

#### 1. 用户认证与登录类
| API名称 | 调用方向 | 参数 | 返回值 | 说明 |
|---------|----------|------|-------|------|
| `accreditlogin` | JS→Native | 登录类型 | 无 | 触发授权登录（支持微信/QQ） |
| `sharelogin` | Native→JS | 用户信息JSON | 无 | 登录成功后回传用户信息 |

**JS调用示例：**
```javascript
// 触发微信登录
WebViewJavascriptBridge.callHandler('accreditlogin', '2', function(response) {
    console.log('登录触发成功');
});
```

**用户信息JSON格式：**
```json
{
    "openid": "用户openid",
    "headimgurl": "头像URL",
    "nickname": "用户昵称",
    "sex": "性别(1男2女)",
    "city": "所在城市",
    "province": "所在省份",
    "unionid": "微信unionid"
}
```

#### 2. 社交分享功能
| API名称 | 调用方向 | 参数 | 返回值 | 说明 |
|---------|----------|------|-------|------|
| `friendsSharetypeUrlToptitleDescript` | JS→Native | 分享参数JSON | 无 | 微信分享（好友/朋友圈/抖音） |
| `sharesuccess` | Native→JS | 分享结果JSON | 无 | 分享结果回调 |

**JS调用示例：**
```javascript
// 微信好友分享
var shareData = {
    "type": "1",           // 1-普通分享, 2-截图分享, 3-图片分享  
    "sharefriend": "1",    // 1-好友, 2-朋友圈, 3-抖音
    "webpageUrl": "https://example.com",
    "title": "分享标题",
    "description": "分享描述",
    "sharetype": "link"
};
WebViewJavascriptBridge.callHandler('friendsSharetypeUrlToptitleDescript', JSON.stringify(shareData));
```

**分享结果回调：**
```javascript
// 注册分享结果监听
WebViewJavascriptBridge.registerHandler('sharesuccess', function(data) {
    var result = JSON.parse(data);
    if(result.success === 1) {
        console.log('分享成功');
    } else {
        console.log('分享失败');
    }
});
```

#### 3. 设备信息获取类
| API名称 | 调用方向 | 参数 | 返回值 | 说明 |
|---------|----------|------|-------|------|
| `getphoneInfo` | JS→Native | 无 | 设备信息JSON | 获取手机基本配置信息 |
| `getbattery` | JS→Native | 无 | 电量百分比 | 获取当前电池电量 |
| `getwifiLevel` | JS→Native | 无 | WiFi信息JSON | 获取WiFi信号强度和名称 |
| `getnetwork` | JS→Native | 无 | 网络状态 | 获取网络连接类型 |
| `getTime` | JS→Native | 无 | 时间戳 | 获取系统当前时间戳 |
| `getcompareCode` | JS→Native | 无 | 版本对比结果 | 获取APK版本对比结果 |

**JS调用示例：**
```javascript
// 获取设备信息
WebViewJavascriptBridge.callHandler('getphoneInfo', '', function(response) {
    var deviceInfo = JSON.parse(response);
    console.log('设备型号：' + deviceInfo.model);
    console.log('系统版本：' + deviceInfo.version);
});

// 获取网络状态
WebViewJavascriptBridge.callHandler('getnetwork', '', function(response) {
    // 返回值：1-无网络, 2-WiFi, 3-移动网络
    console.log('网络状态：' + response);
});
```

#### 4. 多媒体功能类
| API名称 | 调用方向 | 参数 | 返回值 | 说明 |
|---------|----------|------|-------|------|
| `getphoto` | JS→Native | 图片URL数组JSON | 无 | 批量下载网络图片到本地 |
| `opensaoma` | JS→Native | 无 | 扫码结果 | 打开相机扫描二维码 |
| `opencamera` | JS→Native | 无 | 图片路径 | 打开相机拍照 |

**图片下载示例：**
```javascript
// 批量下载图片
var imageUrls = ["http://example.com/1.jpg", "http://example.com/2.jpg"];
WebViewJavascriptBridge.callHandler('getphoto', JSON.stringify(imageUrls));

// 监听下载完成回调
WebViewJavascriptBridge.registerHandler('getphoto', function(data) {
    var result = JSON.parse(data);
    console.log('图片下载完成：' + result.localPath);
});
```

#### 5. 音频功能类
| API名称 | 调用方向 | 参数 | 返回值 | 说明 |
|---------|----------|------|-------|------|
| `prepareaudio` | JS→Native | 无 | 无 | 开始录音准备 |
| `mediaTypeAudio` | JS→Native | 音频参数JSON | 无 | 播放音频文件 |
| `voicePlaying` | JS→Native | 语音动画参数 | 无 | 显示语音播放动画 |
| `srcIsloop` | JS→Native | 循环播放参数 | 无 | 设置音频循环播放 |

**音频播放示例：**
```javascript
// 播放音频
var audioData = {
    "audiourl": "http://example.com/audio.mp3",
    "type": "1",           // 1-普通播放, 2-历史记录播放
    "user": "0"            // 用户位置索引
};
WebViewJavascriptBridge.callHandler('mediaTypeAudio', JSON.stringify(audioData));
```

#### 6. 实时音视频功能（声网Agora）
| API名称 | 调用方向 | 参数 | 返回值 | 说明 |
|---------|----------|------|-------|------|
| `createRoom` | JS→Native | 房间信息JSON | 无 | 创建或加入语音/视频房间 |
| `exitRoom` | JS→Native | 无 | 无 | 退出当前音视频房间 |
| `getVideoinfo` | JS→Native | 无 | 视频窗口信息JSON | 获取视频悬浮窗位置信息 |
| `DragViewvideoIsshow` | JS→Native | 显示类型 | 无 | 控制视频悬浮窗显示/隐藏 |

**房间管理示例：**
```javascript
// 创建音视频房间
var roomData = {
    "roomId": "12345",
    "userId": "user001",
    "token": "agora_token",
    "type": "video"        // audio 或 video
};
WebViewJavascriptBridge.callHandler('createRoom', JSON.stringify(roomData));

// 退出房间
WebViewJavascriptBridge.callHandler('exitRoom', '');
```

#### 7. 地理位置服务类
| API名称 | 调用方向 | 参数 | 返回值 | 说明 |
|---------|----------|------|-------|------|
| `startlocation` | JS→Native | 定位类型 | 无 | 开始GPS定位 |
| `getlocationinfo` | JS→Native | 无 | 位置信息JSON | 获取当前位置信息 |
| `locationinfo` | Native→JS | 位置信息JSON | 无 | 定位结果回调 |

**定位功能示例：**
```javascript
// 开始定位
WebViewJavascriptBridge.callHandler('startlocation', '1'); // 1-连续定位, 2-单次定位

// 监听定位结果
WebViewJavascriptBridge.registerHandler('locationinfo', function(data) {
    var location = JSON.parse(data);
    console.log('纬度：' + location.latitude);
    console.log('经度：' + location.longitude);
    console.log('地址：' + location.address);
});
```

#### 8. 系统交互功能类
| API名称 | 调用方向 | 参数 | 返回值 | 说明 |
|---------|----------|------|-------|------|
| `vibrator` | JS→Native | 震动时长(毫秒) | 无 | 手机震动指定时长 |
| `repeatvibrator` | JS→Native | 震动参数 | 无 | 重复震动 |
| `canclevibrator` | JS→Native | 无 | 无 | 取消所有震动 |
| `orientation` | JS→Native | 方向值 | 无 | 设置屏幕方向锁定 |
| `finsh` | JS→Native | 无 | 无 | 退出应用程序 |
| `notification` | JS→Native | 通知内容 | 无 | 发送系统通知 |

**系统交互示例：**
```javascript
// 震动500毫秒
WebViewJavascriptBridge.callHandler('vibrator', '500');

// 设置横屏
WebViewJavascriptBridge.callHandler('orientation', '0'); // 0-横屏, 1-竖屏

// 发送通知
WebViewJavascriptBridge.callHandler('notification', '您有新消息');
```

#### 9. 摇一摇功能类
| API名称 | 调用方向 | 参数 | 返回值 | 说明 |
|---------|----------|------|-------|------|
| `startshake` | JS→Native | 无 | 无 | 开始监听摇一摇动作 |
| `stopshake` | JS→Native | 无 | 无 | 停止监听摇一摇 |
| `SwitchShake` | JS→Native | 开关状态 | 无 | 摇一摇震动声音开关 |
| `shake` | Native→JS | 摇一摇事件 | 无 | 摇一摇动作回调 |

**摇一摇功能示例：**
```javascript
// 开始摇一摇监听
WebViewJavascriptBridge.callHandler('startshake', '');

// 监听摇一摇事件
WebViewJavascriptBridge.registerHandler('shake', function(data) {
    console.log('检测到摇一摇动作');
    // 处理摇一摇逻辑
});

// 停止摇一摇
WebViewJavascriptBridge.callHandler('stopshake', '');
```

#### 10. 网页操作类
| API名称 | 调用方向 | 参数 | 返回值 | 说明 |
|---------|----------|------|-------|------|
| `OpenurlTitleData` | JS→Native | 网页参数JSON | 无 | 打开新的WebView页面 |
| `browser` | JS→Native | URL | 无 | 使用系统浏览器打开链接 |
| `backgameData` | JS→Native | 返回数据 | 无 | 返回上级页面并传递数据 |

**页面跳转示例：**
```javascript
// 打开新页面
var pageData = {
    "url": "http://example.com/page.html",
    "title": "页面标题",
    "data": "传递数据",
    "orientation": "1"    // 0-横屏, 1-竖屏
};
WebViewJavascriptBridge.callHandler('OpenurlTitleData', JSON.stringify(pageData));

// 返回上级页面
WebViewJavascriptBridge.callHandler('backgameData', '返回的数据');
```

#### 11. 复制粘贴功能类
| API名称 | 调用方向 | 参数 | 返回值 | 说明 |
|---------|----------|------|-------|------|
| `gameCopytext` | JS→Native | 要复制的文本 | 无 | 复制文本到系统剪贴板 |
| `gamepastetext` | JS→Native | 无 | 剪贴板内容 | 获取剪贴板中的文本 |

**复制粘贴示例：**
```javascript
// 复制文本
WebViewJavascriptBridge.callHandler('gameCopytext', '要复制的文本内容');

// 获取剪贴板内容
WebViewJavascriptBridge.callHandler('gamepastetext', '', function(response) {
    console.log('剪贴板内容：' + response);
});
```

#### 12. 电话状态监听类
| API名称 | 调用方向 | 参数 | 返回值 | 说明 |
|---------|----------|------|-------|------|
| `getphonestate` | JS→Native | 无 | 电话状态码 | 获取当前电话通话状态 |
| `phoneStateChanged` | Native→JS | 状态码 | 无 | 电话状态变化回调 |

**电话状态监听示例：**
```javascript
// 获取电话状态
WebViewJavascriptBridge.callHandler('getphonestate', '', function(response) {
    // 0-空闲, 1-通话中, 2-来电振铃
    console.log('电话状态：' + response);
});

// 监听电话状态变化
WebViewJavascriptBridge.registerHandler('phoneStateChanged', function(data) {
    console.log('电话状态改变：' + data);
});
```

#### 13. 应用管理类
| API名称 | 调用方向 | 参数 | 返回值 | 说明 |
|---------|----------|------|-------|------|
| `getGameinstall` | JS→Native | 包名 | 安装状态 | 检查指定应用是否已安装 |
| `openApplyDownloadpath` | JS→Native | 无 | 无 | 打开应用下载安装包 |
| `getmarketname` | JS→Native | 无 | 市场标识 | 获取应用市场来源标识 |
| `getothername` | JS→Native | 文件夹名 | 自定义名称 | 获取自定义文件夹名称 |
| `getOther` | JS→Native | 无 | 其他信息 | 获取其他配置信息 |

**应用管理示例：**
```javascript
// 检查应用是否安装
WebViewJavascriptBridge.callHandler('getGameinstall', 'com.tencent.mm', function(response) {
    if(response === '1') {
        console.log('微信已安装');
    } else {
        console.log('微信未安装');
    }
});

// 获取市场来源
WebViewJavascriptBridge.callHandler('getmarketname', '', function(response) {
    console.log('市场来源：' + response);
});
```

#### 14. 前后台状态管理类
| API名称 | 调用方向 | 参数 | 返回值 | 说明 |
|---------|----------|------|-------|------|
| `SwitchOverGameData` | JS→Native | 流量提醒参数 | 无 | 设置移动网络流量提醒 |
| `appservice` | Native→JS | 前后台状态 | 无 | 应用前后台状态变化通知 |

**前后台监听示例：**
```javascript
// 监听应用前后台状态
WebViewJavascriptBridge.registerHandler('appservice', function(data) {
    if(data === '1') {
        console.log('应用进入前台');
        // 恢复游戏逻辑
    } else if(data === '2') {
        console.log('应用进入后台');
        // 暂停游戏逻辑
    }
});
```

#### 15. 通讯录功能类（已禁用）
| API名称 | 调用方向 | 参数 | 返回值 | 说明 |
|---------|----------|------|-------|------|
| `getAddressBook` | JS→Native | 无 | 通讯录数据 | 获取手机通讯录（已注释禁用） |

> **注意**: 通讯录功能因隐私政策要求已被注释禁用。

### 技术实现细节

#### JS桥接机制
项目采用自定义的JS Bridge实现WebView与原生的双向通信：

**核心组件：**
- `BridgeWebView.java` - 继承腾讯X5 WebView，实现桥接功能
- `BridgeHandler.java` - 原生端消息处理接口
- `CallBackFunction.java` - JS回调函数接口
- `Message.java` - 消息实体类
- `WebViewJavascriptBridge.js` - JS端桥接脚本

**消息传递流程：**
1. JS调用原生：`WebViewJavascriptBridge.callHandler(handlerName, data, callback)`
2. 消息序列化并添加到消息队列
3. 通过`loadUrl()`触发原生方法`flushMessageQueue()`
4. 原生端解析消息并调用对应的`BridgeHandler`
5. 处理完成后通过`CallBackFunction`返回结果给JS

**线程安全保证：**
```java
// 确保JS调用在主线程执行
if (Thread.currentThread() == Looper.getMainLooper().getThread()) {
    this.loadUrl(javascriptCommand);
}
```

#### 权限管理机制
应用采用动态权限申请机制，主要权限包括：

**存储权限（必需）：**
```java
// 动态申请存储权限
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
    if (ContextCompat.checkSelfPermission(this, 
        Manifest.permission.WRITE_EXTERNAL_STORAGE) != PackageManager.PERMISSION_GRANTED) {
        ActivityCompat.requestPermissions(this, 
            new String[]{Manifest.permission.WRITE_EXTERNAL_STORAGE}, 1);
    }
}
```

**位置权限（可选）：**
- GPS定位：`ACCESS_FINE_LOCATION`
- 网络定位：`ACCESS_COARSE_LOCATION`

**音频权限（可选）：**
- 录音权限：`RECORD_AUDIO`
- 音频设置：`MODIFY_AUDIO_SETTINGS`

#### 资源更新机制
项目支持热更新，无需重新安装APK即可更新游戏内容：

**更新流程：**
1. 检查本地版本文件`version.xml`
2. 请求服务器版本信息
3. 比较版本号决定更新策略：
   - APK版本更新：下载新APK并提示安装
   - 资源版本更新：下载资源ZIP包并解压
4. 更新本地版本文件
5. 重新加载游戏

**版本控制文件：**
```xml
<!-- version.xml -->
<version>
    <version>资源版本号</version>
    <gameid>游戏标识</gameid>
    <name>游戏名称</name>
</version>
```

#### 微信SDK集成
项目集成微信开放平台SDK，支持登录、分享功能：

**回调Activity配置：**
```xml
<!-- 微信登录回调 -->
<activity
    android:name=".wxapi.WXEntryActivity"
    android:exported="true"
    android:launchMode="singleTop" />
```

**分享实现：**
- 支持链接分享、图片分享、小程序分享
- 区分好友分享和朋友圈分享
- 抖音分享通过Intent方式实现

#### 音视频功能
集成声网Agora SDK实现实时音视频通话：

**基本功能：**
- 语音房间创建/加入
- 实时语音通话
- 视频悬浮窗显示
- 音频录制播放

**房间管理：**
```javascript
// 创建音视频房间
var roomConfig = {
    "roomId": "房间ID",
    "userId": "用户ID", 
    "token": "Agora Token",
    "channelProfile": "COMMUNICATION"
};
```

#### 定位服务
基于高德地图SDK实现精确定位：

**定位模式：**
- 连续定位：持续获取位置更新
- 单次定位：获取一次高精度位置

**位置信息回调：**
```javascript
// 位置信息格式
{
    "latitude": "31.12345",    // 纬度
    "longitude": "121.12345",  // 经度  
    "accuracy": "15.0",        // 精度(米)
    "address": "详细地址",
    "city": "城市名称",
    "province": "省份"
}
```

### API调用最佳实践

#### 1. 错误处理
```javascript
// JS端错误处理
WebViewJavascriptBridge.callHandler('apiName', data, function(response) {
    try {
        var result = JSON.parse(response);
        if(result.success) {
            // 处理成功逻辑
        } else {
            console.error('API调用失败:', result.error);
        }
    } catch(e) {
        console.error('响应解析失败:', e);
    }
});
```

#### 2. 生命周期管理
```java
// 原生端生命周期处理
@Override
protected void onDestroy() {
    super.onDestroy();
    // 清理WebView
    if(x5webview != null) {
        x5webview.removeAllViews();
        x5webview.destroy();
        x5webview = null;
    }
    // 停止定位服务
    if(locationClient != null) {
        locationClient.stopLocation();
    }
}
```

#### 3. 内存优化
```java
// WebView内存优化
public void optimizeWebView() {
    // 清除缓存
    x5webview.clearCache(true);
    // 清除历史记录
    x5webview.clearHistory();
    // 暂停JavaScript执行
    x5webview.onPause();
    x5webview.pauseTimers();
}
```

#### 4. 网络优化
```java
// 网络状态监听
private void checkNetworkState() {
    ConnectivityManager cm = (ConnectivityManager) 
        getSystemService(Context.CONNECTIVITY_SERVICE);
    NetworkInfo activeNetwork = cm.getActiveNetworkInfo();
    
    if(activeNetwork != null && activeNetwork.isConnected()) {
        if(activeNetwork.getType() == ConnectivityManager.TYPE_WIFI) {
            // WiFi连接
            notifyJSNetworkState("2");
        } else {
            // 移动网络连接
            notifyJSNetworkState("3");
        }
    } else {
        // 无网络连接
        notifyJSNetworkState("1");
    }
}
```

### 调试和测试

#### WebView调试
```java
// 启用WebView调试模式
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.KITKAT) {
    WebView.setWebContentsDebuggingEnabled(true);
}
```

在Chrome浏览器中访问 `chrome://inspect` 可以调试WebView内容。

#### JS Bridge测试
```javascript
// 测试桥接连通性
function testBridge() {
    if(typeof WebViewJavascriptBridge !== 'undefined') {
        console.log('Bridge已就绪');
        // 测试简单API调用
        WebViewJavascriptBridge.callHandler('getTime', '', function(response) {
            console.log('当前时间:', response);
        });
    } else {
        console.error('Bridge未初始化');
    }
}
```

#### 性能监控
```java
// 监控WebView性能
public class WebViewPerformanceMonitor {
    private long pageStartTime;
    
    @Override
    public void onPageStarted(WebView view, String url, Bitmap favicon) {
        pageStartTime = System.currentTimeMillis();
    }
    
    @Override
    public void onPageFinished(WebView view, String url) {
        long loadTime = System.currentTimeMillis() - pageStartTime;
        Log.d("Performance", "页面加载耗时: " + loadTime + "ms");
    }
}
```

### 常见问题和解决方案

#### 1. JS Bridge不响应
**问题**: JS调用原生方法无响应
**解决方案**: 
- 检查WebView是否已完全加载
- 确认Handler名称拼写正确
- 验证是否在主线程调用

#### 2. 分享功能失效
**问题**: 微信分享无法拉起
**解决方案**:
- 检查微信SDK版本兼容性
- 验证应用签名是否与微信开放平台一致
- 确认回调Activity配置正确

#### 3. 定位权限问题
**问题**: 无法获取位置信息
**解决方案**:
- 动态申请定位权限
- 检查GPS是否开启
- 验证高德SDK配置

#### 4. 音视频通话异常
**问题**: 声网通话质量差或连接失败
**解决方案**:
- 检查网络连接质量
- 验证Agora Token有效性
- 优化音频编码参数

### 完整集成示例

#### 前端HTML页面集成示例
```html
<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>TSGame Web</title>
</head>
<body>
    <div id="app">
        <button onclick="loginWithWeChat()">微信登录</button>
        <button onclick="shareToWeChat()">微信分享</button>
        <button onclick="getDeviceInfo()">获取设备信息</button>
        <button onclick="startLocation()">开始定位</button>
        <button onclick="takePhoto()">拍照</button>
        <button onclick="playAudio()">播放音频</button>
        <button onclick="startShake()">开始摇一摇</button>
    </div>

    <script>
        // 初始化Bridge连接
        function connectWebViewJavascriptBridge(callback) {
            if (window.WebViewJavascriptBridge) {
                callback(WebViewJavascriptBridge);
            } else {
                document.addEventListener('WebViewJavascriptBridgeReady', function() {
                    callback(WebViewJavascriptBridge);
                }, false);
            }
        }

        // 等待Bridge就绪
        connectWebViewJavascriptBridge(function(bridge) {
            console.log('Bridge连接成功');
            
            // 注册接收原生回调的方法
            bridge.registerHandler('sharelogin', function(data) {
                var userInfo = JSON.parse(data);
                console.log('登录成功:', userInfo);
                alert('欢迎 ' + userInfo.nickname);
            });

            bridge.registerHandler('sharesuccess', function(data) {
                var result = JSON.parse(data);
                if(result.success === 1) {
                    alert('分享成功');
                } else {
                    alert('分享失败');
                }
            });

            bridge.registerHandler('locationinfo', function(data) {
                var location = JSON.parse(data);
                console.log('定位结果:', location);
                alert('当前位置: ' + location.address);
            });

            bridge.registerHandler('shake', function(data) {
                console.log('检测到摇一摇');
                alert('摇一摇触发!');
            });

            bridge.registerHandler('appservice', function(data) {
                if(data === '1') {
                    console.log('应用进入前台');
                } else if(data === '2') {
                    console.log('应用进入后台');
                }
            });
        });

        // 微信登录
        function loginWithWeChat() {
            WebViewJavascriptBridge.callHandler('accreditlogin', '2', function(response) {
                console.log('登录请求已发送');
            });
        }

        // 微信分享
        function shareToWeChat() {
            var shareData = {
                "type": "1",
                "sharefriend": "1",
                "webpageUrl": "https://example.com",
                "title": "精彩棋牌游戏",
                "description": "快来和朋友一起玩棋牌游戏吧！"
            };
            WebViewJavascriptBridge.callHandler('friendsSharetypeUrlToptitleDescript', 
                JSON.stringify(shareData));
        }

        // 获取设备信息
        function getDeviceInfo() {
            WebViewJavascriptBridge.callHandler('getphoneInfo', '', function(response) {
                var deviceInfo = JSON.parse(response);
                console.log('设备信息:', deviceInfo);
                alert('设备型号: ' + deviceInfo.model);
            });
        }

        // 开始定位
        function startLocation() {
            WebViewJavascriptBridge.callHandler('startlocation', '2'); // 单次定位
        }

        // 拍照
        function takePhoto() {
            WebViewJavascriptBridge.callHandler('opencamera', '', function(imagePath) {
                console.log('照片路径:', imagePath);
                if(imagePath) {
                    // 显示拍摄的照片
                    var img = document.createElement('img');
                    img.src = 'file://' + imagePath;
                    img.style.maxWidth = '300px';
                    document.body.appendChild(img);
                }
            });
        }

        // 播放音频
        function playAudio() {
            var audioData = {
                "audiourl": "https://example.com/audio.mp3",
                "type": "1",
                "user": "0"
            };
            WebViewJavascriptBridge.callHandler('mediaTypeAudio', JSON.stringify(audioData));
        }

        // 开始摇一摇
        function startShake() {
            WebViewJavascriptBridge.callHandler('startshake', '');
            alert('开始摇一摇监听，请摇动手机');
        }

        // 获取网络状态
        function checkNetwork() {
            WebViewJavascriptBridge.callHandler('getnetwork', '', function(response) {
                var status = ['无网络', 'WiFi', '移动网络'][parseInt(response) - 1];
                alert('网络状态: ' + status);
            });
        }

        // 复制文本
        function copyText() {
            var text = '这是要复制的文本内容';
            WebViewJavascriptBridge.callHandler('gameCopytext', text);
            alert('已复制到剪贴板');
        }

        // 获取剪贴板内容
        function pasteText() {
            WebViewJavascriptBridge.callHandler('gamepastetext', '', function(response) {
                alert('剪贴板内容: ' + response);
            });
        }

        // 震动
        function vibrate() {
            WebViewJavascriptBridge.callHandler('vibrator', '500'); // 震动500毫秒
        }

        // 退出应用
        function exitApp() {
            if(confirm('确定要退出应用吗？')) {
                WebViewJavascriptBridge.callHandler('finsh', '');
            }
        }
    </script>
</body>
</html>
```

#### 原生端集成示例
```java
public class GameWebViewActivity extends Activity {
    private BridgeWebView webView;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_webview);

        // 初始化WebView
        webView = findViewById(R.id.webview);
        setupWebView();
        registerHandlers();

        // 加载游戏页面
        webView.loadUrl("file:///android_asset/game.html");
    }

    private void setupWebView() {
        WebSettings settings = webView.getSettings();
        settings.setJavaScriptEnabled(true);
        settings.setDomStorageEnabled(true);
        settings.setAllowFileAccess(true);
        settings.setAllowContentAccess(true);

        // 设置UserAgent
        String userAgent = settings.getUserAgentString();
        settings.setUserAgentString(userAgent + " TSGame/1.0");
    }

    private void registerHandlers() {
        // 注册登录处理
        webView.registerHandler("accreditlogin", new BridgeHandler() {
            @Override
            public void handler(String data, CallBackFunction function) {
                if("2".equals(data)) {
                    // 触发微信登录
                    wechatLogin();
                }
                function.onCallBack("success");
            }
        });

        // 注册分享处理
        webView.registerHandler("friendsSharetypeUrlToptitleDescript", new BridgeHandler() {
            @Override
            public void handler(String data, CallBackFunction function) {
                try {
                    JSONObject shareData = new JSONObject(data);
                    String type = shareData.getString("type");
                    String shareType = shareData.getString("sharefriend");
                    
                    if("1".equals(shareType)) {
                        // 微信好友分享
                        shareToWechatFriend(shareData);
                    } else if("2".equals(shareType)) {
                        // 微信朋友圈分享
                        shareToWechatTimeline(shareData);
                    }
                } catch (JSONException e) {
                    e.printStackTrace();
                }
            }
        });

        // 注册设备信息处理
        webView.registerHandler("getphoneInfo", new BridgeHandler() {
            @Override
            public void handler(String data, CallBackFunction function) {
                JSONObject deviceInfo = getDeviceInfo();
                function.onCallBack(deviceInfo.toString());
            }
        });

        // 注册定位处理
        webView.registerHandler("startlocation", new BridgeHandler() {
            @Override
            public void handler(String data, CallBackFunction function) {
                if("1".equals(data)) {
                    startContinuousLocation();
                } else {
                    startSingleLocation();
                }
            }
        });

        // 注册拍照处理
        webView.registerHandler("opencamera", new BridgeHandler() {
            @Override
            public void handler(String data, CallBackFunction function) {
                cameraCallback = function;
                openCamera();
            }
        });
    }

    private void wechatLogin() {
        // 微信登录实现
        SendAuth.Req req = new SendAuth.Req();
        req.scope = "snsapi_userinfo";
        req.state = "tsgame_login";
        api.sendReq(req);
    }

    private JSONObject getDeviceInfo() {
        JSONObject info = new JSONObject();
        try {
            info.put("model", Build.MODEL);
            info.put("brand", Build.BRAND);
            info.put("version", Build.VERSION.RELEASE);
            info.put("sdk", Build.VERSION.SDK_INT);
            
            DisplayMetrics dm = getResources().getDisplayMetrics();
            info.put("screenWidth", dm.widthPixels);
            info.put("screenHeight", dm.heightPixels);
            info.put("density", dm.density);
        } catch (JSONException e) {
            e.printStackTrace();
        }
        return info;
    }

    // 微信登录成功回调
    public void onWechatLoginSuccess(String openId, String nickname, String headUrl) {
        JSONObject userInfo = new JSONObject();
        try {
            userInfo.put("openid", openId);
            userInfo.put("nickname", nickname);
            userInfo.put("headimgurl", headUrl);
            
            // 回调给JS
            webView.callHandler("sharelogin", userInfo.toString(), null);
        } catch (JSONException e) {
            e.printStackTrace();
        }
    }

    // 定位成功回调
    public void onLocationSuccess(double lat, double lng, String address) {
        JSONObject location = new JSONObject();
        try {
            location.put("latitude", String.valueOf(lat));
            location.put("longitude", String.valueOf(lng));
            location.put("address", address);
            
            // 回调给JS
            webView.callHandler("locationinfo", location.toString(), null);
        } catch (JSONException e) {
            e.printStackTrace();
        }
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        if(webView != null) {
            webView.removeAllViews();
            webView.destroy();
        }
    }
}
```

这个完整的集成示例展示了：
1. 前端HTML页面如何初始化Bridge连接
2. 如何注册监听原生回调
3. 如何调用各种原生API
4. 原生端如何注册Handler处理JS调用
5. 如何实现完整的登录、分享、定位等功能流程

通过这个示例，开发者可以快速理解和集成TSGame的WebView与原生交互功能。

#### JS端调用原生方法示例
```javascript
// 1. 获取设备信息
WebViewJavascriptBridge.callHandler('getphoneInfo', '', function(response) {
    console.log('设备信息:', response);
});

// 2. 微信分享
var shareData = {
    type: "1",
    sharefriend: "1", 
    webpageUrl: "https://example.com",
    title: "分享标题",
    description: "分享描述"
};
WebViewJavascriptBridge.callHandler('friendsSharetypeUrlToptitleDescript', 
    JSON.stringify(shareData));

// 3. 震动效果
WebViewJavascriptBridge.callHandler('vibrator', '500');
```

#### 原生端调用JS方法示例
```java
// 1. 发送用户登录信息给JS
JSONObject userInfo = new JSONObject();
userInfo.put("openid", openid);
userInfo.put("nickname", nickname);
x5webview.callHandler("sharelogin", userInfo.toString(), 
    new CallBackFunction() {
        @Override
        public void onCallBack(String data) {
            // JS的回调处理
        }
    });

// 2. 通知JS分享结果
JSONObject result = new JSONObject();
result.put("success", 1);
result.put("type", "1");
x5webview.callHandler("sharesuccess", result.toString(), null);
```

### 注意事项

#### 数据传递规范
1. **数据格式**: 所有传递的数据都是字符串格式，复杂数据需要JSON序列化
2. **异步回调**: 大部分API都支持异步回调机制
3. **错误处理**: 需要在JS和原生端都做好异常处理
4. **线程安全**: 原生端调用JS必须在主线程进行
5. **生命周期**: 注意WebView生命周期，避免内存泄漏

#### WebView与原生通信注意事项
1. **消息队列**: 使用消息队列机制确保数据不丢失
2. **特殊字符转义**: JSON字符串中的特殊字符需要转义处理
3. **回调函数**: 每个API调用可以包含一个回调函数
4. **超时处理**: 长时间无响应的API调用需要超时机制

#### 性能优化建议
1. **减少频繁调用**: 避免在短时间内频繁调用原生API
2. **数据压缩**: 传递大量数据时考虑压缩或分批传输
3. **内存管理**: 及时释放不需要的WebView资源
4. **缓存策略**: 合理利用WebView缓存机制

#### 安全性考虑
1. **数据校验**: 对JS传入的数据进行严格校验
2. **权限控制**: 敏感API需要权限检查
3. **防注入**: 防范恶意JS代码注入
4. **HTTPS通信**: 敏感数据传输使用HTTPS

#### 兼容性处理
1. **Android版本**: 针对不同Android版本做适配
2. **设备差异**: 考虑不同设备的硬件差异
3. **WebView版本**: 处理不同WebView内核版本的差异
4. **网络环境**: 适配不同网络环境下的功能表现

### 3. 主要Activity流转

```
weclomeactivity1 (启动页)
    ↓ (配置加载完成)
webviewActivity/NewwebviewActivity (主游戏页面)
    ↓ (外部链接)
openwebActivity1 (外部页面)
    ↓ (微信回调)
WXEntryActivity (微信相关)
```

### 4. 关键配置文件

#### version.xml (版本配置)
```xml
<version>
    <version>1</version>
    <gameid>game001</gameid>
    <name>游戏名称</name>
</version>
```

#### app_data.js (运行时配置)
```javascript
var app_version = 1;
var app_gameconfig = 'config_url';
var app_gamedir = 'game_directory';
var app_gamestart = 'start_file';
var app_agent = 'agent_id';
var app_channel = 'channel_id';
var app_market = 'market_id';
```

## 平台技术栈与第三方服务

### Android平台
#### 开发工具和框架
- **Gradle**: 7.0+ (构建工具)
- **Android SDK**: API 33
- **最低支持**: API 21 (Android 5.0)
- **开发语言**: Java 1.8 / Kotlin 1.8
- **IDE**: Android Studio

#### 第三方SDK集成
| 功能模块 | Android SDK | 版本 |
|---------|-------------|------|
| **WebView** | 腾讯X5 WebView | 44286 |
| **网络请求** | OkHttp | 4.12.0 |
| **JSON解析** | Gson | 2.8.9 |
| **微信SDK** | 微信开放平台SDK | 6.8.11 |
| **地图定位** | 高德地图SDK | 5.2.0 |
| **音视频** | 声网Agora SDK | 最新版 |
| **统计分析** | 友盟统计 | 7.5.0 |
| **崩溃收集** | 腾讯Bugly | 3.4.4 |
| **二维码扫描** | ZXing | 3.5.0 |

### iOS平台
#### 开发工具和框架
- **Xcode**: 14.0+
- **iOS SDK**: iOS 16.0
- **最低支持**: iOS 11.0
- **开发语言**: Objective-C / Swift 5.0
- **依赖管理**: CocoaPods / Swift Package Manager

#### 第三方SDK集成
| 功能模块 | iOS SDK | 版本 |
|---------|---------|------|
| **WebView** | WKWebView (系统) | - |
| **网络请求** | AFNetworking / Alamofire | 5.0+ |
| **JSON解析** | 系统JSONSerialization | - |
| **微信SDK** | 微信开放平台SDK | 1.9.2 |
| **地图定位** | 高德地图SDK / CoreLocation | 9.0+ |
| **音视频** | 声网Agora SDK | 最新版 |
| **统计分析** | 友盟统计 / Firebase | 最新版 |
| **崩溃收集** | Bugly / Crashlytics | 最新版 |
| **二维码扫描** | AVFoundation (系统) | - |

### HarmonyOS平台
#### 开发工具和框架
- **DevEco Studio**: 4.0+
- **HarmonyOS SDK**: API 9
- **最低支持**: API 8 (HarmonyOS 3.0)
- **开发语言**: ArkTS / TypeScript
- **应用模型**: Stage模型

#### 第三方SDK集成
| 功能模块 | HarmonyOS SDK | 版本 |
|---------|---------------|------|
| **WebView** | Web组件 (系统) | - |
| **网络请求** | @ohos.net.http | 系统API |
| **JSON解析** | JSON (系统) | - |
| **微信SDK** | 微信开放平台SDK | 待适配 |
| **地图定位** | 华为地图服务 | 最新版 |
| **音视频** | 声网Agora SDK | 最新版 |
| **统计分析** | 华为分析服务 | 最新版 |
| **崩溃收集** | 华为崩溃服务 | 最新版 |
| **二维码扫描** | @ohos.multimedia.camera | 系统API |

### 跨平台共享组件
- **H5游戏引擎**: HTML5 + CSS3 + JavaScript
- **JS Bridge**: 统一接口定义
- **音视频通话**: 声网Agora SDK（全平台支持）
- **数据存储**: 本地存储 + 云端同步
- **配置管理**: JSON配置文件

## 跨平台权限管理

### Android权限配置
#### 核心权限
```xml
<!-- AndroidManifest.xml -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
```

#### 定位权限
```xml
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
```

#### 音频权限
```xml
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
```

#### 其他权限
```xml
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.VIBRATE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.REQUEST_INSTALL_PACKAGES" />
```

### iOS权限配置
#### Info.plist配置
```xml
<!-- Info.plist -->
<key>NSCameraUsageDescription</key>
<string>应用需要使用相机进行拍照功能</string>

<key>NSMicrophoneUsageDescription</key>
<string>应用需要使用麦克风进行语音通话</string>

<key>NSLocationWhenInUseUsageDescription</key>
<string>应用需要获取位置信息提供定位服务</string>

<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>应用需要获取位置信息提供定位服务</string>

<key>NSPhotoLibraryUsageDescription</key>
<string>应用需要访问相册选择图片</string>

<key>NSContactsUsageDescription</key>
<string>应用需要访问通讯录获取联系人信息</string>
```

#### App Transport Security
```xml
<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>
```

### HarmonyOS权限配置
#### module.json5配置
```json
{
  "requestPermissions": [
    {
      "name": "ohos.permission.INTERNET",
      "reason": "网络访问",
      "usedScene": {
        "abilities": ["EntryAbility"],
        "when": "inuse"
      }
    },
    {
      "name": "ohos.permission.LOCATION",
      "reason": "获取位置信息",
      "usedScene": {
        "abilities": ["EntryAbility"],
        "when": "inuse"
      }
    },
    {
      "name": "ohos.permission.CAMERA",
      "reason": "拍照功能",
      "usedScene": {
        "abilities": ["EntryAbility"],
        "when": "inuse"
      }
    },
    {
      "name": "ohos.permission.MICROPHONE",
      "reason": "录音功能",
      "usedScene": {
        "abilities": ["EntryAbility"],
        "when": "inuse"
      }
    },
    {
      "name": "ohos.permission.READ_MEDIA",
      "reason": "读取媒体文件",
      "usedScene": {
        "abilities": ["EntryAbility"],
        "when": "inuse"
      }
    },
    {
      "name": "ohos.permission.WRITE_MEDIA",
      "reason": "写入媒体文件",
      "usedScene": {
        "abilities": ["EntryAbility"],
        "when": "inuse"
      }
    }
  ]
}
```

### 权限动态申请代码示例

#### Android权限申请
```java
// 检查和申请权限
private void checkPermissions() {
    String[] permissions = {
        Manifest.permission.WRITE_EXTERNAL_STORAGE,
        Manifest.permission.CAMERA,
        Manifest.permission.RECORD_AUDIO,
        Manifest.permission.ACCESS_FINE_LOCATION
    };
    
    List<String> permissionsToRequest = new ArrayList<>();
    for (String permission : permissions) {
        if (ContextCompat.checkSelfPermission(this, permission) 
            != PackageManager.PERMISSION_GRANTED) {
            permissionsToRequest.add(permission);
        }
    }
    
    if (!permissionsToRequest.isEmpty()) {
        ActivityCompat.requestPermissions(this, 
            permissionsToRequest.toArray(new String[0]), 
            REQUEST_PERMISSIONS);
    }
}
```

#### iOS权限申请
```objc
// 请求相机权限
- (void)requestCameraPermission {
    AVAuthorizationStatus status = [AVCaptureDevice authorizationStatusForMediaType:AVMediaTypeVideo];
    if (status == AVAuthorizationStatusNotDetermined) {
        [AVCaptureDevice requestAccessForMediaType:AVMediaTypeVideo completionHandler:^(BOOL granted) {
            dispatch_async(dispatch_get_main_queue(), ^{
                if (granted) {
                    // 权限获取成功
                } else {
                    // 权限被拒绝
                }
            });
        }];
    }
}

// 请求定位权限
- (void)requestLocationPermission {
    CLLocationManager *locationManager = [[CLLocationManager alloc] init];
    [locationManager requestWhenInUseAuthorization];
}
```

#### HarmonyOS权限申请
```typescript
// 申请权限
import abilityAccessCtrl, { Permissions } from '@ohos.abilityAccessCtrl';

async requestPermissions() {
  const atManager = abilityAccessCtrl.createAtManager();
  const permissions: Permissions[] = [
    'ohos.permission.CAMERA',
    'ohos.permission.MICROPHONE',
    'ohos.permission.LOCATION'
  ];
  
  try {
    await atManager.requestPermissionsFromUser(this.context, permissions);
    console.log('权限申请成功');
  } catch (error) {
    console.log('权限申请失败:', error);
  }
}
```

## 安全配置

### 签名配置
- **Keystore**: gamehall.keystore
- **密码**: tswl2015
- **别名**: gamehall
- **签名版本**: v1 + v2

### 网络安全
- `usesCleartextTraffic="true"` - 允许HTTP流量
- 支持HTTPS和HTTP混合请求

### 文件权限
- 使用FileProvider共享文件
- 适配Android 7.0+文件访问限制

## 跨平台构建和发布

### Android平台构建
#### 环境要求
- **JDK**: OpenJDK 11+
- **Android Studio**: 2022.1.1+
- **Gradle**: 7.0+
- **Android SDK**: API 33

#### 构建命令
```bash
# 调试版本
./gradlew assembleDebug

# 发布版本  
./gradlew assembleRelease

# 清理项目
./gradlew clean

# 生成签名APK
./gradlew assembleRelease -Pandroid.injected.signing.store.file=keystore/gamehall.keystore
```

#### 签名配置
```gradle
// app/build.gradle
android {
    signingConfigs {
        release {
            storeFile file('../keystore/gamehall.keystore')
            storePassword 'tswl2015'
            keyAlias 'gamehall'
            keyPassword 'tswl2015'
        }
    }
    
    buildTypes {
        release {
            signingConfig signingConfigs.release
            minifyEnabled false
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
}
```

### iOS平台构建
#### 环境要求
- **macOS**: 12.0+
- **Xcode**: 14.0+
- **iOS SDK**: 16.0+
- **CocoaPods**: 1.11+

#### 构建步骤
```bash
# 安装依赖
cd ios
pod install

# 清理项目
xcodebuild clean -workspace TSGame.xcworkspace -scheme TSGame

# 构建Debug版本
xcodebuild build -workspace TSGame.xcworkspace -scheme TSGame -configuration Debug

# 构建Release版本
xcodebuild archive -workspace TSGame.xcworkspace -scheme TSGame -configuration Release -archivePath build/TSGame.xcarchive

# 导出IPA
xcodebuild -exportArchive -archivePath build/TSGame.xcarchive -exportPath build/ipa -exportOptionsPlist ExportOptions.plist
```

#### 证书配置
```xml
<!-- ExportOptions.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>method</key>
    <string>app-store</string>
    <key>teamID</key>
    <string>YOUR_TEAM_ID</string>
    <key>provisioningProfiles</key>
    <dict>
        <key>com.jx.jyhd</key>
        <string>YOUR_PROVISIONING_PROFILE</string>
    </dict>
</dict>
</plist>
```

### HarmonyOS平台构建
#### 环境要求
- **DevEco Studio**: 4.0+
- **HarmonyOS SDK**: API 9
- **Node.js**: 16.0+
- **npm**: 8.0+

#### 构建步骤
```bash
# 清理项目
hvigorw clean

# 构建Debug版本
hvigorw assembleHap --mode module -p module=entry@default -p debuggable=true

# 构建Release版本
hvigorw assembleHap --mode module -p module=entry@default -p debuggable=false

# 构建APP包
hvigorw assembleApp --mode module -p module=entry@default
```

#### 签名配置
```json5
// build-profile.json5
{
  "app": {
    "signingConfigs": [
      {
        "name": "default",
        "type": "HarmonyOS",
        "material": {
          "certpath": "path/to/certificate.p12",
          "storePassword": "your_password",
          "keyAlias": "your_key_alias",
          "keyPassword": "your_key_password",
          "profile": "path/to/profile.p7b",
          "signAlg": "SHA256withECDSA",
          "verify": true,
          "compatibleVersion": 9
        }
      }
    ]
  }
}
```

### 自动化构建配置

#### CI/CD流水线 (GitHub Actions)
```yaml
# .github/workflows/build.yml
name: Multi-Platform Build

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  build-android:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Set up JDK 11
      uses: actions/setup-java@v3
      with:
        java-version: '11'
        distribution: 'adopt'
    - name: Build Android APK
      run: |
        cd android
        ./gradlew assembleRelease
    - name: Upload APK
      uses: actions/upload-artifact@v3
      with:
        name: android-apk
        path: android/app/build/outputs/apk/release/

  build-ios:
    runs-on: macos-latest
    steps:
    - uses: actions/checkout@v3
    - name: Set up Xcode
      uses: maxim-lobanov/setup-xcode@v1
      with:
        xcode-version: '14.0'
    - name: Install CocoaPods
      run: |
        cd ios
        pod install
    - name: Build iOS
      run: |
        cd ios
        xcodebuild build -workspace TSGame.xcworkspace -scheme TSGame -configuration Release

  build-harmonyos:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - name: Set up Node.js
      uses: actions/setup-node@v3
      with:
        node-version: '16'
    - name: Build HarmonyOS
      run: |
        cd harmonyos
        npm install
        hvigorw assembleHap --mode module -p module=entry@default
```

### 发布配置

#### Android发布
- **Google Play Store**: 上传AAB包，配置应用签名
- **国内应用市场**: 上传APK包到各大应用商店
- **企业分发**: 配置内部分发渠道

#### iOS发布
- **App Store**: 通过App Store Connect上传IPA
- **TestFlight**: 内测版本分发
- **企业证书**: 企业内部分发

#### HarmonyOS发布
- **华为应用市场**: 上传HAP/APP包
- **企业分发**: 通过华为开发者平台配置

## 跨平台开发指南

### 平台适配策略
#### 1. 功能对等原则
确保各平台实现相同的核心功能，但可根据平台特性进行优化：
- **必须功能**: 游戏核心玩法、登录认证、基础分享
- **平台特色**: 分享渠道、推送通知
- **性能优化**: 根据平台特性调整渲染和网络策略

#### 2. 统一接口设计
所有平台实现相同的JS Bridge API接口：
```typescript
// bridge-api.d.ts - 统一接口定义
interface TSGameBridge {
  // 用户认证
  accreditLogin(type: string): Promise<void>;
  
  // 设备信息
  getPhoneInfo(): Promise<DeviceInfo>;
  getNetworkStatus(): Promise<NetworkStatus>;
  
  // 多媒体
  openCamera(): Promise<string>;
  playAudio(config: AudioConfig): Promise<void>;
  
  // 系统交互
  vibrate(duration: number): Promise<void>;
  showNotification(message: string): Promise<void>;
  
  // 平台特定功能（可选）
  platformSpecific?: {
    [key: string]: any;
  };
}
```

#### 3. 平台差异处理
```javascript
// platform-detector.js
const Platform = {
  isAndroid: () => /Android/i.test(navigator.userAgent),
  isIOS: () => /iPhone|iPad|iPod/i.test(navigator.userAgent),
  isHarmonyOS: () => /HarmonyOS/i.test(navigator.userAgent),
  
  // 根据平台调用不同的API
  shareToSocial: (data) => {
    if (Platform.isAndroid()) {
      return TSGameBridge.shareToWechat(data);
    } else if (Platform.isIOS()) {
      return TSGameBridge.shareToSystem(data);
    } else if (Platform.isHarmonyOS()) {
      return TSGameBridge.shareToHuawei(data);
    }
  }
};
```

### 开发环境搭建

#### 1. Android开发环境
```bash
# 安装Android Studio
# 配置环境变量
export ANDROID_HOME=/path/to/android-sdk
export PATH=$PATH:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools

# 创建项目
cd android
./gradlew build
```

#### 2. iOS开发环境
```bash
# 安装Xcode (仅限macOS)
# 安装CocoaPods
sudo gem install cocoapods

# 创建项目
cd ios
pod init
pod install
open TSGame.xcworkspace
```

#### 3. HarmonyOS开发环境
```bash
# 下载DevEco Studio
# 安装HarmonyOS SDK
# 创建项目
cd harmonyos
hvigorw assembleHap
```

### 代码复用策略

#### 1. 共享Web资源
```javascript
// shared/webview/js/game-core.js
class GameCore {
  constructor() {
    this.platform = this.detectPlatform();
    this.bridge = this.initBridge();
  }
  
  detectPlatform() {
    if (/Android/i.test(navigator.userAgent)) return 'android';
    if (/iPhone|iPad/i.test(navigator.userAgent)) return 'ios';
    if (/HarmonyOS/i.test(navigator.userAgent)) return 'harmonyos';
    return 'unknown';
  }
  
  initBridge() {
    // 统一的桥接初始化逻辑
    return new PlatformBridge(this.platform);
  }
}
```

#### 2. 平台抽象层
```java
// Android抽象层
public abstract class PlatformService {
    public abstract void login(String type, Callback callback);
    public abstract void share(ShareData data, Callback callback);
    public abstract DeviceInfo getDeviceInfo();
}

public class AndroidPlatformService extends PlatformService {
    @Override
    public void login(String type, Callback callback) {
        // Android特定的登录实现
    }
}
```

```objc
// iOS抽象层
@protocol TSPlatformService <NSObject>
- (void)loginWithType:(NSString *)type callback:(void(^)(NSDictionary *result))callback;
- (void)shareData:(NSDictionary *)data callback:(void(^)(BOOL success))callback;
- (NSDictionary *)getDeviceInfo;
@end

@interface TSIOSPlatformService : NSObject <TSPlatformService>
@end
```

```typescript
// HarmonyOS抽象层
abstract class PlatformService {
  abstract login(type: string): Promise<LoginResult>;
  abstract share(data: ShareData): Promise<boolean>;
  abstract getDeviceInfo(): DeviceInfo;
}

class HarmonyOSPlatformService extends PlatformService {
  async login(type: string): Promise<LoginResult> {
    // HarmonyOS特定的登录实现
  }
}
```

### 测试策略

#### 1. 单元测试
```javascript
// 跨平台测试用例
describe('Bridge API Tests', () => {
  test('should get device info on all platforms', async () => {
    const deviceInfo = await TSGameBridge.getPhoneInfo();
    expect(deviceInfo).toHaveProperty('model');
    expect(deviceInfo).toHaveProperty('version');
    expect(deviceInfo).toHaveProperty('platform');
  });
  
  test('should handle network status correctly', async () => {
    const network = await TSGameBridge.getNetworkStatus();
    expect(['1', '2', '3']).toContain(network);
  });
});
```

#### 2. 集成测试
```yaml
# test-plan.yml
test_scenarios:
  - name: "登录流程测试"
    platforms: ["android", "ios", "harmonyos"]
    steps:
      - "打开应用"
      - "点击登录按钮"
      - "验证登录结果"
  
  - name: "分享功能测试"
    platforms: ["android", "ios", "harmonyos"]
    steps:
      - "进入游戏页面"
      - "点击分享按钮"
      - "选择分享平台"
      - "验证分享成功"
```

### 性能优化建议

#### 1. WebView优化
```javascript
// 通用WebView优化配置
const webViewConfig = {
  android: {
    hardwareAccelerated: true,
    cacheMode: 'LOAD_CACHE_ELSE_NETWORK',
    domStorageEnabled: true
  },
  ios: {
    allowsInlineMediaPlayback: true,
    mediaTypesRequiringUserActionForPlayback: 'none',
    scrollView: { bounces: false }
  },
  harmonyos: {
    javaScriptAccess: true,
    domStorageAccess: true,
    imageAccess: true
  }
};
```

#### 2. 资源加载优化
```javascript
// 预加载关键资源
class ResourceManager {
  preloadAssets() {
    const criticalAssets = [
      'images/logo.png',
      'audio/bgm.mp3',
      'fonts/game-font.woff2'
    ];
    
    return Promise.all(
      criticalAssets.map(asset => this.loadAsset(asset))
    );
  }
  
  loadAsset(url) {
    return new Promise((resolve, reject) => {
      const ext = url.split('.').pop();
      if (['png', 'jpg', 'gif'].includes(ext)) {
        const img = new Image();
        img.onload = resolve;
        img.onerror = reject;
        img.src = url;
      } else if (['mp3', 'wav'].includes(ext)) {
        const audio = new Audio();
        audio.oncanplaythrough = resolve;
        audio.onerror = reject;
        audio.src = url;
      }
    });
  }
}
```

### 维护建议

#### 1. 版本管理
```json
// version-config.json
{
  "version": "3.6.3",
  "platforms": {
    "android": {
      "versionCode": 36300,
      "minSdkVersion": 21,
      "targetSdkVersion": 33
    },
    "ios": {
      "buildNumber": "36300",
      "minimumOSVersion": "11.0"
    },
    "harmonyos": {
      "versionCode": 36300,
      "minAPIVersion": 8,
      "targetAPIVersion": 9
    }
  }
}
```

#### 2. 更新策略
- **强制更新**: 影响安全性和关键功能的更新
- **建议更新**: 新功能和体验优化
- **静默更新**: 资源文件和配置更新
- **灰度发布**: 分阶段推送给不同用户群体

#### 3. 兼容性处理
```javascript
// 版本兼容性检查
class CompatibilityChecker {
  checkPlatformSupport() {
    const requirements = {
      android: { minVersion: 21 },
      ios: { minVersion: '11.0' },
      harmonyos: { minAPIVersion: 8 }
    };
    
    const current = this.getCurrentPlatformVersion();
    const required = requirements[this.platform];
    
    return this.compareVersions(current, required.minVersion) >= 0;
  }
}
```

## 项目总结与展望

### 技术特色
1. **跨平台统一**: 基于WebView + JS Bridge的跨平台解决方案
2. **功能完备**: 涵盖认证、分享、定位、音视频等完整功能
3. **性能优化**: 针对不同平台特性进行深度优化
4. **易于维护**: 统一的API接口和代码架构

### 适用场景
- **棋牌游戏**: 完整的棋牌游戏解决方案
- **社交游戏**: 支持实时音视频和社交分享
- **地方特色应用**: 可快速适配不同地区需求
- **跨平台应用**: 一套代码适配多个平台

### 开发优势
- **开发效率**: H5游戏 + 原生能力，快速开发
- **维护成本**: 统一的业务逻辑，降低维护成本
- **用户体验**: 原生性能 + Web灵活性
- **迭代速度**: 支持热更新，快速迭代

### 扩展方向
1. **平台支持**: 扩展到更多平台（Windows、Web）
2. **技术升级**: 升级到最新的SDK版本和技术栈
3. **功能增强**: 添加更多游戏类型和社交功能
4. **性能优化**: 进一步优化启动速度和运行性能

### 常见问题解答

#### Q: 如何在现有项目基础上开发iOS版本？
A: 
1. 复制`shared/`目录下的所有Web资源
2. 创建iOS项目，实现相同的JS Bridge接口
3. 根据iOS平台特性调整权限配置和第三方SDK
4. 参考本文档的iOS开发指南进行适配

#### Q: HarmonyOS版本开发有什么注意事项？
A: 
1. 使用ArkTS语言开发，语法类似TypeScript
2. 权限管理更加严格，需要详细配置使用场景
3. 部分第三方SDK可能需要寻找替代方案
4. 遵循华为应用市场的审核规范

#### Q: 如何保证各平台功能一致性？
A:
1. 使用统一的API接口定义
2. 建立跨平台测试用例
3. 定期进行功能对比测试
4. 维护详细的功能兼容性文档

#### Q: 性能优化的重点是什么？
A:
1. WebView初始化和资源加载优化
2. JS Bridge通信效率优化
3. 内存管理和垃圾回收优化
4. 网络请求和数据缓存优化

### 技术支持
- **文档更新**: 定期更新技术文档和API说明
- **问题反馈**: 通过Issue跟踪和解决技术问题
- **技术交流**: 建立开发者交流群组
- **版本发布**: 提供稳定的版本发布和更新通知

---

**文档版本**: v2.0  
**更新时间**: 2025年7月5日  
**适用版本**: TSGame 3.6.3+  
**支持平台**: Android、iOS、HarmonyOS  

> 本文档为TSGame跨平台项目的完整技术说明，涵盖了项目架构、开发指南、API参考等所有必要信息。开发者可以基于本文档快速理解项目结构，并在任意支持的平台上实现相同功能的应用。