create-dp-koa 1.0.0

package/template/.trae/skills/21-backend-service.skill.md

@@ -0,0 +1,135 @@
+---
+alwaysApply: false
+---
+# Trae 技能：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)`），避免静态调用/循环依赖

package/template/.trae/skills/25-backend-comments-and-doc.skill.md

@@ -0,0 +1,97 @@
+---
+alwaysApply: false
+---
+# Trae 技能：后端注释与文档规范（Comments & Docs）
+
+## 适用与触发
+- 当你**新增或重构业务代码**时，尤其是以下文件：
+  - `src/controllers/**/*.ts`
+  - `src/service/**/*.ts`
+  - `src/entity/**/*.ts`
+  - `src/dto/**/*.ts`
+- 本 Skill 只约束**代码注释/文档风格**，不改变分层职责（仍遵循 `00/10/11/20/21` 等规则）。
+
+---
+
+## 一、总体原则（必须）
+- **中文为主，面向“后来的业务开发同学”解释意图**，而不是翻译代码本身。
+- 注释重点回答三件事：
+  1. **这段代码在业务上要解决什么问题？**
+  2. **为什么要这么做 / 有什么约束和边界？**
+  3. **有哪些容易踩坑的地方？（例如依赖环境变量、数据库特性、幂等性、并发等）**
+- 禁止：
+  - ❌ 逐行翻译式注释（如 `// 定义一个变量 a`、`// 调用 userService`）。
+  - ❌ 与代码含义完全重复、没有信息增量的注释。
+
+---
+
+## 二、不同层级的注释要求
+
+### 2.1 Controller（必须）
+- 每个 `Controller` 类必须有**类级别注释**：
+  - 说明该 Controller 覆盖的业务域（例如“项目管理相关接口”）。
+  - 对外暴露的大类接口（如“项目列表/创建/更新”等）。
+- 每个对外路由方法（带 `@Get/@Post/...` 的方法）必须有**方法注释**：
+  - 粗略说明：**请求来源场景**（前端页面/模块）+ **业务动作**。
+  - 标出关键入参（DTO 字段）和关键返回值（例如分页结构、是否依赖登录态）。
+  - 如有**权限要求 / 限制条件 / 重要副作用**，必须写清楚。
+
+### 2.2 Service（必须）
+- Service 是业务逻辑核心，注释要尽量详细：
+  - 类注释：说明该 Service 管理的领域/聚合根（例如“项目聚合的用例层服务，负责项目生命周期管理”）。
+  - 方法注释：
+    - 业务用例名称（如“创建项目并绑定负责人”、“按标签过滤项目动态”等）。
+    - 输入输出约定：关键参数的语义（例如 `currentUserId` 是否可空、`tags` 的筛选逻辑是“任一命中”还是“全部命中”）。
+    - 事务性/幂等性/一致性说明（如果涉及多表、多步写操作）。
+    - 对外可见的**错误分支**（对应哪些 `CommonServiceResultCode`）。
+
+### 2.3 Entity（推荐）
+- 实体类上推荐有简短注释：
+  - 该表在业务中的角色（例如“项目主表，承载看板列表数据”）。
+  - 与前端/其他系统的强耦合字段（如 status 枚举、对外展示字段）。
+- 对于**容易产生歧义的字段**必须补充注释，例如：
+  - 标记是否是**展示用字段**（如 `iconColor`），而不是业务逻辑字段。
+  - 说明枚举取值与 PRD 或其他文档的对应关系。
+
+### 2.4 DTO（推荐）
+- 对暴露给前端/第三方的 DTO，建议：
+  - DTO 类注释：说明在哪些接口中被使用。
+  - 对约束较强的字段（必填/长度/格式）补充解释用途（例如“前端用于搜索项目标题和描述的关键字”）。
+
+---
+
+## 三、注释风格与格式
+
+### 3.1 统一使用 TypeScript 风格块注释
+- 类和方法使用 `/** ... */` 块注释，方便 IDE 悬浮提示：
+  ```ts
+  /**
+   * 【业务含义】创建项目并自动绑定负责人
+   * - 从当前登录用户中推导 ownerUser
+   * - 如果请求体未显式传 owner，则默认使用用户昵称或邮箱
+   * - 只负责写入项目主表，不负责创建任何子资源
+   */
+  async createProject(...) { ... }
+  ```
+
+### 3.2 注释粒度
+- **优先注释“函数/逻辑块”，其次才是字段**：
+  - 对复杂 if/循环/过滤条件，使用行上方的简短注释解释“业务规则”。
+  - 不建议每一行都写注释，保持“高信息密度”。
+
+---
+
+## 四、与测试 & 文档的关系
+
+- 当 Service 方法被测试覆盖时，注释可以引用测试用例说明典型场景：
+  - 例如：“见 `project.service.test.ts` 中关于关键字搜索和分页的用例”。
+- PRD 中有明确约束的字段/行为，注释应当**引用 PRD 段落或小节标题**，方便对照。
+
+---
+
+## 五、应用建议
+
+- 新增业务时：
+  - 先写 Controller / Service 框架，再补完整注释，最后写测试。
+- 重构旧代码时：
+  - 优先为“复杂/关键路径”补注释，如鉴权、事务、资金/安全相关逻辑。

