# n8n 数据治理聊天工作流 - 快速开始指南

## 🎉 工作流已创建成功！

**工作流ID**: `tWfjLZE1FmMfQAIn`  
**工作流名称**: Data-governance  
**触发方式**: Chat Trigger（聊天触发器）

---

## 📋 快速开始步骤

### 第 1 步：配置 OpenAI API 凭证 ⚠️

这是**必需**的步骤！

1. 登录 n8n 界面
2. 进入 **Settings** → **Credentials**
3. 点击 **"Add Credential"** 按钮
4. 在搜索框中输入 "OpenAI"
5. 选择 **"OpenAI API"**
6. 输入您的 OpenAI API Key（格式：`sk-...`）
7. 点击 **"Save"** 保存

### 第 2 步：连接凭证到工作流

1. 打开 **"Data-governance"** 工作流
2. 找到 **"OpenAI Chat Model"** 节点（在画布下方）
3. 点击该节点打开配置面板
4. 在 **"Credential to connect with"** 字段中
5. 选择刚才创建的 OpenAI API 凭证
6. 点击 **"Save"** 或直接关闭面板（自动保存）

### 第 3 步：激活工作流 🚀

1. 在工作流编辑器右上角
2. 找到 **"Active"** 开关（滑块）
3. 点击开关，将其切换到 **ON** 状态
4. 等待几秒钟，工作流激活成功后会显示绿色

### 第 4 步：获取聊天界面 URL 🔗

1. 点击画布上的 **"Chat Trigger"** 节点
2. 在右侧配置面板中，找到 **"Chat URL"** 或 **"Production URL"**
3. 复制这个 URL（格式类似：`http://your-n8n-server/chat/tWfjLZE1FmMfQAIn`）

### 第 5 步：测试聊天界面 💬

1. 在浏览器新标签页中打开复制的 URL
2. 您将看到一个聊天界面，标题为 **"数据治理助手 🤖"**
3. 界面会自动显示欢迎消息
4. 在输入框中输入 **"是"** 或 **"否"**
5. 点击发送按钮，观察 AI 的响应

---

## 🎯 测试场景

### 场景 1: 确认元数据管理

```
用户输入: "是"
AI 响应: CONFIRM_METADATA
系统操作: 调用 /api/meta/add 创建元数据
最终响应: "好的！已为您发起元数据新增工作流程。操作结果：成功创建元数据..."
```

### 场景 2: 拒绝元数据管理

```
用户输入: "否"
AI 响应: REJECT_METADATA
最终响应: "好的，已取消元数据管理操作。还有其他需要帮助的吗？..."
```

### 场景 3: 不明确的回答

```
用户输入: "我不太确定"
AI 响应: "请明确回答是否需要进行元数据管理（是/否）？"
```

---

## 🔧 常见问题排查

### 问题 1: 无法激活工作流

**错误信息**: "This workflow has no trigger nodes that require activation"

**原因**: 使用了 Manual Trigger 而不是 Chat Trigger

**解决方案**: ✅ 已修复！当前工作流使用 Chat Trigger，可以正常激活

---

### 问题 2: AI Agent 节点报错

**错误信息**: "No language model connected"

**原因**: OpenAI Chat Model 节点未连接凭证

**解决方案**:
1. 检查 OpenAI Chat Model 节点是否已连接到 AI Agent
2. 确认 OpenAI API 凭证已配置
3. 在 OpenAI Chat Model 节点中选择凭证

---

### 问题 3: 聊天界面无法访问

**错误信息**: 404 Not Found

**原因**: 工作流未激活

**解决方案**:
1. 确认工作流已激活（Active 开关为 ON）
2. 重新复制 Chat URL
3. 如果问题依然存在，重启 n8n 服务

---

### 问题 4: OpenAI API 调用失败

**错误信息**: "API request failed" 或 "Invalid API key"

**原因**: API Key 无效或无法访问 OpenAI

**解决方案**:

**方案 A: 检查 API Key**
```bash
1. 登录 OpenAI 官网 (https://platform.openai.com)
2. 进入 API Keys 页面
3. 验证 API Key 是否有效
4. 检查账户是否有足够的额度
```

**方案 B: 使用代理**
```bash
1. 在 OpenAI Chat Model 节点配置中
2. 找到 "Base URL" 选项
3. 输入代理地址（如：https://api.openai-proxy.com/v1）
4. 保存并测试
```

**方案 C: 使用替代模型**

将 OpenAI Chat Model 替换为：

- **Ollama Chat Model**（本地免费）
  ```bash
  # 安装 Ollama
  curl -fsSL https://ollama.com/install.sh | sh
  
  # 拉取模型
  ollama pull llama2
  
  # 在 n8n 中配置
  Base URL: http://localhost:11434
  Model: llama2
  ```

- **Groq Chat Model**（快速且有免费额度）
  ```bash
  1. 注册 Groq 账号 (https://console.groq.com)
  2. 获取 API Key
  3. 在 n8n 中添加 Groq 凭证
  4. 替换模型节点
  ```

---

### 问题 5: API 调用失败

**错误信息**: "Failed to call /api/meta/add"

**原因**: DataOps 平台 API 不可访问

