agent_9art/product1.0/Phase2-遗留-挖掘任务管理.md

Phase 2 遗留功能：挖掘任务管理

状态：设计已完成，待后续启动开发 记录时间：2026-06-04

---

功能概述

当前「会话挖掘」点击"开始挖掘"后没有任何进度反馈，用户处于黑盒等待状态。 本功能旨在为每次挖掘任务建立完整的生命周期管理：创建 → 执行中 → 完成/失败，并提供实时进度和历史回溯能力。

---

数据库设计

新增表 chat_mining_tasks

CREATE TABLE chat_mining_tasks (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    task_id VARCHAR(64) NOT NULL COMMENT '任务唯一标识 UUID',
    corp_id VARCHAR(64) NOT NULL COMMENT '企业ID',
    target_type VARCHAR(20) NOT NULL COMMENT '挖掘目标: UTTERANCE/KNOWLEDGE/ALL',
    status VARCHAR(20) NOT NULL COMMENT '状态: PENDING/RUNNING/COMPLETED/FAILED',
    total_sessions INT DEFAULT 0 COMMENT '总会话数',
    processed_sessions INT DEFAULT 0 COMMENT '已处理会话数',
    total_extracted INT DEFAULT 0 COMMENT 'LLM提取总数',
    total_saved INT DEFAULT 0 COMMENT '入库候选数',
    total_duplicates INT DEFAULT 0 COMMENT '去重过滤数',
    min_score INT DEFAULT 6 COMMENT '质量分阈值',
    time_range_start BIGINT COMMENT '时间范围起始(ms)',
    time_range_end BIGINT COMMENT '时间范围结束(ms)',
    error_msg TEXT COMMENT '失败原因',
    started_at TIMESTAMP NULL COMMENT '开始时间',
    completed_at TIMESTAMP NULL COMMENT '完成时间',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    UNIQUE KEY uk_task_id (task_id),
    INDEX idx_corp_status (corp_id, status),
    INDEX idx_created_at (created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='会话挖掘任务记录';

---

后端改动清单

1. 新增实体 MiningTask.java

路径：backend/kb-admin-service/src/main/java/com/artedu/kbadmin/entity/MiningTask.java

字段与上表对应，使用 MyBatis-Plus 注解。

2. 新增 Mapper MiningTaskMapper.java

@Mapper
public interface MiningTaskMapper extends BaseMapper<MiningTask> {
}

3. 修改 ChatMiningService.startMining()

• 任务开始时：创建 MiningTask 记录，状态 RUNNING
• 每处理完一个会话：更新 processed_sessions
• 任务完成：更新状态 COMPLETED，记录 total_extracted、total_saved、total_duplicates
• 任务异常：更新状态 FAILED，记录 error_msg

关键代码示意：

@Async
public void startMining(String taskId, String corpId, ...) {
    // 1. 创建任务记录
    MiningTask task = new MiningTask();
    task.setTaskId(taskId);
    task.setStatus("RUNNING");
    task.setStartedAt(LocalDateTime.now());
    miningTaskMapper.insert(task);
    
    try {
        List<String> sessionIds = selectQualitySessions(...);
        task.setTotalSessions(sessionIds.size());
        miningTaskMapper.updateById(task);
        
        for (String sessionId : sessionIds) {
            // ... 提取逻辑 ...
            task.setProcessedSessions(task.getProcessedSessions() + 1);
            task.setTotalExtracted(task.getTotalExtracted() + extracted);
            task.setTotalSaved(task.getTotalSaved() + saved);
            miningTaskMapper.updateById(task); // 每会话更新进度
        }
        
        task.setStatus("COMPLETED");
        task.setCompletedAt(LocalDateTime.now());
    } catch (Exception e) {
        task.setStatus("FAILED");
        task.setErrorMsg(e.getMessage());
    }
    miningTaskMapper.updateById(task);
}

4. 修改 ChatMiningController.startMining()

• 生成 taskId（UUID）
• 异步调用 chatMiningService.startMining(taskId, corpId, ...)
• 立即返回任务 ID：{"taskId": "xxx", "message": "挖掘任务已启动"}

5. 新增接口

// 任务列表（分页）
@GetMapping("/tasks")
public Result<PageResult<MiningTask>> listTasks(
    @RequestParam String corpId,
    @RequestParam(defaultValue = "1") int page,
    @RequestParam(defaultValue = "10") int size)

// 任务进度查询（前端轮询用）
@GetMapping("/tasks/{taskId}/progress")
public Result<Map<String, Object>> getTaskProgress(@PathVariable String taskId)

---

前端改动清单

1. 启动任务后立即显示任务卡片

点击「开始挖掘」后，不再只显示 toast，而是在页面下方新增一个「正在运行」的任务卡片：

• 任务ID、目标类型、时间范围
• 进度条：已处理 N / M 个会话
• 前端每 3 秒轮询 /tasks/{taskId}/progress

2. 新增「任务历史」折叠面板

在「挖掘任务配置」下方增加可折叠的「任务历史」区域：

• 表格列：任务ID、目标类型、状态（带颜色标签）、会话数、提取数、保存数、去重数、耗时、操作
• 状态标签：
  • RUNNING → 蓝色 + 进度条
  • COMPLETED → 绿色
  • FAILED → 红色
• 操作按钮：查看详情（显示失败原因）

3. 实时进度组件

// 轮询任务进度
useEffect(() => {
  if (!runningTaskId) return
  const timer = setInterval(async () => {
    const res = await request.get(`/v1/admin/chat-mine/tasks/${runningTaskId}/progress`)
    setTaskProgress(res.data)
    if (res.data.status !== 'RUNNING') {
      clearInterval(timer)
      loadStats()
      loadCandidates(activeTab)
    }
  }, 3000)
  return () => clearInterval(timer)
}, [runningTaskId])

---

待决策事项

事项	建议方案	备注
进度更新频率	每处理完1个会话更新DB	简单可靠，DB压力可控（单次挖掘≤100会话）
轮询间隔	前端3秒轮询	平衡实时性和服务器压力
历史任务保留	保留最近30天	可定期清理或归档
并发任务	同企业只允许1个RUNNING任务	避免资源竞争和LLM限流

---

关联文件

• 后端：ChatMiningService.java、ChatMiningController.java
• 前端：ChatMining.tsx
• 数据库：chat_mining_tasks 表

启动条件

当运营团队反馈以下痛点时启动开发：

1. "点击挖掘后不知道跑到哪了，刷新页面也不知道有没有完成"
2. "想看一下昨天挖了哪些会话、质量怎么样"
3. "多人同时操作可能会重复挖掘"