# 架构决策记录 - 基础实体类和Mapper创建

## 背景

在完成数据库表结构设计和创建（REQ-010-1）后，需要为9张数据库表创建对应的Java实体类、Mapper接口和XML映射文件，使用MyBatis Plus框架，为后续功能开发提供数据访问基础。

当前系统面临的主要问题包括：
1. 缺少Java实体类，无法进行数据持久化操作
2. 缺少Mapper接口，无法进行数据库查询和更新
3. 缺少XML映射文件，无法配置SQL映射
4. 需要处理JSON类型字段的序列化和反序列化
5. 需要处理TEXT类型大字段
6. 需要保护敏感字段，避免泄露

## 决策

### 1. 实体类创建方案

**决策**: 使用MyBatis Plus注解创建实体类，使用Lombok简化代码，使用Jackson处理JSON字段。

**理由**:
- MyBatis Plus注解（@TableName、@TableId、@TableField）可以简化实体类配置
- Lombok可以简化实体类代码，减少样板代码
- Jackson可以处理JSON类型字段的序列化和反序列化
- 使用String类型处理TEXT类型大字段，简单可靠
- 使用@TableField(select = false)注解保护敏感字段，避免泄露

**实现方案**:
- 使用@TableName注解指定表名
- 使用@TableId注解标识主键，类型为Long
- 使用@TableField注解处理字段映射
- 使用Lombok的@Data、@Builder、@NoArgsConstructor、@AllArgsConstructor注解简化代码
- 使用Jackson的@JsonSerialize和@JsonDeserialize处理JSON字段
- 使用String类型处理TEXT类型大字段
- 使用@TableField(select = false)注解保护敏感字段（client_secret、password、security_token）
- 添加必要的注释说明（类注释、字段注释）
- 代码符合阿里巴巴Java开发规范

### 2. Mapper接口创建方案

**决策**: 创建Mapper接口，继承BaseMapper获取基础CRUD方法，使用@Mapper注解标记Mapper接口。

**理由**:
- BaseMapper提供了基础的CRUD方法，可以减少重复代码
- @Mapper注解标记Mapper接口，便于MyBatis扫描和注册
- 根据需要添加自定义查询方法，满足业务需求
- 代码符合阿里巴巴Java开发规范

**实现方案**:
- 创建Mapper接口，继承BaseMapper获取基础CRUD方法
- 使用@Mapper注解标记Mapper接口
- 根据需要添加自定义查询方法
- 添加必要的注释说明
- 代码符合阿里巴巴Java开发规范

### 3. Mapper XML文件创建方案

**决策**: 创建Mapper XML文件，配置SQL映射，使用MyBatis Plus的XML映射语法。

**理由**:
- XML映射文件可以配置复杂的SQL查询
- MyBatis Plus的XML映射语法简单易用
- namespace配置正确，对应Mapper接口的全限定名
- resultType配置正确，对应实体类的全限定名
- 添加必要的注释说明，提高代码可读性
- 代码符合MyBatis Plus XML映射语法

**实现方案**:
- 创建Mapper XML文件，配置SQL映射
- namespace配置正确，对应Mapper接口的全限定名
- resultType配置正确，对应实体类的全限定名
- 添加必要的注释说明
- 代码符合MyBatis Plus XML映射语法

### 4. JSON字段处理方案

**决策**: 使用Jackson处理JSON类型字段的序列化和反序列化。

**理由**:
- Jackson是Java中常用的JSON处理库，功能强大
- Jackson可以处理复杂的JSON数据结构
- Jackson的@JsonSerialize和@JsonDeserialize注解可以自定义序列化和反序列化逻辑
- Jackson的性能良好，可以满足性能要求

**实现方案**:
- 使用Jackson的@JsonSerialize注解指定序列化器
- 使用Jackson的@JsonDeserialize注解指定反序列化器
- 自定义序列化器和反序列化器，处理JSON字段的序列化和反序列化
- 使用String类型存储JSON字段，使用Jackson进行序列化和反序列化

### 5. 大字段处理方案

**决策**: 使用String类型处理TEXT类型大字段。

**理由**:
- String类型可以存储TEXT类型大字段
- String类型简单易用，不需要额外的处理
- String类型的性能良好，可以满足性能要求

**实现方案**:
- 使用String类型处理TEXT类型大字段
- 使用@TableField注解处理字段映射
- 添加必要的注释说明

### 6. 敏感字段保护方案

**决策**: 使用@TableField(select = false)注解保护敏感字段，默认不查询。

**理由**:
- @TableField(select = false)注解可以保护敏感字段，默认不查询
- 避免敏感字段泄露，提高系统安全性
- 需要查询敏感字段时，使用SQL查询指定字段

**实现方案**:
- 使用@TableField(select = false)注解保护敏感字段（client_secret、password、security_token）
- 默认不查询敏感字段
- 需要查询敏感字段时，使用SQL查询指定字段
- 添加必要的注释说明

## 备选方案

### 1. 实体类创建备选方案

**备选方案 1**: 使用XML映射文件创建实体类

