# 常见错误排查指南

## 前端常见错误

### 日期组件错误

**错误表现**:  
`date4.isValid is not a function`  
`TypeError: date4.isValid is not a function`

**错误原因**:  
使用原生`Date`对象而非`dayjs`对象初始化日期组件

**错误示例**:
```typescript
// 错误示例 - 使用原生Date对象
form.setFieldsValue({
  noteDate: new Date(record.noteDate) // 导致验证失败
});
```

**正确做法**:
```typescript
// 正确示例 - 使用dayjs对象
form.setFieldsValue({
  noteDate: dayjs(record.noteDate) // 正常支持验证方法
});
```

## 后端常见错误

### OpenAPI路由定义错误

#### 1. 路径参数定义错误

**错误表现**:  
路径参数无法正确解析，接口调用404

**错误原因**:  
使用冒号`:`定义路径参数而非花括号`{}`

**错误示例**:
```typescript
// 错误方式
path: '/:id'
```

**正确做法**:
```typescript
// 正确方式
path: '/{id}'
```

#### 2. 参数类型转换错误

**错误表现**:  
数字/布尔型URL参数验证失败，提示类型错误

**错误原因**:  
未使用`z.coerce`处理URL字符串参数到目标类型的转换

**错误示例**:
```typescript
// 错误方式 - 直接使用z.number()
z.number().int().positive() // 无法处理字符串参数

// 错误方式 - 直接使用z.boolean()
z.boolean() // 无法处理字符串参数
```

**正确做法**:
```typescript
// 正确方式 - 使用z.coerce.number()
z.coerce.number().int().positive() // 自动转换字符串参数

// 正确方式 - 使用z.coerce.boolean()
z.coerce.boolean() // 自动转换字符串参数
```

### 实体定义错误

#### 1. 创建/更新Schema缺少coerce

**错误表现**:  
日期/数字类型参数验证失败，接口返回400错误

**错误原因**:  
实体的创建/更新Schema中，日期、数字等类型未使用`z.coerce`进行类型转换

**正确做法**:
```typescript
export const UpdateEntityDto = z.object({
  price: z.coerce.number().multipleOf(0.01).optional().openapi({
    description: '价格',
    example: 89.99
  }),
  isActive: z.coerce.boolean().optional().openapi({
    description: '是否激活',
    example: false
  }),
  expireDate: z.coerce.date().optional().openapi({
    description: '过期日期',
    example: '2025-12-31T23:59:59Z'
  })
});
```

## RPC调用错误

### InferResponseType使用错误

**错误表现**:  
TypeScript类型推断失败，提示属性不存在

**错误原因**:  
访问带参数的路由类型时未正确使用数组语法

**错误示例**:
```typescript
// 错误方式
InferResponseType<typeof zichanClient[':id'].$get, 200>
```

**正确做法**:
```typescript
// 正确方式 - $get要加中括号
InferResponseType<typeof zichanClient[':id']['$get'], 200>
```

## 前后端交互错误

### 表单验证规则不匹配

**错误表现**:  
前端表单提交后后端验证失败，或前端验证通过但后端返回400

**错误原因**:  
前端表单的必填/选填规则与后端实体的create/update schema不一致

**正确做法**:
1. 前端表单验证规则必须与后端保持一致
2. 后端实体schema变更时需同步更新前端表单验证
3. 创建操作使用`CreateXXXDto`，更新操作使用`UpdateXXXDto`