# 自动找工作系统 - MQTT指令列表

> 版本: v1.0 | 更新日期: 2025-12-25

## 文档说明

本文档定义了服务端通过MQTT向客户端下发的所有指令格式和规范。所有操作都通过任务和指令的方式异步执行。

---

## 一、MQTT通信架构

### 1.1 通信流程

```
┌──────────────┐                    ┌──────────────┐
│   服务端      │                    │   客户端      │
│  (Node.js)   │                    │  (设备端)    │
└──────┬───────┘                    └──────┬───────┘
       │                                   │
       │  ① 创建任务(task_status表)         │
       │  ② 生成指令(task_commands表)       │
       │                                   │
       │  ③ MQTT Publish                  │
       │  Topic: {sn_code}/command        │
       │  ─────────────────────────────>  │
       │                                   │
       │                     ④ 执行指令    │
       │                     ⑤ 生成结果    │
       │                                   │
       │  ⑥ MQTT Publish                  │
       │  Topic: response                 │
       │  <─────────────────────────────  │
       │                                   │
       │  ⑦ 更新指令状态(task_commands)     │
       │  ⑧ 更新任务状态(task_status)       │
       │                                   │
```

### 1.2 MQTT配置

- **Broker地址**: `mqtt://192.144.167.231:1883`
- **订阅主题**:
  - `heartbeat` - 设备心跳信息
  - `response` - 设备响应信息
- **发布主题**:
  - `{sn_code}/command` - 向指定设备发送指令

### 1.3 消息格式

**服务端 → 客户端 (指令)**
```json
{
  "commandId": "uuid",
  "taskId": "uuid",
  "platform": "boss",
  "action": "search_jobs",
  "data": {
    "keyword": "全栈工程师",
    "city": "101020100",
    "page": 1
  }
}
```

**客户端 → 服务端 (响应)**
```json
{
  "commandId": "uuid",
  "taskId": "uuid",
  "code": 200,
  "message": "执行成功",
  "data": {
    // 返回数据
  }
}
```

**客户端 → 服务端 (心跳)**
```json
{
  "sn_code": "device001",
  "platform": "boss",
  "timestamp": 1672531200000,
  "status": "online",
  "version": "1.0.0"
}
```

---

## 二、已实现指令列表

### 2.1 用户登录指令

#### get_login_qr_code - 获取登录二维码

**指令格式**
```json
{
  "action": "get_login_qr_code",
  "platform": "boss",
  "data": {}
}
```

**返回格式**
```json
{
  "code": 200,
  "message": "二维码获取成功",
  "data": {
    "qrCode": "https://example.com/qrcode.png",
    "qr_code_url": "https://example.com/qrcode.png",
    "expire_time": 300
  }
}
```

**说明**: 获取登录二维码,用户扫码登录后客户端需要保存cookies/token

---

#### get_user_info - 获取用户信息

**指令格式**
```json
{
  "action": "get_user_info",
  "platform": "boss",
  "data": {}
}
```

**返回格式**
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "userId": "123456",
    "userName": "张三",
    "phone": "138****5678",
    "isLoggedIn": true
  }
}
```

**说明**: 获取当前登录用户的基本信息,验证登录状态

---

### 2.2 简历管理指令

#### get_online_resume - 获取在线简历

**指令格式**
```json
{
  "action": "get_online_resume",
  "platform": "boss",
  "data": {}
}
```

**返回格式**
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "baseInfo": {
      "name": "张三",
      "gender": 1,
      "age": 28,
      "account": "138****5678",
      "emailBlur": "zhang***@qq.com",
      "workYears": 5,
      "workYearDesc": "5年",
      "degreeCategory": "本科"
    },
    "expectList": [{
      "positionName": "全栈工程师",
      "locationName": "上海",
      "salaryDesc": "20-30K",
      "industryDesc": "互联网"
    }],
    "workExpList": [{
      "companyName": "XX科技公司",
      "positionName": "高级前端工程师",
      "startDate": "2020-01",
      "endDate": "2023-12",
      "workContent": "负责前端架构设计和开发..."
    }],
    "projectExpList": [{
      "name": "电商平台项目",
      "roleName": "技术负责人",
      "startDate": "2022-01",
      "endDate": "2023-06",
      "projectDesc": "项目描述...",
      "performance": "项目成果..."
    }],
    "educationExpList": [{
      "school": "XX大学",
      "major": "计算机科学与技术",
      "degreeName": "本科",
      "endYear": 2018
    }],
    "userDesc": "熟悉Vue、React、Node.js等技术栈...",
    "certificationList": []
  }
}
```

