# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目定位

这是 AI 智能客服系统的**前端 SDK 工程**（`chatbot-sdk`），与仓库根目录的 Spring Boot 后端、`src/main/resources/static/` 下的 Vue 3 管理后台是三个独立部分。SDK 产物是一行 `<script>` 标签即可嵌入第三方站点的悬浮客服窗口，IIFE 格式挂载到 `window.ChatbotSDK`。

根目录的 `../CLAUDE.md` 描述后端架构，本文件只覆盖 `client/` 工程。

## 构建与开发

```bash
cd client/

# 安装依赖
npm install

# 构建（输出 dist/chatbot-sdk.js 与 dist/chatbot-sdk.min.js）
npm run build

# 开发 watch 模式
npm run dev
```

- 构建工具：Rollup + `@rollup/plugin-typescript` + `@rollup/plugin-terser`，配置见 `rollup.config.js`
- TypeScript 配置：`tsconfig.json`，`target: ES2017`，`strict: true`，`rootDir: ./src`，不生成 `.d.ts`
- 产物双份：`chatbot-sdk.js`（未压缩 + sourcemap，~93KB）和 `chatbot-sdk.min.js`（压缩，~45KB）
- **无测试框架**：验证通过后端的 `http://localhost:9090/sdk/test.html` 运行 22 个浏览器端用例（见 README 第十四节），本工程内没有可运行的自动化测试

## 运行时依赖

SDK 本身不独立运行，需要后端在 `requestDomain`（通常 `http://localhost:9090`）提供以下接口：

- 基础对话：`GET /ai/assistant_app/chat/sync`、`GET /ai/assistant_app/chat/sse`
- RAG：`GET /ai/assistant_app/chat/rag/sse`、`GET /ai/assistant_app/rag/sources`
- 分类：`GET /category/tree`、`GET /category/list`
- 会话：`GET /conversation/list`、`GET /conversation/{id}/messages`、`DELETE /conversation/{id}`、`GET /conversation/{id}/export`

完整接口契约见 `README.md` 第六节。修改 `api.ts` 时务必与后端 `AiController` / `ConversationController` 保持参数一致。

## 架构

### 模块职责与数据流

入口 `src/index.ts` 是单例，按固定顺序串联各模块（`init()` 中的 12 个步骤即生命周期）：

```
init(rawConfig)
  → config.ts    parseConfig()        解析 + 校验，返回 ResolvedConfig（失败返回 null，不抛异常）
  → i18n.ts      setLocale()          设置语言字典（zh-CN / en）
  → logger.ts    setDebug()           控制日志级别
  → api.ts       setApiConfig()       注入 requestDomain 等，供后续 HTTP/SSE 调用复用
  → styles.ts    injectStyles()       注入 <style data-csk-sdk>，按 primaryColor 生成主题
  → dom.ts       createLauncher() / createChatWindow()  构建 DOM，返回元素引用与 loading 控制函数
  → dom.ts       enableDrag()         弹窗头部拖拽，返回 cleanup 函数
  → chat.ts      initChat()           绑定事件、注入 DOM 引用，建立对话核心状态
  → chat.ts      initChatHistory()    异步加载 chatId 与历史（不阻塞 UI）
```

模块间通过两种方式通信：
1. **闭包状态**：`index.ts`、`chat.ts`、`api.ts` 各自持有模块级变量，靠 `init*` 函数注入
2. **CustomEvent**：DOM 层（`dom.ts`）派发 `csk:categoryChange`、`csk:loadHistory`，`index.ts` 监听后转发给 `chat.ts`

### 关键模块

