SuperBizAgent-java/mvp/architecture/implementation-detail.md

# SuperBizAgent MVP 完整实施计划（AI 执行）

## 协作分工

```
用户角色：规划者 + 验证者 + 架构师
AI 角色：  执行者 + 编码者 + 记录者

用户负责：
├─ 确认架构设计
├─ 验收每个阶段产出
├─ 调整优先级和方向
└─ 最终验收和部署决策

AI 负责：
├─ 编写全部代码
├─ 编写全部测试
├─ 执行测试验证
├─ 记录实施过程
├─ 遇到问题提出方案供用户决策
└─ 自动化构建和本地验证
```

---

## 总览：3 个 Phase，13 天

```
Phase 1: 基础设施（5天）
├─ Day 1-2: 数据库 + 实体 + 会话管理
├─ Day 3:   代码结构重构
└─ Day 4-5: 文档管理（CRUD + Milvus）

Phase 2: 核心功能（5天）
├─ Day 6-7: 意图识别 + RAG 两层加载
├─ Day 8-9: 4 Agent 协作 + Skill
└─ Day 10:  工具层开发

Phase 3: 闭环优化（3天）
├─ Day 11: Verifier + Harness
├─ Day 12: 反馈机制 + 案例沉淀
└─ Day 13: 端到端测试 + 验收
```

---

## Phase 1：基础设施（5天）

### Day 1-2：数据库 + 实体 + 会话

#### 任务 1.1：MySQL 表结构（Flyway 迁移）

```sql
产出文件：
src/main/resources/db/migration/
├── V001__create_diagnosis_record.sql
├── V002__create_case_library.sql
└── V003__create_api_document.sql

依据文档：
- docs/tables/diagnosis_record.md
- docs/tables/case_library.md
- docs/tables/api_document.md

关键点：
- 使用 Flyway 版本管理
- 索引：trace_id, error_code, fault_category
- JSON 字段：steps_executed, evidence_chain
- 时间字段：created_at, updated_at 自动维护

验收标准：
✓ 执行 mvn flyway:migrate 成功
✓ 3 张表创建成功
✓ 索引完整
✓ 约束正确
```

#### 任务 1.2：JPA 实体类

```java
产出文件：
src/main/java/com/superbiz/agent/domain/entity/
├── DiagnosisRecord.java
├── CaseLibrary.java
└── ApiDocument.java

技术栈：
- Spring Data JPA
- Lombok (@Data, @Builder)
- Hibernate @JdbcTypeCode(SqlTypes.JSON)

验收标准：
✓ 字段与 DDL 一致
✓ 枚举映射正确
✓ JSON 字段序列化正常
✓ 编译通过
```

#### 任务 1.3：Repository 层

```java
产出文件：
src/main/java/com/superbiz/agent/repository/
├── DiagnosisRecordRepository.java
├── CaseLibraryRepository.java
└── ApiDocumentRepository.java

常用查询：
- findByOrderId
- findByTraceId
- findByErrorCodeAndFaultCategory
- findTopByOrderByCreatedAtDesc

验收标准：
✓ 继承 JpaRepository
✓ 单元测试覆盖（@DataJpaTest + H2）
✓ 分页查询正确
```

#### 任务 1.4：Redis 会话管理

```java
产出文件：
src/main/java/com/superbiz/agent/session/
├── SessionManager.java              # 接口
├── RedisSessionManager.java         # Redis 实现
├── SessionContext.java              # 会话上下文
└── SessionConfiguration.java        # 配置类

功能：
- 替换内存 HashMap
- TTL：30 分钟
- JSON 序列化（Jackson）
- 按 sessionId 存取删

验收标准：
✓ 单元测试通过
✓ Redis 连接成功
✓ 序列化/反序列化正确
✓ TTL 生效
```

---

### Day 3：代码结构重构

#### 任务 3.1：包名重构

```
重构前：org.example
重构后：com.superbiz.agent

操作：
1. IDEA Refactor → Rename Package
2. 全局搜索替换 import
3. pom.xml 更新 mainClass

验收标准：
✓ 编译通过
✓ 无遗漏的 org.example
✓ 启动成功
```

