create-dp-koa 1.0.1 → 1.1.0

package/package.json

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

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

@@ -38,8 +38,8 @@
 - 入参 DTO 应放在哪个目录、命名建议
 - Service 方法签名建议（含返回类型）
 
-【对齐的项目样例（必须列出）】
-- 列出你参考的文件路径（至少 2 个）
+【对齐的参考来源（必须列出）】
+- 至少列出 **`11-backend-controller-recipes.skill.md` 内嵌示例**中的 2 个小节编号（例如 1.1.2、1.1.4）；若同时参考了仓库内 `src/controllers/base.controller.ts` 或 `src/controllers/example/*`，可一并写出路径
 ```
 
 

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

@@ -50,9 +50,11 @@
 ---
 
 ## 写代码前的对齐动作（必须）
-- 在生成/修改 Controller 代码前，先对齐本项目示例写法：
-  - `src/controllers/example/NewAnnotationExampleController.ts`
-  - `src/controllers/home/ytUser.controller.ts`
-  - `src/controllers/base.controller.ts`
+- 在生成/修改 Controller 代码前，先对齐 **`11-backend-controller-recipes.skill.md` 内嵌示例**（章节 **1.1**），重点核对：
+  - **1.1.1** `BaseController` / `ControllerResponse` 与 `success` / `fail` 用法
+  - **1.1.2** `@State()` 读取整段 `ctx.state`
+  - **1.1.3** `@State('user')` 只读 `ctx.state.user`
+  - **1.1.4** `@ResponseValidateIf` 条件响应校验
+- 若仓库中仍存在 `src/controllers/base.controller.ts` 或 `src/controllers/example/*`，可作为**补充**对照（以实现代码为准）。
 
 

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

@@ -12,11 +12,91 @@ 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 '@src/framework/decorator/controller';
+import { BaseController, ControllerResponse } from '@src/controllers/base.controller';
+
+export class ExampleStateController extends BaseController {
+  @Get('/example/state-full')
+  async getWithFullState(
+    @State() state: { user: { userId: number; type?: number } },
+  ): Promise<ControllerResponse<{ userId: number }>> {
+    return this.success({ userId: state.user.userId });
+  }
+}
+```
+
+#### 1.1.3 `@State('user')`：只读 `ctx.state.user`
+
+```ts
+import { Get, State } from '@src/framework/decorator/controller';
+import { BaseController, ControllerResponse } from '@src/controllers/base.controller';
+
+export class ExampleUserSliceController extends BaseController {
+  @Get('/example/state-user')
+  async getWithUser(
+    @State('user') user: { userId: number; type?: number },
+  ): Promise<ControllerResponse<{ ok: boolean }>> {
+    return this.success({ ok: user.userId > 0 });
+  }
+}
+```
+
+#### 1.1.4 `@ResponseValidateIf`：仅在条件成立时校验响应体
+
+```ts
+import { Get, State, ResponseValidateIf } from '@src/framework/decorator/controller';
+import { BaseController, ControllerResponse } from '@src/controllers/base.controller';
+
+// 示例 DTO：按实际接口替换
+class UserProfileResponseDto {
+  id!: number;
+  nickName!: string;
+}
+
+export class ExampleResponseValidateController extends BaseController {
+  @ResponseValidateIf(UserProfileResponseDto, (data) => Boolean(data && data.data))
+  @Get('/example/profile')
+  async getProfile(
+    @State() state: { user: { userId: number } },
+  ): Promise<ControllerResponse<UserProfileResponseDto | null>> {
+    return this.success({
+      id: state.user.userId,
+      nickName: 'demo',
+    });
+  }
+}
+```
 
 ### 1.2 Controller 标准骨架（复制这个结构）
 目标：DTO 入参 → 调用 Service → 统一响应（`success/fail`）→ try/catch + logger
@@ -76,10 +156,10 @@ export class SomeController extends BaseController {
   - 读取 body 参数
   - 推荐写法：`@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 }`
 
 禁止：
@@ -91,7 +171,7 @@ export class SomeController extends BaseController {
 
 ### 2.4 响应校验注解（进阶，按需）
 - **`@ResponseValidator(DtoClass, objectKey?)`**：对响应数据做校验
-- **`@ResponseValidateIf(DtoClass, fn)`**：仅当 fn 返回真时才校验（样例：`ytUser.controller.ts`）
+- **`@ResponseValidateIf(DtoClass, fn)`**：仅当 fn 返回真时才校验（样例：见 **1.1.4**）
 
 ---
 
@@ -101,9 +181,8 @@ export class SomeController extends BaseController {
 - `@Get('/xxx') + @State('user')`（或 `@State()` 取整段 state）
 
 ### 3.2 带 body 的 POST 接口
-- `@Post('/xxx') + @Body(SomeBodyDto) body: DtSomeBodyDtoo + @ResponseCode(201)`
+- `@Post('/xxx') + @Body(SomeBodyDto) body: SomeBodyDto + @ResponseCode(201)`
 
 ### 3.3 需要自定义 header
 - `@ResponseHeader('X-XXX', 'value')`
 
-

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

@@ -12,11 +12,91 @@ 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 '@src/framework/decorator/controller';
+import { BaseController, ControllerResponse } from '@src/controllers/base.controller';
+
+export class ExampleStateController extends BaseController {
+  @Get('/example/state-full')
+  async getWithFullState(
+    @State() state: { user: { userId: number; type?: number } },
+  ): Promise<ControllerResponse<{ userId: number }>> {
+    return this.success({ userId: state.user.userId });
+  }
+}
+```
+
+#### 1.1.3 `@State('user')`：只读 `ctx.state.user`
+
+```ts
+import { Get, State } from '@src/framework/decorator/controller';
+import { BaseController, ControllerResponse } from '@src/controllers/base.controller';
+
+export class ExampleUserSliceController extends BaseController {
+  @Get('/example/state-user')
+  async getWithUser(
+    @State('user') user: { userId: number; type?: number },
+  ): Promise<ControllerResponse<{ ok: boolean }>> {
+    return this.success({ ok: user.userId > 0 });
+  }
+}
+```
+
+#### 1.1.4 `@ResponseValidateIf`：仅在条件成立时校验响应体
+
+```ts
+import { Get, State, ResponseValidateIf } from '@src/framework/decorator/controller';
+import { BaseController, ControllerResponse } from '@src/controllers/base.controller';
+
+// 示例 DTO：按实际接口替换
+class UserProfileResponseDto {
+  id!: number;
+  nickName!: string;
+}
+
+export class ExampleResponseValidateController extends BaseController {
+  @ResponseValidateIf(UserProfileResponseDto, (data) => Boolean(data && data.data))
+  @Get('/example/profile')
+  async getProfile(
+    @State() state: { user: { userId: number } },
+  ): Promise<ControllerResponse<UserProfileResponseDto | null>> {
+    return this.success({
+      id: state.user.userId,
+      nickName: 'demo',
+    });
+  }
+}
+```
 
 ### 1.2 Controller 标准骨架（复制这个结构）
 目标：DTO 入参 → 调用 Service → 统一响应（`success/fail`）→ try/catch + logger
@@ -76,10 +156,10 @@ export class SomeController extends BaseController {
   - 读取 body 参数
   - 推荐写法：`@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 }`
 
 禁止：
@@ -91,7 +171,7 @@ export class SomeController extends BaseController {
 
 ### 2.4 响应校验注解（进阶，按需）
 - **`@ResponseValidator(DtoClass, objectKey?)`**：对响应数据做校验
-- **`@ResponseValidateIf(DtoClass, fn)`**：仅当 fn 返回真时才校验（样例：`ytUser.controller.ts`）
+- **`@ResponseValidateIf(DtoClass, fn)`**：仅当 fn 返回真时才校验（样例：见 **1.1.4**）
 
 ---
 
@@ -101,7 +181,8 @@ export class SomeController extends BaseController {
 - `@Get('/xxx') + @State('user')`（或 `@State()` 取整段 state）
 
 ### 3.2 带 body 的 POST 接口
-- `@Post('/xxx') + @Body(SomeBodyDto) body: DtSomeBodyDtoo + @ResponseCode(201)`
+- `@Post('/xxx') + @Body(SomeBodyDto) body: SomeBodyDto + @ResponseCode(201)`
 
 ### 3.3 需要自定义 header
-- `@ResponseHeader('X-XXX', 'value')`
+- `@ResponseHeader('X-XXX', 'value')`
+

package/template/docs/FRAMEWORK_V2_UPGRADE_GUIDE.md

@@ -0,0 +1,134 @@
+# Framework v2 升级落地指南（抽包 + 自动升级）
+
+## 1. 为什么需要抽成独立 npm 包
+当前脚手架 `create-dp-koa` 的“生成逻辑”是把模板目录整份递归拷贝到新项目里，因此它本质上是“快照生成”，而不是“运行时依赖可升级框架”。
+
+- 生成阶段：`packages/create-dp-koa/index.mjs` 中使用递归拷贝模板（`cp(TEMPLATE_DIR, targetDir, { recursive: true })`）。
+- 维护阶段：发布脚手架前会通过 `sync-template.mjs` 把仓库根目录同步到 `packages/create-dp-koa/template/`，再发布脚手架包。
+
+因此：**当源框架（本仓库）更新公共能力/公共库后，已经创建的业务项目不会自动获得这些改动**；升级通常会变成“手工合并/拷贝/重构”。
+
+要获得“尽量自动升级”的体验，最稳的工程化方式是：把公共/通用能力抽成可发布的独立 npm 包，业务项目只依赖这些包，然后通过 `npm update`/版本升级即可生效。
+
+## 2. v2 目标与边界
+### 2.1 目标（尽量自动）
+1. 新建业务项目：生成后直接依赖 npm 包，公共能力升级主要通过升级依赖版本完成。
+2. 存量业务项目：提供一次性迁移（codemod/脚本/文档），迁移完成后同样走 npm 升级链路。
+
+### 2.2 抽包边界（与当前代码结构对齐）
+结合当前模板中的职责分层：
+
+- `src/framework/**`：框架核心能力（注解、拦截器、启动/路由装配、事务/迁移/缓存/错误处理等）
+- `src/libs/**`：业务侧“共享适配层/小 SDK”（例如验证码、短信、COS、邮件发送适配等）
+
+建议 v2 至少拆两类包：
+1. `dp-koa-framework-core`：包含框架核心运行时与对外稳定 API。
+2. `dp-koa-framework-libs`：包含原来 `src/libs/**` 下的共享适配层/小 SDK，并作为核心包的配套能力。
+
+可选第三类包（当插件体系需要独立发布、或希望更细粒度升级时）：
+3. `dp-koa-framework-plugins`：内置示例插件（例如 `weboffice` 示例）或插件集合。
+
+## 3. 关键技术难点（必须在文档/方案里提前解决）
+### 3.1 `@src` 路径别名与运行时模块解析
+当前模板中大量代码依赖 `@src/**` 路径别名：
+
+- `packages/create-dp-koa/template/tsconfig.json` 定义了 `paths`（`@src/*` -> `./src/*`）。
+- `packages/create-dp-koa/template/webpack.config.js` 配置了 `resolve.alias`（`@src` -> 模板的 `src/`）。
+- `packages/create-dp-koa/template/src/framework/utils/bootstrap.ts` 运行时使用 `module-alias` 映射 `@src` 指向当前项目 `./src`。
+
+抽成 npm 包后，包内部如果仍然假设“外部业务项目存在 `./src` 结构并且 `@src` 指向它”，就无法真正实现自动升级。
+
+因此 v2 必须明确：
+1. 包内部应尽量使用包内相对路径与显式导出，不再依赖业务项目的 `@src` 结构。
+2. 业务项目只需保证“对包的导入路径存在”，而不是把业务 `src` 映射给包内部。
+
+### 3.2 插件注册表当前是“硬编码示例插件”
+当前插件注册在 `packages/create-dp-koa/template/src/framework/plugins/registry.ts` 中直接：
+- 引入 `@src/plugins/weboffice`
+- 将 `webofficePlugin` 放入固定 `plugins` 数组
+
+这会导致抽包时，框架核心包无法脱离业务项目/模板结构（或必须把示例插件也一起抽成插件包）。
+
+v2 需要在方案里确定其中一种：
+1. 核心包暴露“注册接口”，由业务/插件包提供插件 descriptor 并注入注册（推荐）。
+2. 把内置示例插件也封装进插件包，核心包只负责加载默认插件集合（次选）。
+
+## 4. 抽包实施路线（不写代码，只给步骤与交付物）
+### 4.1 先梳理核心公共 API
+从模板入口开始，列出业务项目会用到的“稳定入口函数/类/类型”，例如：
+
+- `setBeforeBootstrap` / `setAfterBootstrap`
+- 应用启动的 `bootstrap`（或由业务应用注入核心启动流程）
+- 注解系统初始化（`AnnotationSystemInitializer.initialize()` 等）
+- router / middleware 装配（框架级中间件、错误处理、token/静态等）
+- 缓存/事务/迁移/错误处理的对外函数（例如缓存的 `createCache`、迁移管理器、错误中间件）
+
+原则：**把这些定义成 core 包的显式导出**，业务代码只依赖这些导出。
+
+### 4.2 再抽 `src/libs/**` 为 libs 包
+把模板中的 `src/libs/**` 下导出的能力整体搬迁到 `dp-koa-framework-libs`，并确保它们只依赖：
+1. Node/外部依赖（如 `cos-nodejs-sdk-v5`、`svg-captcha` 等）
+2. core 包导出的工具能力（如缓存工具等）
+
+例如 `src/libs/mCache.ts` 当前会依赖框架缓存工具：
+- `createCache` / `CacheType` 来自 `src/framework/utils/cache`
+
+抽包后，这类依赖关系应改为从 `dp-koa-framework-core` import。
+
+### 4.3 调整脚手架模板：新项目直接依赖 npm 包
+更新 `packages/create-dp-koa/template/package.json`（以及最终生成项目的 `package.json`）：
+
+- 将当前模板中“框架源码快照依赖”替换为“npm 包依赖”
+- 更新模板入口（如 `packages/create-dp-koa/template/src/app.ts`）中对框架/库的导入
+
+重点：抽包后，**模板生成的新项目不应再包含完整框架源码**，否则依然无法做到升级自动化。
+
+### 4.4 存量项目一次性迁移（codemod）
+v2 推荐提供一份“迁移脚本/步骤文档”，迁移内容主要包括：
+
+1. 依赖升级：
+   - 修改 `package.json`：加入 `dp-koa-framework-core` 与 `dp-koa-framework-libs` 的版本
+2. import 路径替换：
+   - 将 `@src/framework/**` 替换为 `dp-koa-framework-core` 的对应导出路径
+   - 将 `@src/libs/**` 替换为 `dp-koa-framework-libs` 的对应导出路径
+3. 如有插件体系相关：
+   - 更新插件注册方式（从硬编码改为注入注册或默认插件加载策略）
+
+由于你选择了“存量项目可接受一次性迁移”，迁移脚本可以允许做较多 import/依赖层的机械改动。
+
+## 5. 验证策略（强制把测试纳入升级标准）
+抽包升级的风险主要来自：接口不一致、行为差异、路径/初始化流程变更、缓存/迁移/错误处理的绑定丢失。
+
+因此建议把现有测试用例作为“最低回归集”：
+
+1. 缓存单测：
+   - `test/framework/cache.test.ts`
+   - 关注点：`createCache`、缓存命中/未命中统计（`getCacheStats`）、清空缓存（`clearAllCaches`）、缓存过期行为
+2. 集成测试：
+   - `test/integration/integration.test.ts`
+   - 关注点：数据库连接与查询、缓存与数据库配合、以及错误处理能否正确抛出/捕获
+
+升级完成后，建议至少做到：
+1. `npm test` 全量通过（或 CI 的等价配置）
+2. 针对核心升级的“业务关键路径”用例再次验证（如果你们有业务自测项目/集成环境）
+
+## 6. 风险与规避
+1. **路径别名与运行时解析风险**：抽包后若仍依赖 `@src` 映射，运行时很容易出现找不到模块/实体收集失败。
+   - 规避：core/libs 包尽量不用 `@src` 假设；业务项目只作为使用者。
+2. **插件系统耦合风险**：硬编码插件清单会导致核心包无法独立发布。
+   - 规避：把插件清单来源解耦（核心注入接口 or 插件包）。
+3. **行为一致性风险**：缓存、迁移、错误处理属于“隐式依赖初始化顺序”的高风险模块。
+   - 规避：把对应测试纳入回归集，并确保 core 包暴露的初始化顺序与模板一致。
+
+## 7. 版本发布与升级建议
+1. 抽包属于大版本改造：建议核心包以主版本号（major）管理，遵循 semver。
+2. 对外提供“稳定导出文档”（例如 core 包的 README），并列出弃用/迁移路径。
+3. 对存量项目迁移：先在分支中完成一次迁移验证，再扩展到更多业务项目。
+
+## 8. 附录：建议的目录/文件清单（用于团队对齐）
+1. `packages/dp-koa-framework-core/**`：core 包代码与导出
+2. `packages/dp-koa-framework-libs/**`：libs 包代码与导出
+3. `packages/create-dp-koa/template/**`：模板改为依赖包
+4. `scripts/**` 或 `docs/**`：存量迁移脚本/文档
+5. `test/**`：回归测试集（至少覆盖缓存与集成）
+

package/template/package.json

@@ -65,6 +65,8 @@
     "dotenv": "^16.5.0",
     "dp-ioc2": "^1.0.1",
     "dp-mqueue": "^1.0.4",
+    "dp-koa-framework-core": "0.1.0",
+    "dp-koa-framework-libs": "0.1.0",
     "jsonwebtoken": "^9.0.2",
     "koa": "^3.0.0",
     "koa-body": "^6.0.1",

package/template/scripts/sync-template.mjs

@@ -6,7 +6,7 @@
  * 注意：template 位于仓库内部，不能使用「整棵拷贝根目录」到 template（会构成拷贝到自身子路径）。
  * 因此按顶层条目逐个拷贝。
  */
