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、视频）
  • 进行用户培训（知识库管理、报告生成、智能问答）
  • 解答用户问题
  • 收集用户反馈
  • 交付部署包和文档
  • 提供技术支持联系方式