**解决方案**:
1. 检查 DataOps 平台是否正常运行
2. 验证 API 端点 URL 是否正确（当前：`http://localhost:5000`）
3. 如果 n8n 和 DataOps 不在同一台服务器，需要修改为实际 IP
4. 测试 API 连通性：
   ```bash
   curl -X POST http://localhost:5000/api/meta/add \
     -H "Content-Type: application/json" \
     -d '{"name_zh":"测试","data_type":"string"}'
   ```

---

## 📊 工作流监控

### 查看执行历史

1. 在 n8n 界面中，点击左侧菜单的 **"Executions"**
2. 找到 **"Data-governance"** 工作流的执行记录
3. 点击任意执行记录查看详情
4. 可以看到每个节点的输入输出数据

### 调试技巧

**查看节点数据**:
```bash
1. 点击工作流画布上的任意节点
2. 在右侧面板中切换到 "Output" 标签
3. 查看该节点的输出数据
```

**测试单个节点**:
```bash
1. 点击节点
2. 点击 "Test step" 按钮
3. 查看执行结果
```

---

## 🚀 集成到 DataOps 平台

### 方式 1: iframe 嵌入（推荐）

在 DataOps 平台的前端代码中添加：

```html
<!-- 在页面中添加聊天窗口 -->
<div id="chat-container" style="position: fixed; bottom: 20px; right: 20px; z-index: 1000;">
  <iframe 
    src="http://your-n8n-server/chat/tWfjLZE1FmMfQAIn"
    width="400"
    height="600"
    frameborder="0"
    style="border-radius: 10px; box-shadow: 0 4px 12px rgba(0,0,0,0.15);"
  ></iframe>
</div>
```

### 方式 2: 悬浮按钮

添加一个悬浮按钮，点击后打开聊天窗口：

```html
<!-- HTML -->
<button id="chat-btn" class="floating-chat-btn" onclick="openChat()">
  🤖 数据治理助手
</button>

<!-- CSS -->
<style>
.floating-chat-btn {
  position: fixed;
  bottom: 20px;
  right: 20px;
  padding: 15px 20px;
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
  border: none;
  border-radius: 50px;
  cursor: pointer;
  font-size: 16px;
  font-weight: bold;
  box-shadow: 0 4px 15px rgba(102, 126, 234, 0.4);
  transition: all 0.3s ease;
  z-index: 1000;
}

.floating-chat-btn:hover {
  transform: translateY(-2px);
  box-shadow: 0 6px 20px rgba(102, 126, 234, 0.6);
}
</style>

<!-- JavaScript -->
<script>
function openChat() {
  const chatUrl = 'http://your-n8n-server/chat/tWfjLZE1FmMfQAIn';
  window.open(
    chatUrl,
    'data-governance-chat',
    'width=450,height=700,resizable=yes,scrollbars=yes'
  );
}
</script>
```

### 方式 3: React 组件

如果 DataOps 使用 React，可以创建一个组件：

```jsx
import React, { useState } from 'react';

function DataGovernanceChat() {
  const [isOpen, setIsOpen] = useState(false);
  const chatUrl = 'http://your-n8n-server/chat/tWfjLZE1FmMfQAIn';

  return (
    <>
      {isOpen && (
        <div className="chat-modal">
          <div className="chat-header">
            <span>🤖 数据治理助手</span>
            <button onClick={() => setIsOpen(false)}>×</button>
          </div>
          <iframe
            src={chatUrl}
            width="100%"
            height="550"
            frameBorder="0"
          />
        </div>
      )}
      
      <button 
        className="floating-chat-btn"
        onClick={() => setIsOpen(!isOpen)}
      >
        🤖 数据治理助手
      </button>
    </>
  );
}

export default DataGovernanceChat;
```

---

## 📈 下一步

工作流已成功运行后，您可以：

### 1. 扩展功能
- ✅ 添加更多数据治理操作（数据质量检查、标准制定等）
- ✅ 支持多轮对话，收集更多用户输入
- ✅ 添加数据验证和错误处理

### 2. 优化体验
- ✅ 自定义聊天界面样式
- ✅ 添加更丰富的欢迎消息
- ✅ 支持文件上传和下载

### 3. 监控和分析
- ✅ 查看执行历史和成功率
- ✅ 分析用户对话模式
- ✅ 优化 AI 提示词

---

## 📞 获取帮助

如有问题，请参考：

- **n8n 官方文档**: https://docs.n8n.io
- **LangChain 集成**: https://docs.n8n.io/integrations/langchain/
- **Chat Trigger 文档**: https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-langchain.chatTrigger/
- **项目文档**: `N8N_WORKFLOW_SUMMARY.md`

---

## ✅ 检查清单

使用此清单确保一切配置正确：

- [ ] n8n 服务正常运行
- [ ] OpenAI API 凭证已配置
- [ ] OpenAI Chat Model 节点已连接凭证
- [ ] 工作流已激活（Active 开关为 ON）
- [ ] Chat URL 可以正常访问
- [ ] 聊天界面显示欢迎消息
- [ ] 输入"是"后能正常触发元数据创建
- [ ] DataOps 平台 API 可访问
- [ ] `/api/meta/add` 接口正常工作

全部完成后，您的数据治理聊天工作流就可以正式使用了！🎉