# Prompt - 异常处理机制完善

## 输入引用

引用相关的 docs 文档链接：

- [REQ-010-16.md](../requirements/REQ-010-16.md) - 异常处理机制完善需求文档
- [0025-exception-handling.md](../decisions/adr/0025-exception-handling.md) - 异常处理机制完善架构决策
- [REQ-010.md](../requirements/REQ-010.md) - Salesforce元数据拉取和部署主需求文档
- [REQ-010-5.md](../requirements/REQ-010-5.md) - Metadata API客户端封装需求文档
- [REQ-010-6.md](../requirements/REQ-010-6.md) - 元数据拉取核心功能需求文档
- [REQ-010-8.md](../requirements/REQ-010-8.md) - 元数据部署核心功能需求文档
- [metadata-module.md](../reference-code/com/docs/metadata-module.md) - Salesforce Metadata API 模块说明（唯一真源）
- [index.md](../reference-code/com/docs/index.md) - Salesforce SOAP API Java 客户端参考文档（唯一真源）

## Context Maps

强制列出本次 Prompt 依赖的 Canvas 文件：

- [Authentication.canvas](../Authentication.canvas) - 项目架构视觉化展示
- **相关节点**: [集成核心](node_integration_core) - 提供与Salesforce的各种连接方式
- **相关节点**: [SessionManager](node_session_manager_detail) - 会话管理，提供登录服务
- **快照时间**: 2026-01-19 00:00:00

## 目标

完善异常处理机制，包括异常捕获、异常分类、异常处理、异常恢复、异常告警、异常日志。支持捕获和处理各种异常情况，提供友好的错误提示和恢复机制。

## 输出格式

代码示例（语言：Java）

### 1. 异常类型枚举

```java
package com.datai.salesforce.metadata.exception.enums;

import lombok.Getter;

@Getter
public enum ExceptionType {
    NETWORK("网络异常"),
    API_CALL("API调用异常"),
    FILE_OPERATION("文件操作异常"),
    DATABASE_OPERATION("数据库操作异常"),
    BUSINESS_LOGIC("业务逻辑异常");
    
    private final String description;
    
    ExceptionType(String description) {
        this.description = description;
    }
}
```

### 2. 异常级别枚举

```java
package com.datai.salesforce.metadata.exception.enums;

import lombok.Getter;

@Getter
public enum ExceptionLevel {
    INFO("信息"),
    WARN("警告"),
    ERROR("错误"),
    FATAL("致命错误");
    
    private final String description;
    
    ExceptionLevel(String description) {
        this.description = description;
    }
}
```

### 3. 异常来源枚举

```java
package com.datai.salesforce.metadata.exception.enums;

import lombok.Getter;

@Getter
public enum ExceptionSource {
    METADATA_RETRIEVE("元数据拉取"),
    METADATA_DEPLOY("元数据部署"),
    FILE_STORAGE("文件存储"),
    DATABASE("数据库");
    
    private final String description;
    
    ExceptionSource(String description) {
        this.description = description;
    }
}
```

### 4. 自定义异常类

```java
package com.datai.salesforce.metadata.exception;

import com.datai.salesforce.metadata.exception.enums.ExceptionLevel;
import com.datai.salesforce.metadata.exception.enums.ExceptionSource;
import com.datai.salesforce.metadata.exception.enums.ExceptionType;
import lombok.Getter;

@Getter
public class BaseException extends RuntimeException {
    
    private final ExceptionType exceptionType;
    private final ExceptionLevel exceptionLevel;
    private final ExceptionSource exceptionSource;
    private final String exceptionCode;
    
    public BaseException(ExceptionType exceptionType, 
                     ExceptionLevel exceptionLevel, 
                     ExceptionSource exceptionSource, 
                     String exceptionCode, 
                     String message) {
        super(message);
        this.exceptionType = exceptionType;
        this.exceptionLevel = exceptionLevel;
        this.exceptionSource = exceptionSource;
        this.exceptionCode = exceptionCode;
    }
    
    public BaseException(ExceptionType exceptionType, 
                     ExceptionLevel exceptionLevel, 
                     ExceptionSource exceptionSource, 
                     String exceptionCode, 
                     String message, 
                     Throwable cause) {
        super(message, cause);
        this.exceptionType = exceptionType;
        this.exceptionLevel = exceptionLevel;
        this.exceptionSource = exceptionSource;
        this.exceptionCode = exceptionCode;
    }
}
```

