From 137e6dd23cdb45bed52a7cfab21f86311dffe3cf Mon Sep 17 00:00:00 2001
From: zfc <zfc@zfcdeMacBook-Pro.local>
Date: Wed, 28 Jan 2026 22:08:11 +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=E6=9C=AC=E6=AC=A1=E4=BC=9A=E8=AF=9D=E7=9A=84?=
 =?UTF-8?q?=E5=AD=A6=E4=B9=A0=E7=82=B9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 前后端数据结构一致性要求
- 云图 API 和品牌 API 参数格式
- 前端常见问题解决方案

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 CLAUDE.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 6b69e40..06d9b67 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -485,3 +485,27 @@ export async function queryVideos(request: QueryRequest): Promise<QueryResponse>
 \d kol_videos
 -- 应该看到 idx_star_id, idx_star_unique_id, idx_star_nickname
 ```
+
+## 前后端数据结构一致性
+
+**重要**：后端返回的 JSON 字段名必须与前端 TypeScript 类型定义完全匹配。
+- 前端类型定义位置：`frontend/src/types/index.ts`
+- 修改后端响应结构时，务必同步检查前端类型定义
+- 常见错误：`Cannot read properties of undefined` 通常是字段名不匹配
+
+## 外部 API 参数格式
+
+### 云图 API (GetContentMaterialAnalysisInfo)
+- 日期格式：`YYYYMMDD`（不是 `YYYY-MM-DD`）
+- industry_id：数组格式 `["20"]`（不是字符串）
+- Cookie：直接使用 `sessionid=xxx` 格式
+
+### 品牌 API
+- URL 格式：`/v1/yuntu/brands?brand_id=xxx`（查询参数，非路径参数）
+- 认证：`Authorization: Bearer {token}`
+
+## 前端常见问题
+
+- **Next.js 模块错误**：清理缓存 `rm -rf .next node_modules/.cache && pnpm build`
+- **Ant Design Modal 文字无法复制**：添加 `styles={{ body: { userSelect: 'text' } }}`
+- **CORS 400 错误**：检查后端 `CORSMiddleware` 配置的 `allow_origins`