#### 任务 3.2：分层结构优化

```
目标结构：
src/main/java/com/superbiz/agent/
├── controller/              # REST 接口
├── service/                 # 业务逻辑
├── repository/              # 数据访问
├── domain/
│   ├── entity/              # JPA 实体
│   ├── dto/                 # 数据传输对象
│   ├── vo/                  # 视图对象
│   └── enums/               # 枚举
├── agent/                   # Agent 层
│   ├── supervisor/
│   ├── planner/
│   ├── executor/
│   └── verifier/
├── tool/                    # 工具层
├── harness/                 # Harness 控制
│   ├── gate/
│   └── interrupt/
├── skill/                   # Skill 定义
├── session/                 # 会话管理
├── intent/                  # 意图识别
├── rag/                     # RAG 加载
└── config/                  # 配置

验收标准：
✓ 目录结构清晰
✓ 职责单一
✓ 编译通过
```

#### 任务 3.3：DTO 抽离

```java
产出文件：
src/main/java/com/superbiz/agent/domain/dto/
├── DiagnosisRequest.java
├── DiagnosisResponse.java
├── DocumentUploadRequest.java
├── CaseQueryRequest.java
└── ...

要求：
- Controller 不直接依赖 Entity
- MapStruct 做对象转换
- 校验注解 @Valid + @NotNull
- 统一响应包装类 Result<T>

验收标准：
✓ Controller 不 import Entity
✓ 原有接口兼容
✓ 编译通过
```

---

### Day 4-5：文档管理

#### 任务 4.1：文档上传

```java
产出文件：
controller/DocumentController.java
service/DocumentService.java
service/TextExtractor.java
service/VectorService.java

接口：POST /api/documents/upload
功能：
1. 接收文件（Word/PDF/Markdown）
2. 提取纯文本
3. 分块（chunk_size=500, overlap=50）
4. 向量化（DashScopeEmbedding）
5. 写 MySQL + Milvus

验收标准：
✓ 上传成功返回 document_id
✓ MySQL 记录正确
✓ Milvus 向量正确
✓ 单元测试覆盖
```

#### 任务 4.2：文档查询

```java
接口：
- GET /api/documents/{id}
- GET /api/documents?province=XX&category=YY

验收标准：
✓ 分页查询
✓ 过滤生效
✓ 性能可接受（< 100ms）
```

#### 任务 4.3：文档删除同步

```java
接口：DELETE /api/documents/{id}

功能：
- 删除 MySQL 记录
- 同步删除 Milvus 向量
- 事务一致性

验收标准：
✓ MySQL + Milvus 同步删除
✓ 事务回滚正确
```

#### 任务 4.4：混合检索实现

```java
产出文件：
tool/DocumentSearchTool.java

策略：
1. 精确匹配（MySQL）
2. 语义检索（Milvus）
3. RRF 融合排序

验收标准：
✓ 精确匹配优先
✓ 语义检索补漏
✓ 返回 Top 3
✓ 单元测试覆盖
```

---

## Phase 2：核心功能（5天）

### Day 6-7：意图识别 + RAG

#### 任务 6.1：意图识别模块

```java
产出文件：
intent/IntentClassifier.java
intent/L0RulesMatcher.java
intent/L1AgentClassifier.java
intent/IntentResult.java

L0 规则匹配：
- 正则：订单号、traceId、错误码
- 关键词：报错、异常、失败
- 返回：诊断/文档/案例/闲聊

L1 小模型 Agent：
- 输入：用户原始输入
- Prompt：分类意图
- 输出：意图 + 置信度

验收标准：
✓ L0 命中率 80%+
✓ L1 准确率 90%+
✓ 延迟 < 200ms
✓ 单元测试覆盖
```

#### 任务 6.2：RAG 两层加载