### 5. 网络异常

```java
package com.datai.salesforce.metadata.exception;

import com.datai.salesforce.metadata.exception.enums.ExceptionLevel;
import com.datai.salesforce.metadata.exception.enums.ExceptionSource;
import com.datai.salesforce.metadata.exception.enums.ExceptionType;

public class NetworkException extends BaseException {
    
    public NetworkException(String exceptionCode, String message) {
        super(ExceptionType.NETWORK, ExceptionLevel.ERROR, ExceptionSource.METADATA_RETRIEVE, 
              exceptionCode, message);
    }
    
    public NetworkException(String exceptionCode, String message, Throwable cause) {
        super(ExceptionType.NETWORK, ExceptionLevel.ERROR, ExceptionSource.METADATA_RETRIEVE, 
              exceptionCode, message, cause);
    }
}
```

### 6. API调用异常

```java
package com.datai.salesforce.metadata.exception;

import com.datai.salesforce.metadata.exception.enums.ExceptionLevel;
import com.datai.salesforce.metadata.exception.enums.ExceptionSource;
import com.datai.salesforce.metadata.exception.enums.ExceptionType;

public class ApiCallException extends BaseException {
    
    public ApiCallException(String exceptionCode, String message) {
        super(ExceptionType.API_CALL, ExceptionLevel.ERROR, ExceptionSource.METADATA_RETRIEVE, 
              exceptionCode, message);
    }
    
    public ApiCallException(String exceptionCode, String message, Throwable cause) {
        super(ExceptionType.API_CALL, ExceptionLevel.ERROR, ExceptionSource.METADATA_RETRIEVE, 
              exceptionCode, message, cause);
    }
}
```

### 7. 文件操作异常

```java
package com.datai.salesforce.metadata.exception;

import com.datai.salesforce.metadata.exception.enums.ExceptionLevel;
import com.datai.salesforce.metadata.exception.enums.ExceptionSource;
import com.datai.salesforce.metadata.exception.enums.ExceptionType;

public class FileOperationException extends BaseException {
    
    public FileOperationException(String exceptionCode, String message) {
        super(ExceptionType.FILE_OPERATION, ExceptionLevel.ERROR, ExceptionSource.FILE_STORAGE, 
              exceptionCode, message);
    }
    
    public FileOperationException(String exceptionCode, String message, Throwable cause) {
        super(ExceptionType.FILE_OPERATION, ExceptionLevel.ERROR, ExceptionSource.FILE_STORAGE, 
              exceptionCode, message, cause);
    }
}
```

### 8. 数据库操作异常

```java
package com.datai.salesforce.metadata.exception;

import com.datai.salesforce.metadata.exception.enums.ExceptionLevel;
import com.datai.salesforce.metadata.exception.enums.ExceptionSource;
import com.datai.salesforce.metadata.exception.enums.ExceptionType;

public class DatabaseOperationException extends BaseException {
    
    public DatabaseOperationException(String exceptionCode, String message) {
        super(ExceptionType.DATABASE_OPERATION, ExceptionLevel.ERROR, ExceptionSource.DATABASE, 
              exceptionCode, message);
    }
    
    public DatabaseOperationException(String exceptionCode, String message, Throwable cause) {
        super(ExceptionType.DATABASE_OPERATION, ExceptionLevel.ERROR, ExceptionSource.DATABASE, 
              exceptionCode, message, cause);
    }
}
```

### 9. 业务逻辑异常

```java
package com.datai.salesforce.metadata.exception;

import com.datai.salesforce.metadata.exception.enums.ExceptionLevel;
import com.datai.salesforce.metadata.exception.enums.ExceptionSource;
import com.datai.salesforce.metadata.exception.enums.ExceptionType;

public class BusinessLogicException extends BaseException {
    
    public BusinessLogicException(String exceptionCode, String message) {
        super(ExceptionType.BUSINESS_LOGIC, ExceptionLevel.WARN, ExceptionSource.METADATA_RETRIEVE, 
              exceptionCode, message);
    }
    
    public BusinessLogicException(String exceptionCode, String message, Throwable cause) {
        super(ExceptionType.BUSINESS_LOGIC, ExceptionLevel.WARN, ExceptionSource.METADATA_RETRIEVE, 
              exceptionCode, message, cause);
    }
}
```

### 10. 全局异常处理器

