ylrz_saas_pharmacy/java/scripts/fix_worker_ws_doc_encoding.py

# -*- coding: utf-8 -*-
import pathlib

ROOT = pathlib.Path(r"D:\hdProject\newsaas\ylrz_saas\java\fs-worker-app\docs\worker-ws-task-push.md")

CONTENT = r"""# 工作机 APP WebSocket 任务推送对接说明

## 1. 概述

销售 PC 端在「启动外呼任务」时，若任务为 **APP 外呼模式**（`callModel = 3 / 4 / 5`）且已绑定设备，服务端会通过 **同一条 WebSocket 长连接** 向对应工作机推送 `taskRun` 消息。

- **心跳**与**任务推送**共用连接地址，通过消息体字段 `cmd` 区分类型。
- APP 收到 `taskRun` 后，根据 `callModel` 跳转或刷新对应外呼页面。

| 服务 | 端口 | 说明 |
|------|------|------|
| fs-worker-app | 8008 | WebSocket + APP HTTP 接口 |
| fs-saas-company | 8006 | PC 端启动任务（`taskRun`） |

---

## 2. WebSocket 连接

### 2.1 连接地址（唯一）

```
ws://{host}:8008/worker/webSocket/{meId}?tenantId={tenantId}
```

| 参数 | 说明 |
|------|------|
| `meId` | 设备 IMEI，路径参数；须与登录 `meId`、主库 `company_sms_device.imei` 一致 |
| `tenantId` | 租户 ID，查询参数，建议必传 |

示例：

```
ws://192.168.11.62:8008/worker/webSocket/8601234561212129012?tenantId=338
```

### 2.2 连接生命周期

1. APP 登录成功后建立长连接（与心跳共用）。
2. 连接成功时，服务端主动推送一次当前设备状态。
3. APP 定时发送心跳（建议间隔 30s）。
4. PC 启动任务时，服务端可能额外推送 `taskRun`（无需 APP 回包）。

---

## 3. 消息协议（统一 JSON）

所有消息均为 JSON 文本，通过字段 `cmd` 区分类型。

### 3.1 消息类型一览

| 方向 | `cmd` | 说明 |
|------|-------|------|
| APP → 服务端 | `heartbeat` | 心跳 |
| APP → 服务端 | `deviceStatus` | 主动查询设备状态（可选） |
| 服务端 → APP | `heartbeat` | 心跳回复 |
| 服务端 → APP | `deviceStatus` | 禁用/离线等状态变更 |
| 服务端 → APP | `taskRun` | **PC 启动任务推送** |
| 服务端 → APP | `error` | 处理异常 |

---

## 4. 心跳（已有机制，与任务推送无关）

### 4.1 APP 发送

```json
{
  "cmd": "heartbeat",
  "tenantId": 338,
  "appVersion": "1.0.0",
  "deviceName": "工作机A",
  "phone1": "13800138000",
  "phone2": "13900139000",
  "imei": "卡1IMEI,卡2IMEI"
}
```

### 4.2 服务端回复

```json
{
  "cmd": "heartbeat",
  "meId": "8601234561212129012",
  "status": 1,
  "msg": "ok",
  "appVersion": "1.0.0",
  "deviceName": "工作机A",
  "timestamp": 1718534400000
}
```

`status`：`0` 离线 / `1` 在线 / `2` 禁用。

### 4.3 APP 处理建议

- 更新本地设备状态展示。
- `status === 2` 时提示禁用并限制外呼。
- 心跳逻辑保持现有实现，**无需为 `taskRun` 单独建连接**。

---

## 5. 任务推送 `taskRun`（本次对接重点）

### 5.1 触发条件（PC 端）

PC 调用 `GET /company/companyVoiceRobotic/taskRun?id={任务ID}` 且满足：

- 任务 `callModel` 为 `3`、`4` 或 `5`；
- 任务 `deviceIds` 非空（已绑定设备）；
- 设备 IMEI 能解析成功。

不满足上述条件时 **不会推送** `taskRun`。

### 5.2 推送链路

```
PC taskRun (8006)
  → Redis PUBLISH channel: worker:ws:task:run
  → fs-worker-app Redisson 订阅
  → WorkerWebSocketServer.pushTaskRunToDevices
  → 向在线设备的 WebSocket Session 发送消息
```

**前置条件**：8006 与 8008 使用同一 Redis 实例；APP 已连接 WS 且 `meId` 在推送列表中。

### 5.3 服务端 → APP 消息体

```json
{
  "cmd": "taskRun",
  "robotic": 294,
  "callModel": 3,
  "timestamp": 1718534400000
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `cmd` | String | 固定 `taskRun` |
| `robotic` | Long | 外呼任务 ID（`company_voice_robotic.id`） |
| `callModel` | Integer | 外呼模式：`3` / `4` / `5` |
| `timestamp` | Long | 服务端时间戳（毫秒） |

**说明**：`taskRun` 为服务端单向推送，APP **不需要回包**。

---

## 6. callModel 与页面对应关系

| callModel | 名称 | 业务含义 | APP 页面/行为建议 |
|-----------|------|----------|-------------------|
| **3** | APP-网页点呼 | 销售在 APP 上手动点选客户逐个拨打 | 跳转或刷新 **网页点呼页**；展示该 `robotic` 任务下的待拨客户列表，用户手动点击拨打 |
| **4** | APP-自动呼叫 | APP 按任务自动连续外呼 | 跳转或刷新 **自动呼叫页**；进入自动拨号流程，按队列自动拨打 |
| **5** | APP-AI呼叫 | APP 侧 AI 辅助 / AI 外呼流程 | 跳转或刷新 **AI 呼叫页**；进入 AI 外呼交互流程 |

后端枚举定义见 `AiCallModeEnum`：

- `3` = `APP_WEB`（APP-网页点呼）
- `4` = `APP_AUTO`（APP-自动呼叫）
- `5` = `APP_AI`（APP-AI呼叫）

**注意**：`callModel` 为 `1`（人工外呼）、`2`（AI 自动外呼 / EasyCall）时 **不会** 收到 `taskRun` 推送。

### 6.1 收到 `taskRun` 后的推荐处理流程

```
onWebSocketMessage(json)
  → 解析 cmd
  → if cmd == "taskRun":
       roboticId = json.robotic
       callModel   = json.callModel
       switch (callModel):
         3 → 打开/刷新「网页点呼」页，带 roboticId，拉取任务与客户列表
         4 → 打开/刷新「自动呼叫」页，带 roboticId，启动自动拨号
         5 → 打开/刷新「AI 呼叫」页，带 roboticId，进入 AI 外呼流程
```

若当前已在对应模式页面，仅需 **刷新任务列表/客户列表**（调用下方 HTTP 接口），不必重复跳转。

---

## 7. 配套 HTTP 接口（刷新页面数据）

收到 `taskRun` 后，按 `callModel` 调用对应接口拉取数据（均需登录态 `WorkerToken`）。

### 7.1 执行中任务统计列表

```
GET /company/companyVoiceRobotic/myTaskStatList?callModel={3|4|5}&meId={meId}
```

- `callModel`：与推送消息一致（3 / 4 / 5）
- `meId`：当前设备 IMEI

用于各外呼模式首页的任务列表刷新。

### 7.2 任务拨打统计 / 客户列表

```
GET /company/companyVoiceRoboticCallLogCallphone/...?roboticId={robotic}&callModel={3|4|5}&meId={meId}
```

（具体路径见 `CompanyVoiceRoboticCallLogCallphoneController`，参数需与 `callModel`、`meId` 一致。）

### 7.3 拨打前校验

```
POST /app/aiSipCall/validateAppCall
```

Body 示例：

```json
{
  "roboticId": 294,
  "calleeId": 12345,
  "meId": "8601234561212129012",
  "callModel": 3
}
```

### 7.4 外呼结果回调

```
POST /app/aiSipCall/appCardCallBack
```

通话结束后回调，Body 中需带 `callModel`（默认 3）。

### 7.5 暂停/继续任务

```
POST /company/companyVoiceRobotic/pauseRoboticActive
```

与 PC 端共用，APP / PC 任意一端操作会联动。

---

## 8. APP 端集成示例（伪代码）

```javascript
// 同一 WebSocket 连接
const ws = new WebSocket(
  `ws://${host}:8008/worker/webSocket/${meId}?tenantId=${tenantId}`
);

ws.onopen = () => {
  startHeartbeat(); // 定时发 cmd=heartbeat
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  switch (msg.cmd) {
    case 'heartbeat':
      handleHeartbeatReply(msg);      // 更新在线/禁用状态
      break;
    case 'deviceStatus':
      handleDeviceStatus(msg);        // 禁用、离线提示
      break;
    case 'taskRun':
      handleTaskRunPush(msg);         // 任务推送（见下）
      break;
    case 'error':
      showError(msg.msg);
      break;
  }
};

function handleTaskRunPush(msg) {
  const { robotic, callModel } = msg;
  if (callModel === 3) {
    navigateOrRefresh('WebClickCallPage', { roboticId: robotic, callModel: 3 });
  } else if (callModel === 4) {
    navigateOrRefresh('AutoCallPage', { roboticId: robotic, callModel: 4 });
  } else if (callModel === 5) {
    navigateOrRefresh('AiCallPage', { roboticId: robotic, callModel: 5 });
  }
  fetchMyTaskStatList(callModel, meId);
}

function startHeartbeat() {
  setInterval(() => {
    if (ws.readyState === WebSocket.OPEN) {
      ws.send(JSON.stringify({
        cmd: 'heartbeat',
        tenantId,
        appVersion,
        deviceName,
        phone1,
        phone2,
        imei: cardImeiJoined
      }));
    }
  }, 30000);
}
```

---

## 9. 联调检查清单

| 步骤 | 期望现象 |
|------|----------|
| APP 连接 WS | 服务端日志：`[WorkerWS] 设备连接: meId=...` |
| 8008 启动 | 日志：`[WorkerTaskRunWS] Redisson 订阅成功 channel=worker:ws:task:run` |
| PC 点「启动任务」 | 8006：`[WorkerTaskRunWS] 已发布 roboticId=... callModel=... meIds=[...]` |
| 8008 收 Redis | `[WorkerTaskRunWS] 收到消息 roboticId=...` |
| 设备在线 | `[WorkerWS] 任务启动推送成功 meId=...` |
| APP 收消息 | `cmd=taskRun`，按 `callModel` 进入对应页面 |

**常见问题**：

1. **收不到 `taskRun`**：检查 `meId` 是否与 `deviceIds` 解析出的 IMEI 一致；APP 是否已连 WS。
2. **8008 收到消息但 APP 没反应**：检查 APP `onMessage` 是否处理 `cmd === 'taskRun'`。
3. **推送成功但页面无数据**：检查刷新接口的 `callModel`、`meId` 是否与推送一致。

---

## 10. 附录：完整消息字段（WorkerWsMsg）

| 字段 | 类型 | 说明 |
|------|------|------|
| `cmd` | String | `heartbeat` / `deviceStatus` / `taskRun` / `error` |
| `meId` | String | 设备 IMEI |
| `tenantId` | Long | 租户 ID |
| `appVersion` | String | APP 版本 |
| `deviceName` | String | 设备名称 |
| `phone1` / `phone2` | String | 双卡手机号 |
| `imei` | String | SIM 卡 IMEI（逗号分隔） |
| `status` | Integer | 0 离线 / 1 在线 / 2 禁用 |
| `msg` | String | 提示信息 |
| `timestamp` | Long | 时间戳 |
| `robotic` | Long | 任务 ID（仅 `taskRun`） |
| `callModel` | Integer | 外呼模式（仅 `taskRun`） |

---

**文档版本**：与 `fs-worker-app` WebSocket + Redis 任务推送实现同步。
**Redis 通道**：`worker:ws:task:run`（`WorkerWsConstants.REDIS_CHANNEL_TASK_RUN`）。
"""

ROOT.write_text(CONTENT, encoding="utf-8", newline="\n")
print("written:", ROOT, "bytes:", len(CONTENT.encode("utf-8")))