peipei-backend/db_workflow.md

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/:

-- 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:

# 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:

# 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:

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:

# 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:

`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