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

---
name: entity-db-sync
description: 确保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/        # 开发代码目录（保持独立）
```

#### 变更脚本命名规范
```bash
# 格式：YYYYMMDD_description.sql
20240115_add_user_phone.sql                    # 正向变更
20240115_add_user_phone_rollback.sql           # 回滚脚本
20240115_add_user_phone_verify.sql             # 验证脚本
```

#### 脚本内容模板
```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;
```

#### 回滚脚本模板
```sql
-- ============================================
-- 回滚描述: 撤销用户表手机号字段添加
-- 回滚时间: 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. 提交变更包
```

### 自动化工具集成

#### 变更脚本生成器
```python
# 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
```

#### 文档同步检查器
```bash
#!/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. 生产环境部署
```bash
# 生产环境变更部署流程
1. 备份数据库
2. 执行变更脚本
3. 验证数据一致性
4. 功能测试
5. 监控观察
6. 准备回滚方案
```

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

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