docs: 更新 CLAUDE.md 添加关键词词云系统说明

CLAUDE.md

@@ -210,6 +210,79 @@ API Submitter Agent (提交到生产环境 API)
 /discover-projects all --batch=5
 ```
 
+### Keyword Cloud System (季度 AI 热点词云)
+
+**功能**: 自动化采集 Google Trends 数据，展示季度 AI 热点词汇词云。
+
+**数据流**: n8n 工作流 → AI 清洗 → 规则匹配 → PostgreSQL → Next.js 前端
+
+#### 数据库表
+- `Quarter`: 季度元数据（quarter, title, titleEn, subtitle, subtitleEn, displayOrder, isActive）
+- `Keyword`: 关键词数据（word, trendScore, description, visualConfig）
+- `VisualStyleRule`: 视觉样式规则配置（name, minScore, maxScore, color, size, border, rotation）
+- `KeywordCloudErrorLog`: 错误日志（quarter, keyword, errorType, errorMessage）
+
+#### API 端点
+- `GET /api/keyword-cloud/quarters`: 获取季度列表（支持 `isActive` 过滤）
+- `GET /api/keyword-cloud/keywords/[quarter]`: 获取指定季度的关键词
+- `GET /api/keyword-cloud/rules`: 获取视觉样式规则配置
+- `POST /api/keyword-cloud/keywords`: 批量写入关键词（n8n 使用，需 API Key 认证）
+- `GET /api/keyword-cloud/health`: 健康检查端点（返回系统统计信息）
+
+#### 前端路由
+- `/[locale]/keyword-cloud`: 词云展示页面
+
+#### 前端组件
+- `CloudWord`: 单个词汇组件（支持颜色、大小、边框、旋转、悬停弹出框）
+- `QuarterNavigator`: 季度导航组件（前后切换）
+- `ProgressIndicator`: 进度条组件（显示季度进度）
+- `KeywordCloud`: 主容器组件（集成所有子组件）
+
+#### 数据访问层
+- **Location**: `src/hooks/useKeywordCloud.ts` (服务器端函数)
+- **Functions**:
+  - `getAllQuarters()`: 获取所有季度列表
+  - `getQuarterByQuarter()`: 获取单个季度详情（含关键词计数）
+  - `getKeywordsByQuarter()`: 获取指定季度的所有关键词
+  - `getVisualStyleRules()`: 获取视觉样式规则
+  - `upsertQuarter()`: 创建或更新季度
+  - `createKeywords()`: 批量创建关键词
+  - `logKeywordCloudError()`: 记录错误日志
+
+#### 客户端 Hook
+- **Location**: `src/hooks/useKeywordCloudClient.ts`
+- **Function**: `useKeywordCloud(quarter)` - 响应式获取季度关键词数据
+
+#### n8n 工作流
+- **配置文件**: `n8n-workflows/keyword-cloud-workflow.json`
+- **文档**: `n8n-workflows/README.md`
+- **流程**:
+  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: 写入数据库
+
+#### 初始化数据
+```bash
+# 运行种子数据脚本（创建视觉规则和示例数据）
+pnpm tsx scripts/seed-keyword-cloud.ts
+```
+
+#### 测试 API
+```bash
+# 运行 API 测试脚本
+set -a && source .env.local && set +a && npx tsx scripts/test-keyword-api.ts
+```
+
+#### 环境变量
+- `WEBHOOK_API_KEY`: n8n 工作流使用的 API 密钥（必需）
+- n8n 环境变量（在 n8n 中设置）:
+  - `API_URL`: API 端点 URL（如 `http://localhost:3000`）
+  - `API_KEY`: 与 `WEBHOOK_API_KEY` 相同
+
 ## MCP Servers Usage (按需使用)
 
 1. **context7**: 不确定 API 用法时查阅最新文档