feat(phase1): 完成全局完善和基础设施文档

Task 6.1: 统一异常处理
- 创建 GlobalExceptionHandler:Spring 全局异常拦截器
  - SessionNotFoundException: 404 会话未找到
  - DocumentProcessException: 400 文档处理异常
  - MaxUploadSizeExceededException: 400 文件大小超限
  - IllegalArgumentException: 400 参数错误
  - Exception: 500 系统异常兜底
- 统一响应格式:Result<T> + HTTP 状态码

Task 6.2: Docker Compose 配置
- 创建 docker-compose.yml:本地开发环境一键启动
  - MySQL 8.0: 数据持久化,端口 3306
  - Redis 7: 会话缓存,端口 6379
  - Milvus Standalone: 向量索引,端口 19530
    - etcd: 元数据存储
    - MinIO: 对象存储
- 数据卷持久化:mysql-data, redis-data, milvus-data
- 健康检查:自动重启机制

Task 6.3: 更新 README.md
- 新增 Phase 1 专属章节:
  - 架构概览(已完成功能清单)
  - 本地开发环境(前置要求、快速开始)
  - 数据库迁移(Flyway 脚本说明)
  - API 文档(文档管理接口示例)
  - 项目结构(分层架构说明)
  - 待办事项(向量化索引、混合检索)
  - 技术决策(包名重构、文本格式、分块策略)

编译验证:BUILD SUCCESS

Progress: 31/33 tasks completed (94%)
This commit is contained in:
zhuyongxin
2026-06-23 15:50:47 +08:00
parent e76d4ce48f
commit 26aaf149d8
4 changed files with 340 additions and 3 deletions
@@ -0,0 +1,72 @@
package com.superbiz.agent.exception;
import com.superbiz.agent.dto.Result;
import lombok.extern.slf4j.Slf4j;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.multipart.MaxUploadSizeExceededException;
/**
* 全局异常处理器
*/
@Slf4j
@RestControllerAdvice
public class GlobalExceptionHandler {
/**
* 处理会话未找到异常
*/
@ExceptionHandler(SessionNotFoundException.class)
public ResponseEntity<Result<Void>> handleSessionNotFound(SessionNotFoundException e) {
log.warn("会话未找到: {}", e.getMessage());
return ResponseEntity
.status(HttpStatus.NOT_FOUND)
.body(Result.error(404, e.getMessage()));
}
/**
* 处理文档处理异常
*/
@ExceptionHandler(DocumentProcessException.class)
public ResponseEntity<Result<Void>> handleDocumentProcess(DocumentProcessException e) {
log.error("文档处理异常: {}", e.getMessage(), e);
return ResponseEntity
.status(HttpStatus.BAD_REQUEST)
.body(Result.error(400, e.getMessage()));
}
/**
* 处理文件上传大小超限异常
*/
@ExceptionHandler(MaxUploadSizeExceededException.class)
public ResponseEntity<Result<Void>> handleMaxUploadSizeExceeded(MaxUploadSizeExceededException e) {
log.warn("文件大小超限: {}", e.getMessage());
return ResponseEntity
.status(HttpStatus.BAD_REQUEST)
.body(Result.error(400, "文件大小超限,最大允许 10MB"));
}
/**
* 处理非法参数异常
*/
@ExceptionHandler(IllegalArgumentException.class)
public ResponseEntity<Result<Void>> handleIllegalArgument(IllegalArgumentException e) {
log.warn("非法参数: {}", e.getMessage());
return ResponseEntity
.status(HttpStatus.BAD_REQUEST)
.body(Result.error(400, "参数错误: " + e.getMessage()));
}
/**
* 处理所有未捕获的异常
*/
@ExceptionHandler(Exception.class)
public ResponseEntity<Result<Void>> handleGenericException(Exception e) {
log.error("系统异常", e);
return ResponseEntity
.status(HttpStatus.INTERNAL_SERVER_ERROR)
.body(Result.error(500, "系统内部错误,请稍后重试"));
}
}