create-dp-koa 1.1.10 → 1.1.12

package/package.json

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

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

@@ -5,14 +5,14 @@ alwaysApply: true
 
 ## 适用范围
 - 本项目所有 TypeScript 后端代码
-- 技术栈：Koa + TypeORM + dp-ioc2 + 自定义装饰器体系
+- 技术栈：Koa + TypeORM + dp-ioc2 + 自定义装饰器体系；框架以 npm 包 **`dp-koa-framework-core`**（运行时与对外稳定 API）与 **`dp-koa-framework-libs`**（共享适配/配套能力）引入，版本以项目 `package.json` 为准。
 - **包管理工具：必须使用 yarn（禁止使用 npm）**
 
 ---
 
 ## 运行环境判定（debug 口径，必须）
 
-**唯一标准**：以 `src/framework/utils/function.ts` 为准，**不要**用 `process.env.NODE_ENV` 作为“是否生产/是否调试”的单一判断。
+**唯一标准**：以 **`dp-koa-framework-core`** 导出的运行环境判定 API（`isDebug()`、`getRuntimeEnvironmentLabel()` 等）为准，**不要**用 `process.env.NODE_ENV` 作为“是否生产/是否调试”的单一判断。
 
 - **`isDebug()`**：当进程启动参数中包含 `--env=debug` 时为 `true`。
 - **非 debug**：一律按**生产口径**处理（例如：迁移、静态资源长缓存、对外错误信息脱敏等）。

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

@@ -12,23 +12,111 @@ alwaysApply: false
 
 ## 一、写 Controller 的推荐范式（必须对齐）
 
