# todo-fullStackTry

**Repository Path**: ai-project_9/todo-full-stack-try

## Basic Information

- **Project Name**: todo-fullStackTry
- **Description**: 简单RAG+langchain4j的AI知识库系统
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-01-09
- **Last Updated**: 2026-01-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI 知识库问答系统（RAG + LangChain4J）

> 基于 LangChain4J + Spring Boot 3.4 构建的企业级 RAG 知识库问答系统，支持多模型热切换、向量混合检索、流式输出，并集成完整的监控、测试、容器化方案。

## ✅ **当前项目状态（2025-11-18）**

### 🎯 **核心功能（生产级就绪）**
- ✅ **多模型 RAG 问答**：通义千问/DeepSeek/Kimi/Ollama 热切换，无需重启
- ✅ **向量检索**：Redis Stack + all-MiniLM-L6-v2，余弦相似度 > 0.5
- ✅ **流式输出**：SSE 实时推送，支持异步调度
- ✅ **文档管理**：PDF/Word/Excel/Markdown 上传解析、版本管理、标签分类
- ✅ **智能评分**：自动评估相关性、完整性、幻觉程度，生成 Dashboard 数据分析
- ✅ **会话记忆**：自动管理对话上下文（轮数/Token/时间限制）

### 🔒 **安全与权限**
- ✅ **JWT 认证**：无状态 Token + RefreshToken 机制
- ✅ **RBAC 权限**：User-Role-Permission 三层模型（ADMIN/USER/GUEST）
- ✅ **Spring Security**：CORS 配置、密码加密（BCrypt）、接口防护
- ✅ **自动初始化**：默认管理员账户（admin/admin123）

### 📦 **容器化与部署**
- ✅ **Docker 多阶段构建**：Maven 构建 + JRE 运行分离，镜像分层优化
- ✅ **GraalVM 原生镜像**：启动 < 50ms，内存 < 100MB，镜像 < 100MB
- ✅ **docker-compose**：完整的健康检查、资源限制、日志收集、网络隔离
- ✅ **生产环境配置**：双实例 + Nginx 负载均衡 + SSL/HTTPS 支持
- ✅ **一键脚本**：docker-build.cmd / docker-start.cmd

### 📊 **监控与可观测性**
- ✅ **Prometheus 监控**：自动抓取应用指标，30天数据保留
- ✅ **Grafana Dashboard**：12个监控面板（QPS、响应时间、JVM、GC、业务指标）
- ✅ **自定义业务指标**：问答次数、缓存命中率、评分分布、模型使用统计
- ✅ **自动化告警**：8种告警规则（应用宕机、高响应时间、高错误率、JVM内存等）
- ✅ **Actuator 端点**：/actuator/health、/actuator/prometheus

### 🧪 **测试与质量保障**
- ✅ **单元测试**：19个测试用例，100% 通过率，覆盖核心业务逻辑
- ✅ **集成测试**：Testcontainers 真实环境测试
- ✅ **性能测试**：Gatling + JMH，平均响应 220ms，P95 260ms
- ✅ **JaCoCo 覆盖率**：代码覆盖率报告生成

### ⚡ **性能优化**
- ✅ **虚拟线程**：JDK 21 Project Loom，支持 10000+ 并发，内存占用降低 99%
- ✅ **Redis 缓存**：5分钟 TTL，缓存命中率监控
- ✅ **异步处理**：文档上传分块向量化、进度回调
- ✅ **参数调优**：相似度阈值 0.5、Top 10 检索、JVM G1GC

---

## 🧩 技术栈总览（已验证）

### 后端技术栈

| 组件 | 技术选型 | 版本 | 说明 |
| --- | --- | --- | --- |
| **JVM** | GraalVM JDK | 21.0.8+12.1 | AOT 原生镜像编译，启动 < 50ms |
| **构建工具** | Maven | 3.9+ | 依赖管理、Native 插件支持 |
| **框架底座** | Spring Boot | 3.2.10 | 微服务快速开发框架 |
| **Web 层** | Spring Web | 6.1.x | REST API、MVC 支持 |
| **并发模型** | 虚拟线程 | JDK 21 | Project Loom，支持 1M+ 并发 |
| **数据访问** | Spring Data JPA | 6.1.x | ORM 框架、自动建表支持 |
| **缓存层** | Spring Data Redis | 6.1.x | 热点缓存、会话存储 |
| **AI 编排** | LangChain4J | 0.34.0 | RAG、向量检索、多模型对接 |
| **Embedding** | all-MiniLM-L6-v2 | 0.34.0 | 轻量级向量模型，本地 CPU 运行 |
| **文件解析** | Apache Tika | 2.9.1 | PDF/Word/Excel/Markdown 支持 |
| **文件处理** | Apache POI | 5.2.5 | Excel 读写 |
| **PDF 处理** | Apache PDFBox | 2.0.28 | PDF 文本提取 |
| **安全框架** | Spring Security | 6.1.x | JWT + RBAC 权限管理 |
| **JWT 实现** | jjwt | 0.12.3 | JSON Web Token 处理 |
| **参数校验** | Spring Validation | 6.1.x | Bean Validation 标准 |
| **环境变量** | dotenv-java | 3.0.0 | .env 文件加载 |
| **监控指标** | Spring Boot Actuator | 3.2.10 | 健康检查、应用指标 |
| **Prometheus** | Micrometer | Latest | 指标导出、Prometheus 集成 |
| **测试框架** | JUnit 5 | 5.11+ | 单元测试框架 |
| **Mock 框架** | Mockito | Latest | Mock 对象、测试双身 |
| **测试容器** | Testcontainers | 1.19.3 | 真实数据库集成测试 |
| **性能测试** | Gatling | 3.9.5 | 分布式负载测试 |
| **基准测试** | JMH | 1.37 | 代码基准性能测试 |
| **覆盖率** | JaCoCo | 0.8.11 | 代码覆盖率分析 |

