create-dp-koa 1.0.0

package/template/docs/ENTERPRISE_DATABASE_ARCHITECTURE.md

@@ -0,0 +1,318 @@
+# 企业级数据库架构重构文档
+
+## 📋 概述
+
+本文档描述了基于企业级标准的数据库架构重构，实现了更好的分层、解耦和可维护性。
+
+## 🏗️ 架构层次
+
+### 1. 实体层 (Entity Layer)
+- **位置**: `src/entity/`
+- **职责**: 定义数据模型和实体关系
+- **特点**: 
+  - 继承 `BaseEntity` 提供统一基础字段
+  - 使用 TypeORM 装饰器定义关系
+  - 支持外键约束和索引优化
+
+### 2. Repository 层
+- **位置**: `src/repository/`
+- **职责**: 数据访问抽象和封装
+- **特点**:
+  - 接口与实现分离 (`IBaseRepository`, `BaseRepository`)
+  - 提供通用的 CRUD 操作
+  - 支持复杂查询和业务逻辑
+
+### 3. DTO 验证层
+- **位置**: `src/dto/`
+- **职责**: 数据传输对象和验证
+- **特点**:
+  - 使用 `class-validator` 进行数据验证
+  - 支持创建、更新、查询等不同场景的 DTO
+  - 提供详细的错误信息
+
+### 4. 服务层 (Service Layer)
+- **位置**: `src/service/`
+- **职责**: 业务逻辑处理
+- **特点**:
+  - 使用 Repository 模式进行数据访问
+  - 集成事务管理
+  - 支持 DTO 验证和错误处理
+
+### 5. 控制器层 (Controller Layer)
+- **位置**: `src/controllers/`
+- **职责**: HTTP 请求处理和响应
+- **特点**:
+  - 使用装饰器进行缓存管理
+  - 统一的响应格式
+  - 完整的错误处理
+
+## 🔧 核心组件
+
+### 1. 事务管理器 (`TransactionManager`)
+```typescript
+// 使用示例
+await transactionManager.executeInTransaction(async (manager) => {
+    // 业务逻辑
+    await userRepository.save(user);
+    await orderRepository.save(order);
+});
+```
+
+**特性**:
+- 支持不同隔离级别
+- 嵌套事务支持
+- 只读事务优化
+- 批量操作事务
+
+### 2. 缓存管理器 (`CacheManager`)
+```typescript
+// 使用示例
+@Cacheable({ ttl: 300 })
+async getUserById(id: number) {
+    return await this.userRepository.findById(id);
+}
+
+@CacheEvict({ keys: ['user:${id}'] })
+async updateUser(id: number, data: any) {
+    // 更新逻辑
+}
+```
+
+**特性**:
+- 支持内存缓存和 Redis 缓存
+- 装饰器模式简化使用
+- 自动缓存键生成
+- 批量缓存操作
+
+### 3. DTO 验证器 (`DtoValidator`)
+```typescript
+// 使用示例
+const validation = await DtoValidator.validateAndTransform(CreateUserDto, data);
+if (!validation.isValid) {
+    return new CommonServiceResult(VALIDATION_ERROR, null, validation.errors.join(', '));
+}
+```
+
+**特性**:
+- 自动类型转换
+- 详细的错误信息
+- 批量验证支持
+- 白名单过滤
+
+### 4. 迁移管理器 (`MigrationManager`)
+```typescript
+// 使用示例
+// 生产环境自动执行迁移
+if (process.env.NODE_ENV === 'production') {
+    await migrationManager.runMigrations();
+}
+```
+
+**特性**:
+- 环境特定配置
+- 自动迁移执行
+- 迁移状态监控
+- 数据库备份支持
+
+## 📊 数据库设计
+
+### 实体关系图
+```
+YtUserEntity (1) ←→ (1) ShopAndUserEntity (1) ←→ (1) ShopEntity
+     ↓ (1)                    ↓ (1)
+     ↓ (N)                    ↓ (N)
+YtGoodsUnlockerEntity    YtGoodsEntity
+     ↓ (1)                    ↓ (1)
+     ↓ (N)                    ↓ (N)
+YtGoodsEntity        GoodsImagesUnlockKeyEntity
+```
+
+### 外键约束
+- `shop_and_user.shopId` → `shop.id`
+- `shop_and_user.userId` → `yt_user.id`
+- `yt_goods.shopId` → `shop.id`
+- `yt_goods_unlock.goodsId` → `yt_goods.id`
+- `yt_goods_unlock.ytUserId` → `yt_user.id`
+- `goods_images_unlock_key.goodsId` → `yt_goods.id`
+
+## 🚀 使用指南
+
+### 1. 创建新的实体
+```typescript
+@Entity({ name: "new_entity" })
+export class NewEntity extends BaseEntity {
+    @Column({ default: "" })
+    name: string;
+    
+    @ManyToOne(() => YtUserEntity, user => user.relations)
+    @JoinColumn({ name: 'userId' })
+    user: YtUserEntity;
+}
+```
+
+### 2. 创建 Repository
+```typescript
+export interface INewEntityRepository extends IBaseRepository<NewEntity> {
+    findByUserId(userId: number): Promise<NewEntity[]>;
+}
+
+export class NewEntityRepository extends BaseRepository<NewEntity> implements INewEntityRepository {
+    async findByUserId(userId: number): Promise<NewEntity[]> {
+        return await this.repository.find({ where: { userId } });
+    }
+}
+```
+
+### 3. 创建 DTO
+```typescript
+export class CreateNewEntityDto {
+    @IsNotEmpty({ message: '名称不能为空' })
+    @IsString({ message: '名称必须是字符串' })
+    name: string;
+    
+    @IsNotEmpty({ message: '用户ID不能为空' })
+    @IsInt({ message: '用户ID必须是整数' })
+    userId: number;
+}
+```
+
+### 4. 创建服务
+```typescript
+@Injectable()
+export class NewEntityService {
+    private repository: INewEntityRepository;
+    
+    async createEntity(dto: CreateNewEntityDto): Promise<CommonServiceResult<NewEntity>> {
+        const validation = await DtoValidator.validateAndTransform(CreateNewEntityDto, dto);
+        if (!validation.isValid) {
+            return new CommonServiceResult(VALIDATION_ERROR, null, validation.errors.join(', '));
+        }
+        
+        const entity = await transactionManager.executeInTransaction(async (manager) => {
+            return await this.repository.save(validation.data);
+        });
+        
+        return new CommonServiceResult(SUCCESS, entity, "创建成功");
+    }
+}
+```
+
+### 5. 创建控制器
+```typescript
+@Controller('/api/v1/new-entities')
+export class NewEntityController extends BaseController {
+    @Post('/')
+    @CacheEvict({ keys: ['new-entity:list'] })
+    async createEntity(@Body() dto: CreateNewEntityDto) {
+        const result = await this.newEntityService.createEntity(dto);
+        return result.code === 'SUCCESS' ? this.success(result.data) : this.fail(400, result.message);
+    }
+    
+    @Get('/')
+    @Cacheable({ ttl: 60 })
+    async getEntities(@Query() query: QueryNewEntityDto) {
+        const result = await this.newEntityService.getEntities(query);
+        return this.success(result.data);
+    }
+}
+```
+
+## 🔒 安全特性
+
+### 1. 数据验证
+- 输入数据验证和清理
+- SQL 注入防护
+- XSS 攻击防护
+
+### 2. 事务安全
+- ACID 特性保证
+- 死锁检测和处理
+- 连接池管理
+
+### 3. 缓存安全
+- 缓存键命名规范
+- 敏感数据不缓存
+- 缓存过期策略
+
+## 📈 性能优化
+
+### 1. 数据库优化
+- 索引优化
+- 查询优化
+- 连接池配置
+
+### 2. 缓存优化
+- 多级缓存策略
+- 缓存预热
+- 缓存穿透防护
+
+### 3. 事务优化
+- 只读事务
+- 批量操作
+- 嵌套事务
+
+## 🧪 测试策略
+
+### 1. 单元测试
+- Repository 层测试
+- Service 层测试
+- DTO 验证测试
+
+### 2. 集成测试
+- 数据库集成测试
+- 事务测试
+- 缓存测试
+
+### 3. 性能测试
+- 并发测试
+- 压力测试
+- 缓存性能测试
+
+## 📝 最佳实践
+
+### 1. 代码规范
+- 使用 TypeScript 严格模式
+- 遵循 SOLID 原则
+- 统一的错误处理
+
+### 2. 数据库规范
+- 命名规范统一
+- 索引策略合理
+- 外键约束完整
+
+### 3. 缓存规范
+- 缓存键命名规范
+- TTL 设置合理
+- 缓存失效策略
+
+## 🔄 迁移指南
+
+### 从旧架构迁移
+1. 逐步替换 Service 层使用 Repository
+2. 添加 DTO 验证
+3. 集成事务管理
+4. 添加缓存策略
+5. 执行数据库迁移
+
+### 环境配置
+```bash
+# 开发环境
+NODE_ENV=development
+CACHE_TYPE=memory
+
+# 生产环境
+NODE_ENV=production
+CACHE_TYPE=redis
+REDIS_HOST=localhost
+REDIS_PORT=6379
+```
+
+## 📚 相关文档
+
+- [Repository 模式详解](./docs/REPOSITORY_PATTERN.md)
+- [事务管理指南](./docs/TRANSACTION_GUIDE.md)
+- [缓存策略说明](./docs/CACHE_STRATEGY.md)
+- [DTO 验证规范](./docs/DTO_VALIDATION.md)
+- [数据库迁移指南](./docs/MIGRATION_GUIDE.md)
+
+