create-dp-koa 1.0.0

package/template/.trae/documents/controller_development_plan.md

@@ -0,0 +1,386 @@
+# 控制器（Controller）开发计划
+
+## 项目结构分析
+
+* **控制器目录**：`src/controllers/`
+
+* **基础控制器**：`base.controller.ts`
+
+* **示例控制器**：位于 `example/`、`home/`、`public/` 等子目录
+
+* **装饰器系统**：`framework/decorator/` 目录下的装饰器
+
+## 开发步骤
+
+### \[ ] 步骤 1：创建控制器文件
+
+* **优先级**：P0
+
+* **依赖**：无
+
+* **描述**：
+
+  * 在 `src/controllers/` 目录下创建新的控制器文件
+
+  * 可以创建子目录来组织控制器
+
+  * 文件名使用 `controller.ts` 后缀
+
+* **成功标准**：
+
+  * 控制器文件创建成功
+
+  * 文件结构符合项目规范
+
+* **测试要求**：
+
+  * `programmatic` TR-1.1：文件存在且格式正确
+
+  * `human-judgement` TR-1.2：文件命名规范，目录结构合理
+
+### \[ ] 步骤 2：继承基础控制器
+
+* **优先级**：P0
+
+* **依赖**：步骤 1
+
+* **描述**：
+
+  * 导入 `BaseController` 和 `ControllerResponse`
+
+  * 创建控制器类并继承 `BaseController`
+
+* **成功标准**：
+
+  * 控制器类正确继承 `BaseController`
+
+  * 可以使用 `success` 和 `fail` 方法
+
+* **测试要求**：
+
+  * `programmatic` TR-2.1：代码编译通过
+
+  * `human-judgement` TR-2.2：继承关系正确
+
+### \[ ] 步骤 3：注入服务（如果需要）
+
+* **优先级**：P0
+
+* **依赖**：步骤 2
+
+* **描述**：
+
+  * 导入 `Inject` 装饰器
+
+  * 使用 `@Inject` 注入需要的服务
+
+* **成功标准**：
+
+  * 服务注入正确
+
+  * 可以在控制器中使用服务
+
+* **测试要求**：
+
+  * `programmatic` TR-3.1：代码编译通过
+
+  * `human-judgement` TR-3.2：依赖注入配置正确
+
+### \[ ] 步骤 4：定义路由
+
+* **优先级**：P0
+
+* **依赖**：步骤 3
+
+* **描述**：
+
+  * 导入路由装饰器（`Get`、`Post`、`Put`、`Del`、`All`）
+
+  * 使用装饰器定义路由路径
+
+  * 为需要的接口添加 `@ResponseCode` 装饰器设置 HTTP 状态码
+
+* **成功标准**：
+
+  * 路由装饰器使用正确
+
+  * 路由路径格式规范
+
+  * HTTP 状态码设置合理
+
+* **测试要求**：
+
+  * `programmatic` TR-4.1：代码编译通过
+
+  * `human-judgement` TR-4.2：路由路径命名规范，状态码设置合理
+
+### \[ ] 步骤 5：处理请求参数
+
+* **优先级**：P0
+
+* **依赖**：步骤 4
+
+* **描述**：
+
+  * 导入参数装饰器（`Query`、`Body`、`Params`、`Headers`、`State`）
+
+  * 在方法参数中使用装饰器获取请求参数
+
+  * 使用 DTO 类型定义参数结构，避免使用 `any` 类型
+
+* **成功标准**：
+
+  * 参数装饰器使用正确
+
+  * 能够正确获取请求参数
+
+  * 参数类型定义清晰
+
+* **测试要求**：
+
+  * `programmatic` TR-5.1：代码编译通过
+
+  * `human-judgement` TR-5.2：参数获取逻辑清晰，类型定义合理
+
+### \[ ] 步骤 6：实现业务逻辑编排
+
+* **优先级**：P0
+
+* **依赖**：步骤 5
+
+* **描述**：
+
+  * 在控制器方法中编排业务逻辑
+
+  * 调用服务层方法
+
+  * 不直接访问数据库/Repository
+
+  * 使用 try/catch 捕获异常
+
+* **成功标准**：
+
+  * 业务逻辑编排正确
+
+  * 代码结构清晰
+
+  * 异常处理完善
+
+* **测试要求**：
+
+  * `programmatic` TR-6.1：代码编译通过
+
+  * `human-judgement` TR-6.2：业务逻辑编排合理，代码可读性好
+
+### \[ ] 步骤 7：返回响应
+
+* **优先级**：P0
+
+* **依赖**：步骤 6
+
+* **描述**：
+
+  * 使用 `success` 方法返回成功响应
+
+  * 使用 `fail` 方法返回失败响应
+
+  * 确保响应格式统一
+
+  * 不直接返回 Service 原始结果，必须映射为统一响应格式
+
+* **成功标准**：
+
+  * 响应格式符合项目规范
+
+  * 状态码和消息设置正确
+
+  * 响应数据结构清晰
+
+* **测试要求**：
+
+  * `programmatic` TR-7.1：代码编译通过
+
+  * `human-judgement` TR-7.2：响应格式规范，信息完整
+
+### [ ] 步骤 8：使用其他注解
+
+* **优先级**：P2
+
+* **依赖**：步骤 7
+
+* **描述**：
+
+  * 导入其他装饰器（`Logging`、`Permission`、`RateLimit`、`PerformanceMonitor`）
+
+  * 根据需要使用这些装饰器
+
+* **成功标准**：
+
+  * 装饰器使用正确
+
+  * 功能正常生效
+
+* **测试要求**：
+
+  * `programmatic` TR-8.1：代码编译通过
+
+  * `human-judgement` TR-8.2：装饰器使用合理
+
+### [ ] 步骤 9：注册控制器
+
+* **优先级**：P0
+
+* **依赖**：步骤 8
+
+* **描述**：
+
+  * 确保控制器被正确注册到应用中
+
+  * 检查路由是否被正确加载
+
+* **成功标准**：
+
+  * 控制器注册成功
+
+  * 路由可以访问
+
+* **测试要求**：
+
+  * `programmatic` TR-9.1：应用启动无错误
+
+  * `human-judgement` TR-9.2：路由注册正确
+
+### [ ] 步骤 10：测试控制器
+
+* **优先级**：P1
+
+* **依赖**：步骤 9
+
+* **描述**：
+
+  * 启动应用
+
+  * 测试控制器接口
+
+  * 验证功能是否正常
+
+* **成功标准**：
+
+  * 接口响应正常
+
+  * 功能实现正确
+
+* **测试要求**：
+
+  * `programmatic` TR-10.1：接口返回 200 状态码
+
+  * `human-judgement` TR-10.2：响应数据正确，功能符合预期
+
+## 示例控制器模板
+
+```typescript
+import { Get, Post, Body, Query, Params, Headers, State, ResponseCode } from '@src/framework/decorator/controller';
+import { BaseController, ControllerResponse } from '@src/controllers/base.controller';
+import { Inject } from 'dp-ioc2';
+import { logger } from '@src/framework/utils/logger';
+import { Logging } from '@src/framework/decorator/processor/AnnotationDecorators';
+import { SomeService } from '@src/service/some.service';
+import { SomeQueryDto, SomeBodyDto } from '@src/dto/controller/some/some.controller.dto';
+import { CommonServiceResultCode } from '@src/framework/types/ServiceResult';
+
+/**
+ * 示例控制器
+ * 负责处理示例相关的接口请求
+ */
+export class ExampleController extends BaseController {
+    
+    @Inject(SomeService)
+    private someService: SomeService;
+    
+    /**
+     * 获取数据
+     * - 来源：前端示例页面
+     * - 功能：根据查询参数获取示例数据
+     * - 依赖：需要登录态
+     */
+    @Get('/example/data')
+    @ResponseCode(200)
+    @Logging()
+    async getData(@Query() query: SomeQueryDto, @State('user') user: { userId: number; type?: number }): Promise<ControllerResponse<any>> {
+        try {
+            const result = await this.someService.getData(query, user.userId);
+            if (result.code !== CommonServiceResultCode.SUCCESS) {
+                return this.fail(-1, result.message);
+            }
+            return this.success(result.data);
+        } catch (error) {
+            logger.error('getData 失败', error as Error);
+            return this.fail(-1, '系统错误');
+        }
+    }
+    
+    /**
+     * 创建数据
+     * - 来源：前端示例页面
+     * - 功能：创建新的示例数据
+     * - 入参：示例数据对象
+     */
+    @Post('/example/data')
+    @ResponseCode(201)
+    @Logging()
+    async createData(@Body() body: SomeBodyDto): Promise<ControllerResponse<any>> {
+        try {
+            const result = await this.someService.createData(body);
+            if (result.code !== CommonServiceResultCode.SUCCESS) {
+                return this.fail(-1, result.message);
+            }
+            return this.success(result.data);
+        } catch (error) {
+            logger.error('createData 失败', error as Error);
+            return this.fail(-1, '系统错误');
+        }
+    }
+}
+```
+
+## 注意事项
+
+1. **命名规范**：控制器文件名使用 `controller.ts` 后缀，类名使用 `Controller` 后缀
+2. **路由路径**：使用小写字母和斜杠，避免使用下划线
+3. **响应格式**：统一使用 `success` 和 `fail` 方法返回响应
+4. **参数验证**：使用 DTO 类型定义参数结构，避免使用 `any` 类型
+5. **错误处理**：使用 try/catch 捕获异常，记录错误日志
+6. **性能优化**：根据需要使用 `RateLimit` 和 `PerformanceMonitor` 装饰器
+7. **安全考虑**：对于敏感接口，使用 `Permission` 装饰器进行权限控制
+8. **业务逻辑**：控制器不写业务逻辑，只做编排；不直接访问数据库/Repository
+9. **返回值**：不直接返回 Service 原始结果，必须映射为统一响应格式
+
+## 测试方法
+
+1. 启动应用：`npm run dev`
+2. 使用 Postman 或其他工具测试接口
+3. 检查日志输出
+4. 验证响应数据
+
+## 常见问题
+
+1. **路由未注册**：检查控制器是否被正确导入和注册
+2. **参数获取失败**：检查参数装饰器使用是否正确
+3. **响应格式错误**：确保使用 `success` 和 `fail` 方法
+4. **权限验证失败**：检查 `Permission` 装饰器配置是否正确
+5. **服务注入失败**：检查 `Inject` 装饰器使用是否正确
+6. **异常处理遗漏**：确保所有异步方法都有 try/catch
+
+## 最佳实践
+
+1. **单一职责**：每个控制器负责一个功能模块
+2. **代码组织**：使用子目录组织控制器
+3. **错误处理**：统一处理错误，返回清晰的错误信息
+4. **性能优化**：合理使用缓存和速率限制
+5. **安全措施**：对敏感接口进行权限控制
+6. **代码风格**：保持代码风格一致，使用 TypeScript 类型
+7. **测试覆盖**：为控制器编写单元测试
+8. **依赖注入**：使用 `Inject` 装饰器注入服务，避免硬编码依赖
+9. **响应规范**：使用 `ResponseCode` 装饰器设置合理的 HTTP 状态码
+10. **注释规范**：为控制器和方法添加清晰的中文注释，说明业务含义和使用场景
+