```java
package com.datai.salesforce.metadata.exception.handler;

import com.datai.common.core.domain.R;
import com.datai.salesforce.metadata.exception.BaseException;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@Slf4j
@RestControllerAdvice
public class GlobalExceptionHandler {
    
    @ExceptionHandler(BaseException.class)
    public R<Void> handleBaseException(BaseException e) {
        log.error("业务异常: {}", e.getMessage(), e);
        return R.fail(e.getExceptionCode(), e.getMessage());
    }
    
    @ExceptionHandler(Exception.class)
    public R<Void> handleException(Exception e) {
        log.error("系统异常: {}", e.getMessage(), e);
        return R.fail("SYSTEM_ERROR", "系统异常，请联系管理员");
    }
}
```

### 11. 异常日志实体类

```java
package com.datai.salesforce.metadata.exception.entity;

import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import com.datai.salesforce.metadata.exception.enums.ExceptionLevel;
import com.datai.salesforce.metadata.exception.enums.ExceptionSource;
import com.datai.salesforce.metadata.exception.enums.ExceptionType;
import lombok.Data;

import java.time.LocalDateTime;

@Data
@TableName("datai_exception_log")
public class ExceptionLog {
    
    @TableId(type = IdType.AUTO)
    private Long id;
    
    private ExceptionType exceptionType;
    
    private ExceptionLevel exceptionLevel;
    
    private ExceptionSource exceptionSource;
    
    private String exceptionCode;
    
    private String exceptionMessage;
    
    private String exceptionStack;
    
    private LocalDateTime exceptionTime;
    
    private LocalDateTime createTime;
}
```

### 12. 恢复点实体类

```java
package com.datai.salesforce.metadata.exception.entity;

import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import lombok.Data;

import java.time.LocalDateTime;

@Data
@TableName("datai_recovery_point")
public class RecoveryPoint {
    
    @TableId(type = IdType.AUTO)
    private Long id;
    
    private Long jobExecutionId;
    
    private String recoveryPointName;
    
    private String recoveryPointData;
    
    private String recoveryPointStatus;
    
    private LocalDateTime recoveryPointTime;
    
    private LocalDateTime createTime;
}
```

### 13. 异常告警实体类

```java
package com.datai.salesforce.metadata.exception.entity;

import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import lombok.Data;

import java.time.LocalDateTime;

@Data
@TableName("datai_exception_alarm")
public class ExceptionAlarm {
    
    @TableId(type = IdType.AUTO)
    private Long id;
    
    private Long exceptionLogId;
    
    private String alarmType;
    
    private String alarmTitle;
    
    private String alarmContent;
    
    private String alarmStatus;
    
    private LocalDateTime createTime;
}
```

### 14. 异常日志服务接口

```java
package com.datai.salesforce.metadata.exception.service;

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.datai.salesforce.metadata.exception.entity.ExceptionLog;
import com.datai.salesforce.metadata.exception.enums.ExceptionLevel;
import com.datai.salesforce.metadata.exception.enums.ExceptionSource;
import com.datai.salesforce.metadata.exception.enums.ExceptionType;

import java.time.LocalDateTime;
import java.util.List;

public interface IExceptionLogService {
    
    Long saveExceptionLog(ExceptionLog exceptionLog);
    
    ExceptionLog getExceptionLog(Long id);
    
    IPage<ExceptionLog> queryExceptionLogs(Page<ExceptionLog> page, 
                                          ExceptionType exceptionType, 
                                          ExceptionLevel exceptionLevel, 
                                          ExceptionSource exceptionSource, 
                                          LocalDateTime startTime, 
                                          LocalDateTime endTime);
    
    boolean deleteExceptionLog(Long id);
    
    boolean batchDeleteExceptionLogs(List<Long> ids);
}
```

### 15. 恢复服务接口

```java
package com.datai.salesforce.metadata.exception.service;

import com.datai.salesforce.metadata.exception.entity.RecoveryPoint;

import java.util.List;

public interface IRecoveryService {
    
    Long createRecoveryPoint(RecoveryPoint recoveryPoint);
    
    RecoveryPoint getRecoveryPoint(Long id);
    
    List<RecoveryPoint> getRecoveryPointsByJobExecutionId(Long jobExecutionId);
    
    boolean recoverFromPoint(Long recoveryPointId);
    
    boolean deleteRecoveryPoint(Long id);
    
    boolean batchDeleteRecoveryPoints(List<Long> ids);
}
```

