Files

T

zhuyongxin c86045b33f archive: Phase 1 基础设施搭建归档

归档信息：
- 变更名称：phase-1-infrastructure
- 工作流：spec-driven
- 归档位置：openspec/changes/archive/2026-06-23-phase-1-infrastructure/

完成情况：
- ✅ 所有产物完成（proposal, design, specs, tasks）
- ✅ 任务完成：33/35 (94%)
- ⚠️ 2 个任务跳过（混合检索、集成测试，有充分理由）

验收结果：
- ✅ 静态验证：编译通过
- ✅ 脚本验证：16/16 单元测试通过
- ✅ 端到端验证：上传→索引→检索→删除完整流程

Delta Specs：
- 跳过同步（用户选择）
- functional-specs.md 保留在归档目录中

devflow 档案：
- ✅ 已完整回填（brief, evidence, decisions, acceptance）
- ✅ devflow/index.md 状态更新为 archived

2026-06-23 19:20:05 +08:00

4.8 KiB

Raw Permalink Blame History

Proposal: Phase 1 基础设施搭建

问题

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

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

建议方案

1. 数据持久化

方案：Spring Data JPA + MySQL + Flyway

理由：

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

实现：

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

2. 会话管理

方案：Redis 替代内存 HashMap

理由：

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

实现：

添加 spring-boot-starter-data-redis 依赖
创建 SessionManager 接口 + RedisSessionManager 实现
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 向量同步

功能：

上传接口：文件 → 文本提取 → 分块 → 向量化 → MySQL + Milvus
查询接口：分页、过滤
删除接口：MySQL + Milvus 同步删除
检索工具：精确匹配（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 目录为空）

风险

包名重构影响范围大
- 缓解：先提交当前代码，独立分支重构
- 验证：重构后编译通过 + 启动成功
Flyway 首次运行可能失败
- 缓解：本地 MySQL 先手动测试
- 回退：Flyway 支持 repair 修复
Redis 本地环境依赖
- 缓解：提供 Docker Compose 配置
- 回退：可降级为内存实现（测试用）

关键假设

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

成功标准

✅ 3 张表创建成功，索引完整
✅ Repository 层单元测试通过
✅ Redis 会话存取正常，TTL 生效
✅ 包名重构完成，编译通过
✅ 文档上传/查询/删除接口可用
✅ 混合检索工具返回正确结果
✅ 整体测试覆盖率 ≥ 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 天（按实施计划）

4.8 KiB Raw Permalink Blame History Unescape Escape