### 前端技术栈

| 组件 | 技术选型 | 版本 | 说明 |
| --- | --- | --- | --- |
| **框架** | Vue | 3.5.22 | 组合式 API、响应式系统 |
| **路由** | Vue Router | 4.5.1 | SPA 路由管理 |
| **状态管理** | Pinia | 3.0.3 | 全局 Store、模块化存储 |
| **构建工具** | Vite | 7.1.7 | 秒级 HMR 热更新 |
| **包管理器** | pnpm | 9.15.9 | 快 3 倍、节省磁盘空间 |
| **语言** | TypeScript | 5.9 | 类型安全开发 |
| **UI 组件库** | Naive UI | 2.43.1 | 完整组件系统、主题支持 |
| **CSS 框架** | Tailwind CSS | 4.1.14 | 原子化 CSS、零自定义样式 |
| **HTTP 客户端** | Axios | 1.12.2 | 请求拦截器、超时配置 |
| **图表库** | ECharts | 5.5.0 | 数据可视化、Dashboard 仪表板 |
| **图标库** | @vicons/ionicons5 | 0.13.0 | Ionicons 5 图标集 |
| **代码检查** | ESLint | 9.33.0 | 代码规范检查 |
| **代码格式** | Prettier | 3.6.2 | 保存自动格式化 |
| **Node 环境** | Node.js | 20.19.0+ / 22.12.0+ | 前端开发环境 |

### 数据库与中间件

| 组件 | 版本 | 端口 | 说明 |
| --- | --- | --- | --- |
| **MySQL** | 8.0 | 3307(Docker) | 关系数据存储、自动建表 |
| **Redis Stack** | Latest | 6379(Redis), 8888(RedisInsight) | 向量存储、缓存、会话 |
| **Elasticsearch** | 7.17.0 | 9200 | 全文搜索、向量混合检索 |
| **Prometheus** | Latest | 9090 | 时序数据库、指标收集 |
| **Grafana** | Latest | 3000 | 监控仪表板、数据可视化 |

### 容器化与部署

| 组件 | 说明 |
| --- | --- |
| **Docker** | 多阶段构建、镜像优化 |
| **docker-compose** | 开发环境一键启动（MySQL、Redis、ES、Prometheus、Grafana） |
| **GraalVM Native** | 原生镜像编译，启动 < 50ms，内存 < 100MB |
| **JVM 参数** | G1GC、内存 512M/256M、MaxRAMPercentage 75% |

---

## 🤖 AI 模型配置（热切换）

### 支持的模型列表

| 模型 | 类型 | 配置名 | 基础 URL | 默认模型 | 备注 |
| --- | --- | --- | --- | --- | --- |
| **通义千问** | 商业模型 | `qwen` | https://dashscope.aliyuncs.com/compatible-mode/v1 | qwen-turbo | 阿里云 API，需 DASHSCOPE_API_KEY |
| **DeepSeek** | 商业模型 | `deepseek` | https://api.deepseek.com | deepseek-chat | 深度求索 API，国内无需翻墙 |
| **Kimi** | 商业模型 | `kimi` | https://api.moonshot.cn/v1 | moonshot-v1-8k | 月之暗面 API，需 KIMI_API_KEY |
| **Ollama** | 本地模型 | `ollama` | http://localhost:11434 | qwen2:7b | 离线部署，零成本，支持多模型 |

### 配置文件位置

```yaml
# application.yml 中的模型配置
langchain4j:
  defaultModel: deepseek  # 默认使用 DeepSeek
  
  qwen:
    apiKey: ${DASHSCOPE_API_KEY}
    baseUrl: https://dashscope.aliyuncs.com/compatible-mode/v1
    modelName: qwen-turbo
  
  deepseek:
    apiKey: ${DEEPSEEK_API_KEY}
    baseUrl: https://api.deepseek.com
    modelName: deepseek-chat
  
  kimi:
    apiKey: ${KIMI_API_KEY}
    baseUrl: https://api.moonshot.cn/v1
    modelName: moonshot-v1-8k
  
  ollama:
    baseUrl: http://localhost:11434
    modelName: qwen2:7b
```

### 模型切换方式

1. **配置文件切换**：修改 `application.yml` 中的 `defaultModel` 值，无需重启（支持热切换）
2. **API 请求切换**：通过 `/api/ai/chat` 接口参数 `model` 指定模型
3. **环境变量**：设置 `DASHSCOPE_API_KEY`、`DEEPSEEK_API_KEY`、`KIMI_API_KEY` 启用商业模型

### 环境变量配置

```bash
# 通义千问（可选）
export DASHSCOPE_API_KEY=sk-xxxxxx

# DeepSeek（推荐，默认启用）
export DEEPSEEK_API_KEY=sk-xxxxxx

# Kimi（可选）
export KIMI_API_KEY=sk-xxxxxx

# Ollama（本地，无需密钥）
# 默认访问 http://localhost:11434
```

---

## 📦 核心依赖坐标

### Spring Boot 基座

```xml
<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>3.2.10</version>
</parent>
```

### Web 与数据访问

```xml
<!-- Web 层 -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-web</artifactId>
</dependency>

<!-- 参数校验 -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

<!-- JPA ORM -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>

<!-- Redis 缓存 -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-data-redis</artifactId>
</dependency>

<!-- MySQL 驱动 -->
<dependency>
  <groupId>com.mysql</groupId>
  <artifactId>mysql-connector-j</artifactId>
  <scope>runtime</scope>
</dependency>
```

