sequenceDiagram
    actor 员工 as 👤 员工
    actor 坐席 as 👤 坐席
    actor 训练师 as 👤 AI训练师
    participant H5 as H5前端
    participant AgentFE as 坐席控制台
    participant API as FastAPI
    participant KIS as KnowledgeIterationService
    participant WS as WingmanService
    participant Dify as Dify AI Platform
    participant DB as PostgreSQL
    participant NEO as Neo4jClient
    participant N4J as Neo4j 图数据库

    Note over 员工,N4J: === 通道 A: 会话→Dify→建议 ===

    员工->>H5: 发送 IT 问题（如"VPN 连不上"）
    H5->>API: POST /api/h5/conversations/current/messages
    API->>Dify: 调用 Dify Agent（员工端 AI）
    Dify-->>API: AI 回复 + confidence: 0.62
    API-->>H5: 返回消息（含 confidence）

    alt confidence < 0.7（门控触发）
        H5->>H5: 渲染「转人工」卡片 + 已收集上下文
        员工->>H5: 点击「转人工」
        H5->>API: POST 转人工请求（附上下文快照）
    end

    Note over API,N4J: === 会话结束后触发分析 ===

    API->>KIS: analyze_and_generate_suggestions(db, days=7)
    KIS->>DB: 查询过去N天转人工/标注为无用 的会话
    DB-->>KIS: 返回候选数据

    loop 每个候选会话
        KIS->>WS: generate_knowledge_suggestion(context_messages)
        WS->>WS: _build_context_messages(messages, KN_SUGGEST_PROMPT)
        WS->>Dify: _call_wingman_api(context_messages)
        Dify-->>WS: 结构化 JSON（title/content/category/tags/confidence/issue/action/relation）
        WS->>WS: _parse_json_response(content, default)
        WS-->>KIS: dict {title, content, category, confidence, issue, action, ...}

        KIS->>KIS: _auto_tag_audience(source_type, source_data)
        Note over KIS: source_session_type=="employee" → employee_quick_reply<br/>source_session_type=="engineer" → engineer_workguide

        KIS->>DB: INSERT KnowledgeSuggestion（status=pending, 含图字段）
    end

    KIS->>API: 返回分析结果统计

    Note over 坐席,N4J: === D7 内联审批 ===

    坐席->>AgentFE: 浏览会话中的提案卡片
    AgentFE->>API: GET /api/admin/knowledge-iteration/suggestions?status=pending
    API-->>AgentFE: 提案列表（含拓扑预览、confidence、audience）

    alt 坐席选择「内联审批」
        坐席->>AgentFE: 在会话内联卡片点击「采纳」
        AgentFE->>API: POST /api/admin/knowledge-iteration/suggestions/{id}/approve
        Note over API: 鉴权: require_admin / require_trainer

        API->>KIS: approve_suggestion(db, suggestion_id, reviewer_id)
        KIS->>DB: UPDATE status=approved, reviewed_at=now()
        KIS->>DB: INSERT KnowledgeBase (含 graph_sync_status=pending)
        KIS->>DB: UPDATE suggestion status=applied

        Note over KIS,N4J: D1 解读2·直接写图

        KIS->>NEO: merge_issue(issue_name, category, props)
        NEO->>N4J: MERGE (i:Issue {name: $name}) ON CREATE SET i+=$props
        N4J-->>NEO: IssueNode(uuid=...)

        KIS->>NEO: merge_action(action_name, props)
        NEO->>N4J: MERGE (a:Action {name: $name}) ON CREATE SET a+=$props
        N4J-->>NEO: ActionNode(uuid=...)

        KIS->>NEO: create_relation(issue_uuid, action_uuid, rel)
        NEO->>N4J: MATCH (i),(a) WHERE i.uuid=$i AND a.uuid=$a CREATE (i)-[:LEADS_TO {order:$o,weight:$w}]->(a)

        KIS->>DB: UPDATE suggestion graph_sync_status=synced
        KIS->>DB: UPDATE KnowledgeBase graph_sync_status=synced, graph_node_uuid=...

        API-->>AgentFE: 200 OK（含更新后提案）
    else 坐席选择「驳回」
        AgentFE->>API: POST /api/admin/knowledge-iteration/suggestions/{id}/reject {reject_reason}
        API->>KIS: reject_suggestion(db, id, reviewer_id, reason)
        KIS->>DB: UPDATE status=rejected
        API-->>AgentFE: 200 OK
    else 坐席选择「改写」
        AgentFE->>API: POST /api/admin/knowledge-iteration/suggestions/{id}/rewrite {title, content, ...}
        API->>KIS: rewrite_suggestion(db, id, reviewer_id, data)
        KIS->>DB: UPDATE title/content/category/tags/confidence...
        KIS->>DB: UPDATE status=pending（重新审批）
        API-->>AgentFE: 200 OK
    end

    Note over 训练师,N4J: === D7 独立队列（未处理提案） ===

    训练师->>AgentFE: 打开独立队列页
    AgentFE->>API: GET /api/admin/approval-queue/queued?status=pending
    Note over API: 未处理的=SESSION_CLOSED 后仍 pending 的提案<br/>或手动标记 queued
    API-->>AgentFE: 队列列表

    训练师->>AgentFE: 审核队列中的提案
    AgentFE->>API: POST /api/admin/approval-queue/{id}/dequeue-approve
    Note over API,N4J: 同 approve_suggestion 流程→写图