**优点**:
- XML映射文件可以配置复杂的字段映射
- XML映射文件可以处理特殊的字段类型

**缺点**:
- XML映射文件配置复杂，维护成本高
- XML映射文件不如注解直观
- 不如MyBatis Plus注解简单易用

**备选方案 2**: 使用JPA注解创建实体类

**优点**:
- JPA是标准的ORM框架，易于学习

**缺点**:
- JPA的性能不如MyBatis Plus
- JPA不如MyBatis Plus灵活
- 不如MyBatis Plus注解简单易用

### 2. Mapper接口创建备选方案

**备选方案 1**: 不继承BaseMapper，手动实现CRUD方法

**优点**:
- 可以自定义CRUD方法，满足特殊需求

**缺点**:
- 需要手动实现CRUD方法，代码量大
- 不如BaseMapper简单易用
- 不如BaseMapper功能丰富

**备选方案 2**: 使用注解配置SQL查询

**优点**:
- 注解配置SQL查询，简单直观

**缺点**:
- 注解配置SQL查询，不如XML映射文件灵活
- 注解配置SQL查询，不适合复杂的SQL查询
- 不如XML映射文件功能丰富

### 3. Mapper XML文件创建备选方案

**备选方案 1**: 不创建XML映射文件，使用注解配置SQL查询

**优点**:
- 注解配置SQL查询，简单直观

**缺点**:
- 注解配置SQL查询，不如XML映射文件灵活
- 注解配置SQL查询，不适合复杂的SQL查询
- 不如XML映射文件功能丰富

**备选方案 2**: 使用MyBatis Plus的Wrapper构建查询条件

**优点**:
- Wrapper构建查询条件，简单易用

**缺点**:
- Wrapper构建查询条件，不如XML映射文件灵活
- Wrapper构建查询条件，不适合复杂的SQL查询
- 不如XML映射文件功能丰富

### 4. JSON字段处理备选方案

**备选方案 1**: 使用Gson处理JSON字段

**优点**:
- Gson是Google开发的JSON处理库，性能良好

**缺点**:
- Gson的功能不如Jackson丰富
- Gson的注解不如Jackson灵活
- 不如Jackson流行

**备选方案 2**: 使用Fastjson处理JSON字段

**优点**:
- Fastjson是阿里巴巴开发的JSON处理库，性能良好

**缺点**:
- Fastjson的安全性问题较多，不如Jackson安全
- Fastjson的功能不如Jackson丰富
- 不如Jackson流行

### 5. 大字段处理备选方案

**备选方案 1**: 使用byte[]类型处理TEXT类型大字段

**优点**:
- byte[]类型可以存储二进制数据

**缺点**:
- byte[]类型不如String类型简单易用
- byte[]类型的性能不如String类型
- 不如String类型流行

**备选方案 2**: 使用Blob类型处理TEXT类型大字段

**优点**:
- Blob类型可以存储二进制数据

**缺点**:
- Blob类型不如String类型简单易用
- Blob类型的性能不如String类型
- 不如String类型流行

### 6. 敏感字段保护备选方案

**备选方案 1**: 使用加密算法加密敏感字段

**优点**:
- 加密算法可以保护敏感字段，提高系统安全性

**缺点**:
- 加密算法增加了系统复杂度
- 加密算法影响了系统性能
- 不如@TableField(select = false)注解简单易用

**备选方案 2**: 使用视图隐藏敏感字段

**优点**:
- 视图可以隐藏敏感字段，提高系统安全性

**缺点**:
- 视图增加了系统复杂度
- 视图影响了系统性能
- 不如@TableField(select = false)注解简单易用

## 影响

### 对系统架构的影响

- 新增9个实体类，包括DataiMetaOrgConfig、DataiMetaTask、DataiMetaPackageItem、DataiMetaComponent、DataiMetaComponentVersion、DataiMetaJobExecution、DataiMetaDeployHistory、DataiMetaDeployComponentResult、DataiMetaJobLog
- 新增9个Mapper接口，包括DataiMetaOrgConfigMapper、DataiMetaTaskMapper、DataiMetaPackageItemMapper、DataiMetaComponentMapper、DataiMetaComponentVersionMapper、DataiMetaJobExecutionMapper、DataiMetaDeployHistoryMapper、DataiMetaDeployComponentResultMapper、DataiMetaJobLogMapper
- 新增9个Mapper XML文件，包括DataiMetaOrgConfigMapper.xml、DataiMetaTaskMapper.xml、DataiMetaPackageItemMapper.xml、DataiMetaComponentMapper.xml、DataiMetaComponentVersionMapper.xml、DataiMetaJobExecutionMapper.xml、DataiMetaDeployHistoryMapper.xml、DataiMetaDeployComponentResultMapper.xml、DataiMetaJobLogMapper.xml

### 对开发流程的影响

- 需要开发人员掌握MyBatis Plus框架，包括实体类注解、Mapper接口、XML映射文件
- 需要开发人员掌握Lombok框架，包括@Data、@Builder、@NoArgsConstructor、@AllArgsConstructor注解
- 需要开发人员掌握Jackson框架，包括@JsonSerialize、@JsonDeserialize注解
- 需要开发人员编写单元测试，验证实体类、Mapper接口、XML映射文件