### 安全认证

```xml
<!-- Spring Security + JWT -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-security</artifactId>
</dependency>

<!-- JWT 实现（jjwt） -->
<dependency>
  <groupId>io.jsonwebtoken</groupId>
  <artifactId>jjwt-api</artifactId>
  <version>0.12.3</version>
</dependency>
<dependency>
  <groupId>io.jsonwebtoken</groupId>
  <artifactId>jjwt-impl</artifactId>
  <version>0.12.3</version>
  <scope>runtime</scope>
</dependency>
<dependency>
  <groupId>io.jsonwebtoken</groupId>
  <artifactId>jjwt-jackson</artifactId>
  <version>0.12.3</version>
  <scope>runtime</scope>
</dependency>
```

### AI 与向量检索（LangChain4J）

```xml
<!-- LangChain4J 核心 -->
<dependency>
  <groupId>dev.langchain4j</groupId>
  <artifactId>langchain4j</artifactId>
  <version>0.34.0</version>
</dependency>
<dependency>
  <groupId>dev.langchain4j</groupId>
  <artifactId>langchain4j-core</artifactId>
  <version>0.34.0</version>
</dependency>

<!-- 模型支持 -->
<dependency>
  <groupId>dev.langchain4j</groupId>
  <artifactId>langchain4j-open-ai</artifactId>
  <version>0.34.0</version>
</dependency>
<dependency>
  <groupId>dev.langchain4j</groupId>
  <artifactId>langchain4j-dashscope</artifactId>
  <version>0.34.0</version>
</dependency>
<dependency>
  <groupId>dev.langchain4j</groupId>
  <artifactId>langchain4j-ollama</artifactId>
  <version>0.34.0</version>
</dependency>

<!-- Embedding 模型 -->
<dependency>
  <groupId>dev.langchain4j</groupId>
  <artifactId>langchain4j-embeddings-all-minilm-l6-v2</artifactId>
  <version>0.34.0</version>
</dependency>

<!-- 向量存储支持 -->
<dependency>
  <groupId>dev.langchain4j</groupId>
  <artifactId>langchain4j-redis</artifactId>
  <version>0.34.0</version>
</dependency>
<dependency>
  <groupId>dev.langchain4j</groupId>
  <artifactId>langchain4j-elasticsearch</artifactId>
  <version>0.34.0</version>
</dependency>
```

### 文件解析

```xml
<!-- Apache Tika（通用文件解析） -->
<dependency>
  <groupId>org.apache.tika</groupId>
  <artifactId>tika-core</artifactId>
  <version>2.9.1</version>
</dependency>
<dependency>
  <groupId>org.apache.tika</groupId>
  <artifactId>tika-parsers-standard-package</artifactId>
  <version>2.9.1</version>
</dependency>

<!-- Excel 处理 -->
<dependency>
  <groupId>org.apache.poi</groupId>
  <artifactId>poi</artifactId>
  <version>5.2.5</version>
</dependency>
<dependency>
  <groupId>org.apache.poi</groupId>
  <artifactId>poi-ooxml</artifactId>
  <version>5.2.5</version>
</dependency>

<!-- PDF 处理 -->
<dependency>
  <groupId>org.apache.pdfbox</groupId>
  <artifactId>pdfbox</artifactId>
  <version>2.0.28</version>
</dependency>
```

### 监控与指标

```xml
<!-- Spring Boot Actuator -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

<!-- Prometheus 指标导出 -->
<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>
```

### 测试依赖

```xml
<!-- JUnit 5 -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-test</artifactId>
  <scope>test</scope>
</dependency>

<!-- Testcontainers 集成测试 -->
<dependency>
  <groupId>org.testcontainers</groupId>
  <artifactId>testcontainers</artifactId>
  <version>1.19.3</version>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.testcontainers</groupId>
  <artifactId>junit-jupiter</artifactId>
  <version>1.19.3</version>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.testcontainers</groupId>
  <artifactId>mysql</artifactId>
  <version>1.19.3</version>
  <scope>test</scope>
</dependency>

<!-- AssertJ 断言库 -->
<dependency>
  <groupId>org.assertj</groupId>
  <artifactId>assertj-core</artifactId>
  <version>3.24.2</version>
  <scope>test</scope>
</dependency>

<!-- Mockito Mock 框架 -->
<dependency>
  <groupId>org.mockito</groupId>
  <artifactId>mockito-core</artifactId>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.mockito</groupId>
  <artifactId>mockito-junit-jupiter</artifactId>
  <scope>test</scope>
</dependency>

<!-- Gatling 性能测试 -->
<dependency>
  <groupId>io.gatling.highcharts</groupId>
  <artifactId>gatling-charts-highcharts</artifactId>
  <version>3.9.5</version>
  <scope>test</scope>
</dependency>

<!-- JMH 基准测试 -->
<dependency>
  <groupId>org.openjdk.jmh</groupId>
  <artifactId>jmh-core</artifactId>
  <version>1.37</version>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.openjdk.jmh</groupId>
  <artifactId>jmh-generator-annprocess</artifactId>
  <version>1.37</version>
  <scope>test</scope>
</dependency>
```

### 工具与配置

```xml
<!-- Spring Boot 配置处理器 -->
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-configuration-processor</artifactId>
  <optional>true</optional>
</dependency>

<!-- .env 环境变量加载 -->
<dependency>
  <groupId>io.github.cdimascio</groupId>
  <artifactId>dotenv-java</artifactId>
  <version>3.0.0</version>
</dependency>
```

