create-dp-koa 1.1.3 → 1.1.5

package/package.json

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

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

@@ -12,91 +12,11 @@ alwaysApply: false
 
 ## 一、写 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.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
@@ -117,9 +37,9 @@ export class SomeController extends BaseController {
   @Get('/some/path')
   @ResponseCode(200)
   async getSomething(
-    @Query(SomeQueryDto) query: SomeQueryDto,
+    @Query() query: SomeQueryDto,
     @State('user') user: { userId: number; type?: number },
-  ): Promise<ControllerResponse<any>> {
+  ): Promise<ControllerResponse<SomeResponseDto>> {
     try {
       const result = await this.someService.someMethod(query, user.userId);
       if (result.code !== CommonServiceResultCode.SUCCESS) {
@@ -139,6 +59,7 @@ export class SomeController extends BaseController {
 - Controller **不直接访问数据库/Repository**
 - Controller **不 return Service 原始结果**，必须映射 `success/fail`
 - Controller `async` **必须 try/catch**
+!- Controller 的返回类型 `ControllerResponse<T>` **必须显式指定 T，禁止使用 `any`**
 
 ---
 
@@ -151,15 +72,18 @@ export class SomeController extends BaseController {
 ### 2.2 参数注解（重点）
 - **`@Query()`**：
   - 读取 query 参数
-  - 推荐写法：`@Query(SomeQueryDto) query: XxxQueryDto`
+  - 推荐写法：`@Query() query: XxxQueryDto`
 - **`@Body()`**：
   - 读取 body 参数
-  - 推荐写法：`@Body(SomeBodyDto) body: XxxBodyDto`
+  - 推荐写法：`@Body() body: XxxBodyDto`
+- **`@Params()`**：
+  - 读取路径参数（如 `/:id`、`/:id/files/:fileId`）
+  - 推荐写法：`@Params(ParamsDto) params: XxxParamsDto`
 - **`@State()`**：
-  - 读取整个 `ctx.state`（样例：见 **1.1.2**）
+  - 读取整个 `ctx.state`（样例：`ytUser.controller.ts`）
   - 推荐写法：`@State() state: { user: { userId: number; type?: number } }`
 - **`@State('user')`**：
-  - 读取 `ctx.state.user`（样例：见 **1.1.3**）
+  - 读取 `ctx.state.user`（样例：`NewAnnotationExampleController.ts`）
   - 推荐写法：`@State('user') user: { userId: number; type?: number }`
 
 禁止：
@@ -171,7 +95,7 @@ export class SomeController extends BaseController {
 
 ### 2.4 响应校验注解（进阶，按需）
 - **`@ResponseValidator(DtoClass, objectKey?)`**：对响应数据做校验
-- **`@ResponseValidateIf(DtoClass, fn)`**：仅当 fn 返回真时才校验（样例：见 **1.1.4**）
+- **`@ResponseValidateIf(DtoClass, fn)`**：仅当 fn 返回真时才校验（样例：`ytUser.controller.ts`）
 
 ---
 
@@ -181,8 +105,9 @@ export class SomeController extends BaseController {
 - `@Get('/xxx') + @State('user')`（或 `@State()` 取整段 state）
 
 ### 3.2 带 body 的 POST 接口
-- `@Post('/xxx') + @Body(SomeBodyDto) body: SomeBodyDto + @ResponseCode(201)`
+- `@Post('/xxx') + @Body() body: Dto + @ResponseCode(201)`
 
 ### 3.3 需要自定义 header
 - `@ResponseHeader('X-XXX', 'value')`
 
+

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

@@ -199,8 +199,9 @@ async createUser(@Body(CreateUserControllerDto) body: CreateUserControllerDto) {
 - 常用装饰器：`@IsString()`, `@IsEmail()`, `@IsNotEmpty()`, `@MinLength()`, `@IsOptional()` 等
 
 ### 4.2 Controller DTO 特殊处理
-- 可以使用 `@Transform` 进行数据转换（如字符串转数字、trim）
-- 可以包含 HTTP 层特定的字段（如 `vcodeToken`、`requestId`）
+- **@Transform 必须使用 class-transformer**：Controller 参数绑定走 `plainToInstance`，只有 **class-transformer** 的 `@Transform` 会生效。须 `import { Transform } from 'class-transformer'`，**不要**使用框架 `@src/framework/decorator/controller` 的 Transform（后者不参与 plainToInstance，会不生效）。
+- 使用 `@Transform(({ value }) => yourTransform(value))` 进行数据转换（如逗号分隔字符串转数组、trim、自定义转 number）。
+- 可以包含 HTTP 层特定字段（如 `vcodeToken`、`requestId`）。
 
 ### 4.3 Service DTO 要求
 - **禁止**包含 HTTP 层特性（如 `@Transform`、HTTP 特定字段）
@@ -209,17 +210,30 @@ async createUser(@Body(CreateUserControllerDto) body: CreateUserControllerDto) {
 
 ### 4.4 示例对比
 
-#### Controller DTO（包含 HTTP 层转换）
+#### Controller DTO（包含 HTTP 层转换，使用 class-transformer）
 ```typescript
+import { Transform } from 'class-transformer';
+
 export class CreateUserControllerDto {
-    @Transform((val) => Trim(String(val)))
+    @Transform(({ value }) => (typeof value === 'string' ? value.trim() : value))
     @IsString()
     @IsEmail()
     email: string;
     
-    @Transform((val) => Number(val))
-    @IsNumber()
-    age: number;
+    // number 可由 enableImplicitConversion 自动转，无需 @Transform；若需自定义再用：
+    @Transform(({ value }) => (value != null && value !== '' ? Number(value) : undefined))
+    @IsOptional()
+    @IsInt()
+    age?: number;
+}
+
+// Query 中单字符串/逗号分隔转数组示例
+export class QueryDto {
+    @Transform(({ value }) => toTagsArray(value))  // 如 "a,b" -> ["a","b"]，已是数组则原样
+    @IsOptional()
+    @IsArray()
+    @IsString({ each: true })
+    tags?: string[];
 }
 ```
 
@@ -235,6 +249,14 @@ export class CreateUserServiceDto {
 }
 ```
 
+### 4.5 class-transformer 与 Controller 参数转换（框架内置）
+
+- **框架行为**：对 `@Body(Dto)` / `@Query(Dto)` / `@Params(Dto)`，框架（dp-koa-framework）会使用 **class-transformer** 的 `plainToInstance(Dto, data, { enableImplicitConversion: true })` 从原始请求数据构建 DTO 实例，再经 **class-validator** 校验；校验通过后将该实例写回控制器参数，因此控制器方法收到的是**已转换且已校验的 DTO 实例**，而非原始 `ctx.body` / `ctx.query` / `ctx.params`。
+- **Query/Params 类型**：HTTP Query 与 Params 均为字符串。启用 `enableImplicitConversion` 后，DTO 中声明为 `number` 的字段（如 `page`、`pageSize`）会自动从字符串转为数字，**无需**在 Controller DTO 上为每个字段写 `@Transform`。
+- **适用范围**：仅对 **Body、Query、Params** 做转换与校验；**State、Headers** 不经过 plainToInstance，保持原样传入。
+- **自定义转换**：若需更细粒度控制（如逗号分隔字符串转数组、trim），在 Controller DTO 上使用 **class-transformer** 的 `@Transform`：`import { Transform } from 'class-transformer'`，写法为 `@Transform(({ value }) => yourFn(value))`，在 plainToInstance 时自动应用。
+- **DtoValidator**：在 Service 层手动调用 `DtoValidator.validate` 时，框架同样使用 `plainToInstance` + `enableImplicitConversion`，与上述参数绑定行为一致。
+
 ---
 
 ## 五、校验流程

package/template/.cursor/rules/31-backend-vo.skill.md

@@ -0,0 +1,48 @@
+---
+alwaysApply: false
+---
+
+# Skill：后端 VO 规范
+
+## 适用与触发
+
+- 当你需要新增/修改 `src/vo/**` 下的 VO 类型定义时启用本 Skill
+- 目标：确保 VO 定义在统一位置、命名和使用方式符合项目约定，方便前端/AI 端稳定索引
+
+---
+
+## 一、VO 定义定位（必须）
+
+- VO（View Object）用于跨层返回/展示的“结构类型”
+- VO 不承担运行时校验职责：不使用 `class-validator` 装饰器
+- VO 定义不包含数据库/事务/业务逻辑，只描述字段结构
+
+---
+
+## 二、目录结构（必须遵守）
+
+```
+src/vo/
+└── {module}/
+    └── {name}.vo.ts
+```
+
+示例：
+- `src/vo/im/im.vo.ts`
+
+---
+
+## 三、命名规范（必须）
+
+- 类型名后缀：以 `Vo` 结尾，例如 `ImConversationVo`
+- 字段结构：使用 `export type XxxVo = { ... }`（推荐）或 `export interface XxxVo { ... }`
+- 文件命名：以模块语义为主，建议 `{module}.vo.ts`
+
+---
+
+## 四、使用规范
+
+- Controller / Service 引用 VO 类型时使用 `import type ...`，避免引入无意义的运行时依赖
+- VO 类型只作为返回结构类型使用（例如 `ControllerResponse<ImMessageVo>`、`CommonServiceResult<ImMessageVo>`）
+- 映射逻辑（Entity/领域模型 -> VO）可以写在 Service 私有方法中；但 VO 的“定义本体”必须在 `src/vo/` 中维护
+

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

@@ -1,65 +1,307 @@
-# 后端插件体系规范（dp-koa-framework 模板）
+# 后端插件体系规范（dp-koa-framework）
 
-> 目标：让“独立功能体”以插件形式存在，可插拔、易维护、与宿主框架低耦合。
+> 目标：让类似 `weboffice` 的“独立功能体”以插件形式存在，可插拔、易维护、与宿主框架低耦合。
 
 ---
 
 ## 1. 插件的基本形态
 
+- 插件是**独立功能域**：可以包含路由、Service、实体/迁移、脚本，但通过统一接口暴露给宿主。
 - 插件统一放在 `src/plugins/<plugin-id>/` 目录下。
-- 插件根目录只保留 `index.ts`（插件入口）。
-- 插件入口必须导出一个 `PluginDescriptor`（见 `src/framework/plugins/types.ts`）。
+- 插件入口文件：`src/plugins/<plugin-id>/index.ts`，必须导出一个 `PluginDescriptor`：
 
-推荐目录结构：
+```ts
+import type { PluginDescriptor } from "@src/framework/plugins/types";
 
-- `src/plugins/<plugin-id>/index.ts`
-- `src/plugins/<plugin-id>/core/`：类型、错误、上下文解析、纯函数工具
-- `src/plugins/<plugin-id>/http/`：HTTP 路由入口（Koa Router）
-- `src/plugins/<plugin-id>/entities/`：TypeORM 实体（插件自有表）
-- `src/plugins/<plugin-id>/services/`：插件业务 Service
-- `src/plugins/<plugin-id>/scripts/`：种子/运维脚本（可选）
+export const plugin: PluginDescriptor = {
+  id: "weboffice",
+  displayName: "WPS WebOffice 集成",
+  enabled: (env) => env.WEBOFFICE_ENABLED !== "0",
+  registerRoutes(router) {
+    // 注册本插件路由
+  },
+  entities: [
+    // 插件自有实体
+  ],
+};
+```
 
 ---
 
-## 2. 宿主与插件的依赖方向
+## 2. PluginDescriptor 约定
 
-### 2.1 插件 → 宿主
+定义位置：`src/framework/plugins/types.ts`
 
-- 插件内部业务代码应优先使用相对路径组织。
-- 插件调用宿主业务能力（如用户、项目、权限）应通过 **plugin-api 门面层**（建议放在 `src/plugin-api/*`），避免直接 import 宿主 Service/Repository。
+关键字段：
 
-### 2.2 宿主 → 插件
+- `id: string`：插件唯一 ID，建议与目录名一致（如 `weboffice`）。
+- `displayName?: string`：可读名称，用于日志与管理界面。
+- `enabled?: boolean | (env: NodeJS.ProcessEnv) => boolean`：
+  - 未设置：默认启用；
+  - boolean：固定启/停；
+  - function：根据环境变量或配置动态启/停（如 `WEBOFFICE_ENABLED`）。
+- 生命周期钩子：
+  - `onBeforeBootstrap?(app: Koa)`：Koa 启动前执行，适合注册中间件、事件等。
+  - `onAfterBootstrap?(app: Koa)`：Koa 启动后执行，适合注册定时任务、订阅等。
+- 路由与实体：
+  - `registerRoutes?(router: Router)`：注册插件自己的 HTTP 路由。
+  - `entities?: Function[]`：插件自有 TypeORM 实体（仅包含插件表）。
 
-- 宿主禁止直接 import 插件 Service。
-- 宿主感知插件能力应通过：
-  - 事件扩展点（emit + register handler）
-  - SPI（可替换实现：getXxxSpi + registerXxxSpi）
+---
+
+## 3. 插件注册与加载流程
+
+### 3.1 注册表
+
+- 所有内置插件集中注册在 `src/framework/plugins/registry.ts`：
+
+```ts
+import { plugin as webofficePlugin } from "@src/plugins/weboffice";
+
+export const plugins: PluginDescriptor[] = [webofficePlugin];
+```
+
+- 框架提供辅助方法：
+  - `getEnabledPlugins()`：计算启用的插件（考虑 `enabled` 字段）。
+  - `collectPluginEntities(enabledPlugins)`：合并所有插件实体。
+  - `runBeforeBootstrapHooks(app, enabledPlugins)` / `runAfterBootstrapHooks(app, enabledPlugins)`：
+    串行执行插件生命周期钩子。
+  - `registerPluginRoutes(router, enabledPlugins)`：批量注册插件路由。
+
+### 3.2 与 bootstrap 集成（`src/app.ts`）
+
+- 在 `setBeforeBootstrap` 中：
+  - 计算启用的插件：`const enabledPlugins = getEnabledPlugins();`
+  - 将插件列表挂到 `app`（只读，用于调试或中间件）：`(app as any).plugins = enabledPlugins;`
+  - 调用 `runBeforeBootstrapHooks(app, enabledPlugins)`。
+  - 调用 `Router()` 注册宿主自身路由。
+  - 调用 `registerPluginRoutes(router, enabledPlugins)` 注册所有插件路由。
+  - 在数据库初始化前，合并实体：
+
+    ```ts
+    const allEntities = [...dbEntities, ...collectPluginEntities(enabledPlugins)];
+    const dbconfig = databaseConfigManager.getDatabaseConfig(allEntities);
+    ```
+
+- 在 `setAfterBootstrap` 中：
+  - 再次获取启用插件，调用 `runAfterBootstrapHooks(app, enabledPlugins)`。
+
+---
+
+## 4. 宿主与插件的依赖方向约束
+
+### 4.1 插件 → 宿主：只能通过 `plugin-api`
+
+- 插件 **禁止直接 import 项目的业务 Service**（如 `TaskService`、`ProjectService`）。
+- 宿主通过 `src/plugin-api/*` 暴露给插件一组稳定的门面函数/接口：
+
+  ```ts
+  // 例：task 相关 API（只示意）
+  export interface TaskPluginApi {
+    getById(id: number): Promise<TaskDto | null>;
+    addSystemComment(taskId: number, content: string): Promise<void>;
+  }
+
+  export const taskPluginApi: TaskPluginApi = {
+    // 内部实际调用 TaskService
+  };
+  ```
+
+- 插件内部只能 import `plugin-api`，例如：
+
+  ```ts
+  import { taskPluginApi } from "@src/plugin-api/taskApi";
+  await taskPluginApi.addSystemComment(taskId, "来自插件的系统备注");
+  ```
+
+### 4.2 宿主 → 插件：只通过“事件”和“SPI”
+
+- 宿主禁止直接依赖某个具体插件的 Service。
+- 向插件“要能力”的方式：
+  - **事件扩展点**（推荐，用于大多数“附加效果”）：
+
+    ```ts
+    export type CoreEvent =
+      | { type: "task.created"; payload: { taskId: number } }
+      | { type: "task.completed"; payload: { taskId: number } };
+
+    export type CoreEventHandler = (event: CoreEvent) => Promise<void> | void;
+
+    export function registerCoreEventHandler(h: CoreEventHandler): void;
+    export async function emitCoreEvent(event: CoreEvent): Promise<void>;
+    ```
+
+    - 核心 Service：`await emitCoreEvent({ type: "task.completed", payload: { taskId } });`
+    - 插件：在 `onAfterBootstrap` 或 `registerTasks` 中调用 `registerCoreEventHandler` 订阅事件。
+
+  - **SPI（Service Provider Interface，可替换实现）**：
+    - 适用于可替换能力（审计、搜索、文件存储等）。
+
+    ```ts
+    export interface AuditSpi {
+      writeLog(entry: { type: string; data: any }): Promise<void>;
+    }
+
+    export function registerAuditSpi(impl: AuditSpi): void;
+    export function getAuditSpi(): AuditSpi; // 总能返回一个实现（可为 Noop）
+    ```
+
+    - 宿主：`await getAuditSpi().writeLog(...);`
+    - 插件：实现 `AuditSpi` 并在初始化时 `registerAuditSpi(new MyAuditImpl())`。
+
+---
+
+## 5. 插件的数据库规范
+
+### 5.1 插件是否必须有数据库能力？
+
+否。按能力划分三类插件：
+
+1. **纯逻辑/集成插件**：不建表，仅消费宿主事件/HTTP/外部服务。
+2. **只读宿主数据插件**：通过 `plugin-api` 访问宿主表，不自建表。
+3. **带独立数据模型的重插件**：有自己的实体和迁移，但只操作自己的 schema。
+
+### 5.2 表与实体命名规范
+
+当插件需要自建表时：
+
+- 表名必须使用**插件 ID 作为前缀**：
+  - 插件 `weboffice`：
+    - 表：`weboffice_files`、`weboffice_file_versions`
+    - 索引：`IDX_weboffice_files_fileId`
+    - 外键：`FK_weboffice_file_versions_webofficeFileId`
+- TypeScript 实体命名也应包含插件前缀：
+  - 如：`WebofficeFileEntity`、`WebofficeFileVersionEntity`
+- 迁移文件名包含插件标识：
+  - 如：`1731600000000-WebofficeTables.ts`
+
+约束：
+
+- 插件迁移**原则上只操作自己前缀的表**；
+- 若必须修改宿主核心表结构，迁移应由宿主维护，插件只访问已经存在的字段。
+
+### 5.3 实体注册方式
+
+- 宿主核心实体集中在 `src/entity/index.ts`，**不包含插件实体**。
+- 插件实体通过 `PluginDescriptor.entities` 暴露，由 `collectPluginEntities(enabledPlugins)` 统一合并后交给 `DatabaseConfigManager`。
 
 ---
 
-## 3. 插件注册与加载
+## 6. 插件生命周期与卸载策略
 
-- 插件注册表：`src/framework/plugins/registry.ts`
-- 宿主启动接入点：`src/app.ts`
-  - beforeBootstrap：计算启用插件、执行插件 before hook、注册插件路由、合并插件实体后初始化 DB
-  - afterBootstrap：执行插件 after hook（定时任务/订阅等）
+### 6.1 安装插件
+
+1. 在 `src/plugins/<plugin-id>/` 下创建插件目录和 `index.ts`，导出 `PluginDescriptor`。
+2. 若有 DB：
+   - 在 `entities/` 下定义实体，并加入 `plugin.entities`。
+   - 在 `migrations/` 下定义迁移（放在全局 `src/migrations` 或插件子目录中，按项目规范处理）。
+3. 在 `framework/plugins/registry.ts` 将插件加入 `plugins` 数组。
+4. 重启服务，观察日志中的插件加载信息，确认路由与表生效。
+
+### 6.2 禁用插件（推荐默认“卸载”方式）
+
+- 在 `plugins/registry.ts` 中从 `plugins` 数组移除，或设置 `enabled: false` / 使用环境变量关闭。
+- 重启后：
+  - 插件不再注册路由；
+  - 不再订阅事件或注册 SPI；
+  - 插件相关数据表和数据仍保留，方便未来重新启用或迁移。
+
+### 6.3 物理卸载与数据清理（高风险，可选）
+
+- 不建议在正常启动流程自动执行“删库”操作。
+- 若必须清理插件数据，应通过**独立 CLI/脚本**实现。
+- 插件可选择在 `PluginDescriptor` 中额外导出卸载辅助方法（例如 `uninstall()`），仅供 CLI 调用，用于：
+  - 关闭外部订阅；
+  - 提供需要删除/归档的表信息等。
+- 所有物理卸载操作应当：
+  - 需要人工确认；
+  - 具备日志或变更记录，便于审计与回溯。
 
 ---
 
-## 4. 插件数据库规范
+## 7. 插件测试规范（单元 + 集成）
+
+目标：插件测试要**可复用、稳定、可在 CI 中长期运行**。遵循“测试金字塔”：
+
+- **单元测试（默认）**：覆盖插件 `core/*` 的纯函数/解析逻辑，不启动 Koa、不连接真实数据库。
+- **集成测试（少量但关键）**：覆盖插件对外契约（HTTP 路由、DB 交互），使用 Koa 最小实例 + SQLite 内存库。
+
+### 7.1 测试目录与命名
 
-- 插件自建表必须使用插件 ID 作为表名前缀（例如 `weboffice_files`、`weboffice_file_versions`）。
-- 插件迁移原则上只操作自身前缀表，避免修改宿主核心表结构。
+- 单元测试：`test/plugins/<plugin-id>/*.test.ts`
+- 集成测试：`test/plugins/<plugin-id>/*.int.test.ts`
+
+示例（weboffice）：
+
+- `test/plugins/weboffice/core.utils.test.ts`
+- `test/plugins/weboffice/core.context.test.ts`
+- `test/plugins/weboffice/http.routes.int.test.ts`
+
+### 7.2 单元测试边界
+
+- 仅测试插件内部逻辑（如字段规范化、上下文解析、参数转换）。
+- 禁止依赖：
+  - Koa app 启动
+  - TypeORM DataSource
+  - dp-ioc2 Provider 注入
+  - 外部服务（COS、第三方 HTTP）
+
+### 7.3 集成测试边界（推荐最小闭环）
+
+- 只启动最小 Koa + Router：
+
+  1. `const app = new Koa(); const router = new Router();`
+  2. `plugin.registerRoutes?.(router)`
+  3. `app.use(router.routes()).use(router.allowedMethods())`
+  4. 使用 `supertest` 对 `app.callback()` 发请求，断言 `code/data` 与关键字段
+
+- 数据库使用 SQLite 内存库（`:memory:`）：
+  - 通过 `TestDatabaseHelper.initTestDatabase({ extraEntities: [...] })` 将**插件实体追加**到宿主实体列表。
+  - 集成测试自行准备必要数据（seed 插件自己的表）。
+
+### 7.4 外部依赖与 ESM 包处理
+
+若插件依赖存在 Jest 解析问题的 ESM 包（典型：`uuid@13`），优先在测试中 mock：
+
+```ts
+jest.mock("uuid", () => ({ v4: () => "test-uuid" }));
+```
+
+原则：
+
+- **测试只关心插件对外行为**，不应被第三方包的模块格式（CJS/ESM）牵连。
+- 若确需验证第三方包行为，再考虑 Jest 转译配置或替换依赖。
+
+### 7.5 weboffice 集成测试最小断言建议
+
+- 至少覆盖：
+  - `GET /v3/3rd/files/:file_id/permission` 返回 `{ code: 0, data: { user_id, read, update, ... } }`
+  - `user_id` 应符合 WPS 规范（例如 `test-token` -> `test_token`）
 
 ---
 
-## 5. 示例插件：weboffice
+## 8. weboffice 插件作为示例
+
+当前模板框架中已经将 WebOffice 集成改造成首个插件示例：
+
+- 插件入口：`src/plugins/weboffice/index.ts`
+  - `id: "weboffice"`，`displayName: "WPS WebOffice 集成"`。
+  - `enabled: (env) => env.WEBOFFICE_ENABLED !== "0"`，可通过环境变量关闭。
+  - `registerRoutes` 复用插件内 `src/plugins/weboffice/http/routes.ts`，对接 WPS 回调网关。
+  - `entities` 包含 `WebofficeFileEntity` 与 `WebofficeFileVersionEntity`。
+- 数据表：
+  - `weboffice_files`、`weboffice_file_versions`，前缀即插件 ID。
+  - 迁移示例：`src/migrations/1731600000000-WebofficeTables.ts`。
 
-模板内置示例插件：`src/plugins/weboffice/`
+### weboffice 插件目录结构约定（示例）
 
-- 通过 `WEBOFFICE_ENABLED` 环境变量控制启用（默认启用；设为 `0` 禁用）。
-- 路由入口：`src/plugins/weboffice/http/routes.ts`
-- 插件实体：`src/plugins/weboffice/entities/*`
+- 根目录仅保留 `index.ts`（插件入口）
+- 其余代码按职责归档：
+  - `core/`：`types.ts`、`errors.ts`、`context.ts`、`utils.ts`
+  - `entities/`：TypeORM 实体
+  - `services/`：业务 Service
+  - `scripts/`：种子/运维脚本
+  - 其他入口文件（如路由）建议放在 `http/` 或保持在根目录 `routes.ts`（按团队偏好统一）
 
-> 注意：模板示例插件的 `getUsers` 为占位实现（不依赖宿主业务用户表）。真实业务接入时应改为通过 plugin-api 调宿主用户体系。
+新增插件时，强烈建议参考 weboffice 插件的结构与写法，保持一致的工程风格与解耦思路。
 

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

@@ -11,7 +11,85 @@ alwaysApply: false
 
 ---
 
-## 二、测试要求
+## 二、数据库相关测试（强制）
+
+**凡涉及数据库操作的 Service、Controller 测试，必须使用内存数据库进行测试。**
+
+- 涉及数据库操作：指测试会触发 TypeORM 的 Repository/QueryBuilder 调用（如 list、create、update、delete 等依赖数据库的用例）。
+- 必须通过 `TestDatabaseHelper.initTestDatabase()` 初始化内存库（SQLite `:memory:`），在测试中执行真实 SQL，不得通过 mock `getDataRepository` 或 mock 各个 Repository 的方式绕过真实数据库。
+- 使用 `Provider` 获取 Service 实例，保证 Service 使用真实的 DataSource/Repository，以便暴露列名、约束、SQL 等与真实环境一致的问题。
+- 每个测试前可按需调用 `TestDatabaseHelper.resetTestData()` 或在各用例内自行清理/准备数据；测试套件结束后调用 `TestDatabaseHelper.cleanupTestDatabase()`。
+
+这样可避免「单测全部通过、上线后因列名/方言差异等导致 SQL 报错」的情况。
+
+---
+
+## 三、测试要求
+
+- 必须覆盖：
+  - 成功场景
+  - 失败场景
+  - 边界条件
+- 测试必须相互独立
+- 每个测试前重置数据
+
+---
+
+## 四、测试文件结构
+
+- Controller：`test/controllers/**`
+- Service：`test/service/**`
+- Framework：`test/framework/**`
+
+---
+
+## 五、Controller 测试专项规范
+
+1. **Query / Body 参数要尽量模拟真实 HTTP 形态**
+   - Query 中的数字、布尔、数组，真实请求里通常是字符串，例如：`?page=1&pageSize=20&hasTask=true`。
+   - Controller 单测中，涉及这类字段时应优先使用字符串形态构造入参，再交给 DTO/解析逻辑处理，而不是直接传入 `boolean / number`：
+     - ✅ `const query = { page: "1", pageSize: "20", hasTask: "true" } as any;`
+     - ⛔ `const query = { page: 1, pageSize: 20, hasTask: true } as any;`
+
+2. **新增筛选/查询条件时，必须覆盖“参数解析 + Service 调用”这一整条链路**
+   - 对于新增的 Query 字段（例如：`visibility`、`hasTask` 等）：
+     - Service 层：用 Service 单测验证在 `true / false / 未传` 三种情况下 SQL/查询条件是否正确；
+     - Controller 层：用 Controller 单测验证“从字符串 Query 到 Service DTO”的转换是否正确（包括合法值、非法值、不传三种情况）。
+
+3. **典型反例（经验教训）——hasTask 过滤未生效**
+   - 曾在项目动态列表接口 `GET /api/projects/:id/activities` 上新增 `hasTask`（是否关联待办）筛选条件：
+     - Service 单测直接调用 `list(projectId, { hasTask: true }, userId)`，验证了过滤逻辑本身是正确的；
+     - 但 Controller 层没有正确将 `?hasTask=true / ?hasTask=false` 这类字符串转换为布尔值，而是原样把字符串传入 Service，导致运行时 `hasTask` 始终为 `undefined`，过滤条件完全没有生效；
+     - 由于 Controller 单测构造的是已经「解析好」的对象（`{ hasTask: true }`），真实 HTTP 请求路径（`string -> boolean`）未被覆盖，问题在上线后才通过前端联调暴露。
+   - 结论：凡是需要从 Query/Body 中做类型转换的字段（布尔、数字、数组等），一定要确保至少有一条测试**从原始字符串形态出发**，覆盖到最终调用 Service 的 DTO。
+
+---
+alwaysApply: false
+---
+# Skill：后端测试规范（Jest）
+
+## 一、测试基础
+
+- 使用 Jest
+- 使用 `TestDatabaseHelper` 管理测试数据库
+- 使用 `Provider` 获取 Service 实例
+
+---
+
+## 二、数据库相关测试（强制）
+
+**凡涉及数据库操作的 Service、Controller 测试，必须使用内存数据库进行测试。**
+
+- 涉及数据库操作：指测试会触发 TypeORM 的 Repository/QueryBuilder 调用（如 list、create、update、delete 等依赖数据库的用例）。
+- 必须通过 `TestDatabaseHelper.initTestDatabase()` 初始化内存库（SQLite `:memory:`），在测试中执行真实 SQL，不得通过 mock `getDataRepository` 或 mock 各个 Repository 的方式绕过真实数据库。
+- 使用 `Provider` 获取 Service 实例，保证 Service 使用真实的 DataSource/Repository，以便暴露列名、约束、SQL 等与真实环境一致的问题。
+- 每个测试前可按需调用 `TestDatabaseHelper.resetTestData()` 或在各用例内自行清理/准备数据；测试套件结束后调用 `TestDatabaseHelper.cleanupTestDatabase()`。
+
+这样可避免「单测全部通过、上线后因列名/方言差异等导致 SQL 报错」的情况。
+
+---
+
+## 三、测试要求
 
 - 必须覆盖：
   - 成功场景
@@ -22,7 +100,7 @@ alwaysApply: false
 
 ---
 
-## 三、测试文件结构
+## 四、测试文件结构
 
 - Controller：`test/controllers/**`
 - Service：`test/service/**`

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;
+}
+