package/template/.trae/skills/00-backend-core.skill.md

@@ -0,0 +1,50 @@
+---
+alwaysApply: true
+---
+# Trae 技能：后端核心开发规范（Backend Core）
+
+## 适用范围
+- 本项目所有 TypeScript 后端代码
+- 技术栈：Koa + TypeORM + dp-ioc2 + 自定义装饰器体系
+- **包管理工具：必须使用 yarn（禁止使用 npm）**
+
+---
+
+## 一、分层架构（必须遵守）
+
+### 分层职责
+- **Controller 层**
+  - 接收请求
+  - 参数校验
+  - 调用 Service
+  - 返回统一响应
+- **Service 层**
+  - 编写业务逻辑
+  - 调用 Repository
+- **Repository 层**
+  - 封装数据库访问逻辑（TypeORM）
+
+---
+
+## 二、基类与返回规范
+
+### 基类继承
+- Controller **必须继承** `BaseController`
+- Service **必须继承** `BaseService`
+
+### Service 返回值
+- Service 方法必须返回 `CommonServiceResult<T>`
+
+### Controller 返回值
+- Controller 必须通过：
+  - `this.success<T>(data, message?)`
+  - `this.fail<T>(code, message?)`
+
+返回 `ControllerResponse<T>`：
+```ts
+{
+  code: number
+  data: T | null
+  message: string
+}
+```

