xinli/.kiro/specs/local-rag-knowledge-base/tasks.md

# Implementation Plan

- [ ] 1. 添加Maven依赖和配置
  - 在 ry-xinli-system/pom.xml 添加依赖：OkHttp、Apache PDFBox、Apache POI
  - 在 application.yml 添加RAG相关配置（Ollama URL、ChromaDB URL、文件路径）
  - 创建配置类 RagProperties.java 读取配置
  - _Requirements: 8.1, 9.3_

- [ ] 2. 实现Ollama客户端
  - 创建 com.ddnai.system.rag.client.OllamaClient.java
  - 实现 embed() 方法调用 /api/embeddings 接口
  - 实现 generate() 方法调用 /api/generate 接口
  - 实现 listModels() 和 checkConnection() 方法
  - 添加错误处理和重试机制
  - _Requirements: 3.5, 4.4, 5.1, 5.2_

- [ ]* 2.1 编写Ollama客户端单元测试
  - 测试embed()方法返回768维向量
  - 测试generate()方法返回非空字符串
  - 测试连接失败时的错误处理

- [ ] 3. 实现ChromaDB客户端
  - 创建 com.ddnai.system.rag.client.ChromaDBClient.java
  - 实现 addDocuments() 方法调用 /api/v1/collections/{name}/add
  - 实现 query() 方法调用 /api/v1/collections/{name}/query
  - 实现 deleteDocuments() 方法
  - 实现 getCollection() 方法
  - 添加连接池和错误处理
  - _Requirements: 1.6, 3.2, 8.5_

- [ ]* 3.1 编写ChromaDB客户端单元测试
  - 测试添加文档后能查询到
  - 测试删除文档后查询不到
  - 测试查询返回Top-K结果

- [ ] 4. 实现文档解析工具
  - 创建 com.ddnai.system.rag.util.DocumentParser.java
  - 实现 parsePdf() 方法使用PDFBox解析PDF
  - 实现 parseDocx() 方法使用Apache POI解析Word
  - 实现 parseTxt() 方法读取TXT文件
  - 实现 parse() 方法自动识别格式
  - 处理解析异常和特殊字符
  - _Requirements: 1.1, 1.2, 1.3_

- [ ]* 4.1 编写文档解析单元测试
  - 准备测试文档（PDF、Word、TXT）
  - 测试解析结果包含预期文本
  - 测试特殊字符处理

- [ ] 5. 实现文本分块工具
  - 创建 com.ddnai.system.rag.util.TextSplitter.java
  - 实现 split() 方法按字符数分块（chunkSize=800, overlap=200）
  - 实现 splitBySentences() 方法按句子分块
  - 确保分块大小在500-1000字符之间（除最后一块）
  - _Requirements: 1.4_

- [ ]* 5.1 编写文本分块单元测试
  - 测试分块大小约束
  - 测试分块重叠逻辑
  - 测试边界情况（短文本、空文本）

- [ ] 6. 实现向量化服务
  - 创建 com.ddnai.system.rag.service.EmbeddingService.java
  - 注入 OllamaClient
  - 实现 embedText() 方法生成768维向量
  - 实现 embedBatch() 方法批量向量化
  - 添加缓存机制（可选）
  - _Requirements: 1.5, 3.1, 4.1_

- [ ]* 6.1 编写向量化服务单元测试
  - 测试向量维度为768
  - 测试批量向量化
  - 测试相同文本生成相同向量

- [ ] 7. 实现知识库管理服务
  - 创建 com.ddnai.system.rag.service.KnowledgeService.java
  - 实现 uploadDocument() 方法（解析→分块→向量化→存储）
  - 实现 listDocuments() 方法返回文档列表（分页）
  - 实现 getDocument() 方法返回文档详情
  - 实现 deleteDocument() 方法删除文档和向量
  - 实现 searchDocuments() 方法按文件名搜索
  - 实现 rebuildIndex() 方法重建索引
  - _Requirements: 1.1-1.7, 2.1-2.5, 10.1-10.5_

- [ ]* 7.1 编写知识库管理服务单元测试
  - 测试上传文档后能列表查询到
  - 测试删除文档后查询不到
  - 测试文件名搜索功能
  - 测试重建索引功能

- [ ] 8. 实现RAG检索服务
  - 创建 com.ddnai.system.rag.service.RetrievalService.java
  - 注入 ChromaDBClient 和 EmbeddingService
  - 实现 retrieve() 方法进行语义检索（Top-K=5, threshold=0.7）
  - 实现 retrieveWithFilter() 方法支持分类过滤
  - 实现相似度过滤逻辑
  - 实现结果排序和去重
  - _Requirements: 3.2, 3.3, 4.2_

- [ ]* 8.1 编写RAG检索服务单元测试
  - 测试Top-K数量约束
  - 测试相似度阈值过滤
  - 测试分类过滤功能