-import { cp, mkdir, readdir, rm, stat } from 'fs/promises';
+import { cp, mkdir, readdir, rm, stat, readFile, writeFile } from 'fs/promises';
 import { dirname, join, relative } from 'path';
 import { fileURLToPath } from 'url';
 
@@ -28,6 +28,18 @@ const EXCLUDED_SEGMENTS = new Set([
 /** 仓库根下整目录排除 */
 const EXCLUDED_TOP_LEVEL = new Set(['packages']);
 
+// template 内部“必须保留”的文件（防止后续 sync-template 直接覆盖回旧实现）
+// 相对路径以 DEST 为基准。
+const PRESERVE_RELATIVE_PATHS = [
+  'package.json',
+  'webpack.config.js',
+  'src/app.ts',
+  'src/routers/index.ts',
+  'src/controllers/demo/AnnotationDemoController.ts',
+  'src/controllers/example/ExampleController.ts',
+  'src/controllers/example/EnterpriseExampleController.ts',
+];
+
 function shouldCopySource(absSrc, baseRoot) {
   const rel = relative(baseRoot, absSrc);
   if (!rel || rel === '.') return true;
@@ -48,12 +60,27 @@ async function pathExists(p) {
   }
 }
 
+async function readIfExists(filePath) {
+  if (!(await pathExists(filePath))) return null;
+  return await readFile(filePath, 'utf8');
+}
+
 async function main() {
   if (!(await pathExists(join(REPO_ROOT, 'package.json')))) {
     console.error('sync-template: 请在仓库根目录运行（未找到根 package.json）');
     process.exit(1);
   }
 
+  // 同步前先把需要保留的文件内容读出来
+  const preserved = new Map();
+  for (const rel of PRESERVE_RELATIVE_PATHS) {
+    const abs = join(DEST, rel);
+    const content = await readIfExists(abs);
+    if (content !== null) {
+      preserved.set(rel, content);
+    }
+  }
+
   await rm(DEST, { recursive: true, force: true });
   await mkdir(DEST, { recursive: true });
 
@@ -74,6 +101,17 @@ async function main() {
     });
   }
 
+  // 回填被保留的 template 文件内容
+  for (const [rel, content] of preserved.entries()) {
+    const targetAbs = join(DEST, rel);
+    await mkdir(dirname(targetAbs), { recursive: true });
+    await writeFile(targetAbs, content, 'utf8');
+  }
+
+  // 删除 lock 文件，避免复制后出现 file: 路径依赖问题
+  await rm(join(DEST, 'package-lock.json'), { force: true });
+  await rm(join(DEST, 'yarn.lock'), { force: true });
+
   console.log(`sync-template: 已写入 ${DEST}`);
 }
 