package/template/.trae/skills/01-backend-skill-router.skill.md

@@ -0,0 +1,55 @@
+---
+alwaysApply: true
+---
+# Trae 技能：Backend Skill Router（规则路由器）
+
+你现在的角色是【后端 Skill 路由器】：你的目标是帮助选择应启用的 rules/skills/commands，避免盲用规则。
+
+## 总原则（必须遵守）
+- **优先使用 Commands** 来触发正确的 Skills，而不是把所有规则都写成 alwaysApply。
+- 如果用户需求不清晰，必须先提问澄清（不要臆造不存在的接口/文件/配置）。
+
+---
+
+## 你必须做的事（每次用户提出开发/改动请求时）
+
+### 1) 识别任务类型（多选）
+- Controller/API 开发
+- DTO/参数校验
+- Service/Repository/事务
+- 错误处理/日志
+- 启动流程（`app.ts`/`bootstrap.ts`，before/after）
+- 路由注册（`routers/index.ts`、`bindRouter`）
+- 中间件（`src/middlewares/*`）
+- 测试（Jest）
+- 目录结构与放置（libs/utils）
+
+### 2) 给出推荐启用的 Skills（只列文件名即可）
+按任务类型映射：
+- **Controller/API**：
+  - `10-backend-api.skill.md`
+  -（需要范式/注解速查时）`11-backend-controller-recipes.skill.md`
+- **Service**：
+  - `21-backend-service.skill.md`
+- **DTO/校验**：`30-backend-validation.skill.md`
+- **Service/Repository/事务**：`20-backend-repository.skill.md`
+- **错误/日志**：`40-backend-error-logging.skill.md`
+- **启动流程**：`50-backend-bootstrap-lifecycle.skill.md`
+- **路由注册**：`60-backend-router-registration.skill.md`
+- **中间件**：`70-backend-middleware.skill.md`
+- **测试**：`90-backend-testing.skill.md`
+- **libs/utils 放置**：`80-backend-utils-and-libs.skill.md`
+
+注意：
+- `00-backend-core.skill.md` 已是 alwaysApply，无需重复声明
+
+### 3) 推荐使用的 Command（优先）
+- 需要先规划：`.cursor/commands/plan-backend.md`
+- 要实现/修改 Controller：`.cursor/commands/implement-backend-api-controller.md`
+- 只要 Controller 速查：`.cursor/commands/cheatsheet-backend-controller.md`
+
+---
+
+## 输出要求（简短）
+- 当用户让你“直接写代码”：直接进入实现，但先在心里完成上述路由选择
+- 当用户不确定或信息不足：先问 2~5 个关键澄清问题

