# LangChain 对话机器人技术架构文档

## 1. 架构设计

```mermaid
graph TD
    A[用户/命令行] --> B[FastAPI 应用]
    A --> C[命令行对话程序]
    B --> D[LangGraph 工作流引擎]
    C --> E[LangChain Chain]
    D --> F[意图分析节点]
    D --> G[订单诊断节点]
    D --> H[自然对话节点]
    E --> I[Ollama 本地模型]
    F --> I
    G --> I
    H --> I
    B --> J[LangSmith 监控]
    D --> J

    subgraph "应用层"
        B
        C
    end

    subgraph "业务逻辑层"
        D
        E
        F
        G
        H
    end

    subgraph "模型服务层"
        I
    end

    subgraph "监控层"
        J
    end
```

## 2. 技术描述
- **前端**: 命令行界面 (CLI)
- **后端**: FastAPI + LangChain + LangGraph
- **模型服务**: Ollama 本地部署
- **监控**: LangSmith

核心依赖：
- Python 3.8+
- FastAPI 0.104.1
- LangChain 0.3.27
- LangGraph 0.6.6
- LangChain-Ollama 0.3.7
- LangSmith >= 0.1.0

## 3. 路由定义
| 路由 | 用途 |
|------|------|
| /chat/stream | 流式对话接口，支持意图分析和多轮对话 |
| /health | 健康检查接口，验证服务状态 |

## 4. API 定义

### 4.1 核心 API

流式对话接口
```
POST /chat/stream
```

请求参数:
| 参数名 | 参数类型 | 是否必需 | 描述 |
|--------|----------|----------|------|
| message | string | true | 用户输入的消息内容 |
| session_id | string | false | 会话ID，用于多轮对话上下文 |

响应格式 (Server-Sent Events):
| 字段名 | 字段类型 | 描述 |
|--------|----------|------|
| type | string | 消息类型：intent_analysis, thinking, order_info, diagnosis, chat_response |
| content | string | 消息内容 |
| timestamp | string | 时间戳 |

请求示例:
```json
{
  "message": "我的订单有问题，帮我看看",
  "session_id": "session_123"
}
```

响应示例:
```
data: {"type": "intent_analysis", "content": "检测到订单诊断意图", "timestamp": "2024-01-01T10:00:00Z"}

data: {"type": "thinking", "content": "正在分析订单问题...", "timestamp": "2024-01-01T10:00:01Z"}

data: {"type": "order_info", "content": "{\"order_id\": \"12345\", \"status\": \"processing\"}", "timestamp": "2024-01-01T10:00:02Z"}

data: {"type": "diagnosis", "content": "订单状态正常，预计明天发货", "timestamp": "2024-01-01T10:00:03Z"}
```

## 5. 服务架构图

```mermaid
graph TD
    A[FastAPI 应用] --> B[路由层]
    B --> C[业务逻辑层]
    C --> D[LangGraph 状态机]
    D --> E[意图分析服务]
    D --> F[订单诊断服务]
    D --> G[对话服务]
    E --> H[Ollama 模型接口]
    F --> H
    G --> H
    C --> I[LangSmith 监控服务]

    subgraph 服务层
        A
        B
        C
    end

    subgraph 业务层
        D
        E
        F
        G
    end

    subgraph 外部服务
        H
        I
    end
```

## 6. 数据模型

### 6.1 数据模型定义

```mermaid
erDiagram
    ChatSession ||--o{ Message : contains
    Message ||--|| IntentAnalysis : has
    Message ||--o| OrderDiagnosis : may_have

    ChatSession {
        string session_id PK
        datetime created_at
        datetime updated_at
        string status
    }
    
    Message {
        string message_id PK
        string session_id FK
        string content
        string message_type
        datetime timestamp
        string intent
    }
    
    IntentAnalysis {
        string analysis_id PK
        string message_id FK
        string detected_intent
        float confidence
        string reasoning
    }
    
    OrderDiagnosis {
        string diagnosis_id PK
        string message_id FK
        string order_info_json
        string diagnosis_result
        string thinking_process
    }
```

### 6.2 数据定义语言

由于这是一个演示项目，主要使用内存存储，不需要持久化数据库。以下是主要的数据结构定义：

消息数据结构
```python
# 聊天消息模型
class ChatMessage(BaseModel):
    message_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
    session_id: str
    content: str
    message_type: str  # user, assistant, system
    timestamp: datetime = Field(default_factory=datetime.now)
    intent: Optional[str] = None

# 意图分析结果
class IntentAnalysis(BaseModel):
    detected_intent: str  # order_diagnosis, natural_chat
    confidence: float
    reasoning: str

# 订单信息模拟数据
class OrderInfo(BaseModel):
    order_id: str
    customer_name: str
    product_name: str
    status: str
    order_date: str
    estimated_delivery: str

# 流式响应数据
class StreamResponse(BaseModel):
    type: str  # intent_analysis, thinking, order_info, diagnosis, chat_response
    content: str
    timestamp: str
```

初始化模拟数据
```python
# 模拟订单数据
MOCK_ORDERS = {
    "12345": {
        "order_id": "12345",
        "customer_name": "张三",
        "product_name": "iPhone 15 Pro",
        "status": "processing",
        "order_date": "2024-01-01",
        "estimated_delivery": "2024-01-05"
    },
    "67890": {
        "order_id": "67890", 
        "customer_name": "李四",
        "product_name": "MacBook Pro",
        "status": "shipped",
        "order_date": "2023-12-28",
        "estimated_delivery": "2024-01-03"
    }
}

# 会话存储 (内存)
chat_sessions: Dict[str, List[ChatMessage]] = {}
```