Story 002.001: 用户搜索和高级过滤功能

docs/stories/002.001.story.md

@@ -0,0 +1,165 @@
+# Story 002.001: 用户搜索和高级过滤功能
+
+## Status
+Ready for Development
+
+## Story
+**As a** 系统管理员
+**I want** 增强的用户搜索和高级过滤功能
+**so that** 我可以快速找到和管理特定条件的用户，提高用户管理效率
+
+## Acceptance Criteria
+1. 实现实时搜索功能，支持用户名、昵称、邮箱、手机号的多字段搜索
+2. 添加状态过滤（启用/禁用用户）
+3. 添加角色过滤（按用户角色筛选）
+4. 添加创建时间范围过滤
+5. 确保搜索过滤与现有分页功能兼容
+6. 提供清晰的过滤条件显示和重置功能
+
+## Tasks / Subtasks
+- [ ] 迁移用户API到通用CRUD路由架构 (AC: 1,2,3,4,5)
+  - [ ] 创建混合路由配置（通用CRUD + 自定义路由）
+  - [ ] 移除`getUsersWithPagination`自定义方法
+  - [ ] 配置通用CRUD路由支持用户实体和关联查询
+  - [ ] 确保现有API端点兼容性
+- [ ] 增强前端搜索和过滤界面 (AC: 1,2,3,4,6)
+  - [ ] 添加状态筛选下拉框
+  - [ ] 添加角色选择器
+  - [ ] 添加日期范围选择器
+  - [ ] 实现实时搜索去抖优化
+  - [ ] 添加过滤条件标签显示
+  - [ ] 实现一键重置过滤功能
+- [ ] 更新API文档和类型定义 (AC: 5)
+  - [ ] 更新OpenAPI schema文档
+  - [ ] 更新TypeScript类型定义
+  - [ ] 确保前后端类型安全
+- [ ] 添加集成测试验证过滤功能 (AC: 5)
+  - [ ] 验证通用CRUD路由过滤功能
+  - [ ] 编写前端组件集成测试
+  - [ ] 验证过滤与分页的协同工作
+
+## Dev Notes
+
+### 现有技术栈分析 [Source: architecture.md]
+- **前端**: React 19 + TypeScript + Tailwind CSS + shadcn/ui
+- **后端**: Hono 4.8.5 + TypeORM 0.3.25 + MySQL 8.0.36
+- **API通信**: Hono RPC类型安全客户端
+- **状态管理**: React Query 5.83.0
+
+### 当前用户管理功能 [Source: src/client/admin/pages/Users.tsx]
+- 基础分页列表显示
+- 简单关键词搜索（用户名、昵称、手机号）
+- 用户创建、编辑、删除操作
+- 基本状态显示（启用/禁用）
+
+### 需要增强的过滤参数
+基于通用CRUD路由分析 [Source: src/server/utils/generic-crud.routes.ts]，使用标准filters参数：
+```typescript
+// 通用CRUD过滤参数格式
+interface FilterParams {
+  page: number;
+  pageSize: number;
+  keyword?: string;
+  filters?: string; // JSON字符串格式的过滤条件
+}
+
+// 过滤条件示例：
+const filters = {
+  isDisabled: 0,                     // 启用状态用户
+  'roles.id': [1, 2],                // 特定角色ID
+  createdAt: {                       // 时间范围
+    gte: '2024-01-01',
+    lte: '2024-12-31'
+  }
+};
+```
+
+### 后端实现策略
+**架构**: 采用通用CRUD路由 + 自定义路由混合模式
+- **通用CRUD路由**: 处理列表查询和过滤（利用现有通用CRUD服务）
+- **自定义路由**: 处理特殊业务逻辑（密码加密、用户创建等）
+
+**文件结构调整**:
+- `src/server/api/users/index.ts` - 混合路由配置
+- `src/server/api/users/custom.ts` - 自定义业务路由
+- 移除 `getUsersWithPagination` 方法（功能由通用CRUD替代）
+
+**配置示例**:
+```typescript
+// 通用CRUD路由配置
+const userCrudRoutes = createCrudRoutes({
+  entity: User,
+  searchFields: ['username', 'nickname', 'phone', 'email'],
+  relations: ['roles'],
+  middleware: [authMiddleware],
+  readOnly: true // 创建/更新使用自定义路由
+});
+```
+
+### 前端实现策略
+**组件位置**: `src/client/admin/pages/Users.tsx`
+- 构建符合通用CRUD filters参数的过滤表单
+- 使用React Hook Form管理过滤状态
+- 将过滤条件序列化为JSON字符串格式
+- 添加过滤条件标签显示和重置功能
+
+**API调用示例**:
+```typescript
+// 查询启用状态的admin角色用户
+const filters = JSON.stringify({
+  isDisabled: 0,
+  'roles.id': [1] // admin角色ID
+});
+
+const response = await userClient.$get({
+  query: { page: 1, pageSize: 10, filters }
+});
+```
+
+### 性能考虑
+- 搜索输入使用防抖（300ms延迟）
+- 数据库查询添加合适索引
+- 分页保持合理页面大小（默认10条）
+- 复杂过滤考虑查询性能优化
+
+### 兼容性要求
+- ✅ 现有API端点保持不变
+- ✅ 现有参数继续支持
+- ✅ 数据库schema无变更
+- ✅ 现有功能无回归
+- ✅ 性能影响最小化
+
+### 测试策略
+**后端测试**:
+- 单元测试验证过滤逻辑正确性
+- 集成测试验证API端点过滤功能
+- 性能测试验证查询效率
+
+**前端测试**:
+- 组件测试验证过滤界面交互
+- 集成测试验证过滤功能端到端
+- 用户体验测试验证易用性
+
+## Testing
+- 验证各种过滤组合的正确性
+- 测试边界条件（空结果、大量数据）
+- 验证分页与过滤的协同工作
+- 测试重置功能正常工作
+- 性能测试确保响应时间<200ms
+
+## Change Log
+| Date | Version | Description | Author |
+|------|---------|-------------|--------|
+| 2025-09-15 | 1.0 | 初始故事创建 | Bob (Scrum Master) |
+
+## Dev Agent Record
+
+### Agent Model Used
+
+### Debug Log References
+
+### Completion Notes List
+
+### File List
+
+## QA Results