# ISS-003 MVP 设计与实现 Review 收敛 **状态**：待规划 **严重程度**：高 **发现时间**：2026-07-03 **来源**：MVP 版本设计与实现 review --- ## 背景 当前 MVP 已具备 Chat、Planner/Executor/Verifier、知识检索、诊断会话落库、反馈与 case library 等主线能力，但设计文档、运行时实现和可验证性之间仍存在明显偏差。 本 issue 用来收敛本次 review 的主要风险，方便后续拆 OpenSpec change 或工程任务。 --- ## 核心问题 ### P0：敏感配置直接提交到仓库 `src/main/resources/application.yml` 中包含真实基础设施地址、数据库密码、Redis 密码、Milvus token、LLM API key。 `src/test/java/com/superbiz/agent/service/SimpleMilvusTest.java` 中也硬编码了 Milvus/Zilliz token。 **影响**： - 密钥泄漏后需要立即轮换。 - 合并 worktree 后会扩大泄漏面。 - `show-sql: true` 与 DEBUG 日志可能进一步暴露业务数据。 **建议**： - 立即轮换已提交的 token/password/api-key。 - 将敏感配置改为环境变量或本地 profile 覆盖。 - 提交 `application-example.yml` 或 `.env.example`，不要提交真实值。 ### P1：测试体系不能稳定离线运行 `mvn test` 编译阶段通过，但 surefire 阶段大量失败，主要原因是测试直接依赖外部 MySQL、Redis、Milvus、LLM/Embedding 服务。 典型失败： - MySQL/Flyway 连接失败导致 repository、Redis、Spring context 测试失败。 - Milvus 连接测试出现 `DEADLINE_EXCEEDED`。 - 当前环境下 Mockito inline mock maker self-attach 失败。 **影响**： - 无法在合并前获得可靠的回归信号。 - 实现变更与环境故障混在一起，问题定位成本高。 **建议**： - 将纯单测、H2/JPA slice、外部集成测试分离。 - 用 Maven profile 或 JUnit tag 区分 `unit` / `integration`。 - 默认 `mvn test` 只跑不依赖外部服务的测试。 ### P1：会话管理设计与实现不一致 `mvp/architecture/archive/2026-07-05-legacy/session-management.md` 设计 Redis 作为主会话存储，带 `session:{session_id}` 和 TTL。 实际 `/api/chat` 在 `ChatController` 中使用 JVM 内存 `ConcurrentHashMap` 管理历史消息，`RedisSessionManager` 虽然存在但没有接入 controller。 **影响**： - 应用重启后会话历史丢失。 - 多实例部署时会话不一致。 - Redis TTL 与设计中的生命周期不生效。 - 前端 chat session id 与后端 diagnosis session id 存在分裂。 **建议**： - 明确 MVP 阶段是否接受内存会话。 - 如果接受，需要同步更新文档并标注限制。 - 如果不接受，应将 `ChatController` 接入 `SessionManager`，统一 session id 与 diagnosis session id 的关系。 ### P1：Verifier 证据链仍不完整 `ToolTraceSummaryService` 期望从 `tool_invocation` 汇总 `lookup_knowledge`、`query_logs`、`query_metrics`、`query_order` 等证据工具。 当前只有 `LookupKnowledgeTool` 主动写入 `tool_invocation`。`QueryMetricsTools` 和 `QueryLogsTools` 返回 JSON，但没有落库。 **影响**： - verifier 无法稳定审计日志、指标、订单等非知识库工具事实。 - `thought` 或模型输出中看起来做了很多推理，但可追溯工具调用证据不足。 - 用户侧可观测性仍然偏低。 **建议**： - 抽象统一的 `ToolInvocationRecorder`。 - 所有 evidence tool 都必须记录 input、output preview、success、duration、trace id。 - verifier 只消费结构化 trace summary，不依赖模型自由文本回忆工具调用。 ### P1：上传文档路径存在重复拼接风险 `DocumentManagementService.saveToLocal()` 返回的是包含 `knowledge_base` 前缀的本地路径。 `KnowledgeIndexService.readDocument()` 又执行 `Paths.get(knowledgeBasePath, filePath)`。 **影响**： - 上传文档进入 L0 索引后，命中时读取原文可能拼成 `knowledge_base/knowledge_base/...`。 - 这会降低 L0 命中后的答案质量，并造成“命中但读不到原文”的隐性故障。 **建议**： - 统一 `filePath` 语义：要么存相对 `knowledge.base-path` 的路径，要么存绝对路径。 - `readDocument()` 对 absolute path、已带 base path 的 relative path 做兼容。 - 增加上传文档后 L0 命中并读取原文的回归测试。 ### P2：SupervisorAgent 构建后未使用 `ChatService.executeChatComplex()` 中创建了 `SupervisorAgent`，但实际仍通过 `callAgent(planner/executor/verifier)` 手写顺序编排。 **影响**： - 代码与设计文档中的 multi-agent 编排表述不一致。 - 后续维护者容易误判当前已由 Supervisor 执行调度。 **建议**： - 删除未使用的 `SupervisorAgent` 构建，明确当前是手写编排。 - 或真正切到 Spring AI Alibaba SupervisorAgent flow，并补充行为验证。 ### P2：生产安全边界偏弱 `SessionConfiguration` 使用 `activateDefaultTyping + LaissezFaireSubTypeValidator` 配置 Redis JSON 反序列化。 `WebMvcConfig` 对所有路径放开 CORS。 **影响**： - Redis 若被非可信写入，存在多态反序列化风险。 - CORS 全放开适合本地 MVP，不适合公开环境。 **建议**： - Redis value 使用明确 DTO 类型或受限 subtype validator。 - CORS 改为按 profile 配置允许域名。 --- ## 优先级建议 1. 先处理敏感配置和密钥轮换，避免合并后扩大泄漏范围。 2. 建立可离线运行的单测基线，让默认 `mvn test` 可用于合并门禁。 3. 统一 session id 与 session storage，解决前后端、Redis、diagnosis session 的语义分裂。 4. 补齐所有 evidence tool 的 `tool_invocation` 落库，提升 verifier 可追溯性。 5. 修正上传文档路径语义，并补回归测试。 6. 清理或真正启用 `SupervisorAgent`，避免设计和实现长期漂移。 --- ## 相关文件 - `src/main/resources/application.yml` - `src/test/java/com/superbiz/agent/service/SimpleMilvusTest.java` - `src/main/java/com/superbiz/agent/controller/ChatController.java` - `src/main/java/com/superbiz/agent/service/session/impl/RedisSessionManager.java` - `src/main/java/com/superbiz/agent/service/ToolTraceSummaryService.java` - `src/main/java/com/superbiz/agent/tool/LookupKnowledgeTool.java` - `src/main/java/com/superbiz/agent/agent/tool/QueryMetricsTools.java` - `src/main/java/com/superbiz/agent/agent/tool/QueryLogsTools.java` - `src/main/java/com/superbiz/agent/service/DocumentManagementService.java` - `src/main/java/com/superbiz/agent/service/KnowledgeIndexService.java` - `src/main/java/com/superbiz/agent/service/ChatService.java` - `src/main/java/com/superbiz/agent/config/SessionConfiguration.java` - `src/main/java/com/superbiz/agent/config/WebMvcConfig.java`