datai/docs/archive/changelog/0020-database-table-design-create.md

# Changelog - 数据库表结构设计和创建

## 变更信息

- **版本号**: V0.1.15
- **发布日期**: 2026-01-17
- **变更类型**: 特性更新

## 变更摘要

本次变更为 Salesforce 元数据拉取和部署功能（REQ-010）的第一个子需求（REQ-010-1），完成了数据库表结构设计和创建。通过设计 9 个核心数据库表，为元数据管理提供了完整的数据存储基础，支持组织配置管理、元数据包定义管理、元数据任务管理、组件索引和版本管理、作业执行跟踪、部署历史记录、部署组件结果明细和详细日志查询等功能。

## 详细变更

### 特性更新

- **数据库表结构设计** - 设计了 9 个核心数据库表，采用 MyBatis Plus + MySQL 技术栈，表名前缀为 `datai_meta_`，所有表包含标准基础字段（dept_id, create_by, create_time, update_by, update_time, remark）
  - `datai_meta_org_config` - Salesforce组织配置表，支持 OAuth2 和 JWT 两种认证方式，存储组织连接信息和认证凭证
  - `datai_meta_package_item` - 元数据包定义明细表，为了避免手动拼写 `package.xml`，需要将"我要拉取什么"结构化存储
  - `datai_meta_component` - 元数据组件索引表，这是组件的"户口本"，记录组件的存在，不记录代码
  - `datai_meta_component_version` - 元数据版本内容表，这是实现"Java 版 Git"的核心表。每次拉取如果内容发生变化，就在此增加一条记录
  - `datai_meta_task` - 元数据任务定义表，支持多种任务类型（Retrieve/Deploy/QuickDeploy/DestructiveChanges），支持增量拉取和版本控制
  - `datai_meta_job_execution` - 作业执行记录表，跟踪每次拉取或部署作业的执行状态、进度和结果
  - `datai_meta_deploy_history` - 部署历史记录表，记录每次部署的详细信息，包括部署结果和测试覆盖率
  - `datai_meta_job_log` - 作业执行日志表，记录作业执行过程中的详细日志信息，支持按级别和类型查询
  - `datai_meta_deploy_component_result` - 部署组件结果明细表，CI/CD 最重要的部分，告知用户具体哪个文件失败了

- **索引策略优化** - 为每个表设计了合理的索引策略，在保证查询性能的同时避免冗余索引
  - 唯一索引：确保数据的唯一性和一致性（如组织名称、任务名称）
  - 普通索引：优化常用查询场景（如按状态查询、按时间查询）
  - 联合索引：优化复合查询场景（如按组织和任务类型查询）

- **数据安全设计** - 对敏感字段进行了加密存储设计
  - OAuth 客户端密钥（client_secret）加密存储
  - 用户密码（password）加密存储
  - 安全令牌（security_token）加密存储
  - 访问令牌（access_token）和刷新令牌（refresh_token）加密存储

### Bug 修复

- 无

### 性能优化

- **索引优化** - 通过合理的索引设计，确保常用查询场景的性能
  - 单表查询响应时间目标 < 100ms
  - 批量插入 1000 条数据目标 < 1s
  - 避免了冗余索引，减少写入性能损耗

### 安全修复

- 无

### 其他变更

- **命名规范统一** - 所有表名统一使用 `datai_meta_` 前缀，与现有项目表结构保持一致
- **基础字段标准化** - 所有表包含标准基础字段（dept_id, create_by, create_time, update_by, update_time, remark），与现有项目表结构保持一致
- **无外键约束** - 采用应用层关联而非数据库外键约束，提高灵活性和性能

## 影响范围

### 受影响的模块

- **datai-salesforce-metadata** - 新增模块，用于 Salesforce 元数据拉取和部署功能
  - 数据库表结构：新增 9 个数据库表
  - 实体类：待创建 9 个 Java 实体类
  - Mapper 接口：待创建 9 个 MyBatis Plus Mapper 接口
  - Flyway 迁移脚本：待创建 V1.0.0__create_metadata_tables.sql

### 兼容性说明

- 本次变更为新增模块，不影响现有功能
- 数据库表结构与现有项目表结构保持一致，遵循相同的命名规范和基础字段规范
- 使用 MyBatis Plus 框架，与现有项目技术栈保持一致

## 升级指南

### 升级步骤

1. **数据库迁移** - 执行 Flyway 迁移脚本 `V1.0.0__create_metadata_tables.sql` 创建 9 个数据库表
   ```bash
   # 在项目根目录执行
   mvn flyway:migrate
   ```

2. **代码编译** - 编译项目，确保没有编译错误
   ```bash
   # 在项目根目录执行
   mvn clean compile
   ```

3. **单元测试** - 运行单元测试，验证代码正确性
   ```bash
   # 在项目根目录执行
   mvn test
   ```

### 注意事项

- **数据库版本要求** - 需要 MySQL 8.0+ 版本
- **字符集要求** - 数据库字符集必须为 utf8mb4，排序规则为 utf8mb4_general_ci
- **存储引擎要求** - 使用 InnoDB 存储引擎，支持事务和外键
- **Flyway 版本要求** - 需要配置 Flyway 插件，版本建议 8.x+
- **MyBatis Plus 版本要求** - 需要配置 MyBatis Plus，版本建议 3.5+

## 测试信息

### 测试环境

- **开发环境** - 本地开发环境，MySQL 8.0+，Java 17+
- **测试环境** - 待配置测试环境

### 测试结果

- **功能验证** - 待执行代码生成后进行验证
  - [ ] 所有 9 个数据库表创建成功
  - [ ] 实体类和 Mapper 接口正确
  - [ ] 基础 CRUD 操作正常
- **性能验证** - 待执行代码生成后进行验证
  - [ ] 单表查询响应时间 < 100ms
  - [ ] 批量插入 1000 条数据 < 1s
- **可靠性验证** - 待执行代码生成后进行验证
  - [ ] 数据一致性得到保证
  - [ ] 数据库迁移不丢失数据
- **安全性验证** - 待执行代码生成后进行验证
  - [ ] 敏感字段加密存储
  - [ ] SQL 注入防护有效
- **代码规范性验证** - 待执行代码生成后进行验证
  - [ ] 代码符合阿里巴巴 Java 开发规范
  - [ ] 代码符合 MyBatis Plus 最佳实践

## 相关链接

- [需求文档](../requirements/REQ-010-1.md) - REQ-010-1 数据库表结构设计和创建需求文档
- [架构决策](../decisions/adr/0010-database-table-design.md) - 0010-database-table-design.md 数据库表结构设计和创建架构决策
- [提示词文档](../prompts/011-database-table-design-create.md) - 011-database-table-design-create.md 数据库表结构设计和创建实现提示词
- [会话记录](../sessions/20260117-database-table-design-create.md) - 20260117-database-table-design-create.md 数据库表结构设计和创建实现会话记录
- [现有表结构参考](../sql/datai_table.sql) - datai_table.sql 现有数据库表结构参考

## 发布人员

- **架构师** - 负责数据库表结构设计和架构决策
- **开发工程师** - 负责代码实现和测试验证

## 审核信息

- **审核人员**: 待审核
- **审核日期**: 待审核
- **审核状态**: 待审核
- **审核意见**: 待审核