create-dp-koa 1.0.0 → 1.0.2

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

@@ -0,0 +1,105 @@
+---
+alwaysApply: false
+---
+# Skill：启动生命周期规范（setBeforeBootstrap / setAfterBootstrap）
+
+## 适用与触发（重要）
+- 仅当需要修改/新增启动逻辑（`src/app.ts`）或框架启动流程（`src/framework/utils/bootstrap.ts`）时启用本 Skill。
+- 触发口令建议：
+  - “请按 `50-backend-bootstrap-lifecycle.skill.md` 调整启动流程”
+
+---
+
+## 一、真实执行顺序（必须理解并遵守）
+以 `src/framework/utils/bootstrap.ts` 为准：
+
+1. `bootstrap()` 内部 **先执行** `beforeBootstraps(app)`（如果已注册）
+2. 然后框架挂载：CORS → 日志中间件 → 框架错误处理中间件 → `koaBody()`
+3. 然后挂载：`router.routes()/allowedMethods()` 并 `app.listen(...)`
+4. `listen` 成功后 **再执行** `afterBootstraps(app)`（如果已注册）
+
+结论：
+- **before**：发生在“框架中间件/路由挂载/监听端口”之前
+- **after**：发生在“监听端口成功”之后
+
+---
+
+## 二、setBeforeBootstrap(fn) 规范（必须）
+
+### 2.1 允许做的事情（推荐放这里）
+- **注册必须最先执行的中间件**（例如静态资源 `staticMiddleware`）
+- **完成路由注册/绑定**（例如调用 `Router()` 让 `bindRouter` 把 Controller 注册到 router）
+- **初始化框架级系统**（例如注解系统初始化、配置系统初始化）
+- **初始化数据库与依赖它的组件**
+  - 连接数据库（`initDb`）
+  - 设置 `transactionManager/migrationManager` 的 DataSource
+  - 生产环境迁移（如有）
+  - 内存库模式初始化测试数据（如有）
+
+### 2.1.1 环境变量文件与 `.env` 选择（对齐 `bootstrap.ts`）
+
+- **与 `NODE_ENV` 解耦**：`bootstrap.ts` 最早加载的 `.env` 文件由 **`isDebug()`** 决定：
+  - `--env=debug` → `.env.development`
+  - 否则 → `.env.production`
+- **本地开发**：`package.json` 的 `dev` 建议在 `node dist/main.js` 后追加 `--env=debug`，避免误加载生产 env。
+- **生产部署**：进程**不要**带 `--env=debug`，否则迁移与脱敏等行为会按“调试口径”执行。
+
+### 2.1.2 数据库迁移触发时机（对齐 `app.ts`）
+
+- 迁移执行条件以 **`!isDebug()`** 为准（非 debug 即跑迁移），与 `NODE_ENV` 解耦。
+- 迁移类需**显式注册**到 DataSource（如 `src/migrations/index.ts` 导出 `APP_MIGRATIONS`），避免 webpack 单文件部署后无法按路径扫描迁移文件。
+
+### 2.2 必须遵守的约束
+- 回调函数签名必须能接收 `app: Koa`（框架会 `beforeBootstraps(app)` 调用）
+- **只注册一次**：项目当前实现中 `beforeBootstraps` 只有一个槽位，后注册会覆盖先注册
+- 发生异常必须：
+  - 记录日志
+  - 抛出异常（让启动失败），避免“半初始化”状态继续运行
+
+### 2.3 禁止行为
+- ❌ 在这里启动“永不结束的任务”阻塞启动（例如无限循环、长期 await 不返回）
+- ❌ 在这里写业务逻辑（仅做启动编排/初始化）
+
+---
+
+## 三、setAfterBootstrap(fn) 规范（必须）
+
+### 3.1 允许做的事情（推荐放这里）
+- **启动后台/周期性任务**（例如数据库连接监控 `dbMonitor.startMonitoring()`）
+- **启动只依赖服务器已监听的组件**（例如需要对外暴露端口后再启动的探针/上报）
+- **输出启动完成日志**、打印运行信息
+
+### 3.2 必须遵守的约束
+- 回调函数签名必须能接收 `app: Koa`
+- after 内部出错：
+  - 必须记录日志
+  - 不应静默失败（至少可观测）；必要时应触发优雅退出策略（按项目约定）
+- **只注册一次**：项目当前实现中 `afterBootstraps` 只有一个槽位，后注册会覆盖先注册
+
+### 3.3 禁止行为（强烈）
+- ❌ 在 after 阶段新增路由/中间件/全局行为（会导致启动行为不可预测）
+  - 路由与中间件应在 before 阶段完成，保证一致性
+- ❌ 在 after 阶段再做“数据库 schema 级别变更/迁移”等破坏性操作
+
+---
+
+## 四、`src/app.ts` 推荐写法（对齐范式）
+
+### 4.1 before 推荐结构
+- 注册静态中间件（如需要最前置）
+- 初始化注解系统
+- 调用 `Router()` 完成 Controller→router 绑定
+- 初始化数据库、迁移、测试数据、事务管理器 DataSource
+
+### 4.2 after 推荐结构
+- 启动 dbMonitor 等后台任务
+- 打印启动后日志
+
+---
+
+## 五、常见坑（必须避免）
+- before/after **不是数组**，目前实现是单个槽位：多次调用会覆盖
+- `Router()` 必须在 `app.use(router.routes())` 之前执行；因此应放在 before
+- 若在 before 里注册中间件，其执行顺序会早于框架默认中间件（因为 before 先 `app.use`）
+
+

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

