SuperBizAgent-java/openspec/changes/phase-1-infrastructure/proposal.md

Proposal: Phase 1 基础设施搭建

问题

当前项目是一个 Demo，需要改造为 MVP 诊断 Agent 系统。Phase 1 需要搭建基础设施：

• 缺少持久化层（MySQL + JPA）
• 缺少分布式会话管理（Redis）
• 代码结构需要重构（包名、分层）
• 缺少文档管理基础功能

建议方案

1. 数据持久化

方案：Spring Data JPA + MySQL + Flyway

理由：

• JPA 是 Spring Boot 标准持久化方案
• Flyway 管理数据库版本，团队协作友好
• 3 张表设计已完成（docs/tables/）

实现：

1. 添加依赖（spring-boot-starter-data-jpa, mysql-connector-j, flyway-core）
2. 创建 3 个 Flyway 迁移脚本（V001/V002/V003）
3. 创建 JPA 实体类（DiagnosisRecord, CaseLibrary, ApiDocument）
4. 创建 Repository 接口（继承 JpaRepository）

2. 会话管理

方案：Redis 替代内存 HashMap

理由：

• 支持分布式部署
• 自动 TTL（30 分钟）
• Spring Data Redis 集成简单

实现：

1. 添加 spring-boot-starter-data-redis 依赖
2. 创建 SessionManager 接口 + RedisSessionManager 实现
3. SessionContext 使用 JSON 序列化

3. 代码结构重构

方案：包名重构 + 分层优化 + DTO 抽离

包名重构：

• org.example → com.superbiz.agent
• 工具：IDEA Refactor → Rename Package

分层结构：

com.superbiz.agent/
├── controller/          # REST API
├── service/             # 业务逻辑
├── repository/          # 数据访问
├── domain/
│   ├── entity/          # JPA 实体
│   ├── dto/             # DTO
│   └── enums/           # 枚举
├── agent/               # Agent 层（Phase 2）
├── tool/                # 工具层
├── session/             # 会话管理
└── config/              # 配置

DTO 抽离：

• Controller 不直接依赖 Entity
• 使用 MapStruct 做对象转换

4. 文档管理

方案：CRUD + Milvus 向量同步

功能：

1. 上传接口：文件 → 文本提取 → 分块 → 向量化 → MySQL + Milvus
2. 查询接口：分页、过滤
3. 删除接口：MySQL + Milvus 同步删除
4. 检索工具：精确匹配（MySQL）+ 语义检索（Milvus）+ RRF 融合

范围

包含：

• Day 1-2: MySQL 表 + JPA + Repository + Redis 会话
• Day 3: 包名重构 + 分层优化 + DTO 抽离
• Day 4-5: 文档管理 4 个接口 + 混合检索工具

不包含：

• Agent 功能（Phase 2）
• 意图识别和 RAG（Phase 2）
• Verifier 和 Harness（Phase 3）

非目标

• 性能优化（后续优化）
• 完整的权限控制（MVP 不需要）
• 前端界面（只做后端 API）

来自 devflow 的上下文约束

无（这是首个 OpenSpec，devflow 目录为空）

风险

1. 包名重构影响范围大

   • 缓解：先提交当前代码，独立分支重构
   • 验证：重构后编译通过 + 启动成功

2. Flyway 首次运行可能失败

   • 缓解：本地 MySQL 先手动测试
   • 回退：Flyway 支持 repair 修复

3. Redis 本地环境依赖

   • 缓解：提供 Docker Compose 配置
   • 回退：可降级为内存实现（测试用）

关键假设

1. MySQL 8.0+ 和 Redis 6.0+ 可用（本地或 Docker）
2. 现有 Milvus 集成不需要改动
3. 单元测试覆盖率目标：70%+

成功标准

1. ✅ 3 张表创建成功，索引完整
2. ✅ Repository 层单元测试通过
3. ✅ Redis 会话存取正常，TTL 生效
4. ✅ 包名重构完成，编译通过
5. ✅ 文档上传/查询/删除接口可用
6. ✅ 混合检索工具返回正确结果
7. ✅ 整体测试覆盖率 ≥ 70%

产出文件（预期）

数据库迁移：

• src/main/resources/db/migration/V001__create_diagnosis_record.sql
• src/main/resources/db/migration/V002__create_case_library.sql
• src/main/resources/db/migration/V003__create_api_document.sql

实体类：

• com.superbiz.agent.domain.entity.DiagnosisRecord
• com.superbiz.agent.domain.entity.CaseLibrary
• com.superbiz.agent.domain.entity.ApiDocument

Repository：

• com.superbiz.agent.repository.DiagnosisRecordRepository
• com.superbiz.agent.repository.CaseLibraryRepository
• com.superbiz.agent.repository.ApiDocumentRepository

会话管理：

• com.superbiz.agent.session.SessionManager
• com.superbiz.agent.session.RedisSessionManager
• com.superbiz.agent.session.SessionContext

文档管理：

• com.superbiz.agent.controller.DocumentController
• com.superbiz.agent.service.DocumentService
• com.superbiz.agent.service.TextExtractor
• com.superbiz.agent.tool.DocumentSearchTool

配置：

• pom.xml（增加依赖）
• application.yml（增加 MySQL + Redis 配置）

测试：

• *RepositoryTest.java
• *ServiceTest.java
• *ControllerTest.java

工期估算

5 天（按实施计划）