package/template/src/app.ts

@@ -1,31 +1,36 @@
 import { DataSourceOptions } from "typeorm";
-import { bootstrap, setAfterBootstrap, setBeforeBootstrap } from "./framework/utils/bootstrap";
-import { initDb, closeDb, getDataSource } from "@src/framework/utils/db";
-import { clearAllCaches } from "@src/framework/utils/cache";
-import { databaseConfigManager } from "@src/framework/utils/databaseConfig";
-import { migrationManager } from "@src/framework/utils/MigrationManager";
-import { transactionManager } from "@src/framework/utils/TransactionManager";
-import { cacheManager } from "@src/framework/utils/CacheManager";
 import { testDataInitializer } from "@src/utils/testDataInitializer";
-import { isDebug, sleep } from "@src/framework/utils/function";
-import { logger } from "@src/framework/utils/logger";
-import { MigrationHelper } from "@src/framework/utils/MigrationHelper";
-import { AnnotationSystemInitializer } from "@src/framework/decorator/processor/AnnotationSystemInitializer";
-import { annotationRegistry } from "@src/framework/decorator/processor/AnnotationRegistry";
-import { createGracefulShutdownController } from "@src/framework/utils/gracefulShutdown";
 import Router from "@src/routers";
 import dbEntities from "@src/entity"
