📝 docs(commands): add schema file specification for extended routes

- add schema file location structure specification
- define schema file naming conventions
- provide examples for batch delete and status update schemas
- document schema usage in extended routes
- add schema management best practices
- update notes with schema management and version compatibility requirements

.roo/commands/generic-crud-extend.md

@@ -321,6 +321,107 @@ export default app;
 - **状态变更**：使用 PATCH 方法，路径中体现操作，如 `/status`, `/toggle`
 - **自定义方法**：避免在路径中使用动词，用名词+参数表示
 
+## 扩展路由 Schema 文件规范
+
+### Schema 文件位置
+所有扩展路由的 Zod Schema 定义必须遵循以下文件位置规范：
+
+```
+src/server/modules/[模块名]/
+├── [实体名].entity.ts      # 实体定义
+├── [实体名].schema.ts      # 实体Schema定义（已存在）
+└── schemas/                # 扩展路由专用Schema目录（新增）
+    ├── batch/              # 批量操作Schema
+    │   └── delete.schema.ts
+    ├── [id]/               # 单条记录操作Schema
+    │   ├── status.schema.ts
+    │   ├── toggle.schema.ts
+    │   └── audit.schema.ts
+    ├── export.schema.ts    # 导出操作Schema
+    ├── import.schema.ts    # 导入操作Schema
+    └── stats.schema.ts     # 统计操作Schema
+```
+
+### Schema 文件命名规范
+- **文件名**：`[操作名].schema.ts`
+- **导出**：必须包含完整的请求/响应Schema定义
+- **引用**：在扩展路由文件中直接引用对应的Schema文件
+
+### Schema 文件示例
+
+#### 批量删除Schema - `schemas/batch/delete.schema.ts`
+```typescript
+import { z } from '@hono/zod-openapi';
+
+// 请求Schema
+export const BatchDeleteRequestSchema = z.object({
+  ids: z.array(z.number().int().positive()).openapi({
+    description: '要删除的ID列表',
+    example: [1, 2, 3]
+  })
+});
+
+// 响应Schema
+export const BatchDeleteResponseSchema = z.object({
+  deletedCount: z.number().openapi({
+    example: 3,
+    description: '删除的记录数'
+  })
+});
+
+// 类型定义
+export type BatchDeleteRequest = z.infer<typeof BatchDeleteRequestSchema>;
+export type BatchDeleteResponse = z.infer<typeof BatchDeleteResponseSchema>;
+```
+
+#### 状态更新Schema - `schemas/[id]/status.schema.ts`
+```typescript
+import { z } from '@hono/zod-openapi';
+import { YourEntitySchema } from '../../your-entity.schema';
+
+// 路径参数Schema
+export const StatusUpdateParamsSchema = z.object({
+  id: z.string().openapi({
+    param: { name: 'id', in: 'path' },
+    example: '1',
+    description: '记录ID'
+  })
+});
+
+// 请求体Schema
+export const StatusUpdateBodySchema = z.object({
+  status: z.number().openapi({
+    example: 1,
+    description: '新状态值'
+  })
+});
+
+// 响应Schema（复用实体Schema）
+export const StatusUpdateResponseSchema = YourEntitySchema;
+
+// 类型定义
+export type StatusUpdateParams = z.infer<typeof StatusUpdateParamsSchema>;
+export type StatusUpdateBody = z.infer<typeof StatusUpdateBodySchema>;
+export type StatusUpdateResponse = z.infer<typeof StatusUpdateResponseSchema>;
+```
+
+### 在扩展路由中的使用方式
+
+#### 引用Schema文件
+```typescript
+// src/server/api/your-entity/batch/delete.ts
+import { createRoute, OpenAPIHono } from '@hono/zod-openapi';
+import { BatchDeleteRequestSchema, BatchDeleteResponseSchema } from '@/server/modules/your-module/schemas/batch/delete.schema';
+// ...其他导入
+```
+
+### 最佳实践
+1. **Schema复用**：尽量复用实体已有的Schema定义
+2. **类型安全**：所有Schema必须包含完整的OpenAPI元数据
+3. **模块化**：每个扩展路由对应独立的Schema文件
+4. **命名一致**：Schema文件名与路由功能保持一致
+5. **导出规范**：同时导出Schema和对应的TypeScript类型
+
 ## 注意事项
 
 1. **模块化设计**：每个扩展功能单独一个文件，保持代码清晰
@@ -329,6 +430,8 @@ export default app;
 4. **错误处理**：统一使用标准错误响应格式
 5. **权限控制**：为敏感操作添加适当的中间件
 6. **性能考虑**：批量操作要考虑事务处理和性能优化
+7. **Schema管理**：所有Schema必须放在指定的schemas目录下
+8. **版本兼容**：Schema变更要保持向后兼容性
 
 ## 验证步骤