# Dify & Lovable 协同工作架构设计

## 系统架构概述

本系统采用分层架构，将AI能力和前端展示分离：
- **Dify**: 负责AI工作流、意图识别、智能对话等核心AI能力
- **Lovable**: 负责前端界面、用户交互、数据展示和业务逻辑

## 分工职责

### Dify 职责范围
1. **意图识别与分类**
   - 识别用户消息的意图类型（产品咨询、订单查询、售后服务等）
   - 提供意图置信度评分
   - 提取关键实体信息

2. **工作流管理**
   - 设计和执行复杂的对话工作流
   - 处理多轮对话上下文
   - 管理对话状态转换

3. **智能对话生成**
   - 生成自然、准确的AI回复
   - 根据上下文提供个性化回复
   - 支持多种对话场景

4. **知识库管理**
   - 产品信息检索
   - FAQ自动回答
   - 政策规则查询

### Lovable 职责范围
1. **用户界面展示**
   - 聊天界面渲染
   - 产品卡片展示
   - 订单状态显示

2. **业务数据管理**
   - 用户信息管理
   - 订单数据操作
   - 产品信息展示

3. **系统集成**
   - 调用Dify API
   - 数据格式转换
   - 错误处理和重试

4. **用户体验优化**
   - 加载状态管理
   - 交互反馈
   - 响应式设计

## 交互接口设计

### 1. 意图识别接口
```typescript
// Lovable -> Dify
interface IntentRequest {
  message: string;
  user_id: string;
  conversation_id?: string;
  context?: {
    current_agent?: string;
    conversation_history?: Array<{
      role: 'user' | 'assistant';
      content: string;
      timestamp: string;
    }>;
    user_profile?: {
      name?: string;
      preferences?: Record<string, any>;
    };
  };
}

// Dify -> Lovable
interface IntentResponse {
  intent: string;
  confidence: number;
  entities?: Record<string, any>;
  suggested_agent?: string;
  suggested_actions?: Array<{
    type: 'show_products' | 'show_orders' | 'show_contact';
    data?: any;
  }>;
  response_text: string;
  conversation_id: string;
  message_id: string;
}
```

### 2. 对话接口
```typescript
// Lovable -> Dify
interface ChatRequest {
  message: string;
  user_id: string;
  conversation_id?: string;
  intent_context?: {
    detected_intent?: string;
    confidence?: number;
    entities?: Record<string, any>;
  };
  business_context?: {
    current_products?: Array<any>;
    current_orders?: Array<any>;
    user_preferences?: Record<string, any>;
  };
}

// Dify -> Lovable
interface ChatResponse {
  content: string;
  conversation_id: string;
  message_id: string;
  metadata: {
    intent: string;
    confidence: number;
    source: 'dify';
    created_at: string;
    suggested_actions?: Array<{
      type: 'show_products' | 'show_orders' | 'show_contact' | 'agent_switch';
      data?: any;
      priority?: number;
    }>;
    context_update?: {
      conversation_state?: string;
      user_preferences?: Record<string, any>;
    };
  };
}
```

## 工作流程

### 1. 用户消息处理流程
```mermaid
sequenceDiagram
    participant User
    participant Lovable
    participant Dify
    participant Database

    User->>Lovable: 发送消息
    Lovable->>Dify: 调用意图识别
    Dify-->>Lovable: 返回意图和初步回复
    Lovable->>Database: 查询相关业务数据
    Lovable->>Dify: 发送带业务上下文的对话请求
    Dify-->>Lovable: 返回最终AI回复
    Lovable->>User: 展示AI回复 + 业务数据
```

### 2. 智能推荐流程
```mermaid
sequenceDiagram
    participant User
    participant Lovable
    participant Dify
    participant ProductDB

    User->>Lovable: "我想买手机"
    Lovable->>Dify: 意图识别请求
    Dify-->>Lovable: 识别为产品咨询
    Lovable->>ProductDB: 查询手机产品
    Lovable->>Dify: 带产品数据的对话请求
    Dify-->>Lovable: 生成推荐话术
    Lovable->>User: 展示推荐话术 + 产品卡片
```

## 数据格式规范

### 1. 意图类型定义
```typescript
enum IntentType {
  PRODUCT_INQUIRY = 'product_inquiry',
  ORDER_QUERY = 'order_query',
  LOGISTICS_INQUIRY = 'logistics_inquiry',
  AFTER_SALES = 'after_sales',
  PAYMENT_ISSUE = 'payment_issue',
  ACCOUNT_MANAGEMENT = 'account_management',
  GENERAL_INQUIRY = 'general_inquiry',
  AGENT_SWITCH = 'agent_switch',
  UNKNOWN = 'unknown'
}
```

### 2. 实体提取格式
```typescript
interface ExtractedEntities {
  product_name?: string;
  product_category?: string;
  order_number?: string;
  price_range?: {
    min?: number;
    max?: number;
  };
  quantity?: number;
  brand?: string;
  color?: string;
  size?: string;
  delivery_address?: string;
  phone_number?: string;
  email?: string;
}
```

## 错误处理策略

### 1. Dify 服务异常
- Lovable端实现自动重试机制（最多3次）
- 超时设置：30秒
- 降级策略：使用本地意图识别算法

### 2. 数据格式异常
- 严格校验Dify返回的数据格式
- 提供默认回复文案
- 记录错误日志供后续分析

## 性能优化

### 1. 缓存策略
- 对话上下文缓存（Redis）
- 意图识别结果缓存（5分钟）
- 产品信息缓存（1小时）

### 2. 并发处理
- 意图识别和数据查询并行执行
- 使用连接池管理Dify API调用
- 实现请求去重机制

## 配置管理

### 环境变量
```bash
# Dify 配置
DIFY_API_KEY=your_dify_api_key
DIFY_BASE_URL=https://api.dify.ai
DIFY_TIMEOUT=30000

# 功能开关
ENABLE_INTENT_RECOGNITION=true
ENABLE_CONTEXT_CACHE=true
ENABLE_FALLBACK_INTENT=true
```

### 运行时配置
```typescript
interface SystemConfig {
  intentRecognition: {
    enabled: boolean;
    confidenceThreshold: number;
    fallbackEnabled: boolean;
  };
  cache: {
    enabled: boolean;
    ttl: {
      intent: number;
      context: number;
      products: number;
    };
  };
  retry: {
    maxAttempts: number;
    backoffMs: number;
  };
}
```

## 监控与日志

### 1. 关键指标
- Dify API调用成功率
- 意图识别准确率
- 对话完成率
- 用户满意度

### 2. 日志记录
- 所有Dify API调用记录
- 意图识别结果记录
- 错误和异常记录
- 用户行为轨迹记录

## 部署说明

### 1. Dify工作流部署
- 在Dify平台创建应用
- 配置知识库和工作流
- 获取API密钥和接口地址

### 2. Lovable集成部署
- 配置环境变量
- 部署Supabase Edge Functions
- 更新前端组件

## 版本管理

### API版本兼容性
- 使用语义化版本管理
- 维护向后兼容性
- 提供版本迁移指南

### 更新流程
1. Dify工作流更新
2. 接口格式确认
3. Lovable代码适配
4. 测试验证
5. 生产环境发布