**说明**: 获取用户在招聘平台上的完整简历信息

---

### 2.3 岗位搜索指令

#### search_jobs - 搜索岗位 (已实现但需完善)

**指令格式**
```json
{
  "action": "search_jobs",
  "platform": "boss",
  "data": {
    "keyword": "全栈工程师",
    "city": "101020100",
    "page": 1
  }
}
```

**返回格式**
```json
{
  "code": 200,
  "message": "搜索成功",
  "data": {
    "total": 150,
    "page": 1,
    "jobList": [{
      "jobId": "job123456",
      "jobTitle": "全栈工程师",
      "companyName": "XX科技公司",
      "companySize": "100-499人",
      "salary": "20-30K",
      "location": "上海·浦东新区",
      "experience": "3-5年",
      "education": "本科",
      "jobRequirements": "1. 熟悉Vue/React...",
      "jobDescription": "岗位职责...",
      "bossName": "张经理",
      "bossTitle": "技术总监"
    }]
  }
}
```

**说明**: 当前实现基础,需要扩展支持更多搜索条件

---

#### get_job_list - 获取岗位列表

**指令格式**
```json
{
  "action": "get_job_list",
  "platform": "boss",
  "data": {
    "page": 1,
    "pageSize": 20
  }
}
```

**返回格式**
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "total": 50,
    "page": 1,
    "jobList": [
      // 同 search_jobs 的 jobList 格式
    ]
  }
}
```

**说明**: 获取推荐岗位列表

---

### 2.4 投递管理指令

#### apply_job - 投递岗位 (基础实现)

**指令格式**
```json
{
  "action": "apply_job",
  "platform": "boss",
  "data": {
    "jobId": "job123456",
    "expectSalary": "20-30K"
  }
}
```

**返回格式**
```json
{
  "code": 200,
  "message": "投递成功",
  "data": {
    "applyId": "apply123456",
    "jobId": "job123456",
    "applyTime": "2025-12-25 10:30:00",
    "status": "success"
  }
}
```

**错误码**
- `400` - 参数错误
- `403` - 已投递过该岗位
- `429` - 投递次数达到上限
- `500` - 投递失败

**说明**: 向指定岗位投递简历

---

### 2.5 聊天管理指令

#### get_chat_list - 获取聊天列表

**指令格式**
```json
{
  "action": "get_chat_list",
  "platform": "boss",
  "data": {
    "page": 1,
    "pageSize": 20
  }
}
```

**返回格式**
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "total": 15,
    "chatList": [{
      "conversationId": "conv123456",
      "jobId": "job123456",
      "jobTitle": "全栈工程师",
      "companyName": "XX科技",
      "bossName": "张经理",
      "lastMessage": "您好,请问...",
      "lastMessageTime": "2025-12-25 10:30:00",
      "unreadCount": 2,
      "hasInterview": false
    }]
  }
}
```

**说明**: 获取与HR的聊天会话列表

---

#### send_chat_message - 发送聊天消息

**指令格式**
```json
{
  "action": "send_chat_message",
  "platform": "boss",
  "data": {
    "conversationId": "conv123456",
    "jobId": "job123456",
    "content": "您好,我对这个岗位很感兴趣..."
  }
}
```

**返回格式**
```json
{
  "code": 200,
  "message": "发送成功",
  "data": {
    "messageId": "msg123456",
    "sendTime": "2025-12-25 10:30:00"
  }
}
```

**说明**: 向HR发送聊天消息

---

### 2.6 测试和调试指令

#### open_bot_detection - 打开测试页

**指令格式**
```json
{
  "action": "open_bot_detection",
  "platform": "boss",
  "data": {}
}
```

**返回格式**
```json
{
  "code": 200,
  "message": "测试页已打开",
  "data": {}
}
```

**说明**: 打开测试页面,用于调试

---

## 三、待开发指令列表

### 3.1 搜索投递增强指令 (优先级: HIGH)

#### search_jobs_enhanced - 增强搜索岗位 ⭐⭐⭐⭐⭐

**指令格式**
```json
{
  "action": "search_jobs_enhanced",
  "platform": "boss",
  "data": {
    "keyword": "全栈工程师",
    "city": "101020100",
    "page": 1,
    "pageSize": 20,

    // 新增搜索条件
    "experience": "3",
    "degree": "203",
    "salary": "406",
    "scale": "303",
    "stage": "807",
    "position": "100109",

    // 滚动加载方式
    "scrollLoadType": "auto",
    "maxScrollPages": 5
  }
}
```

