kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop_20260203
datai/docs/archive/sessions/20260117-database-table-design-create.md

14 KiB
Raw Permalink Blame History

会话记录 - 数据库表结构设计和创建

现状

当前项目需要实现 Salesforce 元数据拉取和部署功能，其中 REQ-010-1（数据库表结构设计和创建）是第一个子需求。已完成以下工作：

  1. 需求定义阶段：

    • 创建了 REQ-010 主需求文档
    • 创建了 17 个子需求文档（REQ-010-1 到 REQ-010-17）
    • 创建了子需求拆分文档

  2. 架构决策阶段：

    • 创建了 0010-database-table-design.md 架构决策记录
    • 分析了 2 种备选方案（JPA + PostgreSQL vs MyBatis Plus + MySQL）
    • 选择了 MyBatis Plus + MySQL 作为技术栈
    • 设计了 9 个核心数据库表（datai_meta_org_config, datai_meta_package_item, datai_meta_component, datai_meta_component_version, datai_meta_task, datai_meta_job_execution, datai_meta_deploy_history, datai_meta_job_log, datai_meta_deploy_component_result）
    • 优化了表名称前缀从 datai_sf 改为 datai_meta
    • 优化了基础字段与现有表保持一致
    • 基于参考资料 005-源数据拉取数据库设计方案.md 优化表设计，新增 3 张表（datai_meta_package_item, datai_meta_component_version, datai_meta_deploy_component_result）

  3. 提示词资产化阶段：

    • 创建了 011-database-table-design-create.md 执行提示词
    • 定义了详细的输出格式（SQL、实体类、Mapper、单元测试）
    • 定义了严格的约束条件（技术栈、命名规范、基础字段、MyBatis Plus 注解、性能、安全性、兼容性）
    • 定义了 Rule Set（Canvas 规则、MyBatis Plus 规则、Flyway 规则）
    • 定义了验收标准和风险识别

目标

本次会话的目标是：

  1. 执行代码生成：基于 011-database-table-design-create.md 提示词，生成完整的数据库表结构设计和创建代码
  2. 验证代码质量：确保生成的代码符合 MyBatis Plus 规范和项目编码规范
  3. 测试代码功能：运行单元测试验证代码的正确性
  4. 完成验收标准：满足 REQ-010-1 的所有验收标准

输入链接

Prompt 文件

Context Snapshot

记录本次会话参考了哪些 Canvas 节点：

执行过程

详细记录本次会话的执行过程，包括：

1. 准备阶段

  • 时间: 2026-01-17 00:00:00
  • 操作:
    • 阅读 REQ-010-1 需求文档，理解需求目标
    • 阅读 0010-database-table-design.md 架构决策，理解技术选型
    • 阅读 011-database-table-design-create.md 提示词，理解输出要求
    • 阅读 datai_table.sql 现有表结构，理解命名规范
  • 关键决策: 确认使用 MyBatis Plus + MySQL 技术栈，表名前缀为 datai_meta_

2. 代码生成阶段（待执行）

  • 时间: 待定
  • 操作:
    • 加载 011-database-table-design-create.md 提示词
    • 生成 9 个数据库表的 SQL 创建语句
    • 生成 9 个对应的 Java 实体类
    • 生成 9 个对应的 Mapper 接口
    • 生成 Flyway 迁移脚本
    • 生成单元测试代码
  • 预期产出:
    • V1.0.0__create_metadata_tables.sql
    • DataiMetaOrgConfig.java
    • DataiMetaPackageItem.java
    • DataiMetaComponent.java
    • DataiMetaComponentVersion.java
    • DataiMetaTask.java
    • DataiMetaJobExecution.java
    • DataiMetaDeployHistory.java
    • DataiMetaJobLog.java
    • DataiMetaDeployComponentResult.java
    • 对应的 Mapper 接口
    • 对应的单元测试

3. 验证阶段（待执行）

  • 时间: 待定
  • 操作:
    • 在测试环境中执行 SQL 脚本
    • 验证表结构创建成功
    • 运行单元测试
    • 验证测试通过
    • 代码审查
  • 预期结果: 所有验收标准满足

关键产出

记录本次会话的关键产出，例如：

已完成的产出

  1. 需求文档:

    • REQ-010-1.md - 数据库表结构设计和创建需求文档
    • 17 个子需求文档

  2. 架构决策文档:

    • 0010-database-table-design.md - 数据库表结构设计和创建架构决策

  3. 提示词文档:

    • 011-database-table-design-create.md - 数据库表结构设计和创建实现提示词

  4. 会话记录:

    • 本文档 - 20260117-database-table-design-create.md

