create-dp-koa 1.0.0 → 1.0.2

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "create-dp-koa",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Scaffold a DP-Koa framework project from the official template",
   "type": "module",
   "bin": {
-    "create-dp-koa": "./index.mjs"
+    "create-dp-koa": "index.mjs"
   },
   "files": [
     "index.mjs",

package/template/.cursor/commands/cheatsheet-backend-controller.md

@@ -0,0 +1,45 @@
+# Command：Backend Controller Cheatsheet
+
+你现在是【后端 Controller 速查助手】。
+
+## 适用场景（触发条件）
+- 用户想要 Cursor 快速给出：**Controller 推荐写法** + **常用注解用法** + **最小可复制模板**。
+- 本 Command **不直接修改代码**（只输出建议与模板）。
+
+---
+
+## 必须遵守的 Skills / Rules
+- 始终遵守：`00-backend-core.skill.md`
+- 本次必须启用并参考：
+  - `10-backend-api.skill.md`
+  - `11-backend-controller-recipes.skill.md`
+
+---
+
+## 输出要求（严格遵守）
+请严格按以下结构输出（只输出文本，不直接生成业务代码文件）：
+
+```text
+【适用结论】
+- 这次是否属于“写/改 Controller 路由接口”：是/否
+- 推荐启用的 Skills：
+
+【Controller 推荐骨架（最小模板）】
+- 给出一个可复制的 Controller 方法模板（含 @Get/@Post + @Query/@Body/@State + try/catch + success/fail）
+
+【常用注解速查】
+- @Get/@Post：说明 + 何时用
+- @Query/@Body：说明 + DTO 写法
+- @State() vs @State('user')：差异 + 推荐写法
+- @ResponseCode/@ResponseHeader：何时用
+- @ResponseValidator/@ResponseValidateIf：何时用（可选）
+
+【DTO/Service 设计建议】
+- 入参 DTO 应放在哪个目录、命名建议
+- Service 方法签名建议（含返回类型）
+
+【对齐的参考来源（必须列出）】
+- 至少列出 **`11-backend-controller-recipes.skill.md` 内嵌示例**中的 2 个小节编号（例如 1.1.2、1.1.4）；若同时参考了仓库内 `src/controllers/base.controller.ts` 或 `src/controllers/example/*`，可一并写出路径
+```
+
+

package/template/.cursor/commands/implement-backend-api-controller.md

@@ -0,0 +1,60 @@
+# Command：Implement Backend API Controller
+
+你现在是【后端 API Controller 实现器】。
+
+## 适用场景（触发条件）
+- 仅当用户要 **新增/修改 Controller 路由接口**（含 DTO、Swagger、响应映射）时使用本 Command。
+- 本 Command 的目标是：**直接落地代码改动**（不是只做规划）。
+- 如果用户只要规划，请改用：`plan-backend.md`
+
+---
+
+## 必须遵守的 Skills / Rules
+- 始终遵守：`00-backend-core.skill.md`
+- 本次必须额外启用并严格遵守：`10-backend-api.skill.md`
+- 强烈建议同时启用（用于让写法更“像本项目”）：`11-backend-controller-recipes.skill.md`
+- 同时配套使用（按需要）：
+  - `30-backend-validation.skill.md`（DTO + 校验）
+  - `40-backend-error-logging.skill.md`（try/catch + 日志）
+  - `20-backend-repository.skill.md`（如涉及事务/数据访问）
+  - `90-backend-testing.skill.md`（如需要补测试）
+  
+---
+
+## 输入要求（信息不足必须先澄清）
+当用户未提供以下信息时，必须先提问澄清再写代码：
+- **接口清单**：路径、方法（GET/POST）、接口用途
+- **入参**：Query/Body/State 的字段、类型、是否必填
+- **输出**：成功返回 data 结构、失败场景与错误码/错误信息
+- **Service 目标**：要调用的 Service 方法名（或由你提出建议）
+- **是否需要 Swagger**：对外接口默认需要（若用户明确不需要则不加）
+
+---
+
+## 实现约束（执行时必须检查）
+- **路由/参数装饰器必须使用**：`@Get/@Post` + `@Query/@Body/@State`
+- **DTO 必须强类型**：禁止 `any`；DTO 放到 `src/dto/controller/{module}/`
+- **Controller 必须 try/catch**
+- **Controller 必须映射统一响应**：使用 `BaseController.success/fail`，禁止 `return result`
+- **禁止在 Controller 写业务逻辑/直接访问数据库**
+
+---
+
+## 输出/交付（你必须做到）
+1. **明确将要修改/新增的文件列表**（含路径）
+2. **实现 DTO**（必要时新建文件）
+3. **实现/修改 Controller**（装饰器 + DTO + try/catch + 响应映射）
+4. **如需**：补 Swagger 装饰器、补/改 Service 接口签名
+5. **如需**：补 Jest 测试（至少覆盖成功/失败/边界之一）
+
+---
+
+## 写代码前的对齐动作（必须）
+- 在生成/修改 Controller 代码前，先对齐 **`11-backend-controller-recipes.skill.md` 内嵌示例**（章节 **1.1**），重点核对：
+  - **1.1.1** `BaseController` / `ControllerResponse` 与 `success` / `fail` 用法
+  - **1.1.2** `@State()` 读取整段 `ctx.state`
+  - **1.1.3** `@State('user')` 只读 `ctx.state.user`
+  - **1.1.4** `@ResponseValidateIf` 条件响应校验
+- 若仓库中仍存在 `src/controllers/base.controller.ts` 或 `src/controllers/example/*`，可作为**补充**对照（以实现代码为准）。
+
+

package/template/.cursor/commands/plan-backend.md

@@ -0,0 +1,97 @@
+# Command：Backend Skill Planner
+
+你现在是【后端技能规划器（Backend Skill Planner）】。
+
+你的职责是：
+- 分析用户的后端开发需求
+- 规划应该使用哪些 Backend Skills
+- 给出清晰、可执行的技能调用顺序
+- 不直接生成业务代码
+
+---
+
+## 一、你可以使用的 Skills（已定义）
+
+- Backend Core Skill（始终生效）
+- Backend API Skill
+- Backend Service Skill
+- Backend Repository Skill
+- Backend Validation Skill
+- Backend Error & Logging Skill
+- Backend Testing Skill
+- Backend Bootstrap Lifecycle Skill（启动生命周期：before/after/bootstrap）
+- Backend Router Registration Skill（路由注册：routers/index.ts + bindRouter）
+
+---
+
+## 二、规划规则（必须遵守）
+
+1. **不要直接写代码**
+2. **不要跳过规划步骤**
+3. 每个 Skill 必须说明：
+   - 使用原因
+   - 预期输出
+4. 如果用户信息不足，必须先提出澄清问题
+5. 输出结构必须严格遵守下方格式
+6. 若需求涉及启动流程/中间件顺序/路由注册/数据库初始化/监控任务：
+   - 必须纳入 Backend Bootstrap Lifecycle Skill（`50-backend-bootstrap-lifecycle.skill.md`）
+7. 若需求涉及新增/修改路由绑定（`src/routers/index.ts`）、调整 `bindRouter` 或路由体系：
+   - 必须纳入 Backend Router Registration Skill（`60-backend-router-registration.skill.md`）
+
+---
+
+## 三、输出格式（严格遵守）
+
+```text
+【需求理解】
+- 用户目标：
+- 涉及模块：
+- 是否新增 / 修改：
+
+【技能规划】
+Step 1：Backend Validation Skill
+- 原因：
+- 输出：
+
+Step 2：Backend API Skill
+- 原因：
+- 输出：
+
+Step 3：Backend Service Skill
+- 原因：
+- 输出：
+
+Step 4：Backend Repository Skill
+- 原因：
+- 输出：
+
+Step 5：Backend Error & Logging Skill
+- 原因：
+- 输出：
+
+Step 6：Backend Testing Skill（如需要）
+- 原因：
+- 输出：
+
+Step X：Backend Bootstrap Lifecycle Skill（如涉及启动/bootstrapping）
+- 原因：
+- 输出：
+
+Step Y：Backend Router Registration Skill（如涉及路由注册/routers/index.ts）
+- 原因：
+- 输出：
+
+【不确定点 / 需要澄清】
+- 问题 1：
+- 问题 2：
+
+【执行建议】
+- 推荐使用的 Commands：
+- 是否可以进入代码生成阶段：
+
+---
+
+## 四、可用 Commands（建议在【执行建议】中引用）
+- `plan-backend.md`：只做技能规划，不直接写代码
+- `implement-backend-api-controller.md`：新增/修改 Controller 路由接口（显式启用 Backend API Skill）
+- `cheatsheet-backend-controller.md`：输出 Controller 推荐写法 + 常用注解速查（不直接改代码）

package/template/.cursor/rules/00-backend-core.skill.md

@@ -0,0 +1,61 @@
+---
+alwaysApply: true
+---
+# Skill：后端核心开发规范（Backend Core）
+
+## 适用范围
+- 本项目所有 TypeScript 后端代码
+- 技术栈：Koa + TypeORM + dp-ioc2 + 自定义装饰器体系
+- **包管理工具：必须使用 yarn（禁止使用 npm）**
+
+---
+
+## 运行环境判定（debug 口径，必须）
+
+**唯一标准**：以 `src/framework/utils/function.ts` 为准，**不要**用 `process.env.NODE_ENV` 作为“是否生产/是否调试”的单一判断。
+
+- **`isDebug()`**：当进程启动参数中包含 `--env=debug` 时为 `true`。
+- **非 debug**：一律按**生产口径**处理（例如：迁移、静态资源长缓存、对外错误信息脱敏等）。
+- **`getRuntimeEnvironmentLabel()`**：返回 `'development' | 'production'`，用于日志与配置元数据，**与 `NODE_ENV` 解耦**。
+
+**例外**：`NODE_ENV === 'test'`（Jest 等）仍保留用于测试专用分支，与上述 debug 口径并行，不互相替代。
+
+---
+
+## 一、分层架构（必须遵守）
+
+### 分层职责
+- **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/.cursor/rules/01-backend-skill-router.skill.md

@@ -0,0 +1,57 @@
+---
+alwaysApply: true
+---
+# Skill：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/.cursor/rules/10-backend-api.skill.md

@@ -0,0 +1,55 @@
+---
+alwaysApply: false
+---
+# Skill：后端 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/.cursor/rules/11-backend-controller-recipes.skill.md

@@ -0,0 +1,188 @@
+---
+alwaysApply: false
+---
+# Skill：Controller 推荐写法 + 常用注解速查（Recipes）
+
+## 适用与触发（重要）
+- 仅当需要**新增/修改 Controller 路由接口**，且希望按本项目框架“推荐范式”实现时使用本 Skill。
+- 触发口令建议：
+  - “请同时启用 `11-backend-controller-recipes.skill.md`，按项目范式实现 Controller”
+
+---
+
+## 一、写 Controller 的推荐范式（必须对齐）
+
+### 1.1 内嵌参考样例（本 Skill 自包含）
+以下为从本项目常用写法整理的最小示例；**实现新接口时请先对齐本节的装饰器与类型风格**。若仓库中另有 `src/controllers/example/*` 等运行时代码，可作为补充参考，但**不必依赖**特定业务 Controller 文件是否存在。
+
+#### 1.1.1 `BaseController` 与 `ControllerResponse`（统一响应）
+
+```ts
+export class ControllerResponse<T> {
+  code = 0;
+  data: T | null = null;
+  message = '';
+
+  constructor(code: number, data: T | null, message?: string) {
+    this.code = code;
+    this.data = data;
+    if (message) this.message = message;
+  }
+}
+
+export class BaseController {
+  success<T>(data: T, message?: string) {
+    return new ControllerResponse<T>(0, data, message);
+  }
+  fail<T>(code: number, message?: string) {
+    return new ControllerResponse<T>(code, null, message);
+  }
+}
+```
+
+#### 1.1.2 `@State()`：读取整段 `ctx.state`
+
+```ts
+import { Get, State } from '@src/framework/decorator/controller';
+import { BaseController, ControllerResponse } from '@src/controllers/base.controller';
+
+export class ExampleStateController extends BaseController {
+  @Get('/example/state-full')
+  async getWithFullState(
+    @State() state: { user: { userId: number; type?: number } },
+  ): Promise<ControllerResponse<{ userId: number }>> {
+    return this.success({ userId: state.user.userId });
+  }
+}
+```
+
+#### 1.1.3 `@State('user')`：只读 `ctx.state.user`
+
+```ts
+import { Get, State } from '@src/framework/decorator/controller';
+import { BaseController, ControllerResponse } from '@src/controllers/base.controller';
+
+export class ExampleUserSliceController extends BaseController {
+  @Get('/example/state-user')
+  async getWithUser(
+    @State('user') user: { userId: number; type?: number },
+  ): Promise<ControllerResponse<{ ok: boolean }>> {
+    return this.success({ ok: user.userId > 0 });
+  }
+}
+```
+
+#### 1.1.4 `@ResponseValidateIf`：仅在条件成立时校验响应体
+
+```ts
+import { Get, State, ResponseValidateIf } from '@src/framework/decorator/controller';
+import { BaseController, ControllerResponse } from '@src/controllers/base.controller';
+
+// 示例 DTO：按实际接口替换
+class UserProfileResponseDto {
+  id!: number;
+  nickName!: string;
+}
+
+export class ExampleResponseValidateController extends BaseController {
+  @ResponseValidateIf(UserProfileResponseDto, (data) => Boolean(data && data.data))
+  @Get('/example/profile')
+  async getProfile(
+    @State() state: { user: { userId: number } },
+  ): Promise<ControllerResponse<UserProfileResponseDto | null>> {
+    return this.success({
+      id: state.user.userId,
+      nickName: 'demo',
+    });
+  }
+}
+```
+
+### 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`（样例：见 **1.1.2**）
+  - 推荐写法：`@State() state: { user: { userId: number; type?: number } }`
+- **`@State('user')`**：
+  - 读取 `ctx.state.user`（样例：见 **1.1.3**）
+  - 推荐写法：`@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 返回真时才校验（样例：见 **1.1.4**）
+
+---
+
+## 三、常见组合（直接套用）
+
+### 3.1 需要登录用户的 GET 接口
+- `@Get('/xxx') + @State('user')`（或 `@State()` 取整段 state）
+
+### 3.2 带 body 的 POST 接口
+- `@Post('/xxx') + @Body(SomeBodyDto) body: SomeBodyDto + @ResponseCode(201)`
+
+### 3.3 需要自定义 header
+- `@ResponseHeader('X-XXX', 'value')`
+

package/template/.cursor/rules/20-backend-repository.skill.md

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