package/template/.trae/skills/30-backend-validation.skill.md

@@ -0,0 +1,320 @@
+# Trae 技能：后端数据验证规范
+
+## 适用与触发
+- **仅在**你要生成/修改 **数据验证相关代码** 时应用本 Skill
+- 触发口令：
+  - "按验证技能规范实现数据验证"
+  - "根据验证技能生成符合规范的 DTO"
+
+## 一、DTO 分层架构（必须）
+
+### 1.1 分层原则
+- **Controller DTO**：处理 HTTP 层的数据结构（请求参数、响应数据）
+- **Service DTO**：处理业务领域的数据结构（业务操作输入、查询条件）
+- **必须进行转换**：Controller 接收的 DTO 需要转换为 Service DTO 后再调用 Service
+
+### 1.2 目录结构（必须遵守）
+
+```
+src/dto/
+├── controller/              # Controller 层 DTO（HTTP 层）
+│   ├── home/               # 需要认证的接口
+│   │   ├── ytUser.controller.dto.ts
+│   │   ├── ytGoods.controller.dto.ts
+│   │   └── ytShop.controller.dto.ts
+│   ├── public/             # 公开接口
+│   │   └── ytUserAuth.controller.dto.ts
+│   └── example/            # 示例
+│       └── NewAnnotationExampleController.dto.ts
+└── service/                # Service 层 DTO（业务领域）
+    ├── user.service.dto.ts
+    ├── goods.service.dto.ts
+    └── shop.service.dto.ts
+```
+
+## 二、命名规范（必须）
+
+### 2.1 Controller DTO 命名
+
+#### 请求 DTO（接收 HTTP 参数）
+- **格式**：`{操作}{实体}ControllerDto` 或 `{操作}{实体}RequestDto`
+- **示例**：
+  - `CreateUserControllerDto` - 创建用户请求
+  - `UpdateUserControllerDto` - 更新用户请求
+  - `LoginUserControllerDto` - 登录请求
+  - `GetUserInfoControllerDto` - 获取用户信息请求（Query 参数）
+  - `UnlockGoodsImageControllerDto` - 解锁商品图片请求
+
+#### 响应 DTO（API 返回数据）
+- **格式**：`{操作}{实体}ResponseDto`
+- **示例**：
+  - `GetUserInfoResponseDto` - 获取用户信息响应
+  - `CreateUserResponseDto` - 创建用户响应
+  - `GetYtUserBasicInfoResponseDto` - 获取用户基本信息响应
+
+#### 命名规则总结
+- 请求 DTO：以 `ControllerDto` 或 `RequestDto` 结尾
+- 响应 DTO：以 `ResponseDto` 结尾
+- 文件命名：`{模块}.controller.dto.ts`
+
+### 2.2 Service DTO 命名
+
+#### 业务操作 DTO
+- **格式**：`{操作}{实体}ServiceDto` 或 `{操作}{实体}Dto`（简洁形式）
+- **示例**：
+  - `CreateUserServiceDto` 或 `CreateUserDto` - 创建用户业务输入
+  - `UpdateUserServiceDto` 或 `UpdateUserDto` - 更新用户业务输入
+  - `LoginUserServiceDto` 或 `LoginUserDto` - 登录业务输入
+  - `ChangePasswordServiceDto` 或 `ChangePasswordDto` - 修改密码业务输入
+
+#### 查询 DTO
+- **格式**：`Query{实体}ServiceDto` 或 `Query{实体}Dto`
+- **示例**：
+  - `QueryUserServiceDto` 或 `QueryUserDto` - 用户查询条件
+  - `QueryGoodsServiceDto` 或 `QueryGoodsDto` - 商品查询条件
+
+#### 命名规则总结
+- 业务操作 DTO：以 `ServiceDto` 或 `Dto` 结尾（推荐使用 `ServiceDto` 以明确区分）
+- 查询 DTO：以 `Query{实体}ServiceDto` 或 `Query{实体}Dto` 命名
+- 文件命名：`{模块}.service.dto.ts`
+
+## 三、使用规范（必须）
+
+### 3.1 Controller 层使用
+
+#### 请求 DTO 使用
+```typescript
+import { CreateUserControllerDto, CreateUserResponseDto } from '@src/dto/controller/home/ytUser.controller.dto';
+import { CreateUserServiceDto } from '@src/dto/service/user.service.dto';
+
+@Post()
+async createUser(@Body(CreateUserControllerDto) body: CreateUserControllerDto): Promise<ControllerResponse<CreateUserResponseDto>> {
+    // 必须：将 Controller DTO 转换为 Service DTO
+    const serviceDto: CreateUserServiceDto = {
+        nickName: body.name,        // 字段名可能不同
+        email: body.email,
+        password: body.password,
+        // ... 其他字段映射
+    };
+    
+    // 调用 Service（使用 Service DTO）
+    const result = await this.userService.createUser(serviceDto);
+    
+    // 将 Service 结果转换为 Response DTO
+    return this.success(mapToResponseDto(result.data));
+}
+```
+
+**重要**：
+- `@Body(CreateUserControllerDto)` - 将 DTO 类传给装饰器，框架会自动校验
+- `@Query(QueryDto)` - Query 参数同样将 DTO 类传给装饰器
+- `@Params(ParamsDto)` - 路径参数同样将 DTO 类传给装饰器
+- 框架会在方法执行前自动校验，校验失败会直接返回错误响应
+
+#### 响应 DTO 使用
+```typescript
+import { GetUserInfoResponseDto } from '@src/dto/controller/home/ytUser.controller.dto';
+import { ResponseValidateIf } from '@src/framework/decorator/controller';
+
+// 使用 @ResponseValidateIf 装饰器校验响应数据
+@ResponseValidateIf(GetUserInfoResponseDto, (data) => data && data.data)
+@Get()
+async getUserInfo(@State() state: any): Promise<ControllerResponse<GetUserInfoResponseDto>> {
+    // 返回数据必须符合 ResponseDto 结构
+    return this.success({
+        id: user.id,
+        nickName: user.nickName,
+        // ... 其他字段
+    });
+}
+```
+
+**响应校验说明**：
+- `@ResponseValidateIf(ResponseDto, condition)` - **推荐使用**，条件校验响应数据
+  - 第一个参数：Response DTO 类
+  - 第二个参数：条件函数，返回 `true` 时才进行校验
+  - **必须传 condition 函数**，不传 condition 默认不校验
+  - 示例：`@ResponseValidateIf(GetUserInfoResponseDto, (data) => data && data.data)`
+- `@ResponseValidator(ResponseDto, objectKey?)` - 无条件校验响应数据（不推荐使用）
+  - 第一个参数：Response DTO 类
+  - 第二个参数：可选，指定要校验的数据对象的 key（如 `"data"`）
+  - **注意**：虽然存在，但无法控制校验时机，建议使用 `@ResponseValidateIf`
+- **默认行为**：如果不使用任何响应校验装饰器，默认不进行响应校验
+- 校验失败会在返回前抛出异常或返回错误响应
+
+### 3.2 Service 层使用
+
+```typescript
+import { CreateUserServiceDto } from '@src/dto/service/user.service.dto';
+import { ParamValidate } from 'dp-ioc2';
+
+async createUser(@ParamValidate(CreateUserServiceDto) dto: CreateUserServiceDto): Promise<CommonServiceResult<YtUserEntity>> {
+    // 业务逻辑（校验已在方法调用前自动完成）
+    // ...
+}
+```
+
+### 3.3 DTO 转换规范
+
+#### 转换位置
+- **必须在 Controller 方法内部进行转换**
+- 禁止在 Service 层接收 Controller DTO
+- 禁止在 Controller 层直接传递 Controller DTO 给 Service
+
+#### 转换示例
+```typescript
+// ✅ 正确：在 Controller 中转换
+@Post()
+async createUser(@Body(CreateUserControllerDto) body: CreateUserControllerDto) {
+    // 框架已自动校验 body，校验失败不会进入方法体
+    const serviceDto: CreateUserServiceDto = {
+        // 字段映射
+    };
+    return await this.userService.createUser(serviceDto);
+}
+
+// ❌ 错误：直接传递 Controller DTO
+@Post()
+async createUser(@Body(CreateUserControllerDto) body: CreateUserControllerDto) {
+    return await this.userService.createUser(body); // 禁止！必须转换为 Service DTO
+}
+```
+
+## 四、DTO 定义规范（必须）
+
+### 4.1 必须使用 class-validator
+- 所有 DTO 类必须使用 `class-validator` 装饰器
+- 常用装饰器：`@IsString()`, `@IsEmail()`, `@IsNotEmpty()`, `@MinLength()`, `@IsOptional()` 等
+
+### 4.2 Controller DTO 特殊处理
+- 可以使用 `@Transform` 进行数据转换（如字符串转数字、trim）
+- 可以包含 HTTP 层特定的字段（如 `vcodeToken`、`requestId`）
+
+### 4.3 Service DTO 要求
+- **禁止**包含 HTTP 层特性（如 `@Transform`、HTTP 特定字段）
+- 专注于业务领域的数据结构
+- 可被多个 Controller 复用
+
+### 4.4 示例对比
+
+#### Controller DTO（包含 HTTP 层转换）
+```typescript
+export class CreateUserControllerDto {
+    @Transform((val) => Trim(String(val)))
+    @IsString()
+    @IsEmail()
+    email: string;
+    
+    @Transform((val) => Number(val))
+    @IsNumber()
+    age: number;
+}
+```
+
+#### Service DTO（纯业务结构）
+```typescript
+export class CreateUserServiceDto {
+    @IsString()
+    @IsEmail()
+    email: string;
+    
+    @IsNumber()
+    age: number;
+}
+```
+
+## 五、校验流程
+
+### 5.1 Controller 层校验
+
+#### 请求参数校验
+- **必须**将 DTO 类传给装饰器，框架会自动校验：
+  ```typescript
+  // ✅ 正确：将 DTO 类传给装饰器
+  @Get()
+  async getUserInfo(@Query(GetUserInfoQueryDto) query: GetUserInfoQueryDto) { }
+  
+  @Post()
+  async createUser(@Body(CreateUserControllerDto) body: CreateUserControllerDto) { }
+  
+  @Get('/:id')
+  async getUserById(@Params(GetUserByIdParamsDto) params: GetUserByIdParamsDto) { }
+  
+  // ❌ 错误：不传 DTO 类，框架无法自动校验
+  @Get()
+  async getUserInfo(@Query() query: GetUserInfoQueryDto) { }
+  ```
+- 校验失败自动返回错误响应，不会进入方法体
+
+#### 响应数据校验
+- 使用 `@ResponseValidateIf` 或 `@ResponseValidator` 装饰器：
+  ```typescript
+  // 条件校验（推荐）
+  @ResponseValidateIf(GetUserInfoResponseDto, (data) => data && data.data)
+  @Get()
+  async getUserInfo(): Promise<ControllerResponse<GetUserInfoResponseDto>> {
+      return this.success({ /* ... */ });
+  }
+  
+  // 无条件校验（始终校验）
+  @ResponseValidator(GetUserInfoResponseDto)
+  @Get()
+  async getUserInfo(): Promise<ControllerResponse<GetUserInfoResponseDto>> {
+      return this.success({ /* ... */ });
+  }
+  ```
+- 校验失败会在返回前抛出异常或返回错误响应
+
+### 5.2 Service 层校验
+- **必须**使用 `@ParamValidate` 装饰器进行参数校验（由 dp-ioc2 自动处理）
+- 对象参数（DTO）：使用 `@ParamValidate(DtoClass)`，自动使用 class-validator 校验
+- 非对象参数：使用 `@ParamValidate(undefined, JoiSchema)`，使用 joi 校验
+- 校验失败会抛出 `IOCValidationError`，需要在 Service 方法中捕获并转换为 `CommonServiceResult.validationError(...)`
+- 详细规范参见：`21-backend-service.skill.md` 的"四、参数校验规范"
+
+## 六、迁移指南
+
+### 6.1 现有 DTO 迁移
+- `src/dto/user.dto.ts` → `src/dto/service/user.service.dto.ts`
+- `src/dto/goods.dto.ts` → `src/dto/service/goods.service.dto.ts`
+- 重命名：`CreateUserDto` → `CreateUserServiceDto`（或保持 `CreateUserDto`，但文件放在 service 目录）
+
+### 6.2 迁移步骤
+1. 创建 Service DTO 文件（`src/dto/service/{module}.service.dto.ts`）
+2. 将业务 DTO 移动到 Service DTO 文件
+3. 在 Controller 中创建对应的 Controller DTO
+4. 在 Controller 方法中添加 DTO 转换逻辑
+5. 更新所有引用
+
+## 七、禁止事项
+
+### 7.1 禁止在 Service 层使用 Controller DTO
+- ❌ `async createUser(dto: CreateUserControllerDto)` - 禁止
+- ✅ `async createUser(dto: CreateUserServiceDto)` - 正确
+
+### 7.2 禁止直接传递 Controller DTO 给 Service
+- ❌ `this.service.createUser(controllerDto)` - 禁止
+- ✅ `this.service.createUser(convertToServiceDto(controllerDto))` - 正确
+
+### 7.3 禁止在 Service DTO 中使用 HTTP 层特性
+- ❌ Service DTO 中使用 `@Transform` - 禁止
+- ✅ Controller DTO 中使用 `@Transform` - 允许
+
+## 八、最佳实践
+
+### 8.1 字段映射
+- 如果 Controller DTO 和 Service DTO 字段名相同，可以直接使用展开运算符
+- 如果字段名不同，必须显式映射
+
+### 8.2 响应 DTO
+- 响应 DTO 应该只包含前端需要的数据
+- 避免直接返回 Entity，应该转换为 Response DTO
+
+### 8.3 复用性
+- Service DTO 应该设计为可被多个 Controller 复用
+- Controller DTO 可以针对特定接口优化
+
+## 九、相关规范
+
+- **Service 层规范**：`21-backend-service.skill.md`
+- **Controller 层规范**：`10-backend-api.skill.md`

package/template/.trae/skills/40-backend-error-logging.skill.md

@@ -0,0 +1,21 @@
+---
+alwaysApply: false
+---
+# Trae 技能：错误处理与日志规范
+
+## 一、错误处理
+
+- 所有 async 方法必须 try/catch
+- 业务错误：
+  - 使用 `CommonServiceResult.fail()`
+- 系统错误：
+  - 记录日志
+  - 返回通用失败响应
+
+---
+
+## 二、日志规范
+
+- 使用 `logger.info / warn / error`
+- 日志必须包含上下文信息
+- 敏感信息必须脱敏

package/template/.trae/skills/50-backend-bootstrap-lifecycle.skill.md

@@ -0,0 +1,90 @@
+---
+alwaysApply: false
+---
+# Trae 技能：启动生命周期规范（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.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`）