From abab035b17edb6c0387e74360efd24554260d9ef Mon Sep 17 00:00:00 2001
From: Caihaohan <caihaohan0712@foxmail.com>
Date: Tue, 27 Jan 2026 20:29:51 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20CLAUDE.md=20?=
 =?UTF-8?q?=E6=B7=BB=E5=8A=A0=E5=85=B3=E9=94=AE=E8=AF=8D=E8=AF=8D=E4=BA=91?=
 =?UTF-8?q?=E7=B3=BB=E7=BB=9F=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 CLAUDE.md | 73 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 73 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 826a9e9..08201ca 100644
--- a/CLAUDE.md
+++ b/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 用法时查阅最新文档