test-fork-config-fix/docs/stories/002.001.story.md

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参数：

// 通用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替代）

配置示例:

// 通用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调用示例:

// 查询启用状态的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