wecom_it_smart_desk/docs/03-技术架构/复杂场景重构-时序图.mermaid

# 复杂场景重构第一阶段 — 时序图

> **关联文档**: `复杂场景重构第一阶段-架构设计.md` §4

---

## 4.1 任务暂停流程

```mermaid
sequenceDiagram
    participant H5 as 员工H5
    participant API as FastAPI路由
    participant SM as AutoSessionService
    participant DB as PostgreSQL
    participant Redis as Redis
    participant WS as ProgressPublisher

    H5->>API: 员工发送消息 "我先去开会"
    API->>SM: 处理消息（含全局意图检测）
    SM->>SM: IntentRouter.detect_global_intent("我先去开会")
    SM-->>SM: global_intent = "pause"
    SM->>SM: pause_session(session_id, reason)
    SM->>DB: SELECT AutoSession WHERE id = ?
    SM->>SM: 校验状态（running → 可暂停）
    SM->>DB: UPDATE status='paused', paused_at=NOW()
    SM->>SM: 构建恢复点快照
    Note over SM: 快照: {title, scenario_key,<br/>current_action_id, step_desc,<br/>info_items[], paused_at}
    SM->>Redis: SET auto:resume_point:{id} = {snapshot} TTL=25h
    SM->>Redis: SADD auto:paused_sessions:{emp_id} = {id}
    SM->>WS: publish_paused(id, {title, paused_at, resume_hint})
    WS->>H5: WS事件 automation.paused
    SM-->>API: 返回 AutoSession + 暂停回复消息
    API-->>H5: {code:0, data:{session, message}}
    H5->>H5: 展示暂停确认消息<br/>"好的，您先忙～需要继续时跟我说一声「继续」就好。"
```

## 4.2 任务恢复流程

```mermaid
sequenceDiagram
    participant H5 as 员工H5
    participant API as FastAPI路由
    participant SM as AutoSessionService
    participant Redis as Redis
    participant DB as PostgreSQL
    participant Exec as ActionExecutor
    participant WS as ProgressPublisher

    H5->>API: 员工发送消息 "继续"
    API->>SM: 处理消息（含全局意图检测）
    SM->>SM: IntentRouter.detect_global_intent("继续")
    SM-->>SM: global_intent = "resume_task"
    SM->>SM: resume_session(employee_id, session_id=None)
    SM->>DB: SELECT * FROM auto_sessions<br/>WHERE employee_id=? AND status='paused'

    alt 无暂停会话
        SM-->>API: 返回提示 "没有可恢复的任务"
        API-->>H5: "您当前没有未完成的任务"

    else 仅1个暂停会话
        SM->>Redis: GET auto:resume_point:{id}
        SM->>SM: 加载恢复点快照
        SM->>DB: UPDATE status='running', paused_at=NULL
        SM->>Redis: SREM auto:paused_sessions:{emp_id} {id}
        SM->>Redis: DEL auto:resume_point:{id}
        SM->>SM: 检查必需信息项完整性
        alt 有缺失必需项
            SM-->>API: 返回需补全的信息项列表
            API-->>H5: "恢复成功，还需补充：{items}"
        else 信息完整
            SM->>Exec: run(session_id) 续行
            Note over Exec: 跳过 status in<br/>(success, failed, rejected, skipped)<br/>从 current_action_id 继续
        end
        SM->>WS: publish_resumed(id, {title, current_step})
        WS->>H5: WS事件 automation.resumed
        SM-->>API: 返回 AutoSession + 恢复点信息
        API-->>H5: {code:0, data:{session, resume_point}}
        H5->>H5: 展示恢复点回顾卡片<br/>"欢迎回来！您之前在处理「终端定位」..."

    else 多个暂停会话
        SM-->>API: 返回暂停会话列表
        API-->>H5: 返回多任务选择卡片
        H5->>H5: 展示任务列表（Vant Cell）
        H5->>API: 员工选择 "第一个" 或点击卡片
        API->>SM: resume_session(employee_id, selected_id)
        SM->>Redis: GET auto:resume_point:{selected_id}
        SM->>DB: UPDATE status='running', paused_at=NULL
        SM->>Redis: SREM + DEL 清理
        SM->>Exec: run(session_id) 续行
        SM->>WS: publish_resumed(id, {title, current_step})
        WS->>H5: WS事件 automation.resumed
        API-->>H5: 恢复成功
    end
```

## 4.3 信息更正流程

