%% 3.1 對話主流程（整體）
%% 涵蓋三種使用情境：MCP 工具呼叫 / RAG 知識檢索 / Skills（視覺分析與直接生成）
flowchart TD
    A([使用者輸入\n問題 ± 圖片]) --> B[Desktop App\nChatWindow]
    B -->|"POST /api/v1/chat\nContent-Type: text/event-stream"| C[FastAPI\nSSE Endpoint]
    C --> D[LangGraph Agent\ninitialize_state]
    D --> E[manage_context\nToken 預算控制\n動態調整 RAG top_k]
    E --> F{classify_intent\n意圖分類節點}

    F -->|cad_tool| MC1
    F -->|rag| R1
    F -->|vision| V1
    F -->|general| G1
    F -->|"cad_tool + rag\n複合意圖"| CB1

    %% ─────────────────────────────────────────
    subgraph MCP_FLOW ["🔧 使用情境 A：MCP 工具呼叫（CAD 執行操作）"]
        direction TB
        MC1[MCP Client\n初始化連線 Port 8100]
        MC2{選擇 MCP 工具}
        MC3["cad_run_macro\n參數：software, macro_name, parameters\n回傳：執行狀態 / 輸出結果"]
        MC4["cad_check_interference\n參數：software, assembly_path\n回傳：干涉清單 / 衝突報告"]
        MC5[/MCP 工具執行結果/]
        MC_ERR[連線失敗\n降級至 RAG]

        MC1 -->|連線成功| MC2
        MC1 -->|連線失敗| MC_ERR
        MC2 -->|"執行巨集 / 腳本 / 批次自動化"| MC3
        MC2 -->|"干涉 / 碰撞 / 間隙分析"| MC4
        MC3 --> MC5
        MC4 --> MC5
    end

    %% ─────────────────────────────────────────
    subgraph RAG_FLOW ["📚 使用情境 B：RAG 知識檢索（文件語意搜尋）"]
        direction TB
        R1["rag_retrieve\n查詢 SQLite pre_filter_index 快取"]
        R_CACHE{快取命中？}
        R_REMOTE["向量搜尋 pgvector\n（Remote Server）"]
        R2[rerank_node\n Cross-encoder 語意重排 Top-K]
        R3{assess_retrieval\n品質評估}
        R4["重寫 Query\nIterative Retrieval\n（LangGraph 迴圈邊）"]
        R5[compress_context\nContext 壓縮控制 Token 量]

        R1 --> R_CACHE
        R_CACHE -->|"命中（TTL 有效）"| R2
        R_CACHE -->|未命中 / 過期| R_REMOTE --> R2
        R2 --> R3
        R3 -->|"品質不足，重新檢索"| R4 --> R1
        R3 -->|品質通過| R5
    end

    %% ─────────────────────────────────────────
    subgraph SKILLS_FLOW ["🛠️ 使用情境 C：Skills（視覺分析 ／ 直接生成）"]
        direction TB
        V1["Qwen2.5-VL\n多模態視覺分析\n解析圖片內容與佈局"]
        V2{需補充\n文件知識？}
        G1["generate_response\n直接呼叫 LLM\n（一般問答 / 閒聊 / 計算）"]

        V1 --> V2
    end

    %% ─────────────────────────────────────────
    subgraph COMBO_FLOW ["🔀 複合意圖（MCP + RAG 並行觸發）"]
        direction LR
        CB1["同時觸發\nMCP 工具 + RAG 檢索\n結構化資料 ＋ 文件補充"]
    end

    %% ─────────────────────────────────────────
    %% 跨情境路由
    V2 -->|"是，補充知識"| R1
    MC_ERR --> R1
    CB1 -->|觸發 MCP| MC1
    CB1 -->|觸發 RAG| R1

    %% 收斂合流
    MC5 --> MERGE
    R5  --> MERGE
    V2  -->|否，直接生成| MERGE
    G1  --> MERGE

    MERGE["組裝最終 Prompt\n① 對話歷史（manage_context 截斷後）\n② RAG Context 片段（若有）\n③ MCP / Skills 輸出（若有）"]

    MERGE --> LLM["LLM 推理\nQwen2.5-VL 7B\n（llama.cpp Server）"]

    %% ─────────────────────────────────────────
    subgraph SSE_OUT ["📡 SSE 串流回應事件"]
        direction LR
        S1["token 事件\n逐 token 推送至前端"]
        S2["sources 事件\n引用文件名稱 + 頁碼"]
        S3["done 事件\nsession_id 回傳"]
    end

    LLM --> SSE_OUT
    LLM --> AUDIT[audit_log\n非同步寫入\nSQLite audit_logs]

    SSE_OUT --> UI([前端 ChatWindow\n顯示完整回應與來源])

    %% ─────────────────────────────────────────
    %% 樣式
    classDef scenario fill:#1e3a5f,stroke:#4a9eff,color:#fff,rx:6
    classDef decision fill:#4a3000,stroke:#ffaa00,color:#fff
    classDef io fill:#1a3a1a,stroke:#4caf50,color:#fff
    classDef llm fill:#3a1a3a,stroke:#cc88ff,color:#fff
    classDef audit fill:#3a1a1a,stroke:#ff6666,color:#fff

    class MCP_FLOW,RAG_FLOW,SKILLS_FLOW,COMBO_FLOW,SSE_OUT scenario
    class F,MC2,V2,R_CACHE,R3 decision
    class A,UI io
    class LLM llm
    class AUDIT audit