SuperBizAgent-java/openspec/changes/archive/2026-06-23-phase-1-infrastructure/specs/functional-specs.md

Phase 1 Infrastructure - Specifications

功能规格

1. 数据库表创建

1.1 diagnosis_record 表

输入：Flyway 迁移脚本 V001 输出：MySQL 表创建成功 验收标准：

• ✅ 表结构与 docs/tables/diagnosis_record.md 一致
• ✅ 所有索引创建成功
• ✅ JSON 字段类型正确
• ✅ 默认值和注释完整

1.2 case_library 表

输入：Flyway 迁移脚本 V002 输出：MySQL 表创建成功 验收标准：

• ✅ 表结构与 docs/tables/case_library.md 一致
• ✅ 外键约束正确
• ✅ 索引覆盖查询场景

1.3 api_document 表

输入：Flyway 迁移脚本 V003 输出：MySQL 表创建成功 验收标准：

• ✅ 表结构与 docs/tables/api_document.md 一致
• ✅ province 和 category 索引就绪

---

2. JPA 实体与 Repository

2.1 DiagnosisRecord 实体

字段映射：

• @Id @GeneratedValue - id
• @Column(unique=true) - diagnosis_id
• @JdbcTypeCode(SqlTypes.JSON) - tool_calls
• @Enumerated(EnumType.STRING) - fault_category, status
• LocalDateTime - created_at, updated_at

验收标准：

• ✅ 所有字段与数据库一致
• ✅ JSON 字段序列化正确
• ✅ 枚举映射正确
• ✅ Lombok 注解完整

2.2 Repository 查询方法

DiagnosisRecordRepository：

Optional<DiagnosisRecord> findByDiagnosisId(String diagnosisId);
Optional<DiagnosisRecord> findByBusinessId(String businessId);
Optional<DiagnosisRecord> findByTraceId(String traceId);
List<DiagnosisRecord> findByFaultCategoryAndErrorCode(
    FaultCategory category, String errorCode);
Page<DiagnosisRecord> findByCreatedAtBetween(
    LocalDateTime start, LocalDateTime end, Pageable pageable);

验收标准：

• ✅ 单元测试通过（@DataJpaTest + H2）
• ✅ 分页查询正确
• ✅ 复杂查询性能可接受（< 100ms）

---

3. Redis 会话管理

3.1 SessionManager 接口

public interface SessionManager {
    SessionContext get(String sessionId);
    void save(SessionContext context);
    void delete(String sessionId);
    boolean exists(String sessionId);
}

3.2 RedisSessionManager 实现

存储格式：

• Key: session:{sessionId}
• Value: SessionContext 的 JSON 字符串
• TTL: 1800 秒（30 分钟）

异常处理：

• Redis 连接失败 → 抛出 RedisConnectionException
• 序列化失败 → 抛出 SessionSerializationException
• Session 不存在 → 返回 null（get 方法）

验收标准：

• ✅ 存取删操作成功
• ✅ TTL 自动刷新（每次 get/save）
• ✅ JSON 序列化/反序列化正确
• ✅ 单元测试覆盖（Mock RedisTemplate）

---

4. 文档管理

4.1 文档上传接口

接口：POST /api/documents/upload

请求：

{
  "file": "multipart/form-data",
  "province": "广东",
  "category": "社保接口"
}

响应：

{
  "code": 200,
  "message": "上传成功",
  "data": {
    "documentId": "uuid",
    "fileName": "社保接口文档.docx",
    "chunkCount": 12
  }
}

处理流程：

1. 文件类型校验（.txt, .md, .docx, .pdf）
2. 文本提取
3. 分块（chunk_size=500, overlap=50）
4. DashScope 向量化
5. MySQL 存元数据
6. Milvus 存向量

错误处理：

• 文件类型不支持 → 400 Bad Request
• 文件大小超限（10MB） → 413 Payload Too Large
• 向量化失败 → 500 Internal Server Error（回滚 MySQL）

验收标准：

• ✅ 支持 .txt, .md, .docx, .pdf
• ✅ MySQL + Milvus 事务一致
• ✅ 单元测试覆盖

4.2 文档查询接口

接口：GET /api/documents?province=广东&category=社保接口&page=0&size=10

响应：

{
  "code": 200,
  "data": {
    "content": [
      {
        "documentId": "uuid",
        "fileName": "社保接口文档.docx",
        "province": "广东",
        "category": "社保接口",
        "createdAt": "2026-06-23T10:00:00"
      }
    ],
    "totalElements": 1,
    "totalPages": 1
  }
}

验收标准：

• ✅ 分页正确
• ✅ 过滤生效
• ✅ 性能可接受（< 100ms）

4.3 文档删除接口

接口：DELETE /api/documents/{documentId}

响应：

{
  "code": 200,
  "message": "删除成功"
}

处理流程：

1. 删除 MySQL 记录
2. 根据 document_id 删除 Milvus 向量

事务性：

• MySQL 删除失败 → 不删除 Milvus
• Milvus 删除失败 → 记录日志（容忍）

验收标准：

• ✅ MySQL 记录删除
• ✅ Milvus 向量删除
• ✅ 幂等性（重复删除不报错）

4.4 混合检索工具

接口：DocumentSearchTool.search(errorCode, province)

输入：

{
  "errorCode": "40003",
  "province": "广东"
}

输出：

List<DocumentChunk> {
  "documentId": "uuid",
  "chunkId": "uuid",
  "content": "错误码 40003 表示...",
  "score": 0.95
}

检索策略：

1. 精确匹配（MySQL）：

   SELECT * FROM api_document
   WHERE error_code = '40003' AND province = '广东'
   

2. 语义检索（Milvus）：
   • 向量化查询文本
   • 相似度搜索 Top 10
3. RRF 融合：
   • 精确匹配分数 = 1.0
   • 语义检索分数 = Milvus 相似度
   • 合并排序，返回 Top 3

验收标准：

• ✅ 精确匹配优先
• ✅ 语义检索补漏
• ✅ 返回 Top 3
• ✅ 单元测试覆盖

---

接口规格

API 设计原则

• RESTful 风格
• 统一响应格式 Result<T>
• HTTP 状态码语义化
• 异常统一处理

统一响应格式

class Result<T> {
    int code;           // 业务状态码
    String message;     // 提示信息
    T data;             // 数据
    long timestamp;     // 时间戳
}

错误码约定

• 200: 成功
• 400: 参数错误
• 404: 资源不存在
• 500: 服务器错误

---

性能规格

响应时间要求

• 文档上传：< 5s（单文件 < 5MB）
• 文档查询：< 100ms
• 文档删除：< 200ms
• 混合检索：< 500ms
• Repository 查询：< 50ms

并发要求

• 支持 10 QPS（Phase 1 目标）
• 后续扩展至 100 QPS（Phase 2/3）

---

安全规格

输入校验

• 文件类型白名单
• 文件大小限制（10MB）
• SQL 注入防护（JPA Prepared Statement）
• XSS 防护（输入转义）

数据安全

• Redis 密码保护
• MySQL 用户权限最小化
• 敏感日志脱敏

---

测试规格

单元测试覆盖率

• Repository: 100%
• Service: 80%+
• Tool: 80%+
• Controller: 70%+

测试类型

• 单元测试（JUnit 5 + Mockito）
• 集成测试（@SpringBootTest）
• 接口测试（MockMvc）

必须覆盖的场景

• 正常流程
• 边界条件
• 异常处理
• 并发安全