**参数说明**
| 参数 | 说明 | 示例值 |
|------|------|--------|
| keyword | 搜索关键词 | "全栈工程师" |
| city | 城市代码 | "101020100" (上海) |
| page | 页码 | 1 |
| pageSize | 每页数量 | 20 |
| experience | 工作经验 | "1"=1年以下, "3"=1-3年, "4"=3-5年, "5"=5-10年, "6"=10年以上 |
| degree | 学历要求 | "202"=不限, "203"=大专, "204"=本科, "205"=硕士, "206"=博士 |
| salary | 薪资范围 | "402"=3-5K, "403"=5-10K, "404"=10-15K, "405"=15-20K, "406"=20-30K, "407"=30-50K, "408"=50K以上 |
| scale | 公司规模 | "302"=0-20人, "303"=20-99人, "304"=100-499人, "305"=500-999人, "306"=1000人以上 |
| stage | 融资阶段 | "801"=未融资, "802"=天使轮, "803"=A轮, "804"=B轮, "805"=C轮, "806"=D轮及以上, "807"=已上市, "808"=不需要融资 |
| position | 职位类型 | "100109"=全栈, "100110"=前端, "100111"=后端, "100112"=移动端 |
| scrollLoadType | 加载方式 | "auto"=自动滚动, "manual"=手动翻页 |
| maxScrollPages | 最大滚动页数 | 5 |

**返回格式**
```json
{
  "code": 200,
  "message": "搜索成功",
  "data": {
    "total": 150,
    "page": 1,
    "hasMore": true,
    "jobList": [{
      "jobId": "job123456",
      "jobTitle": "全栈工程师",
      "companyName": "XX科技公司",
      "companySize": "100-499人",
      "companyIndustry": "互联网",
      "companyStage": "已上市",
      "salary": "20-30K",
      "salaryMonth": "14薪",
      "location": "上海·浦东新区",
      "longitude": 121.5273,
      "latitude": 31.2172,
      "experience": "3-5年",
      "education": "本科",
      "skills": ["Vue", "React", "Node.js"],
      "jobRequirements": "1. 熟悉Vue/React...",
      "jobDescription": "岗位职责...",
      "welfare": ["五险一金", "带薪年假", "弹性工作"],
      "bossName": "张经理",
      "bossTitle": "技术总监",
      "bossActiveStatus": "刚刚活跃",
      "publishTime": "2025-12-25",
      "viewCount": 150,
      "applyCount": 30,
      "isOutsourcing": false,
      "jobLink": "https://www.zhipin.com/job_detail/xxx"
    }]
  }
}
```

**说明**:
- 支持Boss直聘完整的搜索筛选条件
- 支持自动滚动加载更多岗位
- 返回更详细的岗位信息

---

#### search_by_url - 通过URL搜索岗位 ⭐⭐⭐⭐⭐

**指令格式**
```json
{
  "action": "search_by_url",
  "platform": "boss",
  "data": {
    "url": "https://www.zhipin.com/web/geek/jobs?city=101020100&query=%E5%85%A8%E6%A0%88%E5%B7%A5%E7%A8%8B%E5%B8%88",
    "scrollLoadType": "auto",
    "maxScrollPages": 5
  }
}
```

**返回格式**
```json
{
  "code": 200,
  "message": "搜索成功",
  "data": {
    // 同 search_jobs_enhanced 返回格式
  }
}
```

**说明**:
- 直接使用Boss直聘的搜索URL
- 自动解析URL参数
- 支持所有筛选条件

---

### 3.2 批量投递指令 (优先级: HIGH)

#### batch_apply_jobs - 批量投递岗位 ⭐⭐⭐⭐⭐

**指令格式**
```json
{
  "action": "batch_apply_jobs",
  "platform": "boss",
  "data": {
    "jobIds": ["job001", "job002", "job003"],
    "expectSalary": "20-30K",
    "applyInterval": 30,
    "maxApplyCount": 10
  }
}
```

**参数说明**
| 参数 | 说明 | 示例值 |
|------|------|--------|
| jobIds | 岗位ID数组 | ["job001", "job002"] |
| expectSalary | 期望薪资 | "20-30K" |
| applyInterval | 投递间隔(秒) | 30 |
| maxApplyCount | 最大投递数量 | 10 |