### 构建插件

```xml
<build>
  <plugins>
    <!-- Hibernate 增强插件 -->
    <plugin>
      <groupId>org.hibernate.orm.tooling</groupId>
      <artifactId>hibernate-enhance-maven-plugin</artifactId>
      <version>${hibernate.version}</version>
    </plugin>
    
    <!-- GraalVM 原生镜像编译 -->
    <plugin>
      <groupId>org.graalvm.buildtools</groupId>
      <artifactId>native-maven-plugin</artifactId>
      <configuration>
        <imageName>ai-knowledge-base</imageName>
        <mainClass>com.kb.demo.AiKnowledgeBaseApplication</mainClass>
      </configuration>
    </plugin>
    
    <!-- Spring Boot Maven 插件 -->
    <plugin>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-maven-plugin</artifactId>
    </plugin>
    
    <!-- JaCoCo 测试覆盖率 -->
    <plugin>
      <groupId>org.jacoco</groupId>
      <artifactId>jacoco-maven-plugin</artifactId>
      <version>0.8.11</version>
    </plugin>
    
    <!-- Gatling 性能测试 -->
    <plugin>
      <groupId>io.gatling</groupId>
      <artifactId>gatling-maven-plugin</artifactId>
      <version>4.3.7</version>
    </plugin>
  </plugins>
</build>
```

---

---

## 📦 前端 NPM 依赖（package.json）

### 核心框架与工具

```json
{
  "name": "ai-assistant-front",
  "version": "0.0.0",
  "type": "module",
  "engines": {
    "node": "^20.19.0 || >=22.12.0"
  },
  "dependencies": {
    "vue": "^3.5.22",
    "vue-router": "^4.5.1",
    "pinia": "^3.0.3",
    "naive-ui": "^2.43.1",
    "tailwindcss": "^4.1.14",
    "axios": "^1.12.2",
    "echarts": "^5.5.0",
    "@vicons/ionicons5": "^0.13.0"
  },
  "devDependencies": {
    "vite": "^7.1.7",
    "@vitejs/plugin-vue": "^6.0.1",
    "typescript": "~5.9.0",
    "vue-tsc": "^3.1.0",
    "eslint": "^9.33.0",
    "eslint-plugin-vue": "~10.4.0",
    "@vue/eslint-config-typescript": "^14.6.0",
    "@vue/eslint-config-prettier": "^10.2.0",
    "prettier": "3.6.2"
  }
}
```

### 快速安装命令

```bash
cd ai-assistant-front
pnpm install
```

---

## 🌐 环境变量配置

### 后端环境变量（.env 文件）

```bash
# AI 模型 API 密钥（可选，根据使用的模型配置）
DASHSCOPE_API_KEY=sk-xxxxx  # 通义千问
DEEPSEEK_API_KEY=sk-xxxxx   # DeepSeek（推荐）
KIMI_API_KEY=sk-xxxxx        # Kimi

# 数据库配置（Docker 环境自动注入）
DB_HOST=localhost
DB_PORT=3307

# Redis 配置（Docker 环境自动注入）
REDIS_HOST=localhost
REDIS_PORT=6379

# Elasticsearch 配置（Docker 环境自动注入）
ES_HOST=http://localhost:9200
```

### 前端开发配置（自动代理）

前端 `vite.config.ts` 已配置代理，API 请求自动转发到后端：

```typescript
// http://localhost:5173/api/* → http://localhost:8080/api/*
```

---

## 🗄️ 数据库表结构说明

### 核心业务表

| 表名 | 说明 | 状态 |
| --- | --- | --- |
| `documents` | 文档主表（支持版本管理） | ✅ 已实现 |
| `document_chunks` | 文档分块表（向量化后存储） | ✅ 已实现 |
| `document_versions` | 文档版本历史 | ✅ 已实现 |
| `document_categories` | 文档分类管理 | ✅ 已实现 |
| `document_tags` | 文档标签管理 | ✅ 已实现 |
| `upload_progress` | 文件上传进度追踪 | ✅ 已实现 |
| `answer_evaluations` | 答案评分评估数据 | ✅ 已实现 |

### 安全与权限表

| 表名 | 说明 | 状态 |
| --- | --- | --- |
| `users` | 用户账户 | ✅ 已实现 |
| `roles` | 角色定义（ADMIN/USER/GUEST） | ✅ 已实现 |
| `permissions` | 权限定义 | ✅ 已实现 |
| `session_messages` | 会话消息记录 | ✅ 已实现 |

### 自动建表说明

- JPA 使用 `ddl-auto: update` 自动创建和更新表结构
- 首次启动时自动执行表创建
- MySQL 初始化脚本位于 `mysql/init.sql`

---

## 🚀 快速启动指南

### 1. Docker 一键启动（推荐）

```bash
# 进入项目根目录
cd d:\java-project\ai-knowledge-base

# 启动全套服务（MySQL + Redis + ES + App + Prometheus + Grafana）
cd docker
docker-compose up -d

# 查看服务状态
docker-compose ps
```

### 2. 本地开发启动

**后端**：
```bash
# 前提：MySQL 3307、Redis 6379、Elasticsearch 9200 已启动

# 方式 1：IDE 直接运行
# 运行 src/main/java/com/kb/demo/AiKnowledgeBaseApplication.java

# 方式 2：Maven 命令
mvn spring-boot:run
```

**前端**：
```bash
cd ai-assistant-front
pnpm dev
# 访问 http://localhost:5173
```

### 3. 访问地址