-import { router } from "@src/framework/utils/router";
 import {
+  bootstrap,
+  setAfterBootstrap,
+  setBeforeBootstrap,
+  initDb,
+  closeDb,
+  getDataSource,
+  clearAllCaches,
+  databaseConfigManager,
+  migrationManager,
+  transactionManager,
+  cacheManager,
+  isDebug,
+  sleep,
+  logger,
+  MigrationHelper,
+  AnnotationSystemInitializer,
+  annotationRegistry,
+  createGracefulShutdownController,
+  router,
   collectPluginEntities,
   getEnabledPlugins,
   registerPluginRoutes,
   runAfterBootstrapHooks,
   runBeforeBootstrapHooks,
-} from "@src/framework/plugins/registry";
+  staticMiddleware,
+} from "dp-koa-framework-core";
 import Koa from "koa";
 import path from "path";
-import staticMiddleware from "@src/middlewares/static.middleware";
 
 const shutdown = createGracefulShutdownController({ logger });
 

package/template/src/controllers/demo/AnnotationDemoController.ts

@@ -1,6 +1,4 @@
-import { Get, Query, State } from '@src/framework/decorator/controller';
-import { Logging, Permission, RateLimit } from '@src/framework/decorator/processor/AnnotationDecorators';
-import { PerformanceMonitor } from '@src/annotations/decorators/PerformanceMonitor';
+import { Get, Query, State, Logging, Permission, RateLimit, PerformanceMonitor } from 'dp-koa-framework-core';
 import { BaseController } from '@src/controllers/base.controller';
 
 /**

package/template/src/controllers/example/EnterpriseExampleController.ts

@@ -3,14 +3,7 @@
  * 展示所有企业级注解的使用方法
  */
 
