create-dp-koa 1.0.0

package/template/docs/ARCHITECTURE_REFACTOR.md

@@ -0,0 +1,109 @@
+# 项目架构重构说明
+
+## 📁 目录结构优化
+
+### 框架级别 (`src/framework/`)
+**职责**: 提供通用的框架功能，不依赖具体业务逻辑
+
+
+```
+src/framework/
+├── decorator/          # 装饰器（控制器、参数等）
+├── utils/             # 框架工具类
+│   ├── bootstrap.ts   # 应用启动框架
+│   ├── cache.ts       # 统一缓存管理
+│   ├── db.ts          # 数据库连接管理
+│   ├── dbMonitor.ts   # 数据库监控
+│   ├── databaseConfig.ts  # 数据库配置管理 ⭐ 新增
+│   ├── function.ts    # 通用函数
+│   ├── logger.ts      # 日志工具
+│   ├── router.ts      # 路由框架
+│   └── token.ts       # Token工具
+└── ...
+```
+
+### 业务级别 (`src/`)
+**职责**: 包含具体的业务逻辑和实体依赖
+
+```
+src/
+├── controllers/       # 控制器（业务逻辑）
+├── entity/           # 数据实体
+├── service/          # 业务服务
+├── dto/              # 数据传输对象
+├── libs/             # 业务库
+├── middlewares/      # 中间件
+├── routers/          # 路由配置
+└── utils/            # 业务工具类 ⭐ 新增
+    └── testDataInitializer.ts  # 测试数据初始化
+```
+
+## 🔧 重构内容
+
+### 1. **数据库配置管理** (`src/framework/utils/databaseConfig.ts`)
+- ✅ **框架级别**: 纯配置管理，无业务依赖
+- ✅ **职责单一**: 只负责数据库模式切换和配置生成
+- ✅ **环境检测**: 自动检测内存数据库/MySQL模式
+- ✅ **配置生成**: 根据模式生成对应的DataSourceOptions
+
+### 2. **测试数据初始化** (`src/utils/testDataInitializer.ts`)
+- ✅ **业务级别**: 包含具体实体依赖
+- ✅ **职责明确**: 专门处理测试数据创建和管理
+- ✅ **模式检测**: 只在内存数据库模式下工作
+- ✅ **数据管理**: 提供完整的CRUD操作
+
+### 3. **应用启动优化** (`src/app.ts`)
+- ✅ **配置解耦**: 使用DatabaseConfigManager管理配置
+- ✅ **逻辑清晰**: 分离配置管理和业务逻辑
+- ✅ **监控优化**: 根据数据库类型决定是否启用监控
+
+## 🎯 架构优势
+
+### 1. **职责分离**
+- **框架层**: 提供通用功能，无业务依赖
+- **业务层**: 处理具体业务逻辑，可依赖实体
+
+### 2. **可维护性**
+- **配置集中**: 数据库配置统一管理
+- **逻辑清晰**: 各模块职责明确
+- **易于扩展**: 新增数据库类型只需修改配置管理器
+
+### 3. **可测试性**
+- **框架独立**: 框架功能可独立测试
+- **业务隔离**: 业务逻辑与框架解耦
+- **数据管理**: 测试数据工具独立管理
+
+## 📋 使用方式
+
+### 环境配置
+```bash
+# .env.development
+db_enable=1
+db_memory=1  # 启用内存数据库模式
+```
+
+### 数据库模式切换
+```typescript
+// 框架自动检测环境变量
+// db_memory=1 -> 内存数据库模式
+// db_memory=0 -> MySQL数据库模式
+```
+
+### 测试数据管理
+```bash
+# 查看测试数据状态
+GET /test/test-data/status
+
+# 重新初始化测试数据
+POST /test/test-data/reset
+```
+
+## 🔄 迁移完成
+
+- ✅ **删除**: `src/framework/utils/testDataInitializer.ts`
+- ✅ **新增**: `src/utils/testDataInitializer.ts`
+- ✅ **新增**: `src/framework/utils/databaseConfig.ts`
+- ✅ **更新**: `src/app.ts` - 使用新的配置管理器
+- ✅ **更新**: `src/controllers/testData.controller.ts` - 更新导入路径
+
+现在项目架构更加合理，框架层和业务层职责分离明确！

package/template/docs/CACHE_MIGRATION_GUIDE.md