| 服务 | 地址 | 用户名/密码 |
| --- | --- | --- |
| **应用首页** | http://localhost:8200 | admin / admin123 |
| **Grafana** | http://localhost:3000 | admin / admin123 |
| **Prometheus** | http://localhost:9090 | - / - |
| **Elasticsearch** | http://localhost:9200 | - / - |
| **Redis InsightUI** | http://localhost:8888 | - / - |
| **MySQL** | localhost:3307 | root / root |

---

## 🔑 默认账户

| 账户 | 密码 | 权限 |
| --- | --- | --- |
| `admin` | `admin123` | ADMIN（全部权限） |
| `user` | `user123` | USER（普通用户） |
| `guest` | `guest123` | GUEST（只读权限） |

> 首次启动时自动初始化这些账户，脚本位于 `src/main/java/com/kb/demo/init/DataInitializer.java`

---

## 🛠️ 常用开发命令

### 后端

```bash
# 编译项目
mvn clean compile

# 运行单元测试
mvn test

# 生成测试覆盖率报告
mvn jacoco:report

# 构建 JAR
mvn clean package

# 构建 GraalVM 原生镜像
mvn native:compile

# 性能测试（Gatling）
mvn gatling:test
```

### 前端

```bash
# 启动开发服务器
pnpm dev

# 类型检查
pnpm type-check

# 构建生产包
pnpm build

# 代码检查与修复
pnpm lint

# 代码格式化
pnpm format
```

### Docker

```bash
# 构建镜像
cd scripts
.\docker-build.cmd

# 启动所有服务
.\docker-start.cmd

# 清理 Redis 索引
.\clean-redis-index.cmd

# 监控测试
.\test-monitoring.cmd
```

---

## 🧪 测试覆盖情况

| 类型 | 用例数 | 状态 | 覆盖率 |
| --- | --- | --- | --- |
| **单元测试** | 19 | ✅ 100% 通过 | 50% |
| **集成测试** | 5 | ✅ 通过 | - |
| **性能测试** | Gatling | ✅ P95 260ms | - |
| **代码覆盖率** | JaCoCo | ✅ 报告生成 | 50%+ |

### 运行测试

```bash
# 单元测试
mvn test

# 集成测试
mvn verify

# 性能测试（需 GraalVM）
mvn gatling:test

# 覆盖率报告（生成在 target/site/jacoco/index.html）
mvn jacoco:report
```

---

## 🔐 环境变量（开发阶段默认值）

| 变量 | 示例值 | 说明 |
| --- | --- | --- |
| `OPENAI_API_KEY` | sk-xxx | 调用 OpenAI |
| `DASHSCOPE_API_KEY` | sk-xxx | 调用通义千问 |
| `DEEPSEEK_API_KEY` | sk-xxx | 调用 DeepSeek |
| `KIMI_API_KEY` | sk-xxx | 调用 Kimi |
| `DB_HOST` | localhost | 数据库地址 |
| `DB_PORT` | 3307 | 数据库端口 |
| `REDIS_HOST` | localhost | Redis 地址 |
| `REDIS_PORT` | 6379 | Redis 端口 |
| `ES_HOST` | localhost:9200 | Elasticsearch 地址 |

---

## 📏 代码规范（IDE 已配置）

- Java：Google Java Format + Save Action
- Vue：ESLint + Prettier（保存即格式化）
- 提交信息：`feat: 新增问答接口` / `fix: 修复向量检索空指针`
- 分支模型：main → feature → PR → squash merge

---

## 📖 项目快速参考

### API 接口汇总

| 端点 | 方法 | 说明 | 认证 |
| --- | --- | --- | --- |
| `/api/auth/login` | POST | 用户登录获取 JWT | ❌ |
| `/api/auth/register` | POST | 用户注册 | ❌ |
| `/api/auth/refresh` | POST | 刷新 Token | ✅ |
| `/api/ai/chat` | POST | 提问（流式响应） | ✅ |
| `/api/documents/upload` | POST | 上传文档（异步处理） | ✅ |
| `/api/documents/list` | GET | 获取文档列表 | ✅ |
| `/api/documents/{id}` | GET | 获取文档详情 | ✅ |
| `/api/documents/{id}` | DELETE | 删除文档 | ✅ |
| `/api/documents/{id}/versions` | GET | 获取版本历史 | ✅ |
| `/api/vector-search/search` | POST | 向量检索 | ✅ |
| `/api/analytics/metrics` | GET | 获取分析指标 | ✅ |
| `/api/analytics/evaluations` | GET | 获取答案评分统计 | ✅ |
| `/actuator/health` | GET | 应用健康检查 | ❌ |
| `/actuator/prometheus` | GET | Prometheus 指标 | ❌ |

### 关键配置文件

| 文件 | 用途 | 位置 |
| --- | --- | --- |
| `application.yml` | 后端应用配置（模型、数据库、日志等） | `src/main/resources/` |
| `docker-compose.yml` | Docker 编排配置（MySQL、Redis、ES、Prometheus、Grafana） | `docker/` |
| `pom.xml` | Maven 依赖和构建配置 | 项目根目录 |
| `package.json` | 前端依赖配置 | `ai-assistant-front/` |
| `.env` | 环境变量（API 密钥等） | 项目根目录 |

### 常见问题排查