### 16. 异常告警服务接口

```java
package com.datai.salesforce.metadata.exception.service;

import com.datai.salesforce.metadata.exception.entity.ExceptionAlarm;

import java.util.List;

public interface IExceptionAlarmService {
    
    Long createExceptionAlarm(ExceptionAlarm exceptionAlarm);
    
    ExceptionAlarm getExceptionAlarm(Long id);
    
    boolean sendExceptionAlarm(Long exceptionLogId, String alarmType, String alarmTitle, String alarmContent);
    
    List<ExceptionAlarm> getExceptionAlarmsByExceptionLogId(Long exceptionLogId);
    
    boolean deleteExceptionAlarm(Long id);
    
    boolean batchDeleteExceptionAlarms(List<Long> ids);
}
```

## 约束

- **技术栈限制**: 必须基于现有的 Spring Boot 3 + Vue 3 技术栈
- **架构约束**: 必须遵循 Authentication.canvas 中定义的架构和调用关系
- **模块约束**: 必须在 datai-salesforce-metadata 模块下实现
- **数据库约束**: 必须使用 MyBatis Plus 作为持久层框架
- **性能约束**: 异常处理性能必须满足要求，不能影响系统响应
- **依赖约束**: 必须依赖于 REQ-010-1, REQ-010-2, REQ-010-5, REQ-010-6, REQ-010-8

## Rule Set

"请严格参考 @Authentication.canvas 中的状态机转移逻辑，不要自行发挥。"

**具体规则**：
- 必须使用 Canvas 中定义的类名和方法名
- 必须遵循 Canvas 中定义的调用关系
- 必须参考 Canvas 中的流程图逻辑
- 必须使用 SessionManager 进行会话管理和自动重新登录
- 必须使用现有的认证模块进行 OAuth 认证
- 必须使用现有的集成核心功能进行 API 调用
- 必须遵循现有的异常处理机制
- 必须遵循现有的日志记录规范

## 验收标准

定义验证输出质量的具体标准，例如：

- **功能完整性**: 所有异常处理功能能够正常工作
  - 异常捕获功能正常工作
  - 异常分类功能正常工作
  - 异常处理功能正常工作
  - 异常恢复功能正常工作
  - 异常告警功能正常工作
  - 异常日志功能正常工作

- **性能指标**: 异常处理性能满足要求，不影响系统响应
  - 异常捕获响应时间 < 10ms
  - 异常处理响应时间 < 100ms
  - 异常恢复响应时间 < 1s
  - 异常告警响应时间 < 1s
  - 异常日志记录响应时间 < 10ms

- **完整性**: 异常信息完整详细，能够追溯异常发生原因
  - 异常信息完整详细
  - 能够追溯异常发生原因

- **代码规范性**: 代码符合项目编码规范，有清晰的注释
  - 使用 Lombok 的 @Data、@RequiredArgsConstructor、@Slf4j 注解
  - 使用 Spring 的 @ControllerAdvice、@ExceptionHandler、@RestControllerAdvice 注解
  - 使用 MyBatis Plus 的 @TableName、@TableId 注解

- **可维护性**: 代码结构清晰，易于扩展和维护
  - 服务接口和实现分离
  - 控制器、服务、实体、Mapper 分层清晰
  - 使用枚举管理异常类型、异常级别、异常来源

- **可测试性**: 代码易于单元测试和集成测试
  - 编写单元测试，测试覆盖率 > 80%
  - 编写集成测试，确保功能正常

## 风险

识别使用此提示词可能带来的风险，例如：

- **输出质量风险**: 代码质量可能不符合项目规范
  - **缓解措施**: 使用代码审查，确保代码质量符合项目规范

- **技术实现风险**: 技术实现可能不符合架构决策
  - **缓解措施**: 参考架构决策文档，确保技术实现符合架构决策

- **时间成本风险**: 开发周期可能较长
  - **缓解措施**: 分阶段实施，优先实现核心功能，逐步完善

- **性能风险**: 异常处理性能可能不佳
  - **缓解措施**: 使用异步异常处理，使用重试机制，使用事务回滚

## 使用记录

| 日期 | 使用场景 | 输入参数 | 输出结果 | 反馈 | 改进措施 |
|------|---------|---------|---------|------|----------|
| 2026-01-19 | 异常处理机制完善实现 | REQ-010-16, 0025-exception-handling | 异常处理机制完善代码 | 代码质量良好 | 无 |