待完成的产出

  1. SQL 脚本:

    • V1.0.0__create_metadata_tables.sql - Flyway 迁移脚本

  2. Java 实体类:

    • DataiMetaOrgConfig.java
    • DataiMetaPackageItem.java
    • DataiMetaComponent.java
    • DataiMetaComponentVersion.java
    • DataiMetaTask.java
    • DataiMetaJobExecution.java
    • DataiMetaDeployHistory.java
    • DataiMetaJobLog.java
    • DataiMetaDeployComponentResult.java

  3. Mapper 接口:

    • DataiMetaOrgConfigMapper.java
    • DataiMetaPackageItemMapper.java
    • DataiMetaComponentMapper.java
    • DataiMetaComponentVersionMapper.java
    • DataiMetaTaskMapper.java
    • DataiMetaJobExecutionMapper.java
    • DataiMetaDeployHistoryMapper.java
    • DataiMetaJobLogMapper.java
    • DataiMetaDeployComponentResultMapper.java

  4. 单元测试:

    • DataiMetaOrgConfigMapperTest.java
    • DataiMetaPackageItemMapperTest.java
    • DataiMetaComponentMapperTest.java
    • DataiMetaComponentVersionMapperTest.java
    • DataiMetaTaskMapperTest.java
    • DataiMetaJobExecutionMapperTest.java
    • DataiMetaDeployHistoryMapperTest.java
    • DataiMetaJobLogMapperTest.java
    • DataiMetaDeployComponentResultMapperTest.java

质疑与替代方案

记录在执行过程中提出的质疑和考虑的替代方案：

质疑 1: 是否需要使用外键约束？

  • 质疑: 在架构决策中，我们决定不使用外键约束，而是在应用层保证数据一致性。这是否合理？
  • 替代方案 1: 使用外键约束
    • 优点: 数据库层面保证数据一致性，级联删除自动执行
    • 缺点: 外键约束可能影响性能，增加数据库维护复杂度
    • 评估: 不推荐，因为现有项目表结构中也没有使用外键约束
  • 替代方案 2: 不使用外键约束（已选择）
    • 优点: 性能更好，灵活性更高，与现有项目保持一致
    • 缺点: 需要在应用层保证数据一致性
    • 评估: 推荐，因为与现有项目规范一致

质疑 2: 是否需要为每个表创建单独的 Mapper？

  • 质疑: MyBatis Plus 的 BaseMapper 已经提供了基本的 CRUD 操作，是否需要为每个表创建单独的 Mapper？
  • 替代方案 1: 创建单独的 Mapper（已选择）
    • 优点: 代码结构清晰，便于扩展自定义 SQL
    • 缺点: 需要创建 6 个 Mapper 接口
    • 评估: 推荐，符合 MyBatis Plus 最佳实践
  • 替代方案 2: 使用通用的 Mapper
    • 优点: 减少文件数量
    • 缺点: 代码可读性差，不便于扩展
    • 评估: 不推荐

质疑 3: 是否需要使用 Lombok？

  • 质疑: 提示词中使用了 Lombok 的 @Data 注解，是否需要引入 Lombok 依赖？
  • 替代方案 1: 使用 Lombok（已选择）
    • 优点: 减少样板代码，提高开发效率
    • 缺点: 需要引入额外依赖
    • 评估: 推荐，现有项目已使用 Lombok
  • 替代方案 2: 手动生成 getter/setter
    • 优点: 不需要额外依赖
    • 缺点: 代码冗长，维护成本高
    • 评估: 不推荐

结论

总结本次会话的结果，包括：

已完成的工作

  1. ✅ 完成了需求定义阶段（REQ-010-1 及 17 个子需求）
  2. ✅ 完成了架构决策阶段（0010-database-table-design.md）
  3. ✅ 完成了提示词资产化阶段（011-database-table-design-create.md）
  4. ✅ 创建了执行会话记录（本文档）

达成的目标

  1. ✅ 明确了数据库表结构设计和创建的需求
  2. ✅ 确定了技术栈（MyBatis Plus + MySQL）
  3. ✅ 设计了 6 个核心数据库表
  4. ✅ 定义了详细的代码生成提示词

后续的行动计划

  1. ⏳ 执行代码生成（使用 011-database-table-design-create.md 提示词）
  2. ⏳ 验证代码质量（代码审查、单元测试）
  3. ⏳ 完成验收标准（功能验证、性能验证、可靠性验证、安全性验证）
  4. ⏳ 进入阶段 5：变更记录与归档
  5. ⏳ 进入阶段 6：闭环复盘

需要跟进的事项

  1. ⏳ 生成 SQL 脚本并执行
  2. ⏳ 生成 Java 实体类并验证
  3. ⏳ 生成 Mapper 接口并验证
  4. ⏳ 生成单元测试并运行
  5. ⏳ 代码审查和优化

Design Update

  • 是否需要更新 Canvas?
    • Authentication.canvas
    • 其他 Canvas 文件: ____________________

说明: 本次会话主要涉及数据库表结构设计，不涉及 Canvas 架构变更，暂不需要更新 Canvas。

复现步骤

提供复现本次会话结果的具体步骤：

步骤 1: 准备工作

  1. 阅读 REQ-010-1.md 需求文档
  2. 阅读 0010-database-table-design.md 架构决策文档
  3. 阅读 011-database-table-design-create.md 提示词文档
  4. 阅读 datai_table.sql 现有表结构参考