### 对运维管理的影响

- 需要运维人员维护数据库表结构，确保表结构与实体类一致
- 需要运维人员监控数据库性能，确保查询性能满足要求

## 风险

### 技术风险

- **实体类映射风险**: 实体类字段映射错误可能导致数据读写失败
- **Mapper XML配置风险**: Mapper XML配置错误可能导致SQL执行失败
- **JSON字段处理风险**: JSON类型字段处理不当可能导致数据丢失
- **大字段处理风险**: 大字段处理不当可能导致性能问题
- **框架兼容风险**: MyBatis Plus版本兼容性问题

### 业务风险

- **数据一致性风险**: 实体类字段映射错误可能导致数据不一致
- **性能风险**: 大字段处理不当可能导致性能下降

### 实施风险

- **开发风险**: 实体类、Mapper接口、XML映射文件开发复杂，可能影响开发进度
- **测试风险**: 实体类、Mapper接口、XML映射文件测试复杂，可能影响测试进度

## 回滚策略

### 实体类创建回滚策略

- 如果实体类字段映射错误，可以修改实体类字段映射，重新编译
- 如果实体类字段映射影响业务功能，可以删除实体类，重新创建

### Mapper接口创建回滚策略

- 如果Mapper接口配置错误，可以修改Mapper接口，重新编译
- 如果Mapper接口影响业务功能，可以删除Mapper接口，重新创建

### Mapper XML文件创建回滚策略

- 如果Mapper XML配置错误，可以修改Mapper XML，重新编译
- 如果Mapper XML影响业务功能，可以删除Mapper XML，重新创建

### JSON字段处理回滚策略

- 如果JSON字段处理错误，可以修改JSON字段处理逻辑，重新编译
- 如果JSON字段影响业务功能，可以删除JSON字段处理逻辑，重新创建

### 大字段处理回滚策略

- 如果大字段处理错误，可以修改大字段处理逻辑，重新编译
- 如果大字段影响业务功能，可以删除大字段处理逻辑，重新创建

### 敏感字段保护回滚策略

- 如果敏感字段保护错误，可以修改敏感字段保护逻辑，重新编译
- 如果敏感字段保护影响业务功能，可以删除敏感字段保护逻辑，重新创建

## 验收标准

### 实体类创建验收标准

- 9个实体类创建成功
- 使用MyBatis Plus的@TableName注解指定表名
- 使用@TableId注解标识主键，类型为Long
- 使用@TableField注解处理字段映射
- 实体类字段与数据库表字段一一对应
- 实体类处理JSON类型字段的序列化和反序列化（使用Jackson的@JsonSerialize和@JsonDeserialize）
- 实体类处理TEXT类型大字段（使用String类型）
- 实体类添加必要的注释说明（类注释、字段注释）
- 实体类使用Lombok简化代码（@Data、@Builder、@NoArgsConstructor、@AllArgsConstructor）
- 实体类代码符合阿里巴巴Java开发规范

### Mapper接口创建验收标准

- 9个Mapper接口创建成功
- Mapper接口继承BaseMapper获取基础CRUD方法
- Mapper接口使用@Mapper注解标记
- Mapper接口添加自定义查询方法（如果需要）
- Mapper接口代码符合阿里巴巴Java开发规范

### Mapper XML文件创建验收标准

- 9个Mapper XML文件创建成功
- XML映射文件namespace配置正确（对应Mapper接口的全限定名）
- XML映射文件resultType配置正确（对应实体类的全限定名）
- XML映射文件添加必要的注释说明
- XML映射文件代码符合MyBatis Plus XML映射语法

### 非功能验收标准

- 性能要求 - 实体类序列化和反序列化耗时不超过 10ms
- 性能要求 - Mapper接口查询响应时间不超过 100ms
- 安全要求 - 敏感字段（client_secret、password、security_token）使用@TableField(select = false)注解，默认不查询
- 可用性要求 - 实体类、Mapper接口、Mapper XML文件编译通过，无错误和警告
- 可维护性要求 - 代码结构清晰，注释完整，易于理解和维护

## 视觉锚点

### Visual Reference

引用 Canvas 的具体节点或快照：
- [Authentication.canvas](../../Authentication.canvas) - 相关架构图
- **具体节点**: [集成Mapper](node_integration_mapper) - 处理集成相关数据的持久化操作

### Status

- [x] Draft
- [ ] Accepted
- [ ] Superceded

## 参考资料

列出与该决策相关的参考资料，包括文档、文章或其他资源：

- [REQ-010-2.md](../requirements/REQ-010-2.md) - 基础实体类和Mapper创建需求文档
- [REQ-010.md](../requirements/REQ-010.md) - Salesforce元数据拉取和部署主需求文档
- [REQ-010-1.md](../requirements/REQ-010-1.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 客户端参考文档（唯一真源）
- MyBatis Plus 文档 - https://baomidou.com/
- Lombok 文档 - https://projectlombok.org/
- Jackson 文档 - https://github.com/FasterXML/jackson