osiman/SuperBizAgent-java
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 添加 Phase 1 完整实施计划和 OpenSpec

Browse Source 
- 添加项目级 CLAUDE.md 和 AGENTS.md 配置
- 添加完整实施计划（docs/architecture/implementation-detail.md）
- 创建 OpenSpec phase-1-infrastructure：
  - proposal.md: 需求和方案
  - design.md: 架构设计
  - specs/functional-specs.md: 功能规格
  - tasks.md: 21 个任务清单
  - decisions.md: grill 阶段决策记录
  - .commit: 标记为 Committed OpenSpec

OpenSpec 已通过 sm-flow 完整流程（clarify → context → propose → grill → specify → audit → commit）
This commit is contained in:
zhuyongxin
2026-06-23 10:58:11 +08:00
parent 5ddb7a6d93
commit 3f15778b28
9 changed files with 2178 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture/implementation-detail.md
+715
View File
@@ -0,0 +1,715 @@
# 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。