create-dp-koa 1.0.0 → 1.0.1

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "create-dp-koa",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Scaffold a DP-Koa framework project from the official template",
   "type": "module",
   "bin": {
-    "create-dp-koa": "./index.mjs"
+    "create-dp-koa": "index.mjs"
   },
   "files": [
     "index.mjs",

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

@@ -0,0 +1,45 @@
+# Command：Backend Controller Cheatsheet
+
+你现在是【后端 Controller 速查助手】。
+
+## 适用场景（触发条件）
+- 用户想要 Cursor 快速给出：**Controller 推荐写法** + **常用注解用法** + **最小可复制模板**。
+- 本 Command **不直接修改代码**（只输出建议与模板）。
+
+---
+
+## 必须遵守的 Skills / Rules
+- 始终遵守：`00-backend-core.skill.md`
+- 本次必须启用并参考：
+  - `10-backend-api.skill.md`
+  - `11-backend-controller-recipes.skill.md`
+
+---
+
+## 输出要求（严格遵守）
+请严格按以下结构输出（只输出文本，不直接生成业务代码文件）：
+
+```text
+【适用结论】
+- 这次是否属于“写/改 Controller 路由接口”：是/否
+- 推荐启用的 Skills：
+
+【Controller 推荐骨架（最小模板）】
+- 给出一个可复制的 Controller 方法模板（含 @Get/@Post + @Query/@Body/@State + try/catch + success/fail）
+
+【常用注解速查】
+- @Get/@Post：说明 + 何时用
+- @Query/@Body：说明 + DTO 写法
+- @State() vs @State('user')：差异 + 推荐写法
+- @ResponseCode/@ResponseHeader：何时用
+- @ResponseValidator/@ResponseValidateIf：何时用（可选）
+
+【DTO/Service 设计建议】
+- 入参 DTO 应放在哪个目录、命名建议
+- Service 方法签名建议（含返回类型）
+
+【对齐的项目样例（必须列出）】
+- 列出你参考的文件路径（至少 2 个）
+```
+
+

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

@@ -0,0 +1,58 @@
+# Command：Implement Backend API Controller
+
+你现在是【后端 API Controller 实现器】。
+
+## 适用场景（触发条件）
+- 仅当用户要 **新增/修改 Controller 路由接口**（含 DTO、Swagger、响应映射）时使用本 Command。
+- 本 Command 的目标是：**直接落地代码改动**（不是只做规划）。
+- 如果用户只要规划，请改用：`plan-backend.md`
+
+---
+
+## 必须遵守的 Skills / Rules
+- 始终遵守：`00-backend-core.skill.md`
+- 本次必须额外启用并严格遵守：`10-backend-api.skill.md`
+- 强烈建议同时启用（用于让写法更“像本项目”）：`11-backend-controller-recipes.skill.md`
+- 同时配套使用（按需要）：
+  - `30-backend-validation.skill.md`（DTO + 校验）
+  - `40-backend-error-logging.skill.md`（try/catch + 日志）
+  - `20-backend-repository.skill.md`（如涉及事务/数据访问）
+  - `90-backend-testing.skill.md`（如需要补测试）
+  
+---
+
+## 输入要求（信息不足必须先澄清）
+当用户未提供以下信息时，必须先提问澄清再写代码：
+- **接口清单**：路径、方法（GET/POST）、接口用途
+- **入参**：Query/Body/State 的字段、类型、是否必填
+- **输出**：成功返回 data 结构、失败场景与错误码/错误信息
+- **Service 目标**：要调用的 Service 方法名（或由你提出建议）
+- **是否需要 Swagger**：对外接口默认需要（若用户明确不需要则不加）
+
+---
+
+## 实现约束（执行时必须检查）
+- **路由/参数装饰器必须使用**：`@Get/@Post` + `@Query/@Body/@State`
+- **DTO 必须强类型**：禁止 `any`；DTO 放到 `src/dto/controller/{module}/`
+- **Controller 必须 try/catch**
+- **Controller 必须映射统一响应**：使用 `BaseController.success/fail`，禁止 `return result`
+- **禁止在 Controller 写业务逻辑/直接访问数据库**
+
+---
+
+## 输出/交付（你必须做到）
+1. **明确将要修改/新增的文件列表**（含路径）
+2. **实现 DTO**（必要时新建文件）
+3. **实现/修改 Controller**（装饰器 + DTO + try/catch + 响应映射）
+4. **如需**：补 Swagger 装饰器、补/改 Service 接口签名
+5. **如需**：补 Jest 测试（至少覆盖成功/失败/边界之一）
+
+---
+
+## 写代码前的对齐动作（必须）
+- 在生成/修改 Controller 代码前，先对齐本项目示例写法：
+  - `src/controllers/example/NewAnnotationExampleController.ts`
+  - `src/controllers/home/ytUser.controller.ts`
+  - `src/controllers/base.controller.ts`
+
+

package/template/.cursor/commands/plan-backend.md

@@ -0,0 +1,97 @@
+# Command：Backend Skill Planner
+
+你现在是【后端技能规划器（Backend Skill Planner）】。
+
+你的职责是：
+- 分析用户的后端开发需求
+- 规划应该使用哪些 Backend Skills
+- 给出清晰、可执行的技能调用顺序
+- 不直接生成业务代码
+
+---
+
+## 一、你可以使用的 Skills（已定义）
+
+- Backend Core Skill（始终生效）
+- Backend API Skill
+- Backend Service Skill
+- Backend Repository Skill
+- Backend Validation Skill
+- Backend Error & Logging Skill
+- Backend Testing Skill
+- Backend Bootstrap Lifecycle Skill（启动生命周期：before/after/bootstrap）
+- Backend Router Registration Skill（路由注册：routers/index.ts + bindRouter）
+
+---
+
+## 二、规划规则（必须遵守）
+
+1. **不要直接写代码**
+2. **不要跳过规划步骤**
+3. 每个 Skill 必须说明：
+   - 使用原因
+   - 预期输出
+4. 如果用户信息不足，必须先提出澄清问题
+5. 输出结构必须严格遵守下方格式
+6. 若需求涉及启动流程/中间件顺序/路由注册/数据库初始化/监控任务：
+   - 必须纳入 Backend Bootstrap Lifecycle Skill（`50-backend-bootstrap-lifecycle.skill.md`）
+7. 若需求涉及新增/修改路由绑定（`src/routers/index.ts`）、调整 `bindRouter` 或路由体系：
+   - 必须纳入 Backend Router Registration Skill（`60-backend-router-registration.skill.md`）
+
+---
+
+## 三、输出格式（严格遵守）
+
+```text
+【需求理解】
+- 用户目标：
+- 涉及模块：
+- 是否新增 / 修改：
+
+【技能规划】
+Step 1：Backend Validation Skill
+- 原因：
+- 输出：
+
+Step 2：Backend API Skill
+- 原因：
+- 输出：
+
+Step 3：Backend Service Skill
+- 原因：
+- 输出：
+
+Step 4：Backend Repository Skill
+- 原因：
+- 输出：
+
+Step 5：Backend Error & Logging Skill
+- 原因：
+- 输出：
+
+Step 6：Backend Testing Skill（如需要）
+- 原因：
+- 输出：
+
+Step X：Backend Bootstrap Lifecycle Skill（如涉及启动/bootstrapping）
+- 原因：
+- 输出：
+
+Step Y：Backend Router Registration Skill（如涉及路由注册/routers/index.ts）
+- 原因：
+- 输出：
+
+【不确定点 / 需要澄清】
+- 问题 1：
+- 问题 2：
+
+【执行建议】
+- 推荐使用的 Commands：
+- 是否可以进入代码生成阶段：
+
+---
+
+## 四、可用 Commands（建议在【执行建议】中引用）
+- `plan-backend.md`：只做技能规划，不直接写代码
+- `implement-backend-api-controller.md`：新增/修改 Controller 路由接口（显式启用 Backend API Skill）
+- `cheatsheet-backend-controller.md`：输出 Controller 推荐写法 + 常用注解速查（不直接改代码）

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

@@ -0,0 +1,61 @@
+---
+alwaysApply: true
+---
+# Skill：后端核心开发规范（Backend Core）
+
+## 适用范围
+- 本项目所有 TypeScript 后端代码
+- 技术栈：Koa + TypeORM + dp-ioc2 + 自定义装饰器体系
+- **包管理工具：必须使用 yarn（禁止使用 npm）**
+
+---
+
+## 运行环境判定（debug 口径，必须）
+
+**唯一标准**：以 `src/framework/utils/function.ts` 为准，**不要**用 `process.env.NODE_ENV` 作为“是否生产/是否调试”的单一判断。
+
+- **`isDebug()`**：当进程启动参数中包含 `--env=debug` 时为 `true`。
+- **非 debug**：一律按**生产口径**处理（例如：迁移、静态资源长缓存、对外错误信息脱敏等）。
+- **`getRuntimeEnvironmentLabel()`**：返回 `'development' | 'production'`，用于日志与配置元数据，**与 `NODE_ENV` 解耦**。
+
+**例外**：`NODE_ENV === 'test'`（Jest 等）仍保留用于测试专用分支，与上述 debug 口径并行，不互相替代。
+
+---
+
+## 一、分层架构（必须遵守）
+
+### 分层职责
+- **Controller 层**
+  - 接收请求
+  - 参数校验
+  - 调用 Service
+  - 返回统一响应
+- **Service 层**
+  - 编写业务逻辑
+  - 调用 Repository
+- **Repository 层**
+  - 封装数据库访问逻辑（TypeORM）
+
+---
+
+## 二、基类与返回规范
+
+### 基类继承
+- Controller **必须继承** `BaseController`
+- Service **必须继承** `BaseService`
+
+### Service 返回值
+- Service 方法必须返回 `CommonServiceResult<T>`
+
+### Controller 返回值
+- Controller 必须通过：
+  - `this.success<T>(data, message?)`
+  - `this.fail<T>(code, message?)`
+
+返回 `ControllerResponse<T>`：
+```ts
+{
+  code: number
+  data: T | null
+  message: string
+}

package/template/.cursor/rules/01-backend-skill-router.skill.md

@@ -0,0 +1,57 @@
+---
+alwaysApply: true
+---
+# Skill：Backend Skill Router（规则路由器）
+
+你现在的角色是【后端 Skill 路由器】：你的目标是帮助选择应启用的 rules/skills/commands，避免盲用规则。
+
+## 总原则（必须遵守）
+- **优先使用 Commands** 来触发正确的 Skills，而不是把所有规则都写成 alwaysApply。
+- 如果用户需求不清晰，必须先提问澄清（不要臆造不存在的接口/文件/配置）。
+
+---
+
+## 你必须做的事（每次用户提出开发/改动请求时）
+
+### 1) 识别任务类型（多选）
+- Controller/API 开发
+- DTO/参数校验
+- Service/Repository/事务
+- 错误处理/日志
+- 启动流程（`app.ts`/`bootstrap.ts`，before/after）
+- 路由注册（`routers/index.ts`、`bindRouter`）
+- 中间件（`src/middlewares/*`）
+- 测试（Jest）
+- 目录结构与放置（libs/utils）
+
+### 2) 给出推荐启用的 Skills（只列文件名即可）
+按任务类型映射：
+- **Controller/API**：
+  - `10-backend-api.skill.md`
+  -（需要范式/注解速查时）`11-backend-controller-recipes.skill.md`
+- **Service**：
+  - `21-backend-service.skill.md`
+- **DTO/校验**：`30-backend-validation.skill.md`
+- **Service/Repository/事务**：`20-backend-repository.skill.md`
+- **错误/日志**：`40-backend-error-logging.skill.md`
+- **启动流程**：`50-backend-bootstrap-lifecycle.skill.md`
+- **路由注册**：`60-backend-router-registration.skill.md`
+- **中间件**：`70-backend-middleware.skill.md`
+- **测试**：`90-backend-testing.skill.md`
+- **libs/utils 放置**：`80-backend-utils-and-libs.skill.md`
+
+注意：
+- `00-backend-core.skill.md` 已是 alwaysApply，无需重复声明
+
+### 3) 推荐使用的 Command（优先）
+- 需要先规划：`.cursor/commands/plan-backend.md`
+- 要实现/修改 Controller：`.cursor/commands/implement-backend-api-controller.md`
+- 只要 Controller 速查：`.cursor/commands/cheatsheet-backend-controller.md`
+
+---
+
+## 输出要求（简短）
+- 当用户让你“直接写代码”：直接进入实现，但先在心里完成上述路由选择
+- 当用户不确定或信息不足：先问 2~5 个关键澄清问题
+
+

package/template/.cursor/rules/10-backend-api.skill.md

@@ -0,0 +1,55 @@
+---
+alwaysApply: false
+---
+# Skill：后端 API 开发规范
+
+## 适用与触发（重要）
+- **仅在**你要生成/修改 **Controller 路由接口** 时应用本 Skill（否则忽略）
+- 触发口令建议：
+  - “按 `10-backend-api.skill.md` 实现/重构这个 Controller”
+  - “按 API Skill 写路由 + DTO + 统一响应”
+
+---
+
+## 一、路由与参数装饰器（必须）
+- 路由装饰器：`@Get` / `@Post`
+- 参数装饰器：`@Query` / `@Body` / `@State`
+- 禁止在 Controller 中手动解析 ctx（除非该 Controller 明确以 ctx 作为参数且项目已有同类写法）
+
+---
+
+## 二、Controller 编排规范（必须）
+
+### 2.1 只做三件事
+- **参数接收与校验**（DTO）
+- **调用 Service**
+- **映射为统一响应**（`BaseController.success/fail`）
+
+### 2.2 统一响应（必须）
+- Controller 必须返回 `ControllerResponse<T>`（通过 `this.success()` / `this.fail()`）
+- 禁止 `return result`（Service 原始结果）：
+  - 成功：`return this.success(result.data, result.message?)`
+  - 失败：`return this.fail(result.code, result.message)`
+
+### 2.3 错误处理（必须）
+- Controller 的 `async` 方法必须 `try/catch`
+- catch：记录日志（见 `40-backend-error-logging.skill.md`）+ 返回通用失败响应
+
+### 2.4 DTO（必须）
+- `@Query()` / `@Body()` 必须使用 **DTO 类型**（禁止 `any`）
+- DTO 的定义与校验遵循 `30-backend-validation.skill.md`
+
+---
+
+## 三、接口文档与元信息（可选但优先）
+- 对外接口优先补齐 Swagger：`@ApiTags` / `@Api` / `@ApiResponse`
+- 需要显式状态码/响应头时使用：`@ResponseCode` / `@ResponseHeader`
+
+---
+
+## 四、禁止行为（必须）
+- ❌ Controller 中编写业务逻辑（应下沉到 Service）
+- ❌ Controller 中直接访问数据库/Repository
+- ❌ Controller 中返回 Service 原始结果（必须映射为统一响应）
+- ❌ `@Query()` / `@Body()` 使用 `any` 或未校验的入参对象
+

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

@@ -0,0 +1,109 @@
+---
+alwaysApply: false
+---
+# Skill：Controller 推荐写法 + 常用注解速查（Recipes）
+
+## 适用与触发（重要）
+- 仅当需要**新增/修改 Controller 路由接口**，且希望按本项目框架“推荐范式”实现时使用本 Skill。
+- 触发口令建议：
+  - “请同时启用 `11-backend-controller-recipes.skill.md`，按项目范式实现 Controller”
+
+---
+
+## 一、写 Controller 的推荐范式（必须对齐）
+
+### 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
+
+```ts
+import { Get, Post, Query, Body, State, ResponseCode, ResponseHeader } from '@src/framework/decorator/controller';
+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)
+  private someService: SomeService;
+
+  @Get('/some/path')
+  @ResponseCode(200)
+  async getSomething(
+    @Query(SomeQueryDto) query: SomeQueryDto,
+    @State('user') user: { userId: number; type?: number },
+  ): Promise<ControllerResponse<any>> {
+    try {
+      const result = await this.someService.someMethod(query, user.userId);
+      if (result.code !== CommonServiceResultCode.SUCCESS) {
+        return this.fail(-1, result.message);
+      }
+      return this.success(result.data);
+    } catch (error) {
+      logger.error('getSomething 失败', error as Error);
+      return this.fail(-1, '系统错误');
+    }
+  }
+}
+```
+
+硬约束：
+- Controller **不写业务逻辑**，只做编排
+- Controller **不直接访问数据库/Repository**
+- Controller **不 return Service 原始结果**，必须映射 `success/fail`
+- Controller `async` **必须 try/catch**
+
+---
+
+## 二、常用注解速查（按本项目实现理解）
+
+### 2.1 路由类注解
+- **`@Get('/path')`**：注册 GET 路由；不传参数时 url 默认使用方法名
+- **`@Post('/path')`**：注册 POST 路由；不传参数时 url 默认使用方法名
+
+### 2.2 参数注解（重点）
+- **`@Query()`**：
+  - 读取 query 参数
+  - 推荐写法：`@Query(SomeQueryDto) query: XxxQueryDto`
+- **`@Body()`**：
+  - 读取 body 参数
+  - 推荐写法：`@Body(SomeBodyDto) body: XxxBodyDto`
+- **`@State()`**：
+  - 读取整个 `ctx.state`（样例：`ytUser.controller.ts`）
+  - 推荐写法：`@State() state: { user: { userId: number; type?: number } }`
+- **`@State('user')`**：
+  - 读取 `ctx.state.user`（样例：`NewAnnotationExampleController.ts`）
+  - 推荐写法：`@State('user') user: { userId: number; type?: number }`
+
+禁止：
+- ❌ `@Query() query: any` / `@Body() body: any` / `@State() state: any`（尽量不要）
+
+### 2.3 响应元信息注解
+- **`@ResponseCode(200|201|...)`**：设置 HTTP 状态码（样例中 GET 用 200，POST 用 201）
+- **`@ResponseHeader(key, value)`**：为响应添加 header
+
+### 2.4 响应校验注解（进阶，按需）
+- **`@ResponseValidator(DtoClass, objectKey?)`**：对响应数据做校验
+- **`@ResponseValidateIf(DtoClass, fn)`**：仅当 fn 返回真时才校验（样例：`ytUser.controller.ts`）
+
+---
+
+## 三、常见组合（直接套用）
+
+### 3.1 需要登录用户的 GET 接口
+- `@Get('/xxx') + @State('user')`（或 `@State()` 取整段 state）
+
+### 3.2 带 body 的 POST 接口
+- `@Post('/xxx') + @Body(SomeBodyDto) body: DtSomeBodyDtoo + @ResponseCode(201)`
+
+### 3.3 需要自定义 header
+- `@ResponseHeader('X-XXX', 'value')`
+
+

package/template/.cursor/rules/20-backend-repository.skill.md

@@ -0,0 +1,25 @@
+---
+alwaysApply: false
+---
+# Skill：Repository 与数据访问规范
+
+## 一、Repository 使用方式
+
+- Service 中通过：
+  - `getDataRepository<Entity>(EntityClass)`
+  - 或 `createLazyRepository()`（推荐）
+
+---
+
+## 二、事务管理
+
+- 涉及多表操作时：
+  - 必须使用 `transactionManager.executeInTransaction()`
+  - 禁止手动管理事务
+
+---
+
+## 三、禁止行为
+
+- ❌ Controller 中访问 Repository
+- ❌ Service 中直接获取 DataSource

package/template/.cursor/rules/21-backend-service.skill.md

@@ -0,0 +1,137 @@
+---
+alwaysApply: false
+---
+# Skill：Service 层开发规范
+
+## 适用与触发（重要）
+- 当需要新增/修改 Service 类（`src/service/**.service.ts` 或等价命名）时启用本 Skill。
+- 典型场景：
+  - 新增业务用例（用户、店铺、商品等）的 Service 方法
+  - 重构/增强现有 Service（增加校验、事务、日志等）
+
+---
+
+## 一、Service 职责定位（必须）
+- Service 负责：
+  - 业务规则/用例编排（多 Repository、多实体、多步骤）
+  - 参数校验（通过 `@ParamValidate` 装饰器，由 dp-ioc2 自动处理）
+  - 事务边界控制（通过 `transactionManager.executeInTransaction`）
+  - 组合/组装领域数据，返回适合 Controller 消费的结果结构
+- Service 不负责：
+  - HTTP/路由层细节（status code、header、ctx 等）
+  - 直接与 Koa `Context` 交互
+  - 直接返回 Controller 统一响应结构（`ControllerResponse`）
+
+---
+
+## 二、类定义与依赖（必须）
+- Service 类必须：
+  - 使用 `@Injectable()` 装饰器
+  - 继承 `BaseService`
+- Repository 访问：
+  - 优先使用 `BaseService` 提供的：
+    - `getDataRepository(EntityClass)`（简单 CRUD）
+    - `createLazyRepository(EntityClass, RepositoryClass, cache)`（自定义 Repository，参考 `YtUserService`）
+  - 禁止在 Service 中直接获取 DataSource：
+    - ❌ `getDataSource()` 直接操作
+    - ✅ 通过 Repository 完成数据访问（见 `20-backend-repository.skill.md`）
+
+---
+
+## 三、返回值规范（必须）
+- 对外公开的 Service 方法，应优先返回：
+  - `Promise<CommonServiceResult<T>>`
+- 使用统一工厂方法：
+  - 成功：`CommonServiceResult.success(data, message?)`
+  - 各种错误：`validationError / notFound / conflict / unauthorized / forbidden / error` 等
+- 仅在兼容旧接口或内部辅助方法时，可返回原始实体/值（需有明确注释说明原因）
+
+---
+
+## 四、参数校验规范（必须）
+
+### 4.1 使用 `@ParamValidate` 装饰器
+- **必须**在方法参数上使用 `@ParamValidate` 装饰器进行自动校验
+- 导入：`import { ParamValidate } from "dp-ioc2"`
+- 对象参数（DTO）校验：
+  ```typescript
+  async createUser(@ParamValidate(CreateUserDto) dto: CreateUserDto): Promise<CommonServiceResult<T>> {
+      // dp-ioc2 会自动使用 class-validator 校验 DTO
+      // 校验失败会抛出 IOCValidationError
+  }
+  ```
+- 非对象参数（基本类型）校验：
+  ```typescript
+  import Joi from "joi";
+  async getUserById(@ParamValidate(undefined, Joi.string().min(3).required()) id: string): Promise<CommonServiceResult<T>> {
+      // dp-ioc2 会自动使用 joi 校验基本类型参数
+  }
+  ```
+- 混合使用：
+  ```typescript
+  async updateUser(
+      @ParamValidate(undefined, Joi.number().positive().required()) userId: number,
+      @ParamValidate(UpdateUserDto) dto: UpdateUserDto
+  ): Promise<CommonServiceResult<T>> {
+      // 可以同时校验基本类型和对象参数
+  }
+  ```
+
+### 4.2 错误处理
+- `@ParamValidate` 校验失败会抛出 `IOCValidationError` 异常
+- **必须**在方法内部捕获并转换为 `CommonServiceResult`：
+  ```typescript
+  import { IOCValidationError } from "dp-ioc2";
+  
+  async createUser(@ParamValidate(CreateUserDto) dto: CreateUserDto): Promise<CommonServiceResult<T>> {
+      try {
+          // 业务逻辑...
+      } catch (error) {
+          if (error instanceof IOCValidationError) {
+              // 将 IOCValidationError 转换为统一的错误响应
+              return CommonServiceResult.validationError(
+                  error.message || "参数校验失败",
+                  error.errors // 可选：传递详细错误信息
+              );
+          }
+          // 其他错误处理...
+      }
+  }
+  ```
+
+### 4.3 DTO 定义要求
+- DTO 类必须使用 `class-validator` 装饰器（`@IsString`、`@IsEmail`、`@MinLength` 等）
+- DTO 定义与目录规范遵循：`30-backend-validation.skill.md`
+- 禁止在 Service 方法内部手动调用 `DtoValidator`（已由 `@ParamValidate` 自动处理）
+
+### 4.4 注意事项
+- `@ParamValidate` 在方法调用前自动执行，无需手动调用校验方法
+- 对象参数会自动转换为 DTO 类实例（支持传入普通对象）
+- 参数校验在 `@Before` hook 之前执行
+- 如果方法有多个参数需要校验，每个参数都需要单独添加 `@ParamValidate` 装饰器
+
+---
+
+## 五、事务与错误处理（必须）
+
+### 5.1 事务使用
+- 涉及多表、多步写操作时，必须使用：
+  - `transactionManager.executeInTransaction(async (manager) => { ... })`
+- 不允许自行手动开启/提交/回滚事务（由 `TransactionManager` 统一处理）
+- 事务内如果需要 Repository，优先通过自定义 Repository/manager 适配（见现有示例）
+
+### 5.2 错误处理与日志
+- Service 方法内部应使用 `try/catch`：
+  - `catch` 中使用 `logger.error(...)` 记录上下文信息
+  - 返回 `CommonServiceResult.error(...)` 或更具体的错误码
+- 生产环境避免将详细错误信息/堆栈返回给调用方（参考 `YtUserService` 的错误处理模式）
+- 详细错误处理规范参见：`40-backend-error-logging.skill.md`
+
+---
+
+## 六、调用关系约束（必须）
+- Controller 只能调用 Service 的公开方法，不应调用 Repository
+- Service 不应调用 Controller，也不应依赖 Koa `Context`
+- Service 之间如需调用，应通过依赖注入（`@Inject(OtherService)`），避免静态调用/循环依赖
+
+