# n8n 工作流文档

本目录包含 Agent Park 的 n8n 工作流配置。

## 关键词词云工作流

**文件**: `keyword-cloud-workflow.json`

### 功能

自动采集 Google Trends 数据，生成 AI 热点词汇词云。

### 执行流程

1. **Schedule Trigger**: 每季度末最后一天的 23:00 自动触发
2. **Calculate Quarter**: 计算当前季度标识和时间范围
3. **Google Trends**: 采集热门搜索词
4. **Extract Keywords**: 提取关键词和热度分数
5. **Get Visual Rules**: 获取视觉样式规则
6. **Match Visual Rules**: 为关键词匹配视觉样式
7. **Send to API**: 写入数据库

### 环境变量

在 n8n 中设置以下环境变量：

| 变量名 | 说明 | 示例值 |
|--------|------|--------|
| `API_URL` | API 端点 URL | `http://localhost:3000` (本地) 或生产环境 URL |
| `API_KEY` | Webhook API Key | 与项目的 `WEBHOOK_API_KEY` 相同 |

### 配置步骤

1. **导入工作流**：
   - 打开 n8n 界面
   - 点击 "Import from File"
   - 选择 `keyword-cloud-workflow.json`

2. **配置 Google Trends 节点**：
   - 确保已安装 `@gamal.dev/n8n-nodes-google-trends` 包
   - 根据需要调整搜索关键词列表

3. **配置环境变量**：
   - 在 n8n 设置中添加环境变量
   - 或在每个节点的表达式字段中使用具体值

4. **手动执行测试**：
   - 点击 "Execute Workflow" 按钮
   - 检查每个节点的输出
   - 验证数据库中的数据

### API 端点

工作流调用以下 API 端点：

- `GET {API_URL}/api/keyword-cloud/rules` - 获取视觉规则
- `POST {API_URL}/api/keyword-cloud/keywords` - 批量写入关键词

### 调试

检查每个节点的输出，确保数据格式正确：

- **Calculate Quarter**: 应输出 `quarter`, `startDate`, `endDate`
- **Extract Keywords**: 应输出 `word`, `trendScore`, `quarter`
- **Match Visual Rules**: 应添加 `visualConfig` 字段
- **Send to API**: 应返回 `success: true`

### 注意事项

1. **Google Trends API 限制**：
   - Google Trends 有请求频率限制
   - 建议在非高峰期执行工作流

2. **数据质量**：
   - 当前工作流中的 `description` 和 `detailPoints` 是占位符
   - 需要添加 AI 节点（如 OpenAI）来生成真实内容

3. **时区处理**：
   - 确保时区设置正确，以便准确计算季度末日期

### 扩展建议

- **AI 内容生成**：在 "Match Visual Rules" 后添加 OpenAI 节点，生成描述和要点
- **数据验证**：添加验证节点检查数据完整性
- **错误处理**：添加错误分支，记录失败的关键词
- **通知**：工作流完成后发送通知（如 Slack、Email）