```java
产出文件：
rag/RagLoader.java
rag/L1PreloadService.java
rag/L2OnDemandService.java

L1 预加载：
- 触发时机：意图识别后，Planner 启动前
- 内容：通用领域知识（架构、流程、高频错误码）
- 注入：Planner System Prompt

L2 按需加载：
- 触发时机：Executor 拿到 errorCode 后
- 内容：具体接口文档
- 调用：searchDoc

验收标准：
✓ L1 预加载成功
✓ L2 按需调用成功
✓ 单元测试覆盖
```

---

### Day 8-9：4 Agent 协作 + Skill

#### 任务 8.1：4 Agent 定义

```java
产出文件：
agent/supervisor/SupervisorAgent.java
agent/planner/PlannerAgent.java
agent/executor/ExecutorAgent.java
agent/verifier/VerifierAgent.java

配置文件：
src/main/resources/prompts/
├── supervisor-system.md
├── planner-system.md
├── executor-system.md
└── verifier-system.md

技术栈：
- Spring AI Alibaba
- SupervisorAgent + ReactAgent
- @Tool 注解

验收标准：
✓ 4 Agent 注册成功
✓ 协作流程跑通
✓ Supervisor 调度正确
```

#### 任务 8.2：Skill 实现

```java
产出文件：
skill/SkillDefinition.java
skill/DiagnoseByOrderIdSkill.java
skill/SkillRegistry.java

工作流（6 步）：
1. queryOrder
2. searchDoc (L2 按需)
3. queryLogs (Mock)
4. recommendCase
5. 生成报告
6. Verifier 验证

验收标准：
✓ 6 步流程正确
✓ 失败处理正确（ABORT/SKIP）
✓ 单元测试覆盖
```

---

### Day 10：工具层开发

#### 任务 10.1：queryOrder 工具

```java
产出文件：
tool/QueryOrderTool.java

功能：
- 只读查询 MySQL
- 返回订单信息 + 错误信息
- SQL 注入防护

验收标准：
✓ 查询正确
✓ 超时控制（10s）
✓ 单元测试覆盖
```

#### 任务 10.2：searchDoc 工具

```java
产出文件：
tool/SearchDocTool.java

功能：
- 调用混合检索
- 返回 Top 3 文档片段

验收标准：
✓ 调用成功
✓ 结果格式正确
✓ 单元测试覆盖
```

#### 任务 10.3：recommendCase 工具

```java
产出文件：
tool/RecommendCaseTool.java

功能：
- 精确匹配：error_code + fault_category
- 语义检索：description 向量相似度
- RRF 融合

验收标准：
✓ 推荐准确
✓ 返回 Top 3
✓ 单元测试覆盖
```

#### 任务 10.4：getCurrentTime 工具

```java
产出文件：
tool/GetCurrentTimeTool.java

功能：
- 返回当前时间戳
- 格式化输出

验收标准：
✓ 返回正确
```

---

## Phase 3：闭环优化（3天）

### Day 11：Verifier + Harness

#### 任务 11.1：Verifier Agent

```java
产出文件：
agent/verifier/VerifierAgent.java

验证逻辑：
1. 事实核查（报告数据 vs 工具返回数据）
2. 完整性检查（3 章节不能为空）

判决：
- PASS：通过
- REVISE：需修正
- REJECT：驳回

验收标准：
✓ 事实核查正确
✓ 编造检测生效
✓ 单元测试覆盖
```

#### 任务 11.2：Harness 5 Gates

```java
产出文件：
harness/gate/InputGates.java
harness/gate/ExecutionGates.java
harness/gate/OutputGates.java

门禁清单：
- Gate 1: 输入参数非空
- Gate 2: 5 分钟内重复 → 缓存
- Gate 3: 工具超时（10s）
- Gate 4: 报告完整性
- Gate 5: 置信度阈值（60）

验收标准：
✓ 5 Gates 生效
✓ 中断机制正确
✓ 单元测试覆盖
```

---

### Day 12：反馈机制 + 案例沉淀

#### 任务 12.1：反馈接口