步骤 2: 代码生成

  1. 加载 011-database-table-design-create.md 提示词
  2. 生成 6 个数据库表的 SQL 创建语句
  3. 生成 6 个对应的 Java 实体类
  4. 生成 6 个对应的 Mapper 接口
  5. 生成 Flyway 迁移脚本（V1.0.0__create_metadata_tables.sql）
  6. 生成单元测试代码

步骤 3: 验证代码

  1. 在测试环境中执行 SQL 脚本
  2. 验证表结构创建成功
  3. 编译 Java 代码
  4. 运行单元测试
  5. 验证测试通过

步骤 4: 代码审查

  1. 检查 SQL 语法正确性
  2. 检查 Java 代码规范性
  3. 检查 MyBatis Plus 注解使用正确性
  4. 检查单元测试覆盖率

验证方法

  1. 功能验证: 所有 6 个数据库表创建成功，实体类和 Mapper 接口正确
  2. 性能验证: 单表查询响应时间 < 100ms，批量插入 1000 条数据 < 1s
  3. 可靠性验证: 数据一致性得到保证，数据库迁移不丢失数据
  4. 安全性验证: 敏感字段加密存储，SQL 注入防护有效
  5. 代码规范性验证: 代码符合阿里巴巴 Java 开发规范，符合 MyBatis Plus 最佳实践

附录

A. 数据库表清单

表名 说明 字段数 索引数
datai_meta_org_config Salesforce 组织配置表 19 3
datai_meta_task 元数据任务定义表 12 3
datai_meta_job_execution 作业执行记录表 25 6
datai_meta_component 元数据组件表 12 4
datai_meta_deploy_history 部署历史表 18 5
datai_meta_job_log 作业日志表 11 4

B. 技术栈清单

组件 版本 说明
MyBatis Plus 3.x 持久层框架
MySQL 8.0+ 数据库
HikariCP - 连接池
Flyway - 数据库迁移
Redis - 缓存（可选）
Lombok - 简化代码
Java 17+ 编程语言
Spring Boot 3.x 应用框架

C. 命名规范清单

类型 命名规则 示例
表名 datai_meta_{table_name} datai_meta_org_config
实体类名 DataiMeta{ClassName} DataiMetaOrgConfig
Mapper 接口名 DataiMeta{ClassName}Mapper DataiMetaOrgConfigMapper
数据库字段名 {field_name} org_name
Java 字段名 {fieldName} orgName
包名 com.datai.salesforce.metadata.{package} com.datai.salesforce.metadata.entity

D. 基础字段清单

所有实体类必须包含以下基础字段：

@TableField("dept_id")
private Long deptId;

@TableField(value = "create_by", fill = FieldFill.INSERT)
private String createBy;

@TableField(value = "create_time", fill = FieldFill.INSERT)
private LocalDateTime createTime;

@TableField(value = "update_by", fill = FieldFill.INSERT_UPDATE)
private String updateBy;

@TableField(value = "update_time", fill = FieldFill.INSERT_UPDATE)
private LocalDateTime updateTime;

@TableField("remark")
private String remark;

E. MyBatis Plus 注解清单

注解 用途 必填 示例
@TableName 指定表名 是 @TableName("datai_meta_org_config")
@TableId 指定主键 是 @TableId(value = "id", type = IdType.AUTO)
@TableField 指定字段映射 是 @TableField("org_name")
@TableField(fill) 指定自动填充 否 @TableField(value = "create_by", fill = FieldFill.INSERT)
@Mapper 标记 Mapper 接口 是 @Mapper

F. Flyway 迁移脚本命名规范

版本 文件名 说明
1.0.0 V1.0.0__create_metadata_tables.sql 创建元数据管理相关的6个核心表

G. 验收标准清单

类别 标准 要求
功能完整性 所有 6 个数据库表创建成功 ✅
功能完整性 所有实体类包含所有字段，字段映射正确 ✅
功能完整性 所有 Mapper 接口继承 BaseMapper ✅
功能完整性 所有 Flyway 迁移脚本可执行 ✅
功能完整性 所有单元测试覆盖主要功能 ✅
代码正确性 SQL 语法正确，可以在 MySQL 中执行 ✅
代码正确性 Java 代码编译通过，无语法错误 ✅
代码正确性 MyBatis Plus 注解使用正确 ✅
代码正确性 单元测试可以执行，测试通过 ✅
文档准确性 代码注释完整，符合 JavaDoc 规范 ✅
文档准确性 字段注释与数据库表注释一致 ✅
文档准确性 类注释清晰描述类的用途 ✅
性能指标 单表查询响应时间 < 100ms ✅
性能指标 批量插入 1000 条数据 < 1s ✅
性能指标 支持并发查询，不出现死锁 ✅
代码规范性 代码符合阿里巴巴 Java 开发规范 ✅
代码规范性 代码符合 MyBatis Plus 最佳实践 ✅
代码规范性 代码符合项目编码规范 ✅
代码规范性 代码格式化正确，缩进一致 ✅

文档创建时间: 2026-01-17
文档创建人: AI Assistant
文档状态: 待执行代码生成