```mermaid
sequenceDiagram
    participant H5 as 员工H5
    participant API as FastAPI路由
    participant SM as AutoSessionService
    participant IIS as InformationItemService
    participant DB as PostgreSQL
    participant WS as ProgressPublisher

    H5->>API: 员工发送消息 "用户名是 lisi，不是 zhangsan"
    API->>SM: 处理消息（含全局意图检测）
    SM->>SM: IntentRouter.detect_global_intent(...)
    SM-->>SM: global_intent = "correct"<br/>corrected_field="用户名"<br/>old_value="zhangsan"<br/>new_value="lisi"
    SM->>SM: correct_info(session_id, "用户名", "lisi", "zhangsan")
    SM->>IIS: correct_value(session_id, "用户名", "lisi")
    IIS->>DB: SELECT InformationItem<br/>WHERE session_id=? AND name='用户名'

    alt is_locked == True
        IIS-->>SM: 抛出异常 INFO_ITEM_LOCKED
        SM-->>API: 错误响应 code=4015
        API-->>H5: "该字段已锁定，不可更正"
    else is_locked == False
        IIS->>IIS: update_history 追加旧值记录
        IIS->>IIS: value = "lisi", version += 1
        IIS->>DB: UPDATE InformationItem
        IIS->>IIS: check_downstream_impact(session_id, "用户名")
        alt 影响已生成动作计划
            IIS-->>SM: impact = True
            SM->>SM: 重新校验映射/动作计划
            SM-->>API: 返回更正结果 + 影响提示
            API-->>H5: "已更正终端名。信息已更新，正在重新评估处置方案..."
        else 无下游影响
            IIS-->>SM: impact = False
        end
        SM->>WS: publish_info_corrected(id, {field, old_value, new_value, version})
        WS->>H5: WS事件 automation.info_corrected
        SM-->>API: 返回 InformationItem
        API-->>H5: {code:0, data:item}
        H5->>H5: 展示更正确认消息<br/>"已更正：用户名 从「zhangsan」改为「lisi」"
    end
```

## 4.4 信息补充流程

```mermaid
sequenceDiagram
    participant H5 as 员工H5
    participant API as FastAPI路由
    participant SM as AutoSessionService
    participant IIS as InformationItemService
    participant DB as PostgreSQL
    participant WS as ProgressPublisher

    H5->>API: 员工发送消息 "再补充一下，是财务部的电脑"
    API->>SM: 处理消息（含全局意图检测）
    SM->>SM: IntentRouter.detect_global_intent(...)
    SM-->>SM: global_intent = "supplement"<br/>supplement_field="部门"<br/>supplement_value="财务部"
    SM->>SM: supplement_info(session_id, "部门", "财务部")
    SM->>IIS: supplement_value(session_id, "部门", "财务部")
    IIS->>DB: SELECT InformationItem<br/>WHERE session_id=? AND name='部门'

    alt 信息项不存在
        IIS->>IIS: 创建新信息项
        Note over IIS: modifiers = ["增量"]<br/>value = "财务部"
        IIS->>DB: INSERT InformationItem
    else 信息项已存在
        alt modifiers 含 "增量"
            IIS->>IIS: value += "; " + "财务部"（追加）
            Note over IIS: 如原值="IT部"<br/>新值="IT部; 财务部"
        else 不含 "增量"
            IIS->>IIS: 同更正处理（旧值存历史，覆盖）
        end
        IIS->>IIS: version += 1
        IIS->>IIS: update_history 追加记录
        IIS->>DB: UPDATE InformationItem
    end

    SM->>WS: publish_info_supplemented(id, {field, supplement_value, new_value})
    WS->>H5: WS事件 automation.info_supplemented
    SM-->>API: 返回 InformationItem
    API-->>H5: {code:0, data:item}
    H5->>H5: 展示补充确认消息<br/>"已补充记录：部门：财务部"
```

## 4.5 超时自动关闭流程

```mermaid
sequenceDiagram
    participant Timer as 定时任务<br/>(每小时)
    participant TC as TimeoutCleaner
    participant DB as PostgreSQL
    participant Redis as Redis
    participant WS as ProgressPublisher
    participant H5 as 员工H5

    Note over Timer: 暂停 24 小时后
    Timer->>TC: run_once()
    TC->>DB: SELECT * FROM auto_sessions<br/>WHERE status='paused'<br/>AND paused_at < NOW() - INTERVAL '24 hours'

    loop 每个超时会话
        TC->>DB: UPDATE status='closed',<br/>closed_by='system(timeout)'
        TC->>Redis: DEL auto:resume_point:{id}
        TC->>Redis: SREM auto:paused_sessions:{emp_id} {id}
        TC->>WS: publish_timeout_closed(id, {closed_at, reason})
        WS->>H5: WS事件 automation.timeout_closed
    end

    TC-->>Timer: 返回关闭数量 N

    Note over H5: 员工次日发送 "继续"
    H5->>API: POST /sessions/resume
    API->>DB: 查询暂停会话
    DB-->>API: 无暂停会话（已关闭）
    API-->>H5: "该任务已超时关闭，请重新描述您的问题，我来帮您处理。"
```

## 4.6 坐席代恢复流程

```mermaid
sequenceDiagram
    participant Agent as 坐席工作台
    participant API as FastAPI路由
    participant SM as AutoSessionService
    participant Redis as Redis
    participant DB as PostgreSQL
    participant Exec as ActionExecutor
    participant WS as ProgressPublisher

    Agent->>API: POST /sessions/{id}/agent-resume {note}
    API->>SM: agent_resume(session_id, agent_id, note)
    SM->>DB: SELECT AutoSession WHERE id = ?
    SM->>SM: 校验状态（paused → 可恢复）
    SM->>Redis: GET auto:resume_point:{id}
    SM->>DB: UPDATE status='running',<br/>paused_at=NULL,<br/>closed_by='agent:{agent_id}(resume)'
    SM->>Redis: SREM + DEL 清理
    SM->>Exec: run(session_id) 续行
    SM->>WS: publish_resumed(id, {title, current_step})
    WS->>Agent: WS事件 automation.resumed
    Note over Agent: 坐席端显示"坐席代恢复"标记
    SM-->>API: 返回 AutoSession
    API-->>Agent: {code:0, data:session}
    Agent->>Agent: 展示"已代恢复，会话继续执行"
```