📝 docs: add common error troubleshooting guide

- 添加前端日期组件错误排查，包括错误表现、原因及正确使用dayjs对象的示例
- 添加后端OpenAPI路由定义错误排查，包含路径参数定义和参数类型转换问题
- 添加后端实体定义错误排查，说明创建/更新Schema中使用z.coerce的重要性
- 添加RPC调用错误排查，重点说明InferResponseType的正确使用方法
- 添加前后端交互错误排查，强调表单验证规则需与后端保持一致

README.md

@@ -0,0 +1,143 @@
+# 常见错误排查指南
+
+## 前端常见错误
+
+### 日期组件错误
+
+**错误表现**:  
+`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`