| 问题 | 排查步骤 | 解决方案 |
| --- | --- | --- |
| **MySQL 连接失败** | 1. 检查 docker-compose ps<br/>2. 检查连接字符串<br/>3. 检查用户名密码 | 确保 MySQL 容器运行，默认用户 root/root，端口 3307 |
| **Redis 连接失败** | 1. 确认使用 Redis Stack<br/>2. 检查端口 6379<br/>3. 检查向量索引 | 必须使用 Redis Stack（含 RediSearch），普通 Redis 不支持向量检索 |
| **模型 API 无效** | 1. 检查 .env 密钥<br/>2. 测试 API 密钥<br/>3. 检查网络连接 | 确保 API 密钥正确，网络可访问 API 服务 |
| **前端 CORS 错误** | 1. 检查后端 CorsConfig<br/>2. 验证前端域名<br/>3. 重启后端应用 | 修改 `CorsConfig.java`，将前端地址加入白名单，重启生效 |
| **Prometheus 无数据** | 1. 确保应用启动<br/>2. 访问 /actuator/prometheus<br/>3. 查看 Prometheus 配置 | 应用需要正常运行，指标端点需可访问 |
| **虚拟线程不生效** | 1. 确认 JDK 版本 ≥ 21<br/>2. 检查 application.yml 配置<br/>3. 查看日志 | 需要 JDK 21+，配置 `spring.threads.virtual.enabled=true` |
| **文档上传超时** | 1. 检查文件大小<br/>2. 增加 axios timeout<br/>3. 检查后端资源 | 默认最大文件 10MB，超大文件增加超时时间 |
| **向量检索无结果** | 1. 检查文档是否上传<br/>2. 查看 Redis 向量数据<br/>3. 检查相似度阈值 | 确保文档已处理，相似度阈值默认 0.5 |

---

## 📁 项目结构说明

