# 工作手机APP控制方案

> 手机安装Agent APP，实现远程控制与项目绑定

---

## 一、整体架构

```
┌─────────────────────────────────────────────────────────────────────────┐
│                           控制中心架构                                   │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌──────────────┐     ┌──────────────────┐     ┌──────────────────┐   │
│  │  管理后台     │     │    SDK服务器      │     │   工作手机       │   │
│  │  (Web/PHP)   │────►│  (Python/Docker) │◄────│   (Android)     │   │
│  │              │     │                  │     │                  │   │
│  │  - 项目管理   │     │  - WebSocket Hub │     │  - Agent APP    │   │
│  │  - 设备监控   │     │  - 项目绑定      │     │  - 后台服务      │   │
│  │  - 批量控制   │     │  - 命令分发      │     │  - 开机自启      │   │
│  └──────────────┘     └──────────────────┘     └──────────────────┘   │
│         │                      │                       │               │
│         │      HTTP API        │     WebSocket         │               │
│         └──────────────────────┴───────────────────────┘               │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘
```

---

## 二、部署步骤

### 2.1 服务器端部署

```bash
# 1. 进入SDK目录
cd /path/to/工作手机/sdk

# 2. 启动服务（Docker方式）
docker compose up -d

# 3. 或者直接运行
cd app && python main.py
```

**服务端口:**
- HTTP API: 8899
- WebSocket: ws://your-server:8899/ws/device/{device_id}

### 2.2 手机端安装

**方式1: 安装APK**
```bash
# 编译APK（需要Android Studio）
cd sdk/android-app
./gradlew assembleRelease

# 安装到手机
adb install app/build/outputs/apk/release/app-release.apk
```

**方式2: 直接下载**
- 从Release页面下载 `WorkPhoneAgent.apk`

### 2.3 APP配置

1. 打开"工作手机Agent"应用
2. 填写配置:
   - **服务器地址**: `ws://sdk.quwanzhi.com:8899/ws/device`
   - **项目ID**: 从管理后台获取（如: `project_001`）
   - **设备ID**: 自动生成或自定义
3. 点击"连接服务器"

---

## 三、API接口说明

### 3.1 项目管理

**获取所有项目:**
```bash
GET /api/v3/projects

# 响应
{
  "success": true,
  "projects": [
    {
      "project_id": "project_001",
      "total_devices": 10,
      "online_devices": 8
    }
  ]
}
```

**获取项目设备:**
```bash
GET /api/v3/projects/{project_id}/devices

# 响应
{
  "success": true,
  "project_id": "project_001",
  "devices": [
    {
      "device_id": "device_001",
      "model": "Redmi Note 13",
      "status": "online",
      "connected_at": "2026-01-27T10:00:00"
    }
  ]
}
```

### 3.2 批量控制

**广播命令（不等待响应）:**
```bash
POST /api/v3/projects/{project_id}/broadcast
Content-Type: application/json

{
  "action": "open_app",
  "params": {"package": "com.tencent.mm"}
}

# 响应
{
  "success": true,
  "sent": 8,
  "failed": 0
}
```

**执行命令（等待响应）:**
```bash
POST /api/v3/projects/{project_id}/execute?timeout=30
Content-Type: application/json

{
  "action": "get_device_info",
  "params": {}
}

# 响应
{
  "success": true,
  "total_devices": 8,
  "success_count": 8,
  "results": [...]
}
```

### 3.3 单设备控制

```bash
POST /api/v3/projects/{project_id}/devices/{device_id}/execute
Content-Type: application/json

{
  "action": "open_app",
  "params": {"package": "com.tencent.mm"}
}
```

---

## 四、支持的命令

| 命令 | 参数 | 说明 |
|------|------|------|
| `open_app` | package: 包名 | 打开指定APP |
| `get_installed_apps` | 无 | 获取已安装APP列表 |
| `get_device_info` | 无 | 获取设备信息 |

**扩展命令（需要ROOT或辅助功能权限）:**
| 命令 | 参数 | 说明 |
|------|------|------|
| `click` | x, y | 点击坐标 |
| `swipe` | x1, y1, x2, y2 | 滑动 |
| `input_text` | text | 输入文字 |
| `screenshot` | 无 | 截图 |

---

## 五、PHP SDK使用

```php
<?php
require_once 'WorkPhoneClient.php';

$client = new WorkPhoneClient('http://sdk.quwanzhi.com:8899');

// 获取项目设备
$devices = $client->getProjectDevices('project_001');

// 向项目所有设备广播命令
$result = $client->broadcastToProject('project_001', [
    'action' => 'open_app',
    'params' => ['package' => 'com.tencent.mm']
]);

// 在指定设备执行命令
$result = $client->executeOnDevice('project_001', 'device_001', [
    'action' => 'get_device_info'
]);
```

---

## 六、运维说明

### 6.1 设备状态监控

```bash
# 查看所有在线设备
curl http://localhost:8899/api/v3/devices

# 查看项目设备
curl http://localhost:8899/api/v3/projects/project_001/devices
```

### 6.2 日志查看

```bash
# 服务器日志
docker compose logs -f sdk

# 手机端日志（通过ADB）
adb logcat -s AgentService
```

### 6.3 故障排查

| 问题 | 原因 | 解决方案 |
|------|------|---------|
| APP无法连接 | 网络或地址错误 | 检查服务器地址和端口 |
| 频繁断线 | 心跳超时 | 检查网络稳定性 |
| 命令执行失败 | 权限不足 | 授予APP必要权限 |
| 开机不自启 | 被系统优化 | 关闭电池优化 |

---

## 七、安全建议

1. **生产环境使用HTTPS/WSS**
2. **添加API认证Token**
3. **限制可执行的命令类型**
4. **记录操作日志**
5. **设置设备白名单**

---

## 八、文件结构

```
sdk/
├── app/                     # SDK服务器
│   ├── main.py             # 主入口
│   ├── routers/
│   │   └── projects.py     # 项目管理API
│   └── services/
│       └── ws_hub.py       # WebSocket连接管理
│
├── android-app/            # Android Agent APP
│   ├── app/src/main/java/
│   │   └── com/workphone/agent/
│   │       ├── MainActivity.kt      # 主界面
│   │       ├── AgentService.kt      # 后台服务
│   │       └── BootReceiver.kt      # 开机启动
│   └── README.md
│
├── php-sdk/                # PHP客户端SDK
│   └── WorkPhoneClient.php
│
└── docs/
    └── APP控制方案.md      # 本文档
```
