# CLAUDE.md

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

## 项目概述

AI 智能客服系统，基于 Spring AI Alibaba + 通义千问 + PGVector，支持 RAG 知识库检索、多轮对话、结构化数据提取、知识库全生命周期管理。

## 构建与运行

```bash
# 编译
./mvnw compile

# 运行（端口 9090）
./mvnw spring-boot:run

# 运行测试
./mvnw test

# 运行单个测试类
./mvnw test -Dtest=SupportBotApplicationTests

# 运行单个测试方法
./mvnw test -Dtest=SupportBotApplicationTests#testRag
```

**前提条件**: PostgreSQL 12+ 需运行且安装 PGVector 扩展，数据库 `support_bot` 需存在。`knowledge_category`、`knowledge_document`、`ai_model_config` 等表由 `DatabaseInitConfig` 自动创建，无需手动建表。

**测试说明**: 所有测试均为集成测试（`@SpringBootTest`），需要运行中的 PostgreSQL 和有效的 DashScope API Key。测试类：`SupportBotApplicationTests`（对话/RAG）、`PgVectorVectorStoreConfigTest`（向量存储）、`QueryTransformerTests`（查询重写策略）。无单元测试。

**访问地址**: 前端管理页面 `http://localhost:9090/index.html`，API 文档 `http://localhost:9090/doc.html`（Knife4j）

## 核心架构决策

### 主启动类排除了 PgVectorStoreAutoConfiguration
`SupportBotApplication.java` 中 `@SpringBootApplication(exclude = PgVectorStoreAutoConfiguration.class)`，因为项目在 `PgVectorStoreConfig` 中手动配置 PgVectorStore Bean（标记 `@Primary`），不使用自动配置。另有一个 `InMemoryVectorStoreConfig` 作为开发备选。

### Spring AI 集成模式
- **ChatClient Builder**: 所有对话通过 `ChatClient.builder(chatModelFactory.getChatModel("CHAT"))` 构建，ChatModel 由 `ChatModelFactory` 按 DB 活跃配置动态创建
- **Advisor 链**: `MessageChatMemoryAdvisor`(记忆) → `MyLoggerAdvisor`(日志) → `QuestionAnswerAdvisor`(RAG)
- **结构化输出**: `ProductInfoApp` 使用 `.entity(ProductInfo.class)` 提取结构化数据
- **SSE 流式**: 三种实现 — Flux\<String\>、Flux\<ServerSentEvent\>、SseEmitter

### ChatMemory 持久化
当前使用 `DatabaseChatMemory`（PostgreSQL 持久化），`FileBasedChatMemory`（Kryo 序列化）已注释掉。`ProductInfoApp` 单独使用 `InMemoryChatMemory`。

### RAG 双模式
1. **QuestionAnswerAdvisor 模式**（生产使用）: 预检索优化 + `QuestionAnswerAdvisor`
2. **RetrievalAugmentationAdvisor 模式**（实验性）: `doChatWithRagEnhance()` 中 `queryTransformers` 和 `multiQueryExpander` 未生效

### 文档处理管道
`DocumentService.uploadDocument()` 统一流程：文档提取 → `MyTokenTextSplitter` 分块 → `MyKeywordEnricher` AI 关键词提取 → `pgVectorVectorStore.add()` 向量化存储。每个分块的 metadata 中注入 `documentId`、`chunkIndex`、`sourceName`、`title` 以关联 `knowledge_document` 表。

### 预检索查询优化
四种策略在 `rag/preretrieval/` 下，由 `AssistantApp.doChatWithRagStrategy()` 根据 `strategy` 参数动态选择：REWRITE / TRANSLATION / COMPRESSION / MULTI_QUERY。另存在 Bean 配置版本（`QueryTransformerConfig`、`QueryExpanderConfig`），但实际使用自定义 Rewriter 组件。

## 关键配置