@@ -0,0 +1,73 @@
+---
+alwaysApply: false
+---
+# Skill：路由注册规范（routers/index.ts + bindRouter）
+
+## 适用与触发（重要）
+- 仅当需要新增/修改路由绑定（`src/routers/index.ts`）或调整路由系统（`src/framework/utils/router.ts`）时启用本 Skill。
+- 触发口令建议：
+  - “请按 `60-backend-router-registration.skill.md` 规范注册路由”
+
+---
+
+## 一、路由注册机制（必须理解）
+本项目路由注册入口：`src/routers/index.ts`  
+路由绑定工具：`src/framework/utils/router.ts` 的 `bindRouter(...)`
+
+### 1.1 bindRouter(...) 的真实行为（以代码为准）
+- 调用形式：
+  - `bindRouter(prefixPath, ControllerClass)`
+  - `bindRouter(prefixPath, middleware1, middleware2, ..., ControllerClass)`
+- Controller 实例化：
+  - 由 `Provider<any>(ControllerClass)` 创建（依赖注入容器）
+- 路由生成：
+  - 读取 Controller 上的 `@Get/@Post/@Put/@Del/@All` 装饰器元数据
+  - 将每个方法的 url 与 `prefixPath` 通过 `path.join` 拼接，并规范化为 `/`
+- middleware 注入顺序：
+  - 传入的 middlewares 会按顺序对该 prefix 下的每个具体 `_url` 执行 `_router.use(_url, middleware)`
+  - 再注册对应 method 的路由处理函数（`_router.get/post/...`）
+- 尾斜杠兼容：
+  - 若生成的 `_url` 以 `/` 结尾，会同时注册“去掉尾斜杠”的版本（避免 `/a/` 与 `/a` 不兼容）
+
+---
+
+## 二、`src/routers/index.ts` 注册规范（必须遵守）
+
+### 2.1 只做“路由绑定”
+- `routers/index.ts` 只负责：
+  - 导入 Controller
+  - 选择是否需要 middlewares（鉴权/日志等）
+  - 调用 `bindRouter(prefix, ...middlewares, Controller)`
+- 禁止在此文件写业务逻辑或数据库操作
+
+### 2.2 路由前缀命名（推荐统一）
+建议用“模块/领域 + 子模块 + 资源”的层级前缀，保持稳定：
+- `"/public/..."`：公开接口（一般不加“认证/鉴权 middleware”）
+- `"/home/..."`：业务接口（按需加“认证/鉴权 middleware”）
+- `"/admin/..."`：管理接口（一般需要认证/鉴权；可在此基础上再加权限/审计中间件）
+- `"/health"`：健康检查（通常不鉴权）
+- `"/test"`：测试/调试接口（仅测试环境或内存库模式有效时暴露）
+
+### 2.3 middleware 使用规范（必须）
+- 需要认证/鉴权的路由必须在 `bindRouter` 里显式挂“认证/鉴权 middleware”（名称不固定，以项目实际为准）：
+  - 示例（本项目当前实现）：`bindRouter("/home/user/yt_user", tokenMiddleware(), YtUserController);`
+- middlewares 必须传“可执行的 koa middleware 函数”：
+  - 例如 `authMiddleware()` / `tokenMiddleware()`（注意是调用结果，而不是函数引用本身）
+- middleware 顺序必须从“通用/鉴权”到“更具体/业务”：
+  - 例如：`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

@@ -0,0 +1,100 @@
+---
+alwaysApply: false
+---
+# Skill：中间件开发与注册规范（src/middlewares）
+
+## 适用与触发（重要）
+- 仅当需要新增/修改中间件（`src/middlewares/*`）或调整中间件注册顺序（`src/framework/utils/bootstrap.ts`、`src/app.ts`、`src/routers/index.ts`）时启用本 Skill。
+- 触发口令建议：
+  - “请按 `70-backend-middleware.skill.md` 新增/调整中间件”
+
+---
+
+## 一、目录与命名（必须）
+- 中间件放在：`src/middlewares/`
+- 文件名使用：`xxx.middleware.ts`
+- 导出方式建议统一为“工厂函数返回 koa middleware”：
+  - `export default function xxxMiddleware(options?) { return async (ctx, next) => { ... } }`
+  - 或 `export const xxxMiddleware = (options?) => async (ctx, next) => { ... }`
+
+---
+
+## 二、已有中间件模式（对齐现状）
+请对齐本项目现有实现风格（不要臆造不存在的框架能力）：
+- `token.middleware.ts`：认证/鉴权类中间件（读取 Authorization Bearer token，验签后写入 `ctx.state.user`）
+- `logging.middleware.ts`：请求链路日志/审计/性能（挂载 `ctx.logger`、`ctx.requestId`）
+- `static.middleware.ts`：静态资源挂载（`koa-mount + koa-static`）
+- `error.middleware.ts`：简单错误兜底（本项目框架层已有更强的 error middleware，谨慎重复）
+
+---
+
+## 三、中间件职责边界（必须）
+
+### 3.1 允许做的事
+- **读取/设置 ctx 上下文**：如 `ctx.state.user`、`ctx.requestId`、`ctx.logger`
+- **做鉴权/限流/审计/缓存/静态资源**等横切能力
+- **按需提前返回**：例如鉴权失败时设置 `ctx.status` + `ctx.body` 并 `return`
+
+### 3.2 禁止做的事
+- ❌ 在中间件里写业务逻辑（应下沉 Service/Controller）
+- ❌ 在中间件里直接访问数据库（除非该中间件明确是“框架级基础设施”，且有清晰的性能与错误策略）
+- ❌ 吞掉错误不抛出导致上层错误处理中间件失效（除非明确要拦截并返回标准错误响应）
+
+---
+
+## 四、错误处理规范（必须）
+- 中间件必须遵循 “可观测 + 可恢复”：
+  - 能处理的错误：在当前中间件内返回明确的 `ctx.status`/`ctx.body`
+  - 不能处理的错误：记录日志后 `throw`，交给框架层错误处理中间件统一处理
+- 鉴权类中间件建议：
+  - 缺 token：`401` + 明确 message
+  - token 无效/过期：`401` + 明确 message
+
+---
+
+## 五、ctx.state 与上下文规范（必须）
+- 认证/鉴权类中间件必须把用户最小信息写入 `ctx.state.user`
+  - 推荐字段：`userId`、`type`（以项目实际 token payload 为准）
+- Controller 读取用户信息应通过 `@State()` 或 `@State('user')`（由 Controller 规范约束）
+
+---
+
+## 六、注册位置与顺序（必须）
+
+### 6.1 全局中间件（bootstrap 阶段）
+在 `src/framework/utils/bootstrap.ts` 中，框架已注册：
+- CORS
+- loggingMiddleware / businessLoggingMiddleware / databaseLoggingMiddleware
+- frameworkErrorMiddleware（框架级错误处理中间件）
+- koaBody
+- router.routes/allowedMethods
+
+当你需要新增“全局中间件”时：
+- 只能在 **before 阶段**（`setBeforeBootstrap`）通过 `app.use(...)` 注册
+- 并遵守 `50-backend-bootstrap-lifecycle.skill.md` 的 before/after 约束
+
+### 6.2 路由级中间件（bindRouter 阶段）
+在 `src/routers/index.ts` 中，通过：
+- `bindRouter(prefix, middleware1, middleware2, Controller)`
+
+适用：
+- 认证/鉴权（示例：当前项目为 `tokenMiddleware()`，未来名称可能变化）
+- 某模块/某前缀下的专用拦截器
+
+顺序规则：
+- 先认证/鉴权，再业务相关中间件
+
+---
+
+## 七、Swagger 中间件（当前暂不启用）
+- 项目中存在 `swagger.middleware.ts`，但如果当前阶段“不需要 swagger”，不要在启动/路由中注册该中间件。
+
+---
+
+## 八、测试建议（可选但推荐）
+- 单元测试优先覆盖：
+  - 鉴权中间件：缺 token / 无效 token / 有效 token 能写入 `ctx.state.user`
+  - 日志中间件：是否写入 `ctx.requestId`、是否脱敏 headers
+  - 静态中间件：prefix 正规化（`/static` vs `/static/`）
+
+

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

@@ -0,0 +1,108 @@
+---
+alwaysApply: false
+---
+# Skill：libs 与 utils 规划规范
+
+## 适用与触发（重要）
+- 当需要新增/调整以下内容时启用本 Skill：
+  - `src/libs/**` 下的类库/适配层
+  - `src/utils/**` 下的工具函数
+  - 业务模块内部的 `xxx.utils.ts`
+
+---
+
+## 一、总体原则
+
+- **libs**：更偏向“小框架 / 小 SDK / 第三方服务适配层”
+- **utils**：更偏向“纯函数工具、小颗粒度无状态函数”
+- 业务相关的工具优先放在**各自业务模块内**，而不是全局 `utils/`
+
+---
+
+## 二、`src/libs/**` 放什么（必须）
+
+### 2.1 适合放在 libs 的内容
+- **第三方服务适配/封装**：
+  - 如：短信服务封装、支付网关封装、HTTP SDK 封装等
+  - 对外暴露一个干净的接口：如 `sendSms(phone, templateId, params)`
+- **可抽成独立 npm 包的库**：
+  - 例如通用缓存实现、加解密库、统一重试器等
+- **有内部状态或生命周期的组件**：
+  - 连接池包装器、复杂缓存管理器、网关客户端等
+
+### 2.2 不适合放在 libs 的内容
+- 单一的小工具函数（字符串、日期、数字转换等）
+- 强业务耦合的逻辑（如订单价格计算、业务规则判断）
+
+---
+
+## 三、`src/utils/**` 放什么（必须）
+
+### 3.1 适合放在 utils 的内容
+- **与业务无关的纯函数工具**：
+  - 时间、字符串、数字处理
+  - 通用 Promise/重试/节流/防抖等
+- **框架内的通用工具**：
+  - 例如：框架级测试数据初始化工具、通用校验帮助函数（若确实需要全局可见）
+
+### 3.2 不适合放在 utils 的内容
+- 直接访问数据库的函数（应放 Service/Repository 或框架层 utils 内聚）
+- 调用第三方 HTTP API 的函数（应放 libs 作为适配层）
+- 仅服务单一业务模块的工具（应放在该模块内部的 `xxx.utils.ts`）
+
+---
+
+## 四、业务模块内的 utils（推荐）
+
+- 用户模块示例：
+  - `src/service/user/user.utils.ts`
+- 商品模块示例：
+  - `src/service/goods/goods.utils.ts`
+
+规则：
+- 仅供本模块使用的业务工具函数，应优先放在模块自身的 utils 文件中
+- 全局 `utils/` 仅存放 **跨模块通用** 的工具
+
+---
+
+## 五、如何决策“新代码放哪”（实用检查清单）
+
+新增工具/类库时，按以下顺序判断：
+
+1. **是否依赖第三方服务/外部系统或有复杂状态？**
+   - 是 → 优先放 `libs/`（适配层/小 SDK）
+2. **是否明显只服务某一个业务模块？**
+   - 是 → 放到该模块自己的 `xxx.utils.ts`
+3. **是否 100% 纯函数、无状态且可跨多个模块复用？**
+   - 是 → 放到全局 `utils/`
+4. **未来是否有机会抽为独立 npm 包？**
+   - 是 → 更倾向放 `libs/`
+
+---
+
+## 六、命名规范（推荐）
+
+- `libs` 目录下：
+  - 文件名：`tecentSms.ts` / `mCache.ts` 等，体现“库/适配器”的语义
+  - 导出：优先导出类或工厂函数，如 `export class TencentSmsClient { ... }`
+- `utils` 目录下：
+  - 文件名：`date.utils.ts` / `string.utils.ts` / `testDataInitializer.ts` 等
+  - 导出：纯函数 `export function xxx(...) { ... }`
+
+---
+
+## 七、框架级 `src/framework/utils/function.ts`（必须）
+
+本文件提供**运行环境判定**，全项目应统一使用，避免散落 `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/.cursor/rules/85-backend-plugins.rule.md

@@ -0,0 +1,65 @@
+# 后端插件体系规范（dp-koa-framework 模板）
+
+> 目标：让“独立功能体”以插件形式存在，可插拔、易维护、与宿主框架低耦合。
+
+---
+
+## 1. 插件的基本形态
+
+- 插件统一放在 `src/plugins/<plugin-id>/` 目录下。
+- 插件根目录只保留 `index.ts`（插件入口）。
+- 插件入口必须导出一个 `PluginDescriptor`（见 `src/framework/plugins/types.ts`）。
+
+推荐目录结构：
+
+- `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. 宿主与插件的依赖方向
+
+### 2.1 插件 → 宿主
+
+- 插件内部业务代码应优先使用相对路径组织。
+- 插件调用宿主业务能力（如用户、项目、权限）应通过 **plugin-api 门面层**（建议放在 `src/plugin-api/*`），避免直接 import 宿主 Service/Repository。
+
+### 2.2 宿主 → 插件
+
+- 宿主禁止直接 import 插件 Service。
+- 宿主感知插件能力应通过：
+  - 事件扩展点（emit + register handler）
+  - SPI（可替换实现：getXxxSpi + registerXxxSpi）
+
+---
+
+## 3. 插件注册与加载
+
+- 插件注册表：`src/framework/plugins/registry.ts`
+- 宿主启动接入点：`src/app.ts`
+  - beforeBootstrap：计算启用插件、执行插件 before hook、注册插件路由、合并插件实体后初始化 DB
+  - afterBootstrap：执行插件 after hook（定时任务/订阅等）
+
+---
+
+## 4. 插件数据库规范
+
+- 插件自建表必须使用插件 ID 作为表名前缀（例如 `weboffice_files`、`weboffice_file_versions`）。
+- 插件迁移原则上只操作自身前缀表，避免修改宿主核心表结构。
+
+---
+
+## 5. 示例插件：weboffice
+
+模板内置示例插件：`src/plugins/weboffice/`
+
+- 通过 `WEBOFFICE_ENABLED` 环境变量控制启用（默认启用；设为 `0` 禁用）。
+- 路由入口：`src/plugins/weboffice/http/routes.ts`
+- 插件实体：`src/plugins/weboffice/entities/*`
+
+> 注意：模板示例插件的 `getUsers` 为占位实现（不依赖宿主业务用户表）。真实业务接入时应改为通过 plugin-api 调宿主用户体系。
+

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

@@ -0,0 +1,29 @@
+---
+alwaysApply: false
+---
+# Skill：后端测试规范（Jest）
+
+## 一、测试基础
+
+- 使用 Jest
+- 使用 `TestDatabaseHelper` 管理测试数据库
+- 使用 `Provider` 获取 Service 实例
+
+---
+
+## 二、测试要求
+
+- 必须覆盖：
+  - 成功场景
+  - 失败场景
+  - 边界条件
+- 测试必须相互独立
+- 每个测试前重置数据
+
+---
+
+## 三、测试文件结构
+
+- Controller：`test/controllers/**`
+- Service：`test/service/**`
+- Framework：`test/framework/**`

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

@@ -0,0 +1,49 @@
+# Cursor Rules 索引（Backend Skills）
+
+本目录用于约束/引导 Cursor 在本项目中的后端代码生成与修改行为。
+
+## 使用建议（先选 Command，再选 Skill）
+- **需要先规划再动手**：用 `.cursor/commands/plan-backend.md`
+- **要写/改 Controller**：用 `.cursor/commands/implement-backend-api-controller.md`（并按需启用 `11-...` Recipes）
+- **只想要 Controller 范式/注解速查**：用 `.cursor/commands/cheatsheet-backend-controller.md`
+
+## Skills 列表（按编号/作用域）
+
+### 00 - 核心约束（默认全局）
+- **`00-backend-core.skill.md`**（alwaysApply: true）
+  - 分层架构（Controller/Service/Repository）
+  - 基类继承与统一响应结构（`BaseController.success/fail`、`CommonServiceResult`）
+  - **运行环境判定**：`isDebug()` / `getRuntimeEnvironmentLabel()`（与 `NODE_ENV` 解耦，详见该文件）
+
+### 10 - Controller / API（按需启用）
+- **`10-backend-api.skill.md`**
+  - Controller 编排规则：DTO + Service 调用 + 统一响应映射 + try/catch
+- **`11-backend-controller-recipes.skill.md`**
+  - Controller 推荐模板（可复制）+ 常用注解速查（@Query/@Body/@State/...）
+
+### 20~40 - 数据/校验/错误（按需启用）
+- **`20-backend-repository.skill.md`**：Repository 使用与事务（`transactionManager.executeInTransaction`）
+- **`30-backend-validation.skill.md`**：DTO 分层规范（Controller DTO / Service DTO）、命名规范、转换规范、参数校验（@ParamValidate）
+- **`40-backend-error-logging.skill.md`**：错误处理与日志（try/catch、脱敏、上下文）
+
+### 50~70 - 启动/路由/中间件（按需启用）
+- **`50-backend-bootstrap-lifecycle.skill.md`**
+  - `setBeforeBootstrap` / `setAfterBootstrap` 的职责与禁止项
+  - `.env` 选择、`isDebug()`、迁移与 webpack 显式注册迁移（`APP_MIGRATIONS`）
+- **`60-backend-router-registration.skill.md`**
+  - `src/routers/index.ts` + `bindRouter` 的注册规范（前缀、middleware 顺序、禁止重复绑定）
+- **`70-backend-middleware.skill.md`**
+  - `src/middlewares/*` 的中间件模式、错误处理、ctx.state 约定、注册位置与顺序
+
+### 80 - 工程结构（按需启用）
+- **`80-backend-utils-and-libs.skill.md`**
+  - `src/libs` vs `src/utils` 的放置规则与决策清单
+  - `src/framework/utils/function.ts`：`isDebug()` / `getRuntimeEnvironmentLabel()` 约定
+
+### 90 - 测试（按需启用）
+- **`90-backend-testing.skill.md`**
+  - Jest 测试结构与基本要求（配合 `TestDatabaseHelper`）
+
+
+
+

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/scripts/sync-template.mjs

@@ -22,7 +22,6 @@ const EXCLUDED_SEGMENTS = new Set([
   'coverage',
   '.git',
   '.DS_Store',
-  '.cursor',
   '.idea',
 ]);