**返回格式**
```json
{
  "code": 200,
  "message": "批量投递完成",
  "data": {
    "total": 10,
    "success": 8,
    "failed": 2,
    "results": [{
      "jobId": "job001",
      "status": "success",
      "applyId": "apply001",
      "message": "投递成功"
    }, {
      "jobId": "job002",
      "status": "failed",
      "message": "已投递过该岗位"
    }]
  }
}
```

**说明**:
- 批量投递多个岗位
- 控制投递间隔避免被限制
- 返回每个岗位的投递结果

---

### 3.3 简历刷新指令 (优先级: HIGH)

#### refresh_resume - 刷新简历 ⭐⭐⭐⭐

**指令格式**
```json
{
  "action": "refresh_resume",
  "platform": "boss",
  "data": {}
}
```

**返回格式**
```json
{
  "code": 200,
  "message": "简历刷新成功",
  "data": {
    "refreshTime": "2025-12-25 10:30:00",
    "nextRefreshTime": "2025-12-25 12:30:00"
  }
}
```

**说明**:
- 刷新简历提升排名
- 每2小时可刷新一次

---

### 3.4 账号保活指令 (优先级: HIGH)

#### auto_active - 自动活跃账号 ⭐⭐⭐⭐

**指令格式**
```json
{
  "action": "auto_active",
  "platform": "boss",
  "data": {
    "actionType": "random",
    "actions": ["browse_jobs", "view_company", "search_keyword", "update_visibility"]
  }
}
```

**参数说明**
| 参数 | 说明 | 可选值 |
|------|------|--------|
| actionType | 动作类型 | "random"=随机, "sequence"=顺序 |
| actions | 动作列表 | ["browse_jobs", "view_company", "search_keyword", "update_visibility"] |

**动作说明**
- `browse_jobs` - 浏览岗位(随机点击5-10个岗位)
- `view_company` - 查看公司主页
- `search_keyword` - 搜索关键词(随机关键词)
- `update_visibility` - 修改简历可见性

**返回格式**
```json
{
  "code": 200,
  "message": "活跃操作完成",
  "data": {
    "executedActions": ["browse_jobs", "view_company"],
    "duration": 120,
    "timestamp": "2025-12-25 10:30:00"
  }
}
```

**说明**:
- 模拟真实用户行为
- 随机时间间隔
- 避免账号被标记为机器人

---

### 3.5 聊天增强指令 (优先级: MEDIUM)

#### get_chat_detail - 获取聊天详情 ⭐⭐⭐

**指令格式**
```json
{
  "action": "get_chat_detail",
  "platform": "boss",
  "data": {
    "conversationId": "conv123456",
    "page": 1,
    "pageSize": 50
  }
}
```

**返回格式**
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "conversationId": "conv123456",
    "jobId": "job123456",
    "messages": [{
      "messageId": "msg001",
      "senderId": "boss123",
      "senderType": "boss",
      "content": "您好,请问什么时候方便面试?",
      "sendTime": "2025-12-25 10:30:00",
      "isRead": true,
      "messageType": "text",
      "isInterviewInvitation": true
    }]
  }
}
```

**说明**: 获取完整的聊天历史记录

---

#### send_greeting - 发送打招呼 ⭐⭐⭐

**指令格式**
```json
{
  "action": "send_greeting",
  "platform": "boss",
  "data": {
    "jobId": "job123456",
    "content": "您好,我对这个岗位很感兴趣,期待能有机会详聊。"
  }
}
```

**返回格式**
```json
{
  "code": 200,
  "message": "打招呼成功",
  "data": {
    "conversationId": "conv123456",
    "messageId": "msg001",
    "sendTime": "2025-12-25 10:30:00"
  }
}
```

**说明**: 主动向HR发起沟通

---

### 3.6 数据采集指令 (优先级: MEDIUM)

#### get_job_detail - 获取岗位详情 ⭐⭐⭐

**指令格式**
```json
{
  "action": "get_job_detail",
  "platform": "boss",
  "data": {
    "jobId": "job123456"
  }
}
```

**返回格式**
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "jobId": "job123456",
    // 完整的岗位详情(同search_jobs_enhanced中的jobList项)
    "companyDetail": {
      "companyId": "company123",
      "companyName": "XX科技公司",
      "companyLogo": "https://...",
      "companySize": "100-499人",
      "companyIndustry": "互联网",
      "companyStage": "已上市",
      "companyAddress": "上海市浦东新区...",
      "companyDesc": "公司介绍..."
    }
  }
}
```

