# Database Development Workflow

This document outlines the recommended workflow for database schema changes and code generation in the peipei-backend project.

## Overview

The project uses a **Database-First** approach with the following flow:
```
Flyway Migration → Database Schema → Code Generator → Java Code
```

## Step-by-Step Workflow

### 1. Create Flyway Migration

Create a new migration file in `/play-admin/src/main/resources/db/migration/`:

```sql
-- V{version}__{description}.sql
-- Example: V2__add_new_feature_table.sql

CREATE TABLE `play_new_feature` (
  `id` varchar(32) NOT NULL COMMENT 'UUID',
  `feature_name` varchar(100) COMMENT '功能名称',
  `feature_type` varchar(20) DEFAULT NULL COMMENT '功能类型',
  `status` char(1) DEFAULT '0' COMMENT '状态(0正常 1停用)',
  `tenant_id` varchar(32) NOT NULL COMMENT '租户ID',
  `created_by` varchar(32) DEFAULT NULL COMMENT '创建人的id',
  `created_time` datetime DEFAULT NULL COMMENT '创建时间',
  `updated_by` varchar(32) DEFAULT NULL COMMENT '修改人的id', 
  `updated_time` datetime DEFAULT NULL COMMENT '修改时间',
  `deleted` tinyint(1) NOT NULL DEFAULT '0' COMMENT '逻辑删除',
  `version` int(11) NOT NULL DEFAULT '1' COMMENT '数据版本',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='新功能表';
```

**Migration Naming Convention:**
- `V{version}__{description}.sql`
- Version format: `V1.2025.0609.10.11` (timestamp-based)
- Description: snake_case with double underscore

### 2. Run Flyway Migration

Apply the migration to update database schema:

```bash
# Run from project root
mvn flyway:migrate

# Or check migration status
mvn flyway:info
```

### 3. Configure Code Generator

Edit `/play-generator/src/main/resources/config.properties`:

```properties
# Database configuration (should match main app)
db.url=jdbc:mysql://localhost:3306/play-with?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai
db.driver=com.mysql.cj.jdbc.Driver
db.username=root
db.password=your_password

# Code generation configuration
gen.author=your_name
gen.packageName=com.starry.admin
gen.outputDir=./generated-code
gen.autoRemovePre=false
gen.tablePrefix=play_
gen.tplCategory=crud

# Specify the new table(s) to generate
gen.tableNames=play_new_feature
```

### 4. Run Code Generator

Generate Java code from the new table structure:

```bash
cd play-generator
./run.sh
# Or manually: mvn clean compile exec:java
```

### 5. Review Generated Code

Check the generated files in `./generated-code/`:

```
generated-code/
├── src/main/java/com/starry/admin/
│   ├── entity/PlayNewFeatureEntity.java
│   ├── mapper/PlayNewFeatureMapper.java
│   ├── service/IPlayNewFeatureService.java
│   ├── service/impl/PlayNewFeatureServiceImpl.java
│   └── controller/PlayNewFeatureController.java
└── src/main/resources/mapper/PlayNewFeatureMapper.xml
```

### 6. Integrate Generated Code

Copy generated files to the appropriate module in play-admin:

```bash
# Create new module directory structure
mkdir -p play-admin/src/main/java/com/starry/admin/modules/newfeature/{controller,service,mapper,module/entity}

# Copy generated files to appropriate locations
cp generated-code/src/main/java/com/starry/admin/controller/* \
   play-admin/src/main/java/com/starry/admin/modules/newfeature/controller/

cp generated-code/src/main/java/com/starry/admin/service/* \
   play-admin/src/main/java/com/starry/admin/modules/newfeature/service/

cp generated-code/src/main/java/com/starry/admin/mapper/* \
   play-admin/src/main/java/com/starry/admin/modules/newfeature/mapper/

cp generated-code/src/main/java/com/starry/admin/entity/* \
   play-admin/src/main/java/com/starry/admin/modules/newfeature/module/entity/

cp generated-code/src/main/resources/mapper/* \
   play-admin/src/main/resources/mapper/newfeature/
```

### 7. Customize and Test

- **Review generated code** for any needed customizations
- **Add business logic** to Service implementations
- **Customize validation** in Controllers
- **Add custom queries** in Mapper if needed
- **Test the new endpoints** via Swagger UI
- **Run application** to ensure everything works

## Database Design Best Practices

### Table Naming Convention
- Use `play_` prefix for all tables
- Use snake_case for table names
- Example: `play_order_info`, `play_clerk_level_info`

### Required Standard Columns
All tables should include these standard columns:
```sql
`id` varchar(32) NOT NULL COMMENT 'UUID',
`tenant_id` varchar(32) NOT NULL COMMENT '租户ID',
`created_by` varchar(32) DEFAULT NULL COMMENT '创建人的id',
`created_time` datetime DEFAULT NULL COMMENT '创建时间',
`updated_by` varchar(32) DEFAULT NULL COMMENT '修改人的id',
`updated_time` datetime DEFAULT NULL COMMENT '修改时间',
`deleted` tinyint(1) NOT NULL DEFAULT '0' COMMENT '逻辑删除',
`version` int(11) NOT NULL DEFAULT '1' COMMENT '数据版本',
```

### Column Guidelines
- Always add meaningful `COMMENT` to columns
- Use appropriate data types (`varchar`, `int`, `decimal`, `datetime`)
- Set proper defaults where applicable
- Consider indexing for foreign keys and frequently queried columns

## Code Generation Notes

### What Gets Generated
- **Entity**: MyBatis Plus entity with Lombok annotations
- **Mapper**: Database access interface extending BaseMapper
- **Service**: Business logic interface with standard CRUD operations
- **ServiceImpl**: Service implementation with basic CRUD logic
- **Controller**: REST API endpoints with Swagger documentation
- **Mapper XML**: MyBatis SQL mapping files

### Generated Code Features
- Swagger API documentation
- Spring Security integration (`@PreAuthorize`)
- Audit logging (`@Log`)
- Input validation
- Pagination support
- Logical deletion support
- Multi-tenant support

## Troubleshooting

### Common Issues

**Migration Fails**:
- Check database connection settings
- Verify migration SQL syntax
- Ensure proper permissions

**Generator Fails**:
- Verify database connection in config.properties
- Check if table exists after migration
- Ensure table follows naming conventions

**Generated Code Issues**:
- Review column comments (used for Java doc)
- Check data type mappings
- Verify package naming in config

### Database Type Mappings

| MySQL Type | Java Type | Notes |
|------------|-----------|-------|
| `varchar(n)` | `String` | |
| `int`, `bigint` | `Integer`, `Long` | |
| `decimal(p,s)` | `BigDecimal` | Precise decimal calculations |
| `datetime` | `Date` | Or `LocalDateTime` |
| `tinyint(1)` | `Boolean` | For flags/status |
| `char(1)` | `String` | For status codes |

## Tips

1. **Always create migration first**, then generate code
2. **Use descriptive table and column names** - they become class and field names
3. **Test migrations on dev environment** before applying to production
4. **Review generated code** before committing - customize as needed
5. **Follow existing module patterns** when organizing generated code
6. **Backup database** before running migrations in production