@@ -0,0 +1,142 @@
+# 统一缓存管理系统使用说明
+
+## 📋 概述
+
+本项目已全面升级为统一的缓存管理系统，所有缓存都使用相同的配置参数和监控机制，有效防止访问量暴增导致的内存过大问题。
+
+## 🔧 已更新的文件
+
+### 1. 核心缓存管理
+- ✅ `src/framework/utils/cache.ts` - 统一缓存管理器
+- ✅ `src/framework/utils/router.ts` - 控制器结果缓存
+- ✅ `src/libs/mCache.ts` - 用户缓存
+
+### 2. 控制器更新
+- ✅ `src/controllers/home/ytUser.controller.ts` - 用户信息缓存
+- ✅ `src/controllers/home/ytShop.controller.ts` - 店铺用户缓存
+- ✅ `src/controllers/captcha.controller.ts` - 验证码缓存（新增防重复验证）
+
+### 3. 监控和管理
+- ✅ `src/controllers/health.controller.ts` - 健康检查（包含缓存监控）
+- ✅ `src/controllers/cacheManagement.controller.ts` - 缓存管理工具
+- ✅ `src/app.ts` - 优雅关闭（包含缓存清理）
+
+## 🚀 使用方法
+
+### 创建缓存
+```typescript
+import { createCache, CacheType } from '@src/framework/utils/cache';
+
+// 使用预定义类型
+const userCache = createCache('user-cache', CacheType.USER);
+
+// 自定义配置
+const customCache = createCache('custom', CacheType.TEMP, {
+    stdTTL: 60,
+    maxKeys: 500
+});
+```
+
+### 缓存操作
+```typescript
+// 设置缓存
+cache.set(key, value, ttl); // ttl 可选，使用默认值
+
+// 获取缓存
+const value = cache.get(key);
+
+// 删除缓存
+cache.del(key);
+
+// 清空所有缓存
+cache.flushAll();
+```
+
+## 📊 监控端点
+
+### 健康检查
+- `GET /health` - 完整系统状态（包含缓存信息）
+- `GET /health/cache` - 专门的缓存健康检查
+
+### 缓存管理
+- `GET /admin/cache/stats` - 获取所有缓存统计信息
+- `POST /admin/cache/clear` - 清理指定缓存
+- `POST /admin/cache/delete` - 删除缓存实例
+- `POST /admin/cache/clear-all` - 清理所有缓存
+- `GET /admin/cache/info` - 获取特定缓存详细信息
+
+## 🛡️ 安全特性
+
+### 1. 内存保护
+- 每个缓存都有最大条目数限制
+- 自动过期清理机制
+- 实时使用率监控
+
+### 2. 防重复验证
+验证码控制器新增防重复验证功能：
+```typescript
+// 验证成功后标记为已使用
+captchaCache.set(verifyKey, true, 300); // 5分钟内不能重复验证
+```
+
+### 3. 优雅关闭
+应用关闭时自动清理所有缓存，防止内存泄露。
+
+## 📈 缓存类型配置
+
+| 类型 | 默认TTL | 最大条目 | 用途 |
+|------|---------|----------|------|
+| USER | 30分钟 | 500 | 用户信息缓存 |
+| CONTROLLER | 1分钟 | 2000 | 控制器结果缓存 |
+| SESSION | 1小时 | 1000 | 会话缓存 |
+| CAPTCHA | 5分钟 | 100 | 验证码缓存 |
+| TEMP | 1分钟 | 100 | 临时缓存 |
+
+## 🔍 监控信息示例
+
+### 缓存统计
+```json
+{
+  "yt-user-controller": {
+    "hits": 150,
+    "misses": 25,
+    "keys": 45,
+    "hitRate": "85.71%"
+  }
+}
+```
+
+### 内存使用
+```json
+{
+  "yt-user-controller": {
+    "keyCount": 45,
+    "maxKeys": 500,
+    "usage": "9.00%"
+  }
+}
+```
+
+## ⚠️ 注意事项
+
+1. **缓存键命名**: 使用有意义的键名，避免冲突
+2. **过期时间**: 根据业务需求设置合适的TTL
+3. **内存监控**: 定期检查缓存使用率，避免超过80%
+4. **错误处理**: 缓存操作失败时要有降级方案
+
+## 🎯 最佳实践
+
+1. **分层缓存**: 不同类型数据使用不同缓存类型
+2. **缓存预热**: 系统启动时预加载热点数据
+3. **监控告警**: 设置缓存使用率告警
+4. **定期清理**: 定期清理过期和无用缓存
+
+## 🔄 迁移完成
+
+所有原有的缓存使用已成功迁移到新的统一管理系统：
+- ✅ 用户信息缓存
+- ✅ 店铺用户缓存  
+- ✅ 控制器结果缓存
+- ✅ 验证码缓存（新增功能）
+
+系统现在具备了完整的缓存管理能力，可以有效防止内存泄露问题！