**说明**: 获取岗位的完整详情信息

---

#### get_company_info - 获取公司信息 ⭐⭐⭐

**指令格式**
```json
{
  "action": "get_company_info",
  "platform": "boss",
  "data": {
    "companyId": "company123"
  }
}
```

**返回格式**
```json
{
  "code": 200,
  "message": "获取成功",
  "data": {
    "companyId": "company123",
    "companyName": "XX科技公司",
    "companyLogo": "https://...",
    "companySize": "100-499人",
    "companyIndustry": "互联网",
    "companyStage": "已上市",
    "companyAddress": "上海市浦东新区...",
    "companyDesc": "公司介绍...",
    "companyBenefit": ["五险一金", "带薪年假"],
    "companyPhotos": ["https://...", "https://..."],
    "jobCount": 50,
    "isVerified": true
  }
}
```

**说明**: 获取公司的详细信息

---

## 四、指令执行规范

### 4.1 指令生命周期

```
1. 创建 (pending)
   ↓
2. 下发 (sent)
   ↓
3. 执行中 (executing)
   ↓
4. 完成 (completed) / 失败 (failed) / 超时 (timeout)
```

### 4.2 超时设置

| 指令类型 | 超时时间 | 重试次数 |
|---------|----------|----------|
| 登录类指令 | 60秒 | 1次 |
| 简历获取 | 30秒 | 2次 |
| 岗位搜索 | 60秒 | 2次 |
| 岗位投递 | 30秒 | 1次 |
| 聊天消息 | 30秒 | 2次 |
| 保活操作 | 120秒 | 0次 |

### 4.3 错误码规范

| 错误码 | 说明 | 处理方式 |
|--------|------|----------|
| 200 | 成功 | - |
| 400 | 参数错误 | 不重试 |
| 401 | 未登录 | 触发重新登录 |
| 403 | 无权限/已操作 | 不重试 |
| 429 | 请求过于频繁 | 延迟后重试 |
| 500 | 服务器错误 | 重试 |
| 503 | 服务不可用 | 延迟后重试 |
| 600 | 网络超时 | 重试 |
| 700 | 客户端错误 | 记录日志,不重试 |

### 4.4 重试策略

- **指数退避**: `delay = min(1000 * 2^(retryCount-1), 30000ms)`
- **最大重试次数**: 根据指令类型决定(见4.2表格)
- **可重试错误**: 429, 500, 503, 600
- **不可重试错误**: 400, 401, 403, 700

---

## 五、客户端实现要求

### 5.1 MQTT客户端

- **连接保持**: 断线自动重连
- **心跳间隔**: 10秒
- **订阅主题**: `{sn_code}/command`
- **发布主题**: `response`, `heartbeat`

### 5.2 指令处理

1. **接收指令**
   - 解析JSON格式
   - 验证必需字段
   - 记录指令日志

2. **执行指令**
   - 根据action分发到对应处理器
   - 更新执行状态
   - 捕获异常错误

3. **返回响应**
   - 统一响应格式
   - 包含commandId用于追踪
   - 返回详细的执行结果

### 5.3 异常处理

- **网络异常**: 自动重试
- **登录过期**: 通知服务端重新登录
- **页面加载失败**: 刷新页面重试
- **元素定位失败**: 记录截图,返回错误

### 5.4 日志记录

- **请求日志**: 记录所有接收到的指令
- **响应日志**: 记录所有返回的响应
- **错误日志**: 记录所有异常和错误
- **操作日志**: 记录关键操作步骤

---

## 六、开发优先级

### P0 - 立即开发 (投递核心功能)

1. ✅ `search_jobs_enhanced` - 增强搜索
2. ✅ `search_by_url` - URL搜索
3. ✅ `batch_apply_jobs` - 批量投递
4. ✅ `refresh_resume` - 简历刷新

### P1 - 短期开发 (保活和聊天)

5. ✅ `auto_active` - 账号保活
6. ✅ `send_greeting` - 发送打招呼
7. ✅ `get_chat_detail` - 聊天详情

### P2 - 中期开发 (数据采集)

8. ⭐ `get_job_detail` - 岗位详情
9. ⭐ `get_company_info` - 公司信息

---

**文档维护**: 开发团队
**最后更新**: 2025-12-25