fundplatform/.qoder/skills/entity-db-sync/SKILL.md

name, description

name	description
entity-db-sync	确保Java实体类与数据库SQL脚本同步的技能，当修改实体类字段时自动检查并更新对应的数据库初始化脚本，保证表结构与实体定义严格一致。使用场景：修改实体类属性、添加字段、删除字段、字段类型变更时自动触发。实践要求：同步更新设计文档中的数据表信息，独立目录保存变更脚本便于生产环境更新。

实体类与数据库脚本同步技能

触发条件

当出现以下情况时自动应用此技能：

1. 实体类修改相关：

   • 修改Java实体类的字段定义
   • 添加新的实体类字段
   • 删除实体类字段
   • 修改字段的数据类型或注解

2. 数据库脚本相关：

   • 需要更新数据库初始化SQL脚本
   • 需要创建新的表结构SQL
   • 需要修改现有表的字段定义

3. 同步检查相关：

   • 需要验证实体类与数据库脚本的一致性
   • 需要生成差异报告
   • 需要修复不一致的地方

4. 文档维护相关：

   • 需要同步更新设计文档中的表结构信息
   • 需要生成数据库变更脚本
   • 需要维护生产环境更新包

核心原则

同步规范

• 一对一映射：每个实体类字段必须对应数据库表中的列
• 类型匹配：Java数据类型与MySQL数据类型必须兼容
• 约束一致：非空约束、长度限制等必须保持一致
• 注解驱动：基于JPA/Hibernate注解生成SQL定义

文档同步规范

• 设计文档更新：实体类变更时同步更新相关设计文档
• 变更脚本管理：独立目录保存数据库变更脚本
• 版本控制：维护清晰的变更历史和版本信息

生产环境部署规范

• 变更脚本独立存储：便于生产环境按需执行
• 回滚方案准备：每个变更都提供回滚脚本
• 影响评估：评估变更对现有数据的影响

实践要求

1. 设计文档同步更新

需要维护的文档类型

• 数据库设计文档：表结构定义、字段说明、约束条件
• API接口文档：涉及数据模型变更的接口说明
• 业务流程文档：受数据结构影响的业务逻辑说明

文档更新流程

1. 实体类修改 → 2. 生成SQL变更脚本 → 3. 更新设计文档 → 4. 验证一致性

文档更新检查清单

• 数据库表结构调整说明
• 字段新增/删除/修改记录
• 约束条件变更说明
• 索引变更记录
• 业务影响评估

2. 变更脚本管理

目录结构规范

project/
├── change/                    # 部署相关文件（与开发代码分离）
│   └── sql/
│       ├── init/              # 初始化脚本（首次部署）
│       │   ├── user.sql
│       │   ├── order.sql
│       │   └── product.sql
│       └── upgrade/           # 升级脚本（版本变更）
│           ├── v1.1.0/
│           │   ├── 20240115_add_user_phone.sql
│           │   ├── 20240115_modify_order_amount_precision.sql
│           │   └── rollback/
│           │       ├── 20240115_add_user_phone_rollback.sql
│           └── v1.2.0/
│               └── 20240201_add_product_category.sql
└── src/main/resources/        # 开发代码目录（保持独立）

变更脚本命名规范

# 格式：YYYYMMDD_description.sql
20240115_add_user_phone.sql                    # 正向变更
20240115_add_user_phone_rollback.sql           # 回滚脚本
20240115_add_user_phone_verify.sql             # 验证脚本

脚本内容模板

-- ============================================
-- 变更描述: 为用户表添加手机号字段
-- 变更时间: 2024-01-15
-- 影响版本: v1.1.0
-- 影响表: user
-- ============================================

-- 1. 添加字段
ALTER TABLE `user` 
ADD COLUMN `phone` VARCHAR(20) COMMENT '手机号码';

-- 2. 添加索引
ALTER TABLE `user` 
ADD INDEX `idx_phone` (`phone`);

-- 3. 更新现有数据（如有必要）
UPDATE `user` SET `phone` = '' WHERE `phone` IS NULL;

-- 4. 验证变更
SELECT COUNT(*) as phone_count FROM `user` WHERE `phone` IS NOT NULL;

回滚脚本模板

-- ============================================
-- 回滚描述: 撤销用户表手机号字段添加
-- 回滚时间: 20240115
-- 原变更: 20240115_add_user_phone.sql
-- ============================================