package/template/.trae/skills/10-backend-api.skill.md

@@ -0,0 +1,54 @@
+---
+alwaysApply: false
+---
+# Trae 技能：后端 API 开发规范
+
+## 适用与触发（重要）
+- **仅在**你要生成/修改 **Controller 路由接口** 时应用本 Skill（否则忽略）
+- 触发口令建议：
+  - "按 `10-backend-api.skill.md` 实现/重构这个 Controller"
+  - "按 API Skill 写路由 + DTO + 统一响应"
+
+---
+
+## 一、路由与参数装饰器（必须）
+- 路由装饰器：`@Get` / `@Post`
+- 参数装饰器：`@Query` / `@Body` / `@State`
+- 禁止在 Controller 中手动解析 ctx（除非该 Controller 明确以 ctx 作为参数且项目已有同类写法）
+
+---
+
+## 二、Controller 编排规范（必须）
+
+### 2.1 只做三件事
+- **参数接收与校验**（DTO）
+- **调用 Service**
+- **映射为统一响应**（`BaseController.success/fail`）
+
+### 2.2 统一响应（必须）
+- Controller 必须返回 `ControllerResponse<T>`（通过 `this.success()` / `this.fail()`）
+- 禁止 `return result`（Service 原始结果）：
+  - 成功：`return this.success(result.data, result.message?)`
+  - 失败：`return this.fail(result.code, result.message)`
+
+### 2.3 错误处理（必须）
+- Controller 的 `async` 方法必须 `try/catch`
+- catch：记录日志（见 `40-backend-error-logging.skill.md`）+ 返回通用失败响应
+
+### 2.4 DTO（必须）
+- `@Query()` / `@Body()` 必须使用 **DTO 类型**（禁止 `any`）
+- DTO 的定义与校验遵循 `30-backend-validation.skill.md`
+
+---
+
+## 三、接口文档与元信息（可选但优先）
+- 对外接口优先补齐 Swagger：`@ApiTags` / `@Api` / `@ApiResponse`
+- 需要显式状态码/响应头时使用：`@ResponseCode` / `@ResponseHeader`
+
+---
+
+## 四、禁止行为（必须）
+- ❌ Controller 中编写业务逻辑（应下沉到 Service）
+- ❌ Controller 中直接访问数据库/Repository
+- ❌ Controller 中返回 Service 原始结果（必须映射为统一响应）
+- ❌ `@Query()` / `@Body()` 使用 `any` 或未校验的入参对象