-### 1.1 参考样例（写代码前先对齐）
-- 推荐在实现前先对齐以下文件的写法（不要臆造新风格）：
-  - `src/controllers/example/NewAnnotationExampleController.ts`
-  - `src/controllers/home/ytUser.controller.ts`
-  - `src/controllers/base.controller.ts`
+### 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 'dp-koa-framework-core';
+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 'dp-koa-framework-core';
+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 'dp-koa-framework-core';
+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 {
+  Get,
+  Post,
+  Query,
+  Body,
+  State,
+  ResponseCode,
+  ResponseHeader,
+  logger,
+  CommonServiceResultCode,
+} 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 { 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)
@@ -37,9 +125,9 @@ export class SomeController extends BaseController {
   @Get('/some/path')
   @ResponseCode(200)
   async getSomething(
-    @Query() query: SomeQueryDto,
+    @Query(SomeQueryDto) query: SomeQueryDto,
     @State('user') user: { userId: number; type?: number },
-  ): Promise<ControllerResponse<SomeResponseDto>> {
+  ): Promise<ControllerResponse<any>> {
     try {
       const result = await this.someService.someMethod(query, user.userId);
       if (result.code !== CommonServiceResultCode.SUCCESS) {
@@ -59,7 +147,6 @@ export class SomeController extends BaseController {
 - Controller **不直接访问数据库/Repository**
 - Controller **不 return Service 原始结果**，必须映射 `success/fail`
 - Controller `async` **必须 try/catch**
-!- Controller 的返回类型 `ControllerResponse<T>` **必须显式指定 T，禁止使用 `any`**
 
 ---
 
@@ -72,19 +159,17 @@ export class SomeController extends BaseController {
 ### 2.2 参数注解（重点）
 - **`@Query()`**：
   - 读取 query 参数
-  - 推荐写法：`@Query() query: XxxQueryDto`
+  - 推荐写法：`@Query(SomeQueryDto) query: XxxQueryDto`
 - **`@Body()`**：
   - 读取 body 参数
-  - 推荐写法：`@Body() body: XxxBodyDto`
-- **`@Params()`**：
-  - 读取路径参数（如 `/:id`、`/:id/files/:fileId`）
-  - 推荐写法：`@Params(ParamsDto) params: XxxParamsDto`
+  - 推荐写法：`@Body(SomeBodyDto) body: XxxBodyDto`
 - **`@State()`**：
-  - 读取整个 `ctx.state`（样例：`ytUser.controller.ts`）
+  - 读取整个 `ctx.state`（样例：见 **1.1.2**）
   - 推荐写法：`@State() state: { user: { userId: number; type?: number } }`
 - **`@State('user')`**：
-  - 读取 `ctx.state.user`（样例：`NewAnnotationExampleController.ts`）
+  - 读取 `ctx.state.user`（样例：见 **1.1.3**）
   - 推荐写法：`@State('user') user: { userId: number; type?: number }`
+- **`@Session` / `@Cookie`**：会话与普通 Cookie 的注入规则见 **2.5**（均从 **`dp-koa-framework-core`** 导入）
 
 禁止：
 - ❌ `@Query() query: any` / `@Body() body: any` / `@State() state: any`（尽量不要）
@@ -92,10 +177,97 @@ export class SomeController extends BaseController {
 ### 2.3 响应元信息注解
 - **`@ResponseCode(200|201|...)`**：设置 HTTP 状态码（样例中 GET 用 200，POST 用 201）
 - **`@ResponseHeader(key, value)`**：为响应添加 header
+- **HTTP 3xx 重定向**：使用 **`return redirect(...)`**（**`dp-koa-framework-core`**），规则见 **§2.6**；与 `this.success` / JSON 体返回**互斥**。
 
 ### 2.4 响应校验注解（进阶，按需）
 - **`@ResponseValidator(DtoClass, objectKey?)`**：对响应数据做校验
-- **`@ResponseValidateIf(DtoClass, fn)`**：仅当 fn 返回真时才校验（样例：`ytUser.controller.ts`）
+- **`@ResponseValidateIf(DtoClass, fn)`**：仅当 fn 返回真时才校验（样例：见 **1.1.4**）
+
+### 2.5 `@Session` 与 `@Cookie`（**`dp-koa-framework-core`**）
+
+均由 **`dp-koa-framework-core`** 导出（与 `@Get` / `@State` 同源：`import { Session, Cookie, ... } from 'dp-koa-framework-core'`）。
+
+#### `@Session`（`ctx.session`）
+
+- **何时用**：与 JWT + `ctx.state`（`@State`）**并存**；适合 OAuth2/OIDC/SSO 等需要在服务端存**短期握手数据**的场景，**不替代**鉴权中间件写入的 `ctx.state.user`。
+- **谁负责启用**：**`dp-koa-framework-core`** 在 `bootstrap` 中已注册 `koa-session`，业务 **`src/app.ts` 一般不要再 `app.use(session(...))`**。
+- **语义与绑定数据**：
+  - `@Session()`：注入**整段** `ctx.session`（类型建议用 interface/明确结构，避免裸 `any`）。
+  - `@Session('uid')`：注入 `ctx.session['uid']`（字符串参数表示 **key**）。
+  - `@Session(SomeDtoClass)`：传入 **class** 时，与 `@Body(SomeDto)` 类似，会对**当前取到的 session 对象**（无 key 时为整段 session）做 **class-transformer + class-validator**。
+- **默认行为（框架内建）**：会话 Cookie 名默认 `dpkoa.sid`、`httpOnly`、`signed`、`rolling`、`sameSite: 'lax'` 等由 **`dp-koa-framework-core`** 的 bootstrap 与 `koa-session` 决定；可用环境变量覆盖。
+- **环境变量（摘要）**：
+  - `SESSION_KEYS`：逗号分隔多 key（**优先**作签名密钥）；
+  - `SESSION_SECRET`：单 key（无 `SESSION_KEYS` 时使用）；
+  - `SESSION_KEY`：Cookie 名；
+  - `SESSION_MAX_AGE_MS`：过期毫秒数。
+- **实践要求**：生产**必须**配置 `SESSION_KEYS` 或 `SESSION_SECRET`；Session 仅存短期字段，流程结束**清理**一次性键；跨站回调重点核对 `SameSite`、HTTPS、域名与代理头。
+- **延伸阅读**：`docs/SESSION_DECORATOR_GUIDE.md`（Session 环境变量与更多示例）。
+
+#### `@Cookie`（读 / 写 Cookie）
+
+- **`@Cookie('name')`**：读取名为 `name` 的单个 Cookie；底层为带 **`signed: true`** 的 `ctx.cookies.get`。
+- **`@Cookie()`**（无参）：注入 **`CookieHandle`**：`{ get(name, opts?), set(name, value, opts?) }`，默认读写仍带 **`signed: true`**，可在 `opts` 中按需覆盖。
+- **硬性限制**：**不支持** `@Cookie(SomeDtoClass)`；装饰器要求参数为 **string 或省略**，否则**抛错**。需要多字段时多次 `@Cookie('a')` / `@Cookie('b')`，或极少数场景自行解析（仍保持 Controller 薄）。
+- **前置条件**：依赖 Koa 标准 **`ctx.cookies`**；`set` 时按需传入 `maxAge`、`path`、`httpOnly`、`sameSite` 等安全相关选项。
+
+#### 示例（Session / Cookie / State 组合）
+
+```ts
+import { Get, Session, Cookie, State } from 'dp-koa-framework-core';
+import { BaseController, ControllerResponse } from '@src/controllers/base.controller';
+
+export class OauthDemoController extends BaseController {
+  @Get('/oauth/callback')
+  async callback(
+    @Session('oauthState') oauthState: string | undefined,
+    @State('user') user: { userId: number } | undefined,
+  ): Promise<ControllerResponse<{ ok: boolean }>> {
+    return this.success({ ok: Boolean(oauthState && user) });
+  }
+
+  @Get('/prefs')
+  async prefs(@Cookie('theme') theme: string | undefined): Promise<ControllerResponse<{ theme: string | null }>> {
+    return this.success({ theme: theme ?? null });
+  }
+
+  @Get('/notice-dismiss')
+  async dismiss(
+    @Cookie() jar: { get: (name: string, opts?: object) => string | undefined; set: (name: string, value: string | null, opts?: object) => void },
+  ): Promise<ControllerResponse<null>> {
+    jar.set('notice', '', { maxAge: 0 });
+    return this.success(null);
+  }
+}
+```
+
+### 2.6 声明式 HTTP 重定向（`redirect`）
+
+- **导入**：`import { redirect } from 'dp-koa-framework-core'`。另导出 `RedirectResponse`、`RedirectStatusCode`、`isRedirectResponse`、`applyRedirectToCtx`（后两者多用于中间件或脱离 `bindRouter` 的手动写入；常规控制器 **`return redirect(...)`** 即可）。
+- **基本用法**：**`return redirect(location)`**；`location` 将作为 **`Location`** 响应头。可选 **`redirect(location, { status?, headers? })`**。
+- **`status`**：仅 **`302` | `303` | `307` | `308`**，默认 **`302`**。
+- **路由层**：识别重定向后写入 **`ctx.status` / `Location` / `Cache-Control: no-store`**，**`ctx.body = ''`** 并短路；**跳过**响应 DTO 校验与 JSON 赋值。
+- **与 `@ControllerCache`**：命中缓存时直接返回缓存体，与本次 `redirect` 二选一；勿在同一方法混用两种出口语义。
+- **不要**与 `this.success` / `ControllerResponse` 混用；跳转方法可省略 `@ResponseCode`（最终以 `redirect` 的 `status` 为准）。
+- **开放重定向**：对用户可控 `next`、回调 URL 等做白名单或站内路径约束，并正确编码 query。
+- **延伸阅读**：`packages/dp-koa-framework-core/README.md` 中「HTTP 重定向（SSO 常用）」。
+
+#### 示例（SSO 入口）
+
+```ts
+import { Get, Query, redirect } from 'dp-koa-framework-core';
+import { BaseController } from '@src/controllers/base.controller';
+
+export class SsoController extends BaseController {
+  @Get('/sso/login')
+  async login(@Query() query: { next?: string }): Promise<ReturnType<typeof redirect>> {
+    const next = query?.next;
+    const safeNext = next && next.startsWith('/') ? next : '/';
+    const url = `https://sso.example.com/authorize?next=${encodeURIComponent(safeNext)}`;
+    return redirect(url, { status: 302 });
+  }
+}
+```
 
 ---
 
@@ -105,9 +277,15 @@ export class SomeController extends BaseController {
 - `@Get('/xxx') + @State('user')`（或 `@State()` 取整段 state）
 
 ### 3.2 带 body 的 POST 接口
-- `@Post('/xxx') + @Body() body: Dto + @ResponseCode(201)`
+- `@Post('/xxx') + @Body(SomeBodyDto) body: SomeBodyDto + @ResponseCode(201)`
 
 ### 3.3 需要自定义 header
 - `@ResponseHeader('X-XXX', 'value')`
 
+### 3.4 Session 与登录态 / OAuth
+- 回调或握手：`@Session('state')` / `@Session()` 承载临时字段，与 `@State('user')` 分职责（Session=临时、State=已鉴权用户）。
+- 非 Session 的普通 Cookie：在方法内使用 `@Cookie()` 注入的 `CookieHandle.set(...)`，避免在 Controller 外散落 `ctx.cookies`。
+
+### 3.5 HTTP 重定向（SSO / 登录页）
+- **`return redirect(url)`** 或带 **`{ status: 303 }`** 等选项，详见 **§2.6**；与 **`this.success` / `ControllerResponse`** 不要混在同一返回路径。
 

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)
@@ -199,9 +199,8 @@ async createUser(@Body(CreateUserControllerDto) body: CreateUserControllerDto) {
 - 常用装饰器：`@IsString()`, `@IsEmail()`, `@IsNotEmpty()`, `@MinLength()`, `@IsOptional()` 等
 
 ### 4.2 Controller DTO 特殊处理
-- **@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`）。
+- 可以使用 `@Transform` 进行数据转换（如字符串转数字、trim）
+- 可以包含 HTTP 层特定的字段（如 `vcodeToken`、`requestId`）
 
 ### 4.3 Service DTO 要求
 - **禁止**包含 HTTP 层特性（如 `@Transform`、HTTP 特定字段）
@@ -210,30 +209,17 @@ async createUser(@Body(CreateUserControllerDto) body: CreateUserControllerDto) {
 
 ### 4.4 示例对比
 
-#### Controller DTO（包含 HTTP 层转换，使用 class-transformer）
+#### Controller DTO（包含 HTTP 层转换）
 ```typescript
-import { Transform } from 'class-transformer';
-
 export class CreateUserControllerDto {
-    @Transform(({ value }) => (typeof value === 'string' ? value.trim() : value))
+    @Transform((val) => Trim(String(val)))
     @IsString()
     @IsEmail()
     email: string;
     
-    // 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[];
+    @Transform((val) => Number(val))
+    @IsNumber()
+    age: number;
 }
 ```
 
@@ -249,14 +235,6 @@ 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/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`** 暴露的启动 API（`bootstrap`、`setBeforeBootstrap` 等）的接入方式时启用本 Skill；若需修改框架内置启动顺序，应到 **`dp-koa-framework-core`** 包源码修改。
 - 触发口令建议：
   - “请按 `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

@@ -4,7 +4,7 @@ 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` 规范注册路由”
 
@@ -12,7 +12,7 @@ alwaysApply: false
 
 ## 一、路由注册机制（必须理解）
 本项目路由注册入口：`src/routers/index.ts`  
-路由绑定工具：`src/framework/utils/router.ts` 的 `bindRouter(...)`
+路由绑定工具：从 **`dp-koa-framework-core`** 导入 `bindRouter(...)`（业务侧通常在 `src/routers/index.ts` 使用）。
 
 ### 1.1 bindRouter(...) 的真实行为（以代码为准）
 - 调用形式：

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

@@ -13,6 +13,7 @@ alwaysApply: false
 
 ## 一、总体原则
 
+- **框架内置能力**：与框架重叠的通用工具/适配层，优先使用 **`dp-koa-framework-libs`** 或 **`dp-koa-framework-core`** 的稳定导出；业务目录下的 `src/libs` 仅承载**本项目特有**的适配与 SDK 封装。
 - **libs**：更偏向“小框架 / 小 SDK / 第三方服务适配层”
 - **utils**：更偏向“纯函数工具、小颗粒度无状态函数”
 - 业务相关的工具优先放在**各自业务模块内**，而不是全局 `utils/`
@@ -91,9 +92,9 @@ alwaysApply: false
 
 ---
 
-## 七、框架级 `src/framework/utils/function.ts`（必须）
+## 七、框架级运行环境判定（**`dp-koa-framework-core`**，必须）
 
-本文件提供**运行环境判定**，全项目应统一使用，避免散落 `NODE_ENV === 'production'` 判断。
+以下 API 由 **`dp-koa-framework-core`** 提供，全项目应统一使用，避免散落 `NODE_ENV === 'production'` 判断。
 
 | API | 含义 |
 |-----|------|

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

@@ -1,307 +1,65 @@
-# 后端插件体系规范（dp-koa-framework）
+# 后端插件体系规范（**`dp-koa-framework-core`** / 模板）
 
-> 目标：让类似 `weboffice` 的“独立功能体”以插件形式存在，可插拔、易维护、与宿主框架低耦合。
+> 目标：让“独立功能体”以插件形式存在，可插拔、易维护、与宿主框架低耦合。
 
 ---
 
 ## 1. 插件的基本形态
 
-- 插件是**独立功能域**：可以包含路由、Service、实体/迁移、脚本，但通过统一接口暴露给宿主。
 - 插件统一放在 `src/plugins/<plugin-id>/` 目录下。
-- 插件入口文件：`src/plugins/<plugin-id>/index.ts`，必须导出一个 `PluginDescriptor`：
+- 插件根目录只保留 `index.ts`（插件入口）。
+- 插件入口必须导出一个 `PluginDescriptor`（类型由 **`dp-koa-framework-core`** 导出）。
 
-```ts
-import type { PluginDescriptor } from "@src/framework/plugins/types";
+推荐目录结构：
 
-export const plugin: PluginDescriptor = {
-  id: "weboffice",
-  displayName: "WPS WebOffice 集成",
-  enabled: (env) => env.WEBOFFICE_ENABLED !== "0",
-  registerRoutes(router) {
-    // 注册本插件路由
-  },
-  entities: [
-    // 插件自有实体
-  ],
-};
-```
+- `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/`：种子/运维脚本（可选）
 
 ---
 
-## 2. PluginDescriptor 约定
+## 2. 宿主与插件的依赖方向
 
-定义位置：`src/framework/plugins/types.ts`
+### 2.1 插件 → 宿主
 
-关键字段：
+- 插件内部业务代码应优先使用相对路径组织。
+- 插件调用宿主业务能力（如用户、项目、权限）应通过 **plugin-api 门面层**（建议放在 `src/plugin-api/*`），避免直接 import 宿主 Service/Repository。
 
-- `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 实体（仅包含插件表）。
+### 2.2 宿主 → 插件
 
----
-
-## 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`。
+- 宿主禁止直接 import 插件 Service。
+- 宿主感知插件能力应通过：
+  - 事件扩展点（emit + register handler）
+  - SPI（可替换实现：getXxxSpi + registerXxxSpi）
 
 ---
 
-## 6. 插件生命周期与卸载策略
+## 3. 插件注册与加载
 
-### 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 调用，用于：
-  - 关闭外部订阅；
-  - 提供需要删除/归档的表信息等。
-- 所有物理卸载操作应当：
-  - 需要人工确认；
-  - 具备日志或变更记录，便于审计与回溯。
+- 插件注册表：**`src/plugins/registry.ts`**（`PluginDescriptor` 来自 **`dp-koa-framework-core`**）
+- 宿主启动接入点：`src/app.ts`
+  - beforeBootstrap：计算启用插件、执行插件 before hook、注册插件路由、合并插件实体后初始化 DB
+  - afterBootstrap：执行插件 after hook（定时任务/订阅等）
 
 ---
 
-## 7. 插件测试规范（单元 + 集成）
-
-目标：插件测试要**可复用、稳定、可在 CI 中长期运行**。遵循“测试金字塔”：
-
-- **单元测试（默认）**：覆盖插件 `core/*` 的纯函数/解析逻辑，不启动 Koa、不连接真实数据库。
-- **集成测试（少量但关键）**：覆盖插件对外契约（HTTP 路由、DB 交互），使用 Koa 最小实例 + SQLite 内存库。
-
-### 7.1 测试目录与命名
+## 4. 插件数据库规范
 
-- 单元测试：`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`）
+- 插件自建表必须使用插件 ID 作为表名前缀（例如 `weboffice_files`、`weboffice_file_versions`）。
+- 插件迁移原则上只操作自身前缀表，避免修改宿主核心表结构。
 
 ---
 
-## 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`。
+## 5. 示例插件：weboffice
 
-### weboffice 插件目录结构约定（示例）
+模板内置示例插件：`src/plugins/weboffice/`
 
-- 根目录仅保留 `index.ts`（插件入口）
-- 其余代码按职责归档：
-  - `core/`：`types.ts`、`errors.ts`、`context.ts`、`utils.ts`
-  - `entities/`：TypeORM 实体
-  - `services/`：业务 Service
-  - `scripts/`：种子/运维脚本
-  - 其他入口文件（如路由）建议放在 `http/` 或保持在根目录 `routes.ts`（按团队偏好统一）
+- 通过 `WEBOFFICE_ENABLED` 环境变量控制启用（默认启用；设为 `0` 禁用）。
+- 路由入口：`src/plugins/weboffice/http/routes.ts`
+- 插件实体：`src/plugins/weboffice/entities/*`
 
-新增插件时，强烈建议参考 weboffice 插件的结构与写法，保持一致的工程风格与解耦思路。
+> 注意：模板示例插件的 `getUsers` 为占位实现（不依赖宿主业务用户表）。真实业务接入时应改为通过 plugin-api 调宿主用户体系。
 

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

@@ -21,6 +21,11 @@
 - **`11-backend-controller-recipes.skill.md`**
   - Controller 推荐模板（可复制）+ 常用注解速查（@Query/@Body/@State/...）
 
+### 25 - 注释与文档（按需启用）
+- **`25-backend-comments-and-doc.skill.md`**
+  - Controller / Service / Entity / DTO 的 **`/** ... */`** 注释粒度与必写项（类注释、对外路由方法注释等）
+  - 禁止逐行翻译式注释；可与测试、PRD 交叉引用
+
 ### 20~40 - 数据/校验/错误（按需启用）
 - **`20-backend-repository.skill.md`**：Repository 使用与事务（`transactionManager.executeInTransaction`）
 - **`30-backend-validation.skill.md`**：DTO 分层规范（Controller DTO / Service DTO）、命名规范、转换规范、参数校验（@ParamValidate）
@@ -38,7 +43,7 @@
 ### 80 - 工程结构（按需启用）
 - **`80-backend-utils-and-libs.skill.md`**
   - `src/libs` vs `src/utils` 的放置规则与决策清单
-  - `src/framework/utils/function.ts`：`isDebug()` / `getRuntimeEnvironmentLabel()` 约定
+  - **`dp-koa-framework-core`**：`isDebug()` / `getRuntimeEnvironmentLabel()` 约定
 
 ### 90 - 测试（按需启用）
 - **`90-backend-testing.skill.md`**

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

@@ -5,7 +5,7 @@ alwaysApply: true
 
 ## 适用范围
 - 本项目所有 TypeScript 后端代码
-- 技术栈：Koa + TypeORM + dp-ioc2 + 自定义装饰器体系
+- 技术栈：Koa + TypeORM + dp-ioc2 + 自定义装饰器体系；框架以 npm 包 **`dp-koa-framework-core`**（运行时与对外稳定 API）与 **`dp-koa-framework-libs`**（共享适配/配套能力）引入，版本以项目 `package.json` 为准。
 - **包管理工具：必须使用 yarn（禁止使用 npm）**
 
 ---

package/template/.vscode/launch.json

@@ -14,7 +14,6 @@
       "env": {
         "NODE_ENV": "development",
         "USE_NEW_ANNOTATION_SYSTEM": "1",
-        "db_enable": "1",
         "PATH": "${env:HOME}/.nvm/versions/node/v24.12.0/bin:${env:PATH}"
       }
     },
@@ -30,8 +29,7 @@
       "protocol": "inspector",
       "env": {
         "NODE_ENV": "development",
-        "USE_NEW_ANNOTATION_SYSTEM": "1",
-        "db_enable": "1"
+        "USE_NEW_ANNOTATION_SYSTEM": "1"
       }
     }
   ]

package/template/package.json

@@ -65,7 +65,7 @@
     "dotenv": "^16.5.0",
     "dp-ioc2": "^1.0.1",
     "dp-mqueue": "^1.0.4",
-    "dp-koa-framework-core": "^0.1.9",
+    "dp-koa-framework-core": "^0.1.10",
     "dp-koa-framework-libs": "^0.1.4",
     "jsonwebtoken": "^9.0.2",
     "koa": "^3.0.0",