create-dp-koa 1.0.0

package/template/docs/NEW_ROUTER_USAGE_GUIDE.md

@@ -0,0 +1,364 @@
+# NewRouter 集成使用指南
+
+## 1. 快速开始
+
+### 1.1 环境配置
+
+在项目根目录创建环境配置文件：
+
+```bash
+# .env.development
+USE_NEW_ANNOTATION_SYSTEM=1
+
+# .env.production  
+USE_NEW_ANNOTATION_SYSTEM=0
+
+# .env.test
+USE_NEW_ANNOTATION_SYSTEM=1
+```
+
+### 1.2 应用启动
+
+新注解系统会在应用启动时自动初始化：
+
+```typescript
+// src/app.ts
+import { MigrationHelper } from "./framework/utils/MigrationHelper";
+
+setBeforeBootstrap(async function () {
+  // 自动初始化新注解处理器系统
+  MigrationHelper.initializeNewSystem();
+  
+  // 记录系统状态
+  const systemStatus = MigrationHelper.getSystemStatus();
+  logger.info(`注解系统状态: ${systemStatus.newSystemEnabled ? '新系统' : '旧系统'}`);
+  
+  // ... 其他初始化代码
+});
+```
+
+## 2. 控制器开发
+
+### 2.1 基础用法
+
+```typescript
+import { Get, Post, Query, Body } from '../../framework/decorator/controller';
+import { Logging, Permission, RateLimit } from '../../framework/decorator/processor/AnnotationDecorators';
+import { BaseController } from '../base.controller';
+
+export class MyController extends BaseController {
+    @Get('/data')
+    @Logging()
+    @Permission({ requiredPermission: 'read:data' })
+    @RateLimit({ maxRequests: 10, windowMs: 60000 })
+    async getData(@Query() query: any): Promise<any> {
+        return this.success({ data: 'example' });
+    }
+}
+```
+
+### 2.2 注解组合使用
+
+```typescript
+export class AdvancedController extends BaseController {
+    @Post('/submit')
+    @Logging() // 记录请求日志
+    @Permission({ requiredPermission: 'write:data' }) // 权限检查
+    @RateLimit({ maxRequests: 5, windowMs: 300000 }) // 限流：5分钟内最多5次
+    @ResponseCode(201) // 设置响应码
+    @ResponseHeader('X-Custom-Header', 'value') // 设置响应头
+    async submitData(@Body() body: any): Promise<any> {
+        // 业务逻辑
+        return this.success({ message: 'submitted' });
+    }
+}
+```
+
+### 2.3 新旧注解混合使用
+
+```typescript
+export class MixedController extends BaseController {
+    @Get('/legacy-compatible')
+    @Logging() // 新注解
+    @ResponseCode(200) // 旧注解
+    @ResponseHeader('X-Legacy', 'true') // 旧注解
+    async legacyCompatible(@Query() query: any): Promise<any> {
+        return this.success({ message: '兼容模式' });
+    }
+}
+```
+
+## 3. 自定义注解处理器
+
+### 3.1 创建自定义处理器
+
+```typescript
+// src/framework/decorator/processor/processors/CustomProcessors.ts
+import { AnnotationProcessor } from '../AnnotationProcessor';
+import { Context } from 'koa';
+
+export class CustomProcessor implements AnnotationProcessor {
+    readonly name = 'CustomProcessor';
+    readonly priority = 50;
+
+    async process(
+        ctx: Context,
+        controller: any,
+        methodName: string,
+        annotationData: any,
+        callParams: any[]
+    ): Promise<boolean> {
+        // 自定义处理逻辑
+        console.log(`执行自定义处理器: ${methodName}`);
+        
+        // 返回 true 继续执行，false 中断执行
+        return true;
+    }
+}
+```
+
+### 3.2 注册自定义处理器
+
+```typescript
+// src/framework/decorator/processor/ProcessorManager.ts
+import { CustomProcessor } from './processors/CustomProcessors';
+
+export class ProcessorManager {
+    static initialize() {
+        // 注册默认处理器
+        // ...
+        
+        // 注册自定义处理器
+        AnnotationExecutor.registerProcessor(new CustomProcessor());
+    }
+}
+```
+
+### 3.3 创建自定义注解装饰器
+
+```typescript
+// src/framework/decorator/processor/AnnotationDecorators.ts
+import { createAnnotationDecorator } from './AnnotationDecorators';
+
+export const CustomAnnotation = createAnnotationDecorator('CustomProcessor');
+```
+
+### 3.4 使用自定义注解
+
+```typescript
+export class MyController extends BaseController {
+    @Get('/custom')
+    @CustomAnnotation({ customData: 'value' })
+    async customMethod(): Promise<any> {
+        return this.success({ message: 'custom' });
+    }
+}
+```
+
+## 4. 系统管理
+
+### 4.1 检查系统状态
+
+```typescript
+import { MigrationHelper } from './framework/utils/MigrationHelper';
+
+// 获取系统状态
+const status = MigrationHelper.getSystemStatus();
+console.log('新系统启用:', status.newSystemEnabled);
+console.log('系统已初始化:', status.newSystemInitialized);
+console.log('当前环境:', status.environment);
+```
+
+### 4.2 切换注解系统
+
+```typescript
+// 启用新系统
+MigrationHelper.enableNewSystem();
+
+// 禁用新系统
+MigrationHelper.disableNewSystem();
+
+// 切换系统
+const isNewSystem = MigrationHelper.toggleSystem();
+```
+
+### 4.3 控制器兼容性检查
+
+```typescript
+// 检查单个控制器
+const compatibility = MigrationHelper.checkControllerCompatibility(controller);
+console.log('兼容性:', compatibility.compatible);
+console.log('问题:', compatibility.issues);
+console.log('建议:', compatibility.recommendations);
+
+// 生成迁移报告
+const report = MigrationHelper.generateMigrationReport(controllers);
+console.log('总控制器数:', report.total);
+console.log('旧系统控制器:', report.legacy);
+console.log('新系统控制器:', report.new);
+console.log('混合系统控制器:', report.mixed);
+```
+
+## 5. 测试
+
+### 5.1 单元测试
+
+```typescript
+import { TestDatabaseHelper } from '../utils/testHelpers';
+import { MigrationHelper } from '../../../src/framework/utils/MigrationHelper';
+
+describe('控制器测试', () => {
+    beforeAll(async () => {
+        await TestDatabaseHelper.initTestDatabase();
+        MigrationHelper.enableNewSystem();
+    });
+
+    test('应该能够执行控制器方法', async () => {
+        const controller = new MyController();
+        const result = await controller.getData({ id: '123' });
+        
+        expect(result.code).toBe(0);
+        expect(result.data).toBeDefined();
+    });
+});
+```
+
+### 5.2 集成测试
+
+```typescript
+describe('新注解系统集成测试', () => {
+    test('应该能够处理复合注解', async () => {
+        const controller = new AdvancedController();
+        const result = await controller.submitData({ name: 'test' });
+        
+        expect(result.code).toBe(0);
+        expect(result.data.message).toBe('submitted');
+    });
+});
+```
+
+## 6. 性能优化
+
+### 6.1 处理器优先级
+
+```typescript
+export class OptimizedProcessor implements AnnotationProcessor {
+    readonly name = 'OptimizedProcessor';
+    readonly priority = 10; // 较低优先级，在其他处理器之后执行
+
+    async process(): Promise<boolean> {
+        // 轻量级处理逻辑
+        return true;
+    }
+}
+```
+
+### 6.2 缓存优化
+
+```typescript
+export class CachedProcessor implements AnnotationProcessor {
+    private static cache = new Map();
+
+    async process(ctx: Context, controller: any, methodName: string, annotationData: any): Promise<boolean> {
+        const cacheKey = `${methodName}_${JSON.stringify(annotationData)}`;
+        
+        if (CachedProcessor.cache.has(cacheKey)) {
+            // 使用缓存结果
+            return CachedProcessor.cache.get(cacheKey);
+        }
+        
+        // 执行处理逻辑
+        const result = await this.executeLogic();
+        
+        // 缓存结果
+        CachedProcessor.cache.set(cacheKey, result);
+        
+        return result;
+    }
+}
+```
+
+## 7. 故障排除
+
+### 7.1 常见问题
+
+**问题1：注解处理器未执行**
+```typescript
+// 检查处理器是否注册
+const processor = ProcessorManager.getProcessor('ProcessorName');
+if (!processor) {
+    console.error('处理器未注册');
+}
+```
+
+**问题2：权限检查失败**
+```typescript
+// 检查用户权限
+const user = ctx.state.user;
+if (!user || !user.permissions) {
+    console.error('用户权限信息缺失');
+}
+```
+
+**问题3：限流不生效**
+```typescript
+// 检查限流配置
+const rateLimitData = { maxRequests: 10, windowMs: 60000 };
+// 确保 windowMs 大于 0
+```
+
+### 7.2 调试技巧
+
+```typescript
+// 启用详细日志
+process.env.LOG_LEVEL = 'debug';
+
+// 检查注解数据
+console.log('控制器注解:', controller.$_Annotations);
+
+// 检查处理器状态
+const allProcessors = ProcessorManager.getAllProcessors();
+console.log('已注册处理器:', allProcessors.map(p => p.name));
+```
+
+## 8. 最佳实践
+
+### 8.1 注解使用原则
+
+1. **单一职责**：每个注解处理器只负责一个功能
+2. **优先级合理**：根据执行顺序设置合适的优先级
+3. **性能考虑**：避免在处理器中执行耗时操作
+4. **错误处理**：处理器应该优雅地处理错误
+
+### 8.2 迁移策略
+
+1. **渐进式迁移**：先在新控制器中使用新注解
+2. **兼容性测试**：确保新旧系统可以共存
+3. **性能监控**：监控迁移过程中的性能变化
+4. **回滚准备**：准备快速回滚到旧系统的方案
+
+### 8.3 代码组织
+
+```typescript
+// 按功能分组注解处理器
+src/framework/decorator/processor/processors/
+├── DefaultProcessors.ts      // 默认处理器
+├── CustomProcessors.ts       // 自定义处理器
+├── SecurityProcessors.ts     // 安全相关处理器
+├── PerformanceProcessors.ts // 性能相关处理器
+└── BusinessProcessors.ts     // 业务相关处理器
+```
+
+## 9. 总结
+
+新注解处理器系统提供了：
+
+- **灵活性**：可以轻松创建自定义注解处理器
+- **可扩展性**：支持插件式的功能扩展
+- **兼容性**：与现有注解系统完全兼容
+- **性能**：优化的执行流程和缓存机制
+- **可维护性**：清晰的代码结构和职责分离
+
+通过合理使用新注解系统，可以显著提高代码的可读性、可维护性和可扩展性。
+
+

