create-dp-koa 1.1.3 → 1.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-dp-koa",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "description": "Scaffold a DP-Koa framework project from the official template",
   "type": "module",
   "bin": {

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

@@ -12,7 +12,7 @@ alwaysApply: true
 
 ## 运行环境判定（debug 口径，必须）
 
-**唯一标准**：以 `src/framework/utils/function.ts` 为准，**不要**用 `process.env.NODE_ENV` 作为“是否生产/是否调试”的单一判断。
+**唯一标准**：以 `dp-koa-framework-core` 导出的 `isDebug()` / `getRuntimeEnvironmentLabel()` 为准，**不要**用 `process.env.NODE_ENV` 作为“是否生产/是否调试”的单一判断。
 
 - **`isDebug()`**：当进程启动参数中包含 `--env=debug` 时为 `true`。
 - **非 debug**：一律按**生产口径**处理（例如：迁移、静态资源长缓存、对外错误信息脱敏等）。

package/template/.cursor/rules/01-backend-skill-router.skill.md

@@ -6,6 +6,7 @@ alwaysApply: true
 你现在的角色是【后端 Skill 路由器】：你的目标是帮助选择应启用的 rules/skills/commands，避免盲用规则。
 
 ## 总原则（必须遵守）
+
 - **优先使用 Commands** 来触发正确的 Skills，而不是把所有规则都写成 alwaysApply。
 - 如果用户需求不清晰，必须先提问澄清（不要臆造不存在的接口/文件/配置）。
 
@@ -14,18 +15,21 @@ alwaysApply: true
 ## 你必须做的事（每次用户提出开发/改动请求时）
 
 ### 1) 识别任务类型（多选）
+
 - Controller/API 开发
 - DTO/参数校验
 - Service/Repository/事务
 - 错误处理/日志
 - 启动流程（`app.ts`/`bootstrap.ts`，before/after）
 - 路由注册（`routers/index.ts`、`bindRouter`）
-- 中间件（`src/middlewares/*`）
+- 中间件（`src/middlewares/`*）
 - 测试（Jest）
 - 目录结构与放置（libs/utils）
 
 ### 2) 给出推荐启用的 Skills（只列文件名即可）
+
 按任务类型映射：
+
 - **Controller/API**：
   - `10-backend-api.skill.md`
   -（需要范式/注解速查时）`11-backend-controller-recipes.skill.md`
@@ -41,9 +45,11 @@ alwaysApply: true
 - **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`
@@ -51,7 +57,7 @@ alwaysApply: true
 ---
 
 ## 输出要求（简短）
+
 - 当用户让你“直接写代码”：直接进入实现，但先在心里完成上述路由选择
 - 当用户不确定或信息不足：先问 2~5 个关键澄清问题
 
-

package/template/.cursor/rules/10-backend-api.skill.md

@@ -4,6 +4,7 @@ alwaysApply: false
 # Skill：后端 API 开发规范
 
 ## 适用与触发（重要）
+
 - **仅在**你要生成/修改 **Controller 路由接口** 时应用本 Skill（否则忽略）
 - 触发口令建议：
   - “按 `10-backend-api.skill.md` 实现/重构这个 Controller”
@@ -12,6 +13,7 @@ alwaysApply: false
 ---
 
 ## 一、路由与参数装饰器（必须）
+
 - 路由装饰器：`@Get` / `@Post`
 - 参数装饰器：`@Query` / `@Body` / `@State`
 - 禁止在 Controller 中手动解析 ctx（除非该 Controller 明确以 ctx 作为参数且项目已有同类写法）
@@ -21,33 +23,39 @@ alwaysApply: false
 ## 二、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 原始结果（必须映射为统一响应）

package/template/.cursor/rules/11-backend-controller-recipes.skill.md

@@ -43,13 +43,14 @@ export class BaseController {
 #### 1.1.2 `@State()`：读取整段 `ctx.state`
 
 ```ts
-import { Get, State } from '@src/framework/decorator/controller';
+import { Get, State } from 'dp-koa-framework-core';
 import { BaseController, ControllerResponse } from '@src/controllers/base.controller';
+import type { AppCtxState } from '@src/types/ctxState';
 
 export class ExampleStateController extends BaseController {
   @Get('/example/state-full')
   async getWithFullState(
-    @State() state: { user: { userId: number; type?: number } },
+    @State() state: AppCtxState,
   ): Promise<ControllerResponse<{ userId: number }>> {
     return this.success({ userId: state.user.userId });
   }
@@ -59,13 +60,14 @@ export class ExampleStateController extends BaseController {
 #### 1.1.3 `@State('user')`：只读 `ctx.state.user`
 
 ```ts
-import { Get, State } from '@src/framework/decorator/controller';
+import { Get, State } from 'dp-koa-framework-core';
 import { BaseController, ControllerResponse } from '@src/controllers/base.controller';
+import type { UserState } from '@src/types/ctxState';
 
 export class ExampleUserSliceController extends BaseController {
   @Get('/example/state-user')
   async getWithUser(
-    @State('user') user: { userId: number; type?: number },
+    @State('user') user: UserState,
   ): Promise<ControllerResponse<{ ok: boolean }>> {
     return this.success({ ok: user.userId > 0 });
   }
@@ -75,8 +77,9 @@ export class ExampleUserSliceController extends BaseController {
 #### 1.1.4 `@ResponseValidateIf`：仅在条件成立时校验响应体
 
 ```ts
-import { Get, State, ResponseValidateIf } from '@src/framework/decorator/controller';
+import { Get, State, ResponseValidateIf } from 'dp-koa-framework-core';
 import { BaseController, ControllerResponse } from '@src/controllers/base.controller';
+import type { AppCtxState } from '@src/types/ctxState';
 
 // 示例 DTO：按实际接口替换
 class UserProfileResponseDto {
@@ -88,7 +91,7 @@ export class ExampleResponseValidateController extends BaseController {
   @ResponseValidateIf(UserProfileResponseDto, (data) => Boolean(data && data.data))
   @Get('/example/profile')
   async getProfile(
-    @State() state: { user: { userId: number } },
+    @State() state: AppCtxState,
   ): Promise<ControllerResponse<UserProfileResponseDto | null>> {
     return this.success({
       id: state.user.userId,
@@ -102,13 +105,13 @@ export class ExampleResponseValidateController extends BaseController {
 目标：DTO 入参 → 调用 Service → 统一响应（`success/fail`）→ try/catch + logger
 
 ```ts
-import { Get, Post, Query, Body, State, ResponseCode, ResponseHeader } from '@src/framework/decorator/controller';
+import { Get, Post, Query, Body, State, ResponseCode, ResponseHeader } from 'dp-koa-framework-core';
 import { BaseController, ControllerResponse } from '@src/controllers/base.controller';
 import { Inject } from 'dp-ioc2';
-import { logger } from '@src/framework/utils/logger';
+import { logger } from 'dp-koa-framework-core';
 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';
+import { CommonServiceResultCode } from 'dp-koa-framework-core';
 
 export class SomeController extends BaseController {
   @Inject(SomeService)

package/template/.cursor/rules/21-backend-service.skill.md

@@ -133,5 +133,19 @@ alwaysApply: false
 - Controller 只能调用 Service 的公开方法，不应调用 Repository
 - Service 不应调用 Controller，也不应依赖 Koa `Context`
 - Service 之间如需调用，应通过依赖注入（`@Inject(OtherService)`），避免静态调用/循环依赖
+- 禁止在 Service 内手动创建实例：
+  - ❌ 禁止 `new OtherService()` / `new XxxService()`（包括在方法内部临时 new）
+  - ❌ 禁止通过手写单例/缓存实例绕过 IoC 容器
+  - ✅ 必须依赖 dp-ioc2 在运行期注入（例如字段注入或构造注入）
+- 推荐写法（字段注入示例）：
+  ```ts
+  import { Inject } from "dp-ioc2";
+  import { OtherService } from "./other.service";
+
+  export class MyService extends BaseService {
+    @Inject(OtherService)
+    private otherService!: OtherService;
+  }
+  ```
 
 

package/template/.cursor/rules/30-backend-validation.skill.md

@@ -124,7 +124,7 @@ async createUser(@Body(CreateUserControllerDto) body: CreateUserControllerDto):
 #### 响应 DTO 使用
 ```typescript
 import { GetUserInfoResponseDto } from '@src/dto/controller/home/ytUser.controller.dto';
-import { ResponseValidateIf } from '@src/framework/decorator/controller';
+import { ResponseValidateIf } from 'dp-koa-framework-core';
 
 // 使用 @ResponseValidateIf 装饰器校验响应数据
 @ResponseValidateIf(GetUserInfoResponseDto, (data) => data && data.data)

package/template/.cursor/rules/40-backend-error-logging.skill.md

@@ -6,11 +6,15 @@ alwaysApply: false
 ## 一、错误处理
 
 - 所有 async 方法必须 try/catch
-- 业务错误：
-  - 使用 `CommonServiceResult.fail()`
-- 系统错误：
-  - 记录日志
-  - 返回通用失败响应
+- 业务错误（可预期、可分类）：
+  - 主要在 **Service 层 catch 中**处理
+  - 返回 `CommonServiceResult.fail()/validationError/notFound/...`（由 Service 统一封装）
+- 系统错误（不可预期、疑似异常）：
+  - **必须记录日志（logger.error）**
+  - Service 层返回通用失败的 `CommonServiceResult.error(...)`
+- 映射到 Controller：
+  - Controller 不应直接返回 `CommonServiceResult`
+  - Controller 必须把 Service 的 `CommonServiceResult` 通过 `this.success()/this.fail()` 映射为 `ControllerResponse`
 
 ---
 

package/template/.cursor/rules/50-backend-bootstrap-lifecycle.skill.md

@@ -4,14 +4,14 @@ alwaysApply: false
 # Skill：启动生命周期规范（setBeforeBootstrap / setAfterBootstrap）
 
 ## 适用与触发（重要）
-- 仅当需要修改/新增启动逻辑（`src/app.ts`）或框架启动流程（`src/framework/utils/bootstrap.ts`）时启用本 Skill。
+- 仅当需要修改/新增启动逻辑（`src/app.ts`）或框架启动流程（由 `dp-koa-framework-core` 的 bootstrap 决定）时启用本 Skill。
 - 触发口令建议：
   - “请按 `50-backend-bootstrap-lifecycle.skill.md` 调整启动流程”
 
 ---
 
 ## 一、真实执行顺序（必须理解并遵守）
-以 `src/framework/utils/bootstrap.ts` 为准：
+以 `dp-koa-framework-core` 的 bootstrap 内部执行顺序为准：
 
 1. `bootstrap()` 内部 **先执行** `beforeBootstraps(app)`（如果已注册）
 2. 然后框架挂载：CORS → 日志中间件 → 框架错误处理中间件 → `koaBody()`
@@ -36,9 +36,9 @@ alwaysApply: false
   - 生产环境迁移（如有）
   - 内存库模式初始化测试数据（如有）
 
-### 2.1.1 环境变量文件与 `.env` 选择（对齐 `bootstrap.ts`）
+### 2.1.1 环境变量文件与 `.env` 选择（对齐 `dp-koa-framework-core` 的 bootstrap）
 
-- **与 `NODE_ENV` 解耦**：`bootstrap.ts` 最早加载的 `.env` 文件由 **`isDebug()`** 决定：
+- **与 `NODE_ENV` 解耦**：`dp-koa-framework-core` 的 bootstrap 最早加载的 `.env` 文件由 **`isDebug()`** 决定：
   - `--env=debug` → `.env.development`
   - 否则 → `.env.production`
 - **本地开发**：`package.json` 的 `dev` 建议在 `node dist/main.js` 后追加 `--env=debug`，避免误加载生产 env。

package/template/.cursor/rules/60-backend-router-registration.skill.md

@@ -1,20 +1,24 @@
 ---
-alwaysApply: false
----
+
+## alwaysApply: false
+
 # Skill：路由注册规范（routers/index.ts + bindRouter）
 
 ## 适用与触发（重要）
-- 仅当需要新增/修改路由绑定（`src/routers/index.ts`）或调整路由系统（`src/framework/utils/router.ts`）时启用本 Skill。
+
+- 仅当需要新增/修改路由绑定（`src/routers/index.ts`）或调整路由系统（由 `dp-koa-framework-core` 的 `bindRouter` 机制决定）时启用本 Skill。
 - 触发口令建议：
   - “请按 `60-backend-router-registration.skill.md` 规范注册路由”
 
 ---
 
 ## 一、路由注册机制（必须理解）
-本项目路由注册入口：`src/routers/index.ts`  
-路由绑定工具：`src/framework/utils/router.ts` 的 `bindRouter(...)`
+
+本项目路由注册入口：`src/routers/index.ts`
+路由绑定工具：`dp-koa-framework-core` 导出的 `bindRouter(...)`
 
 ### 1.1 bindRouter(...) 的真实行为（以代码为准）
+
 - 调用形式：
   - `bindRouter(prefixPath, ControllerClass)`
   - `bindRouter(prefixPath, middleware1, middleware2, ..., ControllerClass)`
@@ -34,6 +38,7 @@ alwaysApply: false
 ## 二、`src/routers/index.ts` 注册规范（必须遵守）
 
 ### 2.1 只做“路由绑定”
+
 - `routers/index.ts` 只负责：
   - 导入 Controller
   - 选择是否需要 middlewares（鉴权/日志等）
@@ -41,7 +46,9 @@ alwaysApply: false
 - 禁止在此文件写业务逻辑或数据库操作
 
 ### 2.2 路由前缀命名（推荐统一）
+
 建议用“模块/领域 + 子模块 + 资源”的层级前缀，保持稳定：
+
 - `"/public/..."`：公开接口（一般不加“认证/鉴权 middleware”）
 - `"/home/..."`：业务接口（按需加“认证/鉴权 middleware”）
 - `"/admin/..."`：管理接口（一般需要认证/鉴权；可在此基础上再加权限/审计中间件）
@@ -49,6 +56,7 @@ alwaysApply: false
 - `"/test"`：测试/调试接口（仅测试环境或内存库模式有效时暴露）
 
 ### 2.3 middleware 使用规范（必须）
+
 - 需要认证/鉴权的路由必须在 `bindRouter` 里显式挂“认证/鉴权 middleware”（名称不固定，以项目实际为准）：
   - 示例（本项目当前实现）：`bindRouter("/home/user/yt_user", tokenMiddleware(), YtUserController);`
 - middlewares 必须传“可执行的 koa middleware 函数”：
@@ -57,17 +65,19 @@ alwaysApply: false
   - 例如：`authMiddleware()` → 其他业务中间件
 
 ### 2.4 禁止重复绑定（必须）
+
 - ❌ 禁止对同一个 `prefixPath + Controller` 重复调用 `bindRouter`
   - 重复绑定会导致路由重复注册、重复执行中间件、行为不可预测
 
 ### 2.5 尾斜杠（推荐）
+
 - 推荐 `bindRouter` 的 `prefixPath` **不要以 `/` 结尾**，保持统一（除非明确需要）
 - 若使用了尾斜杠，框架会额外注册无尾斜杠版本；应避免产生重复/歧义的路由
 
 ---
 
 ## 三、与启动流程的配合（必须）
+
 - `Router()`（即 `src/routers/index.ts` 的默认导出函数）必须在 `app.use(router.routes())` 之前执行  
   - 因此通常应在 `setBeforeBootstrap(...)` 中调用（见 `50-backend-bootstrap-lifecycle.skill.md`）
 
-

package/template/.cursor/rules/70-backend-middleware.skill.md

@@ -4,7 +4,7 @@ alwaysApply: false
 # Skill：中间件开发与注册规范（src/middlewares）
 
 ## 适用与触发（重要）
-- 仅当需要新增/修改中间件（`src/middlewares/*`）或调整中间件注册顺序（`src/framework/utils/bootstrap.ts`、`src/app.ts`、`src/routers/index.ts`）时启用本 Skill。
+- 仅当需要新增/修改中间件（`src/middlewares/*`）或调整中间件注册顺序（由 `dp-koa-framework-core` 的 bootstrap + `src/app.ts` + `src/routers/index.ts` 共同决定）时启用本 Skill。
 - 触发口令建议：
   - “请按 `70-backend-middleware.skill.md` 新增/调整中间件”
 
@@ -62,7 +62,7 @@ alwaysApply: false
 ## 六、注册位置与顺序（必须）
 
 ### 6.1 全局中间件（bootstrap 阶段）
-在 `src/framework/utils/bootstrap.ts` 中，框架已注册：
+在 `dp-koa-framework-core` 的 bootstrap 挂载过程中，框架已注册：
 - CORS
 - loggingMiddleware / businessLoggingMiddleware / databaseLoggingMiddleware
 - frameworkErrorMiddleware（框架级错误处理中间件）

package/template/.cursor/rules/80-backend-utils-and-libs.skill.md

@@ -4,8 +4,9 @@ alwaysApply: false
 # Skill：libs 与 utils 规划规范
 
 ## 适用与触发（重要）
+
 - 当需要新增/调整以下内容时启用本 Skill：
-  - `src/libs/**` 下的类库/适配层
+  - 共享适配/可抽包的代码（优先使用 `dp-koa-framework-libs`；仅临时代码可放业务模块内）
   - `src/utils/**` 下的工具函数
   - 业务模块内部的 `xxx.utils.ts`
 
@@ -19,9 +20,10 @@ alwaysApply: false
 
 ---
 
-## 二、`src/libs/**` 放什么（必须）
+## 二、共享适配/可抽包代码放什么（必须）
+
+### 2.1 适合的内容
 
-### 2.1 适合放在 libs 的内容
 - **第三方服务适配/封装**：
   - 如：短信服务封装、支付网关封装、HTTP SDK 封装等
   - 对外暴露一个干净的接口：如 `sendSms(phone, templateId, params)`
@@ -30,15 +32,66 @@ alwaysApply: false
 - **有内部状态或生命周期的组件**：
   - 连接池包装器、复杂缓存管理器、网关客户端等
 
-### 2.2 不适合放在 libs 的内容
+### 2.2 不适合放到共享适配层的内容
+
 - 单一的小工具函数（字符串、日期、数字转换等）
 - 强业务耦合的逻辑（如订单价格计算、业务规则判断）
 
+### 2.3 框架库内置工具（缓存/短信/验证码等）（重点）
+当你需要使用“框架已经内置好的工具”，优先直接从 `dp-koa-framework-libs` 导入稳定导出；其中**缓存**建议按业务通过 `createCache + CacheType` 创建你的“业务缓存”对象。
+
+#### 2.3.1 缓存工具：用 `createCache` + `CacheType` 构建你的缓存
+- 核心提供缓存工厂：`createCache(name, type, customConfig?)`（配合 `CacheType`）
+- 你可以完全参考 `dp-koa-framework-libs/src/libs/mCache.ts`（1-8 行）的写法，在你自己的 `libs/` 里创建“业务自定义缓存对象”
+- 注意：`name` 作为全局缓存标识，同名会复用已有缓存实例（避免重复创建）
+- `CacheType` 用于选择默认 TTL/容量策略（来自 `dp-koa-framework-core` 缓存模块默认配置）：
+  - `CacheType.USER`：用户缓存（默认 `stdTTL=1800` 秒，`maxKeys=500`）
+  - `CacheType.CONTROLLER`：控制器结果缓存（默认 `stdTTL=60` 秒，`maxKeys=2000`）
+  - `CacheType.SESSION`：会话缓存（默认 `stdTTL=3600` 秒，`maxKeys=1000`）
+  - `CacheType.CAPTCHA`：验证码缓存（默认 `stdTTL=300` 秒，`maxKeys=100`）
+  - `CacheType.TEMP`：临时缓存（默认 `stdTTL=60` 秒，`maxKeys=100`）
+- `customConfig` 的行为：会在“默认配置（DEFAULT_CACHE_CONFIG）+ CacheType 配置”基础上进行合并，从而覆盖 `stdTTL/maxKeys/checkperiod/...` 等参数
+
+```ts
+import { createCache, CacheType } from "dp-koa-framework-core";
+
+// 例：给当前业务域创建一个“用户缓存”
+export const myUserCache = createCache("my-user", CacheType.USER, {
+  stdTTL: 600, // 10分钟过期（秒）
+  maxKeys: 500, // 用户缓存最大条目数
+});
+```
+
+使用方式示例（以 `node-cache` 风格的 `get/set` 为准）：
+```ts
+import { myUserCache } from "@src/libs/myUserCache"; // 示例：把 myUserCache 放到你的 libs 文件并导出
+
+const cached = myUserCache.get(String(userId));
+if (!cached) {
+  const value = await buildValue();
+  myUserCache.set(String(userId), value); // TTL 由 createCache 配置决定
+}
+```
+
+#### 2.3.2 其它常用内置工具（快速导入）
+- 验证码：`CaptchaGenerator`
+- 短信：
+  - `TencentSms`（类）
+  - `tencentSms`（函数/实例）
+- 邮件：`AokEmailSender`
+- COS/文件：
+  - `isCosConfigured`
+  - `uploadToCos`
+  - `getFilePublicUrl`
+  - `webofficeCosKey`
+- 通用业务校验：`ServiceValidate`
+
 ---
 
-## 三、`src/utils/**` 放什么（必须）
+## 三、`src/utils/`** 放什么（必须）
 
 ### 3.1 适合放在 utils 的内容
+
 - **与业务无关的纯函数工具**：
   - 时间、字符串、数字处理
   - 通用 Promise/重试/节流/防抖等
@@ -46,6 +99,7 @@ alwaysApply: false
   - 例如：框架级测试数据初始化工具、通用校验帮助函数（若确实需要全局可见）
 
 ### 3.2 不适合放在 utils 的内容
+
 - 直接访问数据库的函数（应放 Service/Repository 或框架层 utils 内聚）
 - 调用第三方 HTTP API 的函数（应放 libs 作为适配层）
 - 仅服务单一业务模块的工具（应放在该模块内部的 `xxx.utils.ts`）
@@ -60,6 +114,7 @@ alwaysApply: false
   - `src/service/goods/goods.utils.ts`
 
 规则：
+
 - 仅供本模块使用的业务工具函数，应优先放在模块自身的 utils 文件中
 - 全局 `utils/` 仅存放 **跨模块通用** 的工具
 
@@ -70,13 +125,13 @@ alwaysApply: false
 新增工具/类库时，按以下顺序判断：
 
 1. **是否依赖第三方服务/外部系统或有复杂状态？**
-   - 是 → 优先放 `libs/`（适配层/小 SDK）
+  - 是 → 优先放共享适配层（`dp-koa-framework-libs` 或独立 npm 包）
 2. **是否明显只服务某一个业务模块？**
-   - 是 → 放到该模块自己的 `xxx.utils.ts`
+  - 是 → 放到该模块自己的 `xxx.utils.ts`
 3. **是否 100% 纯函数、无状态且可跨多个模块复用？**
-   - 是 → 放到全局 `utils/`
+  - 是 → 放到全局 `utils/`
 4. **未来是否有机会抽为独立 npm 包？**
-   - 是 → 更倾向放 `libs/`
+  - 是 → 更倾向放共享适配层（`dp-koa-framework-libs` 或独立 npm 包）
 
 ---
 
@@ -91,15 +146,17 @@ alwaysApply: false
 
 ---
 
-## 七、框架级 `src/framework/utils/function.ts`（必须）
+## 七、运行环境判定（必须）
 
-本文件提供**运行环境判定**，全项目应统一使用，避免散落 `NODE_ENV === 'production'` 判断。
+应统一使用 `dp-koa-framework-core` 导出的**运行环境判定** API，避免散落 `NODE_ENV === 'production'` 判断。
 
-| API | 含义 |
-|-----|------|
-| `isDebug()` | `process.argv` 含 `--env=debug` 为 `true` |
+
+| API                            | 含义                                                       |
+| ------------------------------ | -------------------------------------------------------- |
+| `isDebug()`                    | `process.argv` 含 `--env=debug` 为 `true`                  |
 | `getRuntimeEnvironmentLabel()` | `'development'`（debug）或 `'production'`（非 debug），用于日志/元数据 |
 
+
 **约定**：
 
 - **非 debug = 生产口径**（迁移、静态缓存策略、对外错误信息是否脱敏等）。

package/template/.cursor/rules/85-backend-plugins.rule.md

@@ -8,7 +8,7 @@
 
 - 插件统一放在 `src/plugins/<plugin-id>/` 目录下。
 - 插件根目录只保留 `index.ts`（插件入口）。
-- 插件入口必须导出一个 `PluginDescriptor`（见 `src/framework/plugins/types.ts`）。
+- 插件入口必须导出一个 `PluginDescriptor`（见 `dp-koa-framework-core` 的 `PluginDescriptor` 类型）。
 
 推荐目录结构：
 
@@ -39,10 +39,10 @@
 
 ## 3. 插件注册与加载
 
-- 插件注册表：`src/framework/plugins/registry.ts`
+- 插件注册表：`src/plugins/registry.ts`
 - 宿主启动接入点：`src/app.ts`
-  - beforeBootstrap：计算启用插件、执行插件 before hook、注册插件路由、合并插件实体后初始化 DB
-  - afterBootstrap：执行插件 after hook（定时任务/订阅等）
+  - before：计算启用插件、执行插件 `onBeforeBootstrap` hook、注册插件路由、合并插件实体后初始化 DB
+  - after：执行插件 `onAfterBootstrap` hook（定时任务/订阅等）
 
 ---
 

package/template/.cursor/rules/90-backend-testing.skill.md

@@ -20,6 +20,32 @@ alwaysApply: false
 - 测试必须相互独立
 - 每个测试前重置数据
 
+## 二.2 涉及数据库读写的 Service 测试：必须使用内存数据库
+
+- 如果测试中调用的 Service（或其依赖）会发生数据库读写（查询/插入/更新/删除、事务、迁移/初始化等）：
+  - 必须启用内存数据库模式：通过 `TestDatabaseHelper.initTestDatabase(...)` 初始化测试用 `DataSource`
+  - 必须在测试结束后清理：调用 `TestDatabaseHelper.cleanupTestDatabase()`（确保释放资源，并清理缓存）
+- 禁止为了“方便”而只模拟数据：
+  - 不允许用简单对象/假 Repository 来替代数据库读写（会掩盖 SQL/实体映射/事务边界问题）
+  - 允许 mock 的范围：仅限非数据库行为（如外部 HTTP 调用、消息发送、第三方 SDK 等）
+
+---
+
+## 二.1 测试是否发“真实 HTTP”（需要理解）
+
+- `test/controllers/**`：Controller 单元测试
+  - 通常是 `new Controller()` 后直接调用 controller 方法
+  - 不会触发真实的 `app.listen` 端口监听
+  - 这是在验证“编排/返回结构/装饰器效果（mock 情况）”的正确性
+
+- `test/plugins/**` / `test/integration/**`：路由/插件集成测试
+  - 会创建 `Koa` + `router`
+  - 通过 `supertest` 调用 `request(app.callback()).get/post/...`
+  - 走完整 Koa 路由链路，但仍是“in-memory callback”，**不需要也不建议**真实 `app.listen`
+
+原则：
+- 测试环境不要 `app.listen` 开端口（避免端口占用、慢、难复现）
+
 ---
 
 ## 三、测试文件结构

package/template/.cursor/rules/README.md

@@ -37,8 +37,8 @@
 
 ### 80 - 工程结构（按需启用）
 - **`80-backend-utils-and-libs.skill.md`**
-  - `src/libs` vs `src/utils` 的放置规则与决策清单
-  - `src/framework/utils/function.ts`：`isDebug()` / `getRuntimeEnvironmentLabel()` 约定
+  - 共享适配/可抽包代码的放置策略（与 `dp-koa-framework-libs` 对齐）
+  - 运行环境判定：使用 `dp-koa-framework-core` 导出的 `isDebug()` / `getRuntimeEnvironmentLabel()`（不要引用本地 `src/framework` 文件）
 
 ### 90 - 测试（按需启用）
 - **`90-backend-testing.skill.md`**

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

@@ -43,13 +43,14 @@ export class BaseController {
 #### 1.1.2 `@State()`：读取整段 `ctx.state`
 
 ```ts
-import { Get, State } from '@src/framework/decorator/controller';
+import { Get, State } from 'dp-koa-framework-core';
 import { BaseController, ControllerResponse } from '@src/controllers/base.controller';
+import type { AppCtxState } from '@src/types/ctxState';
 
 export class ExampleStateController extends BaseController {
   @Get('/example/state-full')
   async getWithFullState(
-    @State() state: { user: { userId: number; type?: number } },
+    @State() state: AppCtxState,
   ): Promise<ControllerResponse<{ userId: number }>> {
     return this.success({ userId: state.user.userId });
   }
@@ -59,13 +60,14 @@ export class ExampleStateController extends BaseController {
 #### 1.1.3 `@State('user')`：只读 `ctx.state.user`
 
 ```ts
-import { Get, State } from '@src/framework/decorator/controller';
+import { Get, State } from 'dp-koa-framework-core';
 import { BaseController, ControllerResponse } from '@src/controllers/base.controller';
+import type { UserState } from '@src/types/ctxState';
 
 export class ExampleUserSliceController extends BaseController {
   @Get('/example/state-user')
   async getWithUser(
-    @State('user') user: { userId: number; type?: number },
+    @State('user') user: UserState,
   ): Promise<ControllerResponse<{ ok: boolean }>> {
     return this.success({ ok: user.userId > 0 });
   }
@@ -75,8 +77,9 @@ export class ExampleUserSliceController extends BaseController {
 #### 1.1.4 `@ResponseValidateIf`：仅在条件成立时校验响应体
 
 ```ts
-import { Get, State, ResponseValidateIf } from '@src/framework/decorator/controller';
+import { Get, State, ResponseValidateIf } from 'dp-koa-framework-core';
 import { BaseController, ControllerResponse } from '@src/controllers/base.controller';
+import type { AppCtxState } from '@src/types/ctxState';
 
 // 示例 DTO：按实际接口替换
 class UserProfileResponseDto {
@@ -88,7 +91,7 @@ export class ExampleResponseValidateController extends BaseController {
   @ResponseValidateIf(UserProfileResponseDto, (data) => Boolean(data && data.data))
   @Get('/example/profile')
   async getProfile(
-    @State() state: { user: { userId: number } },
+    @State() state: AppCtxState,
   ): Promise<ControllerResponse<UserProfileResponseDto | null>> {
     return this.success({
       id: state.user.userId,
@@ -102,13 +105,13 @@ export class ExampleResponseValidateController extends BaseController {
 目标：DTO 入参 → 调用 Service → 统一响应（`success/fail`）→ try/catch + logger
 
 ```ts
-import { Get, Post, Query, Body, State, ResponseCode, ResponseHeader } from '@src/framework/decorator/controller';
+import { Get, Post, Query, Body, State, ResponseCode, ResponseHeader } from 'dp-koa-framework-core';
 import { BaseController, ControllerResponse } from '@src/controllers/base.controller';
 import { Inject } from 'dp-ioc2';
-import { logger } from '@src/framework/utils/logger';
+import { logger } from 'dp-koa-framework-core';
 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';
+import { CommonServiceResultCode } from 'dp-koa-framework-core';
 
 export class SomeController extends BaseController {
   @Inject(SomeService)

package/template/.trae/skills/21-backend-service.skill.md

@@ -132,4 +132,18 @@ alwaysApply: false
 ## 六、调用关系约束（必须）
 - Controller 只能调用 Service 的公开方法，不应调用 Repository
 - Service 不应调用 Controller，也不应依赖 Koa `Context`
-- Service 之间如需调用，应通过依赖注入（`@Inject(OtherService)`），避免静态调用/循环依赖
+- Service 之间如需调用，应通过依赖注入（`@Inject(OtherService)`），避免静态调用/循环依赖
+- 禁止在 Service 内手动创建实例：
+  - ❌ 禁止 `new OtherService()` / `new XxxService()`（包括在方法内部临时 new）
+  - ❌ 禁止通过手写单例/缓存实例绕过 IoC 容器
+  - ✅ 必须依赖 dp-ioc2 在运行期注入（例如字段注入或构造注入）
+- 推荐写法（字段注入示例）：
+  ```ts
+  import { Inject } from "dp-ioc2";
+  import { OtherService } from "./other.service";
+
+  export class MyService extends BaseService {
+    @Inject(OtherService)
+    private otherService!: OtherService;
+  }
+  ```

package/template/.trae/skills/40-backend-error-logging.skill.md

@@ -6,11 +6,15 @@ alwaysApply: false
 ## 一、错误处理
 
 - 所有 async 方法必须 try/catch
-- 业务错误：
-  - 使用 `CommonServiceResult.fail()`
-- 系统错误：
-  - 记录日志
-  - 返回通用失败响应
+- 业务错误（可预期、可分类）：
+  - 主要在 **Service 层 catch 中**处理
+  - 返回 `CommonServiceResult.fail()/validationError/notFound/...`（由 Service 统一封装）
+- 系统错误（不可预期、疑似异常）：
+  - **必须记录日志（logger.error）**
+  - Service 层返回通用失败的 `CommonServiceResult.error(...)`
+- 映射到 Controller：
+  - Controller 不应直接返回 `CommonServiceResult`
+  - Controller 必须把 Service 的 `CommonServiceResult` 通过 `this.success()/this.fail()` 映射为 `ControllerResponse`
 
 ---
 

package/template/.trae/skills/80-backend-utils-and-libs.skill.md

@@ -5,7 +5,7 @@ alwaysApply: false
 
 ## 适用与触发（重要）
 - 当需要新增/调整以下内容时启用本 Skill：
-  - `src/libs/**` 下的类库/适配层
+  - 共享适配/可抽包的代码（优先使用 `dp-koa-framework-libs`；仅临时代码可放业务模块内）
   - `src/utils/**` 下的工具函数
   - 业务模块内部的 `xxx.utils.ts`
 
@@ -19,9 +19,9 @@ alwaysApply: false
 
 ---
 
-## 二、`src/libs/**` 放什么（必须）
+## 二、共享适配/可抽包代码放什么（必须）
 
-### 2.1 适合放在 libs 的内容
+### 2.1 适合的内容
 - **第三方服务适配/封装**：
   - 如：短信服务封装、支付网关封装、HTTP SDK 封装等
   - 对外暴露一个干净的接口：如 `sendSms(phone, templateId, params)`
@@ -30,15 +30,67 @@ alwaysApply: false
 - **有内部状态或生命周期的组件**：
   - 连接池包装器、复杂缓存管理器、网关客户端等
 
-### 2.2 不适合放在 libs 的内容
+### 2.2 不适合放到共享适配层的内容
 - 单一的小工具函数（字符串、日期、数字转换等）
 - 强业务耦合的逻辑（如订单价格计算、业务规则判断）
 
 ---
 
-## 三、`src/utils/**` 放什么（必须）
+### 2.3 框架库内置工具（缓存/短信/验证码等）（重点）
+当你需要使用“框架已经内置好的工具”，优先直接从 `dp-koa-framework-libs` 导入稳定导出；其中**缓存**建议按业务通过 `createCache + CacheType` 创建你的“业务缓存”对象。
+
+#### 2.3.1 缓存工具：用 `createCache` + `CacheType` 构建你的缓存
+- 核心提供缓存工厂：`createCache(name, type, customConfig?)`（配合 `CacheType`）
+- 你可以完全参考 `dp-koa-framework-libs/src/libs/mCache.ts`（1-8 行）的写法，在你自己的 `libs/` 里创建“业务自定义缓存对象”
+- 注意：`name` 作为全局缓存标识，同名会复用已有缓存实例（避免重复创建）
+- `CacheType` 用于选择默认 TTL/容量策略（来自 `dp-koa-framework-core` 缓存模块默认配置）：
+  - `CacheType.USER`：用户缓存（默认 `stdTTL=1800` 秒，`maxKeys=500`）
+  - `CacheType.CONTROLLER`：控制器结果缓存（默认 `stdTTL=60` 秒，`maxKeys=2000`）
+  - `CacheType.SESSION`：会话缓存（默认 `stdTTL=3600` 秒，`maxKeys=1000`）
+  - `CacheType.CAPTCHA`：验证码缓存（默认 `stdTTL=300` 秒，`maxKeys=100`）
+  - `CacheType.TEMP`：临时缓存（默认 `stdTTL=60` 秒，`maxKeys=100`）
+- `customConfig` 的行为：会在“默认配置（DEFAULT_CACHE_CONFIG）+ CacheType 配置”基础上进行合并，从而覆盖 `stdTTL/maxKeys/checkperiod/...` 等参数
+
+```ts
+import { createCache, CacheType } from "dp-koa-framework-core";
+
+// 例：给当前业务域创建一个“用户缓存”
+export const myUserCache = createCache("my-user", CacheType.USER, {
+  stdTTL: 600, // 10分钟过期（秒）
+  maxKeys: 500, // 用户缓存最大条目数
+});
+```
+
+使用方式示例（以 `node-cache` 风格的 `get/set` 为准）：
+```ts
+import { myUserCache } from "@src/libs/myUserCache"; // 示例：把 myUserCache 放到你的 libs 文件并导出
+
+const cached = myUserCache.get(String(userId));
+if (!cached) {
+  const value = await buildValue();
+  myUserCache.set(String(userId), value); // TTL 由 createCache 配置决定
+}
+```
+
+#### 2.3.2 其它常用内置工具（快速导入）
+- 验证码：`CaptchaGenerator`
+- 短信：
+  - `TencentSms`（类）
+  - `tencentSms`（函数/实例）
+- 邮件：`AokEmailSender`
+- COS/文件：
+  - `isCosConfigured`
+  - `uploadToCos`
+  - `getFilePublicUrl`
+  - `webofficeCosKey`
+- 通用业务校验：`ServiceValidate`
+
+---
+
+## 三、`src/utils/`** 放什么（必须）
 
 ### 3.1 适合放在 utils 的内容
+
 - **与业务无关的纯函数工具**：
   - 时间、字符串、数字处理
   - 通用 Promise/重试/节流/防抖等
@@ -70,13 +122,13 @@ alwaysApply: false
 新增工具/类库时，按以下顺序判断：
 
 1. **是否依赖第三方服务/外部系统或有复杂状态？**
-   - 是 → 优先放 `libs/`（适配层/小 SDK）
+   - 是 → 优先放共享适配层（`dp-koa-framework-libs` 或独立 npm 包）
 2. **是否明显只服务某一个业务模块？**
    - 是 → 放到该模块自己的 `xxx.utils.ts`
 3. **是否 100% 纯函数、无状态且可跨多个模块复用？**
    - 是 → 放到全局 `utils/`
 4. **未来是否有机会抽为独立 npm 包？**
-   - 是 → 更倾向放 `libs/`
+   - 是 → 更倾向放共享适配层（`dp-koa-framework-libs` 或独立 npm 包）
 
 ---
 
@@ -87,4 +139,21 @@ alwaysApply: false
   - 导出：优先导出类或工厂函数，如 `export class TencentSmsClient { ... }`
 - `utils` 目录下：
   - 文件名：`date.utils.ts` / `string.utils.ts` / `testDataInitializer.ts` 等
-  - 导出：纯函数 `export function xxx(...) { ... }`
+  - 导出：纯函数 `export function xxx(...) { ... }`
+
+---
+
+## 七、运行环境判定（必须）
+
+应统一使用 `dp-koa-framework-core` 导出的**运行环境判定** API，避免散落 `NODE_ENV === 'production'` 判断。
+
+| API                            | 含义                                                       |
+| ------------------------------ | -------------------------------------------------------- |
+| `isDebug()`                    | `process.argv` 含 `--env=debug` 为 `true`                  |
+| `getRuntimeEnvironmentLabel()` | `'development'`（debug）或 `'production'`（非 debug），用于日志/元数据 |
+
+**约定**：
+
+- **非 debug = 生产口径**（迁移、静态缓存策略、对外错误信息是否脱敏等）。
+- **不要**单独用 `NODE_ENV` 替代上述判定；`NODE_ENV=test` 仅用于 Jest 等测试分支。
+- 新增种子脚本若需读 `.env.development`，启动命令应带 `--env=debug`（与 `bootstrap` 一致）。

package/template/.trae/skills/90-backend-testing.skill.md

@@ -20,6 +20,32 @@ alwaysApply: false
 - 测试必须相互独立
 - 每个测试前重置数据
 
+## 二.2 涉及数据库读写的 Service 测试：必须使用内存数据库
+
+- 如果测试中调用的 Service（或其依赖）会发生数据库读写（查询/插入/更新/删除、事务、迁移/初始化等）：
+  - 必须启用内存数据库模式：通过 `TestDatabaseHelper.initTestDatabase(...)` 初始化测试用 `DataSource`
+  - 必须在测试结束后清理：调用 `TestDatabaseHelper.cleanupTestDatabase()`（确保释放资源，并清理缓存）
+- 禁止为了“方便”而只模拟数据：
+  - 不允许用简单对象/假 Repository 来替代数据库读写（会掩盖 SQL/实体映射/事务边界问题）
+  - 允许 mock 的范围：仅限非数据库行为（如外部 HTTP 调用、消息发送、第三方 SDK 等）
+
+---
+
+## 二.1 测试是否发“真实 HTTP”（需要理解）
+
+- `test/controllers/**`：Controller 单元测试
+  - 通常是 `new Controller()` 后直接调用 controller 方法
+  - 不会触发真实的 `app.listen` 端口监听
+  - 这是在验证“编排/返回结构/装饰器效果（mock 情况）”的正确性
+
+- `test/plugins/**` / `test/integration/**`：路由/插件集成测试
+  - 会创建 `Koa` + `router`
+  - 通过 `supertest` 调用 `request(app.callback()).get/post/...`
+  - 走完整 Koa 路由链路，但仍是“in-memory callback”，**不需要也不建议**真实 `app.listen`
+
+原则：
+- 测试环境不要 `app.listen` 开端口（避免端口占用、慢、难复现）
+
 ---
 
 ## 三、测试文件结构

package/template/src/types/ctxState.ts

@@ -0,0 +1,9 @@
+export interface UserState {
+  userId: number;
+  type?: number;
+}
+
+export interface AppCtxState {
+  user: UserState;
+}
+