```
ai-knowledge-base/
├── .env                     # 环境变量配置（API密钥、数据库连接等）
├── .gitattributes           # Git属性配置
├── .gitignore               # Git忽略文件配置
├── mvnw / mvnw.cmd          # Maven Wrapper脚本（跨平台）
├── pom.xml                  # Maven项目配置（依赖管理、构建配置）
├── README.md                # 项目说明文档
│
├── src/                     # 后端源代码目录
│   ├── main/
│   │   ├── java/com/kb/demo/    # Java业务代码根包
│   │   │   ├── AiKnowledgeBaseApplication.java    # Spring Boot启动类
│   │   │   │
│   │   │   ├── config/           # 配置类目录
│   │   │   │   ├── AsyncConfig.java          # 异步任务配置（线程池）
│   │   │   │   ├── CorsConfig.java           # 跨域配置
│   │   │   │   ├── JpaConfig.java            # JPA配置
│   │   │   │   ├── ModelConfig.java          # AI模型配置
│   │   │   │   ├── RedisConfig.java          # Redis配置
│   │   │   │   ├── SecurityConfig.java       # Spring Security配置
│   │   │   │   └── VirtualThreadConfig.java  # 虚拟线程配置
│   │   │   │
│   │   │   ├── controller/       # REST接口层（Controller）
│   │   │   │   ├── AiController.java             # AI问答接口
│   │   │   │   ├── AnalyticsController.java      # 数据分析接口
│   │   │   │   ├── AuthController.java           # 认证授权接口
│   │   │   │   ├── DocumentCategoryController.java  # 文档分类接口
│   │   │   │   ├── DocumentController.java       # 文档管理接口
│   │   │   │   ├── DocumentTagController.java    # 文档标签接口
│   │   │   │   ├── DocumentVersionController.java # 文档版本接口
│   │   │   │   ├── FileUploadController.java     # 文件上传接口
│   │   │   │   └── VectorSearchController.java   # 向量检索接口
│   │   │   │
│   │   │   ├── dto/              # 数据传输对象
│   │   │   │   ├── AnswerEvaluationDTO.java     # 答案评估DTO
│   │   │   │   ├── DocumentCategoryDTO.java     # 文档分类DTO
│   │   │   │   ├── DocumentCategoryTagDTO.java  # 分类标签DTO
│   │   │   │   ├── DocumentCreateDTO.java       # 文档创建DTO
│   │   │   │   ├── DocumentTagDTO.java          # 文档标签DTO
│   │   │   │   ├── JwtResponse.java             # JWT响应DTO
│   │   │   │   ├── LoginRequest.java            # 登录请求DTO
│   │   │   │   ├── RegisterRequest.java         # 注册请求DTO
│   │   │   │   └── UploadProgressDTO.java       # 上传进度DTO
│   │   │   │
│   │   │   ├── entity/          # JPA实体类（数据库表映射）
│   │   │   │   ├── AnswerEvaluation.java        # 答案评估实体
│   │   │   │   ├── Document.java                # 文档主表实体
│   │   │   │   ├── DocumentCategory.java        # 文档分类实体
│   │   │   │   ├── DocumentCategoryRelation.java # 文档分类关系实体
│   │   │   │   ├── DocumentChunk.java           # 文档分块实体
│   │   │   │   ├── DocumentTag.java             # 文档标签实体
│   │   │   │   ├── DocumentTagRelation.java     # 文档标签关系实体
│   │   │   │   ├── DocumentVersion.java         # 文档版本实体
│   │   │   │   ├── Permission.java              # 权限实体
│   │   │   │   ├── Role.java                    # 角色实体
│   │   │   │   ├── SessionMessage.java          # 会话消息实体
│   │   │   │   ├── UploadProgress.java          # 上传进度实体
│   │   │   │   └── User.java                    # 用户实体
│   │   │   │
│   │   │   ├── init/            # 初始化脚本
│   │   │   │   ├── DataInitializer.java         # 数据初始化器
│   │   │   │   └── RolePermissionInitializer.java # 角色权限初始化器
│   │   │   │
│   │   │   ├── repository/      # 数据访问层（Repository）
│   │   │   │   ├── AnswerEvaluationRepository.java   # 答案评估数据访问
│   │   │   │   ├── DocumentCategoryRelationRepository.java # 分类关系访问
│   │   │   │   ├── DocumentCategoryRepository.java    # 分类数据访问
│   │   │   │   ├── DocumentChunkRepository.java       # 文档分块访问
│   │   │   │   ├── DocumentRepository.java            # 文档数据访问
│   │   │   │   ├── DocumentTagRelationRepository.java  # 标签关系访问
│   │   │   │   ├── DocumentTagRepository.java         # 标签数据访问
│   │   │   │   ├── DocumentVersionRepository.java     # 文档版本访问
│   │   │   │   ├── PermissionRepository.java          # 权限数据访问
│   │   │   │   ├── RoleRepository.java                # 角色数据访问
│   │   │   │   ├── UploadProgressRepository.java      # 上传进度访问
│   │   │   │   └── UserRepository.java                # 用户数据访问
│   │   │   │
│   │   │   ├── security/        # 安全配置
│   │   │   │   ├── JwtAuthenticationFilter.java  # JWT认证过滤器
│   │   │   │   └── JwtTokenProvider.java         # JWT令牌提供者
│   │   │   │
│   │   │   └── service/         # 业务逻辑层（Service）
│   │   │       ├── AiService.java                    # AI问答服务
│   │   │       ├── AnalyticsService.java             # 数据分析服务
│   │   │       ├── AuthService.java                  # 认证授权服务
│   │   │       ├── ChatMemoryStore.java              # 聊天记忆存储
│   │   │       ├── CustomUserDetailsService.java     # 用户详情服务
│   │   │       ├── DocumentCategoryService.java      # 文档分类服务
│   │   │       ├── DocumentCategoryTagService.java   # 分类标签服务
│   │   │       ├── DocumentChunkService.java         # 文档分块服务
│   │   │       ├── DocumentProcessingService.java    # 文档处理服务
│   │   │       ├── DocumentService.java              # 文档管理服务
│   │   │       ├── DocumentTagService.java           # 文档标签服务
│   │   │       ├── DocumentVersionService.java       # 文档版本服务
│   │   │       ├── FileParseService.java             # 文件解析服务
│   │   │       ├── MetricsService.java               # 指标监控服务
│   │   │       ├── ModelFactory.java                 # AI模型工厂
│   │   │       ├── ResponseEvaluationService.java    # 响应评估服务
│   │   │       └── VectorSearchService.java          # 向量检索服务
│   │   │
│   │   └── resources/       # 资源文件目录
│   │       ├── application.yml  # Spring Boot应用配置
│   │       ├── META-INF/native-image/ # GraalVM原生镜像配置
│   │       ├── static/           # 静态资源
│   │       │   ├── favicon.ico   # 网站图标
│   │       │   └── index.html    # 前端入口HTML
│   │       └── templates/        # 模板文件（Thymeleaf等）
│   │
│   └── test/                # 测试代码目录
│       ├── java/com/kb/demo/     # Java测试代码
│       └── scala/com/kb/         # Scala测试代码（Gatling性能测试）
│
├── ai-assistant-front/      # 前端Vue3项目目录
│   ├── .editorconfig        # 编辑器配置
│   ├── .gitattributes       # Git属性配置
│   ├── .gitignore           # Git忽略文件
│   ├── .prettierrc.json     # Prettier代码格式化配置
│   ├── README.md            # 前端项目说明
│   ├── env.d.ts             # 环境变量类型定义
│   ├── eslint.config.ts     # ESLint代码检查配置
│   ├── index.html           # 前端入口HTML文件
│   ├── package-lock.json    # NPM依赖锁定文件
│   ├── package.json         # NPM依赖配置
│   ├── pnpm-lock.yaml       # PNPM依赖锁定文件
│   ├── tailwind.config.js   # TailwindCSS配置
│   ├── tsconfig.app.json    # TypeScript应用配置
│   ├── tsconfig.json        # TypeScript基础配置
│   ├── tsconfig.node.json   # TypeScript Node.js配置
│   ├── vite.config.ts       # Vite构建工具配置
│   ├── public/
│   │   └── favicon.ico      # 前端网站图标
│   │
│   └── src/                 # 前端源代码目录
│       ├── App.vue          # Vue应用根组件
│       ├── main.ts          # 前端应用入口文件
│       ├── assets/          # 前端静态资源
│       │   ├── base.css     # 基础样式
│       │   ├── logo.svg     # 项目Logo
│       │   └── main.css     # 主样式文件
│       │
│       ├── components/      # Vue组件目录
│       │   ├── ChatComponent.vue          # 聊天组件
│       │   ├── DashboardComponent.vue     # 仪表板组件
│       │   ├── DocumentComponent.vue      # 文档组件
│       │   ├── DocumentVersionComponent.vue # 文档版本组件
│       │   ├── FileUploadComponent.vue    # 文件上传组件
│       │   ├── HelloWorld.vue             # 示例组件
│       │   ├── TheWelcome.vue             # 欢迎组件
│       │   ├── VectorSearchComponent.vue  # 向量搜索组件
│       │   ├── WelcomeItem.vue            # 欢迎项组件
│       │   └── icons/                     # 图标组件目录
│       │       ├── IconCommunity.vue      # 社区图标
│       │       ├── IconDocumentation.vue  # 文档图标
│       │       ├── IconEcosystem.vue      # 生态图标
│       │       ├── IconSupport.vue        # 支持图标
│       │       └── IconTooling.vue        # 工具图标
│       │
│       ├── router/          # Vue Router路由配置
│       │   └── index.ts     # 路由定义文件
│       │
│       ├── services/        # 前端服务层
│       │   └── api.ts       # API调用封装
│       │
│       ├── stores/          # Pinia状态管理
│       │   ├── auth.ts      # 认证状态管理
│       │   └── counter.ts   # 计数器状态管理
│       │
│       └── views/           # Vue页面组件
│           ├── AboutView.vue        # 关于页面
│           ├── DashboardView.vue    # 仪表板页面
│           ├── HomeView.vue         # 首页
│           ├── LoginView.vue        # 登录页面
│           ├── RegisterView.vue     # 注册页面
│           └── VectorSearchView.vue # 向量搜索页面
│
├── docker/                  # Docker相关文件集中管理
│   ├── .dockerignore        # Docker构建忽略文件
│   ├── Dockerfile           # JVM版本Docker镜像（多阶段构建）
│   ├── Dockerfile.native    # GraalVM原生镜像Dockerfile
│   ├── docker-compose.yml   # 开发环境Docker编排
│   ├── docker-compose.prod.yml # 生产环境Docker编排（双实例+Nginx）
│   │
│   ├── grafana/             # Grafana监控配置
│   │   ├── dashboards/      # 仪表板配置
│   │   │   └── ai-knowledge-base-dashboard.json # AI知识库仪表板
│   │   └── provisioning/    # 自动配置目录
│   │       ├── dashboards/  # 仪表板自动配置
│   │       │   └── dashboard.yml
│   │       └── datasources/ # 数据源配置
│   │           └── prometheus.yml
│   │
│   ├── nginx/               # Nginx配置目录
│   │   └── nginx.conf       # 反向代理配置
│   │
│   └── prometheus/          # Prometheus监控配置
│       ├── alert_rules.yml  # 告警规则配置
│       └── prometheus.yml   # Prometheus主配置
│
├── scripts/                 # 脚本文件集中管理
│   ├── build-native.cmd     # GraalVM原生镜像构建脚本
│   ├── check-mysql.bat      # MySQL服务检查脚本
│   ├── check-redis.bat      # Redis服务检查脚本
│   ├── clean-redis-index.cmd # Redis索引清理脚本
│   ├── docker-build.cmd     # Docker镜像构建脚本
│   ├── docker-start.cmd     # Docker服务启动脚本
│   ├── mvnw21.cmd           # Maven Wrapper脚本（JDK 21专用）
│   ├── performance-test.cmd # 性能测试脚本（Gatling）
│   ├── simple-performance-test.cmd # 简易性能测试脚本
│   ├── start-local.cmd      # 本地开发启动脚本
│   ├── switch-to-local-dev.cmd # 切换到本地开发模式脚本
│   ├── test-metrics.cmd     # 指标测试脚本
│   └── test-monitoring.cmd  # 监控测试脚本
│
├── docs/                    # 项目文档目录（分类管理）
│   
├── mysql/                   # MySQL数据库相关文件
│   ├── init.sql             # 数据库初始化脚本
│   ├── 02-add-evaluation-tables.sql # 评估表添加脚本
│   └── add-file-type-column.sql     # 文件类型列添加脚本
│
├── mysql-init/              # MySQL初始化目录（预留）
│
└── .mvn/                    # Maven Wrapper配置目录
    ├── jvm.config           # JVM配置
    ├── settings.xml         # Maven设置
    └── wrapper/             # Maven Wrapper相关
        └── maven-wrapper.properties
```