package/template/docs/QUICK_START.md

@@ -0,0 +1,268 @@
+# 快速开始指南
+
+本指南将帮助您在 5 分钟内快速启动 DP-Koa Framework 项目。
+
+## 🎯 目标
+
+通过本指南，您将能够：
+- 在本地环境中运行项目
+- 访问 Swagger API 文档
+- 运行基本的测试用例
+- 了解项目的基本结构
+
+## 📋 前置条件
+
+确保您的系统已安装：
+- Node.js 18.0.0 或更高版本
+- npm 8.0.0 或更高版本
+- Git
+
+### 检查版本
+
+```bash
+node --version  # 应该显示 v18.0.0 或更高
+npm --version   # 应该显示 8.0.0 或更高
+git --version   # 任何版本都可以
+```
+
+## 🚀 快速启动
+
+### 1. 克隆项目
+
+```bash
+git clone <your-repository-url>
+cd dp-koa-framework
+```
+
+### 2. 安装依赖
+
+```bash
+npm install
+```
+
+### 3. 配置环境变量
+
+```bash
+# 复制环境变量模板
+cp env.production.example .env
+
+# 编辑环境变量（可选，默认配置已足够用于快速开始）
+# 默认使用内存数据库模式，无需额外配置
+```
+
+### 4. 启动开发服务器
+
+```bash
+npm run dev
+```
+
+### 5. 验证启动
+
+打开浏览器访问：
+- **应用首页**: http://localhost:3000
+- **健康检查**: http://localhost:3000/health
+- **Swagger API 文档**: http://localhost:3000/swagger-ui
+
+## 🧪 运行测试
+
+### 运行所有测试
+
+```bash
+npm test
+```
+
+### 运行特定测试
+
+```bash
+# 运行框架测试
+npm run test:framework
+
+# 运行拦截器测试
+npm run test:interceptors
+
+# 运行服务层测试
+npm run test:service
+
+# 运行集成测试
+npm run test:integration
+```
+
+### 查看测试覆盖率
+
+```bash
+npm run test:coverage
+```
+
+## 📁 项目结构
+
+```
+dp-koa-framework/
+├── src/                    # 源代码目录
+│   ├── app.ts             # 应用入口文件
+│   ├── controllers/       # 控制器
+│   ├── service/          # 服务层
+│   ├── entity/           # 数据实体
+│   ├── framework/        # 框架核心
+│   │   ├── decorator/    # 装饰器系统
+│   │   ├── interceptors/ # 拦截器
+│   │   └── utils/        # 工具函数
+│   └── examples/         # 示例代码
+├── test/                 # 测试文件
+├── docs/                 # 文档
+├── docker/               # Docker 配置
+└── package.json          # 项目配置
+```
+
+## 🔧 常用命令
+
+### 开发命令
+
+```bash
+# 启动开发服务器（热重载）
+npm run dev
+
+# 构建生产版本
+npm run build
+
+# 启动生产服务器
+npm start
+
+# 类型检查
+npm run type-check
+
+# 代码检查
+npm run lint
+
+# 修复代码格式
+npm run lint:fix
+```
+
+### Docker 命令
+
+```bash
+# 构建 Docker 镜像
+npm run docker:build
+
+# 运行 Docker 容器
+npm run docker:run
+
+# 使用 Docker Compose 启动完整环境
+npm run docker:compose:up
+
+# 停止 Docker Compose 服务
+npm run docker:compose:down
+
+# 查看 Docker Compose 日志
+npm run docker:compose:logs
+```
+
+### 健康检查
+
+```bash
+# 检查应用健康状态
+npm run health:check
+
+# 检查监控指标
+npm run metrics:check
+```
+
+## 🌟 快速体验
+
+### 1. 查看 API 文档
+
+访问 http://localhost:3000/swagger-ui 查看 Swagger 文档，您可以：
+- 浏览所有可用的 API 端点
+- 在线测试 API 接口
+- 查看请求/响应示例
+
+### 2. 测试基本功能
+
+```bash
+# 测试健康检查端点
+curl http://localhost:3000/health
+
+# 测试用户相关 API
+curl http://localhost:3000/api/users
+
+# 测试商品相关 API
+curl http://localhost:3000/api/goods
+```
+
+### 3. 查看日志
+
+```bash
+# 查看应用日志
+tail -f logs/log.$(date +%Y-%m-%d).log
+
+# 查看错误日志
+tail -f logs/error.$(date +%Y-%m-%d).log
+
+# 查看性能日志
+tail -f logs/performance.$(date +%Y-%m-%d).log
+```
+
+## 🔍 故障排除
+
+### 常见问题
+
+#### 1. 端口被占用
+
+```bash
+# 检查端口占用
+netstat -tulpn | grep :3000
+
+# 杀死占用进程
+kill -9 <PID>
+```
+
+#### 2. 依赖安装失败
+
+```bash
+# 清理缓存
+npm cache clean --force
+
+# 删除 node_modules 重新安装
+rm -rf node_modules package-lock.json
+npm install
+```
+
+#### 3. 数据库连接问题
+
+项目默认使用内存数据库模式，无需额外配置。如果遇到数据库问题：
+
+```bash
+# 检查环境变量
+cat .env
+
+# 确保使用内存数据库模式
+echo "DB_TYPE=memory" >> .env
+```
+
+### 获取帮助
+
+如果遇到问题：
+1. 查看 [故障排除指南](TROUBLESHOOTING.md)
+2. 检查 [错误处理指南](ENTERPRISE_ERROR_HANDLING_GUIDE.md)
+3. 提交 [GitHub Issue](https://github.com/your-repo/issues)
+
+## 📚 下一步
+
+现在您已经成功启动了项目，建议您：
+
+1. **阅读开发指南**: [开发指南](DEVELOPMENT_GUIDE.md)
+2. **了解注解系统**: [注解系统指南](ENTERPRISE_ANNOTATION_SYSTEM_GUIDE.md)
+3. **学习服务层设计**: [服务层指南](SERVICE_PATTERN_GUIDE.md)
+4. **查看 API 文档**: [API 文档](API_DOCUMENTATION.md)
+
+## 🎉 恭喜！
+
+您已经成功完成了 DP-Koa Framework 的快速开始！现在可以开始您的开发之旅了。
+
+---
+
+**相关链接**:
+- [安装配置指南](INSTALLATION_GUIDE.md) - 详细安装步骤
+- [开发指南](DEVELOPMENT_GUIDE.md) - 开发规范和最佳实践
+- [故障排除指南](TROUBLESHOOTING.md) - 常见问题解决
+
+