- **`chat.ts`**（最大、最核心）：对话状态机。处理发送、SSE 流式追加、Markdown 渲染、RAG 来源展示、流中断兜底、无流内容降级为同步、`chatId` 自动管理逻辑、清空会话。修改对话行为优先改这里。
- **`api.ts`**：HTTP 封装 + SSE 流解析。三种 SSE 接口（普通流式、RAG 流式、同步）的解析逻辑都在这里，注意流式解析的边界处理。
- **`dom.ts`**：纯 DOM 构建与事件绑定，含知识库下拉、RAG 来源卡片、历史会话面板的渲染。
- **`styles.ts`**：所有 CSS 字符串模板，按 `primaryColor` 动态着色。改动 UI 视觉改这里，**不要**在 `dom.ts` 里写内联样式。
- **`markdown.ts`**：基于 marked（源文件 `assets/marked.min.js`，实际为 **v15.0.12**，构建时由 rollup 自动复制到 `dist/` 与后端 `static/sdk/`）的 Markdown 渲染器，`preloadMarked` 异步加载并缓存安全实例。**安全模型**：自定义 renderer 全接管输出，链接/图片仅允许 http/https，禁止 raw HTML，代码内容 escapeHtml 转义；修改渲染器时必须维持这一 XSS 防护顺序。**列表渲染坑**：`list(token)` 渲染列表项必须调用 `this.listitem(item)`，**不可** `this.parser.parse([item])` —— marked v15 的 `Parser.parse` 按 `token.type` 做 switch 分发、无 `list_item` 分支，直接 parse 会抛 `Token with "list_item" type was not found`，被 `renderMarkdown` 的 catch 降级为纯文本，导致整段回复挤成一行。

### 单例与生命周期

`index.ts` 用模块级变量持有 `config` 和所有 DOM 引用，`isInitialized` 防止重复初始化。`destroy()` 必须清理：移除 DOM、调用 `dragCleanup()`、`removeStyles()`、置空所有引用。新增 DOM 引用时记得在 `destroy()` 中同步置空。

## 关键约定

### 参数映射（SDK → 后端）

| SDK 入参 | 后端参数 | 说明 |
|----------|----------|------|
| `integrateId` | `roleId` | 客服角色 ID，决定 AI 人设和知识库范围（**必传**） |
| `userId` | `accountId` | 客户账号 ID，账号绑定角色后服务端会覆盖 roleId |
| （自动管理） | `chatId` | 从 `/conversation/list` 取或生成 `sdk_时间戳_随机串` |

`chatId` 缓存在 localStorage（key: `csk_chatId_{integrateId}_{userId}`），`clearHistory()` 会重新生成。改 `chat.ts` 的 chatId 逻辑时注意与后端 `ConversationController` 的会话匹配规则一致。

### CSS 命名空间

所有 class/id 用 `csk-` 前缀，样式注入到 `<style data-csk-sdk>`，z-index：悬浮按钮 9998，弹窗 9999。新增 DOM 元素必须带前缀，避免污染宿主页面。

### localStorage

- 消息历史 key：`csk_history_{integrateId}`，上限 200 条，超出裁剪最早 50 条
- chatId key：`csk_chatId_{integrateId}_{userId}`
- 不同 `integrateId` 隔离，互不影响

### 错误处理

**所有错误不抛异常、不阻塞宿主页面**，仅 `console.error` 输出（`error` 始终输出，`info`/`warn` 受 `debug` 控制）。新增异步逻辑要 try/catch 包裹，失败走 `logger.warn` / `logger.error`。

## 部署

构建脚本（`rollup.config.js` 的 `copyAssets` 插件）会自动把 `chatbot-sdk.js` / `chatbot-sdk.min.js`、`marked.min.js`（运行时依赖，由 `markdown.ts` 动态加载）和 `launcher-logo.png` 复制到后端 `src/main/resources/static/sdk/`，宿主页面通过 `<script src="/sdk/chatbot-sdk.min.js"></script>` 引入；CDN 分发时需同时部署这三类文件，且 `marked.min.js` 必须与 SDK 同目录（`getSdkBasePath()` 从 script src 推断加载路径）。`README.md` 有完整接入示例与全部配置参数表，文档是 SDK 对外契约的一部分，改公开 API（`init/destroy/open/close/toggle/clearHistory`）或 `SDKConfig` 字段时同步更新 README。