- `application.yml` 含 DashScope API Key，已被 `.gitignore` 排除
- **模型名称、温度、最大 Token 等参数已全部迁移到前端「AI 大模型配置管理」页面**，通过 `ai_model_config` 表管理，不再在 yml 中配置（yml 仅保留 `api-key`）
- MyBatis Plus 逻辑删除字段: `isDelete`，主键策略: `assign_id`(雪花算法)
- **雪花 ID 精度问题**: `KnowledgeDocument.id`、`categoryId` 和 `KnowledgeCategory.id`、`parentId` 已添加 `@JsonSerialize(using = ToStringSerializer.class)`，序列化为字符串避免前端 JS 精度丢失。新增 Long ID 字段时务必加上此注解
- PostgreSQL JSONB 字段使用自定义 `PostgresJsonTypeHandler`（期望 JSON 对象 `'{}'`，非数组 `'[]'`）
- **向量维度**: 由 `knowledge.vector.dimension` 配置（默认 1536）。修改后需执行 `DROP TABLE IF EXISTS vector_store CASCADE` 重建向量表，并重新上传知识库文档。距离类型: COSINE_DISTANCE，索引: HNSW
- **分块配置**: `knowledge.chunk.*` 配置项（`ChunkConfig`），默认 chunkSize=200, overlap=100, minChunkSizeChars=10, maxNumChunks=5000, keepSeparator=true
- **上传校验**: `ALLOWED_EXTENSIONS` 白名单 + 50MB 大小限制（`spring.servlet.multipart` 配置），前后端双重校验
- **文档去重**: `KnowledgeDocument.contentHash` 字段（SHA-256），上传时自动计算并查重
- **数据库自动初始化**: `DatabaseInitConfig` 在启动时检查并创建 `knowledge_category`/`knowledge_document`/`ai_model_config` 等表，对已存在的 `knowledge_document` 表会自动补加 `content_hash` 列。注意 `knowledge-base.sql` 脚本为早期版本，缺少此列，实际以 `DatabaseInitConfig` 为准

### 模型配置管理
- **ai_model_config 表**: 存储大模型配置，支持多套配置按 App 类型（CHAT / PRODUCT_EXTRACT / EMBEDDING / RAG_REWRITE）独立管理。**所有模型参数（名称、温度、最大Token、API Key、Base URL 等）全部由此表管理，不再依赖 application.yml**
- **激活互斥**: 同一 App 类型只能有一个 `is_active=true` 的配置，激活操作由 Service 层 `@Transactional` 保证
- **启动 seed**: 首次启动时使用硬编码默认值写入 DB（`qwen-turbo` / `text-embedding-v2`），用户可在前端修改
- **启动校验**: `ModelConfigLoader` 在应用就绪后检查 DB 中每种 App 类型是否有活跃配置，并对 DashScope 提供商比较 DB 与 yml 的 API Key 一致性
- **API Key 脱敏**: 前端展示时只显示前 4 位 + `****` + 后 4 位
- **ChatModel 运行时切换**: 通过 `ChatModelFactory` 按 DB 活跃配置动态创建/缓存 ChatModel（包括 DashScope，不再复用 yml 自动配置的 Bean），配置变更时立即生效（无需重启）
- **EmbeddingModel 运行时切换**: 通过 `EmbeddingModelFactory` + `DynamicEmbeddingModel` 代理，按 DB 活跃配置动态创建/缓存 EmbeddingModel，`PgVectorStoreConfig` 和 `InMemoryVectorStoreConfig` 注入 `DynamicEmbeddingModel`，向量化模型配置变更后无需重启即可生效
- **多提供商支持**: DashScope（通义千问）+ OpenAI 兼容提供商（DeepSeek / 豆包 / Kimi / 智谱 / OpenAI），ChatModel 和 EmbeddingModel 均通过对应 API 手动构建
- **缓存刷新**: 配置增删改激活时 Controller 自动调用 `ChatModelFactory.clearCache()` + `EmbeddingModelFactory.clearCache()` + `AssistantApp.clearCache()`

### 依赖版本
- Spring AI BOM: `1.0.1`，统一管理所有 `org.springframework.ai` 依赖版本
- `spring-ai-alibaba-starter-dashscope`: `1.0.0.4`（新版 starter，替代老版 `spring-ai-alibaba-starter` M6.1）
- `spring-ai-openai`: BOM 管理（OpenAI 兼容提供商支持）
- `spring-ai-alibaba-starter` (M6.1) 已移除，不再使用