- [ ] 9. 实现提示词构建工具
  - 创建 com.ddnai.system.rag.util.PromptBuilder.java
  - 实现 buildReportPrompt() 方法构建报告生成提示词
  - 实现 buildQAPrompt() 方法构建问答提示词
  - 实现 buildSuggestionPrompt() 方法构建建议提示词
  - 确保提示词包含所有必要信息（检索知识、用户数据）
  - 优化提示词模板以提高生成质量
  - _Requirements: 3.4, 4.3_

- [ ]* 9.1 编写提示词构建单元测试
  - 测试提示词包含检索知识
  - 测试提示词包含用户数据
  - 测试提示词格式正确

- [ ] 10. 实现AI生成服务
  - 创建 com.ddnai.system.rag.service.GenerationService.java
  - 注入 OllamaClient 和 RetrievalService
  - 实现 generateReport() 方法（检索→构建提示词→生成报告）
  - 实现 answerQuestion() 方法（检索→构建提示词→生成回答）
  - 实现 generateSuggestions() 方法生成矫治建议
  - 确保返回格式包含内容和来源引用
  - 添加生成超时控制（30秒）
  - _Requirements: 3.5, 3.6, 4.4, 4.5_

- [ ]* 10.1 编写AI生成服务单元测试
  - 测试生成响应非空
  - 测试响应包含来源引用
  - 测试超时处理

- [ ] 11. 实现文件监听服务
  - 创建 com.ddnai.system.rag.service.FileWatcherService.java
  - 使用 Java WatchService 监听 D:\wwwroot\RAG\uploads 目录
  - 实现 @PostConstruct startWatching() 方法启动监听
  - 实现 processNewFile() 方法处理新文件
  - 实现 @PreDestroy stopWatching() 方法停止监听
  - 添加文件处理状态记录（避免重复处理）
  - 添加错误处理和日志记录
  - _Requirements: 1.1-1.7_

- [ ]* 11.1 编写文件监听服务单元测试
  - 测试检测到新文件
  - 测试自动处理文件
  - 测试避免重复处理

- [ ] 12. 创建数据模型类
  - 创建 com.ddnai.system.rag.domain.DocumentInfo.java
  - 创建 com.ddnai.system.rag.domain.RetrievalResult.java
  - 创建 com.ddnai.system.rag.domain.GenerationResult.java
  - 创建 com.ddnai.system.rag.domain.SourceReference.java
  - 创建 com.ddnai.system.rag.domain.SystemStatusResponse.java
  - 创建 com.ddnai.system.rag.domain.KnowledgeStats.java
  - 创建 com.ddnai.system.rag.domain.RebuildResult.java
  - 添加必要的注解和验证
  - _Requirements: 2.1, 2.2, 3.6, 4.5, 5.1_

- [ ] 13. 实现知识库管理Controller
  - 创建 com.ddnai.web.controller.psychology.PsyKnowledgeController.java
  - 注入 KnowledgeService
  - 实现 @PostMapping("/upload") 上传文档接口
  - 实现 @GetMapping("/list") 获取文档列表接口（分页）
  - 实现 @GetMapping("/{id}") 获取文档详情接口
  - 实现 @DeleteMapping("/{id}") 删除文档接口
  - 实现 @PostMapping("/search") 搜索文档接口
  - 实现 @PostMapping("/rebuild") 重建索引接口
  - 添加权限控制注解 @PreAuthorize
  - 添加参数验证和错误处理
  - _Requirements: 2.1-2.5, 10.1-10.5_

- [ ] 14. 实现AI分析Controller
  - 创建 com.ddnai.web.controller.psychology.PsyAIAnalysisController.java
  - 注入 GenerationService
  - 实现 @PostMapping("/generate-report") 生成报告接口
  - 实现 @PostMapping("/chat") 智能问答接口
  - 实现 @GetMapping("/system/status") 系统状态接口
  - 添加权限控制注解
  - 添加请求日志记录
  - _Requirements: 3.1-3.7, 4.1-4.5, 5.1-5.3_

- [ ] 15. 集成AI报告生成到现有报告服务
  - 修改 PsyComprehensiveReportServiceImpl.java
  - 注入 GenerationService
  - 在生成综合报告时调用 generateReport()
  - 解析生成结果并存储到MySQL
  - 保存知识来源引用到数据库（新增字段或表）
  - 实现错误处理和降级策略（AI失败时使用原有逻辑）
  - 添加生成日志记录
  - _Requirements: 6.2, 6.4_

- [ ]* 15.1 编写报告集成单元测试
  - 测试报告生成成功
  - 测试报告存储到MySQL
  - 测试AI失败时的降级处理

- [ ] 16. 第一次检查点 - 测试核心功能
  - 启动Ollama服务
  - 启动ChromaDB服务
  - 启动Spring Boot应用
  - 测试文档上传功能
  - 测试知识库管理功能
  - 测试RAG报告生成功能
  - 测试智能问答功能
  - 确保所有测试通过，询问用户是否有问题