package/template/.trae/skills/11-backend-controller-recipes.skill.md

@@ -0,0 +1,107 @@
+---
+alwaysApply: false
+---
+# Trae 技能：Controller 推荐写法 + 常用注解速查（Recipes）
+
+## 适用与触发（重要）
+- 仅当需要**新增/修改 Controller 路由接口**，且希望按本项目框架“推荐范式”实现时使用本 Skill。
+- 触发口令建议：
+  - “请同时启用 `11-backend-controller-recipes.skill.md`，按项目范式实现 Controller”
+
+---
+
+## 一、写 Controller 的推荐范式（必须对齐）
+
+### 1.1 参考样例（写代码前先对齐）
+- 推荐在实现前先对齐以下文件的写法（不要臆造新风格）：
+  - `src/controllers/example/NewAnnotationExampleController.ts`
+  - `src/controllers/home/ytUser.controller.ts`
+  - `src/controllers/base.controller.ts`
+
+### 1.2 Controller 标准骨架（复制这个结构）
+目标：DTO 入参 → 调用 Service → 统一响应（`success/fail`）→ try/catch + logger
+
+```ts
+import { Get, Post, Query, Body, State, ResponseCode, ResponseHeader } from '@src/framework/decorator/controller';
+import { BaseController, ControllerResponse } from '@src/controllers/base.controller';
+import { Inject } from 'dp-ioc2';
+import { logger } from '@src/framework/utils/logger';
+import { SomeService } from '@src/service/some.service';
+import { SomeQueryDto, SomeBodyDto } from '@src/dto/controller/xxx/some.controller.dto';
+import { CommonServiceResultCode } from '@src/framework/types/ServiceResult';
+
+export class SomeController extends BaseController {
+  @Inject(SomeService)
+  private someService: SomeService;
+
+  @Get('/some/path')
+  @ResponseCode(200)
+  async getSomething(
+    @Query(SomeQueryDto) query: SomeQueryDto,
+    @State('user') user: { userId: number; type?: number },
+  ): Promise<ControllerResponse<any>> {
+    try {
+      const result = await this.someService.someMethod(query, user.userId);
+      if (result.code !== CommonServiceResultCode.SUCCESS) {
+        return this.fail(-1, result.message);
+      }
+      return this.success(result.data);
+    } catch (error) {
+      logger.error('getSomething 失败', error as Error);
+      return this.fail(-1, '系统错误');
+    }
+  }
+}
+```
+
+硬约束：
+- Controller **不写业务逻辑**，只做编排
+- Controller **不直接访问数据库/Repository**
+- Controller **不 return Service 原始结果**，必须映射 `success/fail`
+- Controller `async` **必须 try/catch**
+
+---
+
+## 二、常用注解速查（按本项目实现理解）
+
+### 2.1 路由类注解
+- **`@Get('/path')`**：注册 GET 路由；不传参数时 url 默认使用方法名
+- **`@Post('/path')`**：注册 POST 路由；不传参数时 url 默认使用方法名
+
+### 2.2 参数注解（重点）
+- **`@Query()`**：
+  - 读取 query 参数
+  - 推荐写法：`@Query(SomeQueryDto) query: XxxQueryDto`
+- **`@Body()`**：
+  - 读取 body 参数
+  - 推荐写法：`@Body(SomeBodyDto) body: XxxBodyDto`
+- **`@State()`**：
+  - 读取整个 `ctx.state`（样例：`ytUser.controller.ts`）
+  - 推荐写法：`@State() state: { user: { userId: number; type?: number } }`
+- **`@State('user')`**：
+  - 读取 `ctx.state.user`（样例：`NewAnnotationExampleController.ts`）
+  - 推荐写法：`@State('user') user: { userId: number; type?: number }`
+
+禁止：
+- ❌ `@Query() query: any` / `@Body() body: any` / `@State() state: any`（尽量不要）
+
+### 2.3 响应元信息注解
+- **`@ResponseCode(200|201|...)`**：设置 HTTP 状态码（样例中 GET 用 200，POST 用 201）
+- **`@ResponseHeader(key, value)`**：为响应添加 header
+
+### 2.4 响应校验注解（进阶，按需）
+- **`@ResponseValidator(DtoClass, objectKey?)`**：对响应数据做校验
+- **`@ResponseValidateIf(DtoClass, fn)`**：仅当 fn 返回真时才校验（样例：`ytUser.controller.ts`）
+
+---
+
+## 三、常见组合（直接套用）
+
+### 3.1 需要登录用户的 GET 接口
+- `@Get('/xxx') + @State('user')`（或 `@State()` 取整段 state）
+
+### 3.2 带 body 的 POST 接口
+- `@Post('/xxx') + @Body(SomeBodyDto) body: DtSomeBodyDtoo + @ResponseCode(201)`
+
+### 3.3 需要自定义 header
+- `@ResponseHeader('X-XXX', 'value')`

package/template/.trae/skills/20-backend-repository.skill.md

@@ -0,0 +1,25 @@
+---
+alwaysApply: false
+---
+# Trae 技能：Repository 与数据访问规范
+
+## 一、Repository 使用方式
+
+- Service 中通过：
+  - `getDataRepository<Entity>(EntityClass)`
+  - 或 `createLazyRepository()`（推荐）
+
+---
+
+## 二、事务管理
+
+- 涉及多表操作时：
+  - 必须使用 `transactionManager.executeInTransaction()`
+  - 禁止手动管理事务
+
+---
+
+## 三、禁止行为
+
+- ❌ Controller 中访问 Repository
+- ❌ Service 中直接获取 DataSource