1

_doc/task.md

@@ -0,0 +1,176 @@
+# task_status_${snCode} 主题推送位置分析
+
+## 一、推送位置（服务端）
+
+### 1. 任务状态变更推送 (`task_status_update`)
+
+**位置**: `autoAiWorkSys/api/middleware/schedule/taskQueue.js`
+
+**方法**: `notifyTaskStatusChange(sn_code, taskData)`
+
+**推送时机**:
+- ✅ **任务开始执行时** (第586行)
+  - 状态: `running`
+  - 进度: `0`
+  - 触发位置: `executeTask` 方法中，任务开始执行时
+
+- ✅ **任务完成时** (第631行)
+  - 状态: `completed`
+  - 进度: `100`
+  - 触发位置: `executeTask` 方法中，任务成功完成后
+
+- ✅ **任务失败时** (第675行)
+  - 状态: `failed`
+  - 进度: `0`
+  - 错误信息: `errorMessage`
+  - 触发位置: `executeTask` 方法中，任务执行失败时
+
+**推送内容**:
+```javascript
+{
+  action: 'task_status_update',
+  data: {
+    taskId: task.id,
+    taskName: task.taskName,
+    taskType: task.taskType,
+    status: 'running' | 'completed' | 'failed',
+    progress: 0 | 100,
+    errorMessage?: string,
+    endTime?: Date
+  },
+  timestamp: string
+}
+```
+
+### 2. 任务状态摘要推送 (`task_status_summary`)
+
+**位置**: `autoAiWorkSys/api/middleware/schedule/taskQueue.js`
+
+**方法**: `sendTaskStatusSummary(sn_code)`
+
+**推送时机**:
+- ✅ **定时推送** (每10秒一次)
+  - 位置: `autoAiWorkSys/api/middleware/schedule/scheduledJobs.js`
+  - 方法: `syncTaskStatusSummary()`
+  - 条件: 只向在线设备推送（最后心跳时间 < 3分钟）
+
+**推送内容**:
+```javascript
+{
+  action: 'task_status_summary',
+  data: {
+    sn_code: string,
+    currentTask: {
+      taskId: number,
+      taskName: string,
+      taskType: string,
+      status: 'running',
+      progress: number,
+      currentStep: string,
+      startTime: Date,
+      jobTitle?: string,      // 新增：职位名称
+      companyName?: string     // 新增：公司名称
+    } | null,
+    pendingTasks: Array<{
+      taskId: number,
+      taskName: string,
+      taskType: string,
+      status: 'pending',
+      scheduledTime: Date,
+      priority: number
+    }>,
+    nextTaskTime: Date | null,
+    pendingCount: number,           // 队列中的任务数
+    totalPendingCount: number,      // 总待执行数（包括当前任务的剩余步骤）
+    mqttTopic: string,
+    timestamp: string
+  },
+  timestamp: string
+}
+```
+
+## 二、接收位置（客户端）
+
+### 1. MQTT 订阅
+
+**位置**: `boss-automation-nodejs/src/services/mqttService.js`
+
+**订阅时机**: MQTT 连接成功后 (第360行)
+
+**订阅代码**:
+```javascript
+const taskStatusTopic = `task_status_${this.config.snCode}`;
+this.client.subscribe(taskStatusTopic, { qos: 1 });
+```
+
+### 2. 消息处理
+
+**位置**: `boss-automation-nodejs/src/services/mqttService.js`
+
+**处理方法**: `handleMessage` (第292行)
+
+**处理逻辑**:
+- 如果 `action === 'task_status_update'`:
+  - 发送到渲染进程: `task:status-update`
+  
+- 如果 `action === 'task_status_summary'`:
+  - 发送到渲染进程: `task:status-summary`
+
+### 3. 渲染进程接收
+
+**位置**: `boss-automation-nodejs/app/mixins/taskMixin.js`
+
+**方法**:
+- `onTaskStatusUpdate(taskData)` - 处理任务状态变更
+- `onTaskStatusSummary(summary)` - 处理任务状态摘要
+
+**事件监听**: `boss-automation-nodejs/app/mixins/eventListenerMixin.js`
+
+## 三、当前推送策略分析
+
+### ✅ 优点
+1. **实时性**: 任务状态变更立即推送
+2. **完整性**: 定时推送完整的状态摘要
+3. **可靠性**: 只向在线设备推送，避免资源浪费
+
+### ⚠️ 潜在问题
+1. **推送频率**: 定时任务每10秒推送一次，可能过于频繁
+2. **重复推送**: 任务状态变更和定时摘要可能推送重复信息
+3. **推送时机**: 某些关键状态变更可能没有及时推送（如进度更新）
+
+## 四、建议的优化方案
+
+### 方案1: 减少定时推送频率
+- 当前: 每10秒推送一次
+- 建议: 改为每30秒或60秒推送一次
+- 理由: 任务状态变更已实时推送，定时推送主要用于同步完整状态
+
+### 方案2: 只在关键时机推送摘要
+- 任务队列变化时推送（新增/删除任务）
+- 当前任务完成/失败时推送
+- 定时推送作为兜底（频率降低）
+
+### 方案3: 合并推送
+- 将任务状态变更和摘要合并为一个消息
+- 减少消息数量，提高效率
+
+### 方案4: 添加进度更新推送
+- 任务执行过程中，定期推送进度更新
+- 例如：每完成10%进度推送一次
+
+## 五、需要推送的场景建议
+
+### ✅ 必须推送的场景
+1. **任务开始执行** - 立即推送状态变更
+2. **任务完成** - 立即推送状态变更 + 状态摘要
+3. **任务失败** - 立即推送状态变更 + 状态摘要
+4. **任务队列变化** - 新增/删除任务时推送摘要
+
+### ⚠️ 可选推送的场景
+1. **进度更新** - 每10%或每完成一个步骤推送一次
+2. **定时同步** - 作为兜底，频率降低到30-60秒
+
+### ❌ 不需要推送的场景
+1. **任务状态未变化** - 避免重复推送相同状态
+2. **设备离线** - 不向离线设备推送
+