- [ ] 17. 创建知识库管理前端页面
  - 创建 xinli-ui/src/views/psychology/knowledge/index.vue
  - 实现文档列表展示（表格、分页）
  - 实现文档上传功能（文件选择、进度条）
  - 实现文档删除功能（确认对话框）
  - 实现分类筛选功能
  - 实现文件名搜索功能
  - 实现索引重建功能（进度显示）
  - 添加权限控制
  - _Requirements: 7.1, 7.2, 7.3_

- [ ] 18. 优化报告展示页面
  - 修改 xinli-ui/src/views/psychology/report/comprehensive.vue
  - 添加知识来源引用展示区域
  - 实现来源链接点击查看详情
  - 添加来源文档片段弹窗
  - 优化报告内容排版
  - 添加"基于知识库生成"标识
  - _Requirements: 7.4, 7.5_

- [ ] 19. 创建智能问答前端页面
  - 创建 xinli-ui/src/views/psychology/ai-chat/index.vue
  - 实现对话界面（消息列表、输入框）
  - 实现发送问题功能
  - 实现显示回答和来源引用
  - 实现多轮对话支持
  - 实现对话历史记录
  - 添加加载动画和错误提示
  - _Requirements: 7.6_

- [ ] 20. 添加前端路由和菜单
  - 在 router/index.js 添加知识库管理路由
  - 在 router/index.js 添加智能问答路由
  - 在菜单配置中添加"知识库管理"菜单项
  - 在菜单配置中添加"智能问答"菜单项
  - 配置权限控制（管理员可见）
  - _Requirements: 7.1, 7.6_

- [ ] 21. 创建系统监控页面
  - 创建 xinli-ui/src/views/psychology/ai-system/status.vue
  - 显示Ollama连接状态（绿色/红色指示灯）
  - 显示ChromaDB状态
  - 显示可用模型列表
  - 显示知识库统计信息（文档数、向量数、存储空间）
  - 实现连接测试按钮
  - 实现自动刷新功能（每30秒）
  - _Requirements: 5.1, 5.2, 5.3_

- [ ] 22. 第二次检查点 - 端到端测试
  - 测试完整的文档上传流程（前端→Controller→Service→ChromaDB）
  - 测试完整的报告生成流程（前端→Controller→Service→Ollama→MySQL）
  - 测试完整的问答流程（前端→Controller→Service→Ollama）
  - 测试知识库管理功能（列表、搜索、删除、重建）
  - 测试系统监控功能
  - 测试文件监听功能（放文件到uploads目录）
  - 确保所有测试通过，询问用户是否有问题

- [ ] 23. 实现错误处理和日志记录
  - 创建统一异常处理类 RagExceptionHandler.java
  - 定义自定义异常类（RagException、OllamaException、ChromaDBException）
  - 配置Logback日志（按天切分、保留30天）
  - 实现日志脱敏工具类
  - 在所有Service方法中添加日志记录
  - 在所有Controller中添加请求日志
  - _Requirements: 1.7, 3.7, 5.4_

- [ ] 24. 性能优化
  - 实现向量缓存（使用Caffeine或Redis）
  - 优化文档分块算法（并行处理）
  - 优化向量化批处理（批量调用Ollama API）
  - 添加数据库索引优化查询
  - 实现异步任务处理（文档上传、索引重建使用@Async）
  - 配置线程池参数
  - _Requirements: 1.4, 1.5, 1.6_

- [ ] 25. 安全加固
  - 实现文件上传大小限制（50MB）
  - 实现文件格式白名单验证
  - 实现API访问频率限制（使用拦截器）
  - 实现日志脱敏（移除敏感信息）
  - 添加文件内容安全扫描（可选）
  - 配置HTTPS（生产环境）
  - _Requirements: 9.1, 9.2_

- [ ] 26. 编写部署文档和脚本
  - 编写 README.md（项目介绍、功能说明）
  - 编写 INSTALL.md（安装步骤、环境要求）
  - 编写 USER_MANUAL.md（用户手册）
  - 创建 start.bat 启动脚本
  - 创建 stop.bat 停止脚本
  - 创建 backup.bat 备份脚本
  - 创建部署包目录结构
  - _Requirements: 8.1_

- [ ] 27. 准备初始知识库文档
  - 收集心理学专业文档（PDF、Word）
  - 整理文档分类（人格心理学、认知心理学、临床心理学等）
  - 放置文档到 D:\wwwroot\RAG\uploads 目录
  - 等待系统自动处理或手动上传
  - 验证文档已成功向量化
  - _Requirements: 1.1-1.7_

- [ ] 28. 最终检查点 - 生产环境验证
  - 在生产环境部署Spring Boot应用
  - 导入初始心理学文档到知识库
  - 进行压力测试（并发用户、大文档处理）
  - 验证数据持久化和恢复
  - 验证日志记录和监控
  - 验证备份和恢复流程
  - 生成测试报告
  - 确保所有功能正常，询问用户是否满意

- [ ] 29. 用户培训和交付
  - 准备用户培训材料（PPT、视频）
  - 进行用户培训（知识库管理、报告生成、智能问答）
  - 解答用户问题
  - 收集用户反馈
  - 交付部署包和文档
  - 提供技术支持联系方式