### 📌 目录分类原则

- **`scripts/`** - 所有执行脚本集中管理，包括 Docker 构建、服务启动、性能测试等
- **`docker/`** - Docker 相关配置集中管理，Dockerfile、docker-compose、Nginx 配置等

---

## 🚀 性能基线（开发机实测）

| 指标 | 数值 | 环境 |
| --- | --- | --- |
| 启动时间 | < 50 ms | GraalVM 原生镜像 |
| 内存占用 | < 80 MB | 容器限制 128 M |
| 并发 QPS | 200+ | 虚拟线程 + Redis 缓存 |
| 镜像大小 | 60 M | 原生可执行文件 |
| 前端构建 | < 3 s | Vite + pnpm |

---

## 📌 后续迭代路线（已规划）

| 阶段 | 目标 | 技术点 |
| --- | --- | --- |
| V1.0 | 单模型问答 | LangChain4J + Redis 向量 |
| V1.1 | 流式输出 | Server-Sent Events |
| V1.2 | 多模型切换 | Qwen/Claude/Ollama |
| V1.3 | PDF 上传解析 | Apache Tika + 分块 |
| V1.4 | 权限体系 | Spring Security + JWT |
| V1.5 | 网关+注册 | Spring Cloud Gateway + Nacos |
| V2.0 | K8s GitOps | Helm + ArgoCD + SkyWalking |

---

## 📞 联系方式 & 贡献

- 项目地址（Gitee）：`https://gitee.com/li-jinglin251/todo-full-stack-try`
- 提交 PR → 自动 CI → 镜像构建 → K8s 滚动发布
- Issue 模板：Bug/Feature/Question 已内置

---

## 🔗 项目参考与资源

### 官方文档

- **LangChain4J**：https://github.com/langchain4j/langchain4j
- **Spring Boot**：https://spring.io/projects/spring-boot
- **Vue 3**：https://vuejs.org
- **Redis**：https://redis.io
- **Elasticsearch**：https://www.elastic.co/guide/
- **Docker**：https://docs.docker.com
- **Kubernetes**：https://kubernetes.io/docs/

---