### EmbeddingModel 架构
- **EmbeddingConfigFixer**：`ApplicationListener<ApplicationReadyEvent>`，启动时检查 EMBEDDING 配置合理性、**校验 EmbeddingModel 实际维度与配置维度是否一致**，不一致时 WARN 告警并给出修复步骤。**不再强制修正非 DashScope 配置**，尊重用户在 DB 中配置的提供商和模型
- **EmbeddingModelFactory**：按 DB 活跃配置动态创建/缓存 EmbeddingModel，**支持多种提供商**：
  - DashScope（通义千问）：`DashScopeEmbeddingModel`
  - OpenAI 兼容提供商（DeepSeek / Kimi / 智谱 / OpenAI）：通过 `OpenAiEmbeddingModel` + 自定义 baseUrl + `embeddingsPath` 创建
  - **豆包文本模型**（volcengine + 非 vision）：通过 `OpenAiEmbeddingModel`，embeddingsPath=`/embeddings`
  - **豆包多模态模型**（volcengine + `*vision*`）：通过 `VolcengineMultimodalEmbeddingModel`，手写 `RestClient` 直调 `/embeddings/multimodal`，适配 `{type, text}` 格式
  - **各厂商 embeddingsPath 映射**：
    | 提供商 | embeddingsPath | 实现类 |
    |--------|---------------|--------|
    | dashscope | — | DashScopeEmbeddingModel |
    | volcengine (vision) | `/embeddings/multimodal` | VolcengineMultimodalEmbeddingModel |
    | volcengine (text) | `/embeddings` | OpenAiEmbeddingModel |
    | moonshot | `/embeddings` | OpenAiEmbeddingModel |
    | zhipu | `/embeddings` | OpenAiEmbeddingModel |
    | deepseek | `/v1/embeddings` | OpenAiEmbeddingModel |
    | openai | `/v1/embeddings` | OpenAiEmbeddingModel |
  - 注意：各提供商的 embedding 端点兼容性由用户自行验证，向量维度需与 PgVectorStore 的 `dimensions` 一致
- **DynamicEmbeddingModel**：代理类实现 `EmbeddingModel` 接口，每次调用委托给 Factory，使 VectorStore 无需重建即可热切换
- **前端**：`ModelConfigManager.js` 对 EMBEDDING 类型不再限制 provider，可自由选择任意提供商；EMBEDDING 类型弹窗增加「向量维度」输入框（写入 `extraConfig.dimensions`）

## 前端架构

- **技术栈**: Vue 3 CDN + ES Module（`importmap` 引入，无构建工具）
- **入口**: `src/main/resources/static/index.html` → `js/app.js`
- **组件化**: 每个功能模块一个 JS 文件（`components/` 目录），导出 Vue 组件定义对象
- **状态管理**: `js/store.js` 使用 Vue 3 `reactive`，跨组件共享分类、统计、弹窗状态
- **API 封装**: `js/api.js` 统一封装所有后端调用，API 基址为空字符串（同源部署）
- **SSE 流式**: `js/utils.js` 中 `readSSEStream()` 统一处理三种 SSE 接口
- **添加新功能**: 在 `components/` 下新建 JS 组件文件，在 `app.js` 中导入注册即可

## API 路由约定

- AI 对话: `/ai/*`（`AiController`）
- 模型配置: `/model-config/*`（`AiModelConfigController`）
- 文档上传: `/upload/*`（`DocumentController`）
- 文档管理: `/document/*`（`DocumentController`）
- 批量操作: `/document/batch/*`（`DocumentController`，用 POST 避免 DELETE+RequestBody 路径冲突）
- 分类管理: `/category/*`（`DocumentController`）

## 已知 TODO

- `AssistantApp.doChatWithRagEnhance()`: `queryTransformers` 未生效
- `DocumentService.updateDocumentMetadata()`: Spring AI 无直接更新 vector_store metadata 的 API，向量元数据同步留后续
- `DocumentService.searchDocuments()`: Spring AI 1.0.1 的 filter 支持有限，分类过滤暂未实现
- `CompressionQueryRewriter`: 当前传入空历史列表
- MyBatis Plus 3.5.12 的 `mybatis-plus-spring-boot3-starter` 不含 `PaginationInnerInterceptor`，分页通过 SQL `LIMIT/OFFSET` 手动实现
- `PgVectorStoreConfig.dimensions(1536)` 硬编码了向量维度，切换非 1536 维的 Embedding 模型时需修改并重建 vector_store 表 → **已修复：维度由 `knowledge.vector.dimension` 配置，启动时自动检测不匹配并告警**