-import { Get, Post, Body, Query, State } from '@src/framework/decorator/controller';
-import { Logging, Permission, RateLimit } from '@src/framework/decorator/processor/AnnotationDecorators';
-import { 
-    EnterprisePerformance, 
-    SecurityAudit, 
-    DistributedTracing, 
-    ConfigManagement 
-} from '@src/annotations';
+import { Get, Post, Body, Query, State, Logging, Permission, RateLimit, EnterprisePerformance, SecurityAudit, DistributedTracing, ConfigManagement } from 'dp-koa-framework-core';
 import { BaseController } from '@src/controllers/base.controller';
 
 /**
@@ -148,7 +141,7 @@ export class EnterpriseExampleController extends BaseController {
             { type: 'object' },
             { 
                 type: 'object',
-                custom: (value) => typeof value.newFeature === 'boolean'
+                custom: (value: any) => typeof (value as any).newFeature === 'boolean'
             }
         ]
     })

package/template/src/controllers/example/ExampleController.ts

@@ -1,8 +1,17 @@
-import { Get, Query, State } from '@src/framework/decorator/controller';
-import { Logging, Permission, RateLimit } from '@src/framework/decorator/processor/AnnotationDecorators';
-import { PerformanceMonitor } from '@src/annotations/decorators/PerformanceMonitor';
+import { Get, Query, State, Logging, Permission, RateLimit, PerformanceMonitor } from 'dp-koa-framework-core';
 import { BaseController } from '@src/controllers/base.controller';
-import { Api, ApiTags, ApiResponse, ApiOperation } from '@src/framework/decorator/swagger';
+import { Api, ApiTags, ApiResponse, ApiOperation, ProcessorManager, LoggingProcessor, PermissionProcessor, RateLimitProcessor, logger } from 'dp-koa-framework-core';
+
+/**
+ * 测试/示例用：注册自定义注解处理器。
+ * 注意：此函数不会影响框架的默认初始化流程；只用于按需注册。
+ */
+export function initializeCustomProcessors(): void {
+    ProcessorManager.registerProcessor(new LoggingProcessor());
+    ProcessorManager.registerProcessor(new PermissionProcessor());
+    ProcessorManager.registerProcessor(new RateLimitProcessor());
+    logger.info('自定义注解处理器已注册');
+}
 
 /**
  * 示例控制器 - 展示新的注解系统用法

package/template/src/entity/index.ts

@@ -1,15 +1 @@
-import { GoodsImagesUnlockKeyEntity } from "@src/entity/goodsImagesUnlockKey.entity";
-import { YtGoodsUnlockerEntity } from "@src/entity/goodsUnlocker.entity";
-import { ShopEntity } from "@src/entity/shop.entity";
-import { ShopAndUserEntity } from "@src/entity/shopUser.entity";
-import { YtGoodsEntity } from "@src/entity/ytGoods.entity";
-import { YtUserEntity } from "@src/entity/ytUser.entity";
-
-export default [
-    YtUserEntity,
-    YtGoodsEntity,
-    YtGoodsUnlockerEntity,
-    GoodsImagesUnlockKeyEntity,
-    ShopEntity,
-    ShopAndUserEntity,
-]
+export default []

package/template/src/framework/decorator/processor/AnnotationProcessor.ts

@@ -1,5 +1,6 @@
 import { Context } from 'koa';
 import { annotationRegistry } from '@src/framework/decorator/processor/AnnotationRegistry';
+import { logger } from '@src/framework/utils/logger';
 
 /**
  * 注解处理器接口
@@ -111,7 +112,10 @@ export class AnnotationExecutor {
                         return false;
                     }
                 } catch (error) {
-                    console.error(`注解处理器 ${processor.name} 执行失败:`, error);
+                    // 处理器异常不应中断后续处理器；测试用例里该异常属于“预期流程”时不打印堆栈噪音
+                    if (process.env.NODE_ENV !== 'test') {
+                        logger.error(`注解处理器 ${processor.name} 执行失败`, error as Error);
+                    }
                     // 可以选择是否继续执行其他处理器
                     // 这里选择继续执行
                 }