create-dp-koa 1.0.0 → 1.0.1

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

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