-- 1. 删除索引
ALTER TABLE `user` DROP INDEX `idx_phone`;

-- 2. 删除字段
ALTER TABLE `user` DROP COLUMN `phone`;

-- 3. 验证回滚
SELECT COUNT(*) as remaining_indexes 
FROM information_schema.STATISTICS 
WHERE TABLE_NAME = 'user' AND COLUMN_NAME = 'phone';

工作流程

完整同步流程

1. 实体类修改
   ↓
2. 生成差异报告
   ↓
3. 编写变更脚本
   ↓
4. 更新初始化脚本
   ↓
5. 同步设计文档
   ↓
6. 验证一致性
   ↓
7. 提交变更包

自动化工具集成

变更脚本生成器

# generate-change-script.py
import datetime
import os

def create_change_script(table_name, changes, version):
    """生成标准变更脚本"""
    today = datetime.date.today().strftime('%Y%m%d')
    timestamp = datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')
    
    # 部署目录结构
    change_dir = "change/sql/upgrade"
    version_dir = f"{change_dir}/{version}"
    rollback_dir = f"{version_dir}/rollback"
    
    # 创建目录
    os.makedirs(version_dir, exist_ok=True)
    os.makedirs(rollback_dir, exist_ok=True)
    
    script_content = f"""-- ============================================
-- 变更描述: {changes['description']}
-- 变更时间: {timestamp}
-- 影响版本: {version}
-- 影响表: {table_name}
-- ============================================

"""
    
    # 添加具体的SQL变更
    for change_type, change_detail in changes.items():
        if change_type == 'add_columns':
            for column in change_detail:
                script_content += f"ALTER TABLE `{table_name}` ADD COLUMN {column};\n"
        
        elif change_type == 'modify_columns':
            for column in change_detail:
                script_content += f"ALTER TABLE `{table_name}` MODIFY COLUMN {column};\n"
    
    # 保存脚本
    filename = f"{today}_{changes['description'].replace(' ', '_').lower()}.sql"
    filepath = f"{version_dir}/{filename}"
    
    with open(filepath, 'w', encoding='utf-8') as f:
        f.write(script_content)
    
    return filepath

文档同步检查器

#!/bin/bash
# sync-documentation.sh

ENTITY_FILE=$1
CHANGE_SCRIPT=$2

echo "=== 同步设计文档 ==="

# 提取变更信息
TABLE_NAME=$(grep -o '@Table(name = "[^"]*")' "$ENTITY_FILE" | cut -d'"' -f2)
CHANGE_DESC=$(basename "$CHANGE_SCRIPT" .sql | cut -d'_' -f2-)

# 更新数据库设计文档到change目录
echo "更新数据库设计文档..."
DOC_DIR="change/docs/database"
mkdir -p "$DOC_DIR"

# 生成变更说明文档
cat > "${DOC_DIR}/${TABLE_NAME}_change_${CHANGE_DESC}.md" << EOF
# ${TABLE_NAME} 表结构变更说明

## 变更概述
- 变更时间: $(date '+%Y-%m-%d')
- 变更类型: 字段添加/修改/删除
- 影响范围: ${TABLE_NAME} 表

## 详细变更
$(cat "$CHANGE_SCRIPT")

## 业务影响
- [ ] API接口适配
- [ ] 前端页面调整
- [ ] 数据迁移需求
- [ ] 测试用例更新

## 验证清单
- [ ] 开发环境验证
- [ ] 测试环境验证
- [ ] 生产环境预演
EOF

echo "文档同步完成: ${DOC_DIR}/${TABLE_NAME}_change_${CHANGE_DESC}.md"

最佳实践

1. 变更管理

版本分支 → 开发变更 → 生成脚本 → 文档同步 → 测试验证 → 合并发布

2. 生产环境部署

# 生产环境变更部署流程
1. 备份数据库
2. 执行变更脚本
3. 验证数据一致性
4. 功能测试
5. 监控观察
6. 准备回滚方案

3. 团队协作规范

• 实体类修改必须附带变更脚本
• 变更前必须进行影响评估
• 多人协作时建立变更协调机制
• 定期审查变更历史和文档同步情况

这个增强版的技能不仅确保实体类与数据库脚本的技术同步，还建立了完整的文档维护和生产环境变更管理流程。