```java
产出文件：
controller/FeedbackController.java
service/FeedbackService.java

接口：POST /api/diagnosis/{id}/feedback
参数：useful / not_useful

功能：
- 更新 diagnosis_record.feedback
- useful → 自动生成 case_library

验收标准：
✓ 反馈记录成功
✓ 案例生成正确
✓ 单元测试覆盖
```

#### 任务 12.2：案例自动生成

```java
产出文件：
service/CaseGenerationService.java

触发条件：
- feedback = useful
- confidence >= 80

生成逻辑：
- 提取关键信息
- 生成 case_library 记录
- 向量化 solution_steps

验收标准：
✓ 案例生成正确
✓ 向量化成功
✓ 单元测试覆盖
```

---

### Day 13：端到端测试 + 验收

#### 任务 13.1：Mock 5 个场景

```
场景 1：外部接口故障（广东社保 40003）
场景 2：内部空指针异常
场景 3：数据库连接超时
场景 4：意图不明（闲聊）
场景 5：缓存命中（重复诊断）

验收标准：
✓ 5 个场景全部跑通
✓ 诊断报告正确
✓ 反馈闭环完整
```

#### 任务 13.2：性能测试

```
指标：
- 诊断延迟 < 10s（P95）
- 意图识别 < 200ms
- 文档检索 < 500ms
- 并发 10 QPS 稳定

验收标准：
✓ 性能达标
✓ 无内存泄漏
✓ 无明显瓶颈
```

#### 任务 13.3：文档更新

```
产出文件：
docs/
├── API.md               # 接口文档
├── DEPLOYMENT.md        # 部署指南
└── TEST_REPORT.md       # 测试报告

验收标准：
✓ 文档完整
✓ 部署可复现
✓ 测试报告详实
```

---

## 测试要求

### 单元测试

```
框架：JUnit 5 + Mockito
覆盖率：
- Repository: 100%
- Service:    80%+
- Tool:       80%+
- Agent:      70%+
- Controller: 70%+
```

### 集成测试

```
框架：@SpringBootTest
覆盖：
- Redis 集成
- MySQL 集成
- Milvus 集成
- Agent 协作
```

### E2E 测试

```
工具：RestAssured
场景：5 个 Mock 场景
```

---

## 实施记录格式

每完成一个任务，AI 在此文档追加：

```markdown
---

## [完成] 任务 X.X：任务名称

**执行时间**：2026-XX-XX HH:mm

**产出文件**：
- path/to/file1.java (126 行)
- path/to/file2.java (89 行)

**关键决策**：
- 决策点：选择方案 A，因为...
- 权衡点：备选方案 B 的劣势是...

**遇到的问题**：
- 问题：XXX
- 解决方案：YYY
- 影响范围：ZZZ

**测试结果**：
✓ 单元测试：8/8 通过
✓ 集成测试：3/3 通过
✓ 代码覆盖率：85%

**验收状态**：⏳ 等待用户确认 / ✅ 已通过

**用户反馈**：（用户确认后填写）
```

---

## 当前进度

```
Phase 1: 基础设施（5天）         [    ] 0%
├─ Day 1-2: 数据库 + 实体         [    ] 未开始
├─ Day 3:   代码结构重构          [    ] 未开始
└─ Day 4-5: 文档管理              [    ] 未开始

Phase 2: 核心功能（5天）         [    ] 0%
├─ Day 6-7: 意图识别 + RAG        [    ] 未开始
├─ Day 8-9: Agent + Skill         [    ] 未开始
└─ Day 10:  工具层                [    ] 未开始

Phase 3: 闭环优化（3天）         [    ] 0%
├─ Day 11: Verifier + Harness     [    ] 未开始
├─ Day 12: 反馈 + 案例            [    ] 未开始
└─ Day 13: E2E 测试               [    ] 未开始

总体进度：0/13 天
```

---

## 下一步

等待用户确认：
1. ✅ 这个完整计划是否符合预期？
2. 有没有需要调整的优先级？
3. 有没有需要增删的任务？
4. 确认后开始执行 Phase 1 Day 1-2。