mini-starter/docs/stories/010.002.story.md

Story 010.002: 增强残疾人管理筛选功能

Status

Draft

Story

As a 残疾人信息管理员 I want 能够使用更多筛选条件查询残疾人信息 so that 更精确地查找和管理残疾人数据

Acceptance Criteria

1. 新增银行卡类别筛选条件
2. 新增残疾类型筛选条件
3. 新增残疾级别筛选条件
4. 新增居住省份筛选条件
5. 所有筛选条件能够组合使用
6. 筛选结果准确无误

Tasks / Subtasks

• 分析现有筛选功能实现 (AC: 1-6)
  • 检查前端筛选组件实现
  • 检查后端API查询参数处理
  • 检查数据库查询逻辑
• 设计筛选组件扩展方案 (AC: 1-6)
  • 设计银行卡类别筛选组件
  • 设计残疾类型筛选组件
  • 设计残疾级别筛选组件
  • 设计居住省份筛选组件
  • 设计筛选条件组合逻辑
• 扩展后端API查询参数 (AC: 1-6)
  • 修改SearchDisabledPersonQuerySchema添加新筛选参数
  • 更新disabled-person.service.ts查询逻辑
  • 添加关联数据查询支持
• 实现前端筛选组件 (AC: 1-6)
  • 实现银行卡类别筛选下拉框
  • 实现残疾类型筛选下拉框
  • 实现残疾级别筛选下拉框
  • 实现居住省份筛选下拉框
  • 集成到DisabilityPersonManagement组件
• 添加或更新集成测试 (AC: 1-6)
  • 添加筛选功能集成测试用例
  • 测试各筛选条件单独使用
  • 测试筛选条件组合使用
  • 验证筛选结果准确性
• 验证筛选功能效果 (AC: 1-6)
  • 手动测试各筛选条件
  • 测试筛选条件组合查询
  • 验证筛选结果准确性
  • 确保页面正确显示筛选结果

Dev Notes

项目结构信息

• 残疾人管理后端模块位置: allin-packages/disability-module/ [Source: architecture/source-tree.md#实际项目结构]
• 残疾人管理UI包位置: allin-packages/disability-person-management-ui/ [Source: architecture/source-tree.md#实际项目结构]
• 银行名称模块位置: packages/bank-names-module/ [Source: architecture/source-tree.md#实际项目结构]
• 地区模块位置: packages/geo-areas/ [Source: architecture/source-tree.md#实际项目结构]
• 枚举包位置: allin-packages/enums/ [Source: architecture/source-tree.md#实际项目结构]

技术栈信息

• 运行时: Node.js 20.18.3 [Source: architecture/tech-stack.md#现有技术栈维护]
• 前端框架: React 19.1.0 [Source: architecture/tech-stack.md#现有技术栈维护]
• 状态管理: React Query 5.83.0 [Source: architecture/tech-stack.md#现有技术栈维护]
• UI组件库: shadcn/ui [Source: architecture/component-architecture.md#前端组件架构]
• 验证: Zod [Source: architecture/tech-stack.md#现有技术栈维护]

数据模型信息

• 残疾人实体字段:
  • id: number - 残疾人ID [Source: allin-packages/disability-module/src/entities/disabled-person.entity.ts:14]
  • name: string - 姓名 [Source: allin-packages/disability-module/src/entities/disabled-person.entity.ts:23]
  • gender: string - 性别 [Source: allin-packages/disability-module/src/entities/disabled-person.entity.ts:32]
  • idCard: string - 身份证号 [Source: allin-packages/disability-module/src/entities/disabled-person.entity.ts:41]
  • disabilityId: string - 残疾证号 [Source: allin-packages/disability-module/src/entities/disabled-person.entity.ts:52]
  • disabilityType: string - 残疾类型 [Source: allin-packages/disability-module/src/entities/disabled-person.entity.ts:61]
  • disabilityLevel: string - 残疾等级 [Source: allin-packages/disability-module/src/entities/disabled-person.entity.ts:70]
  • province: string - 省级 [Source: allin-packages/disability-module/src/entities/disabled-person.entity.ts:139]
  • city: string - 市级 [Source: allin-packages/disability-module/src/entities/disabled-person.entity.ts:148]
  • district: string - 区县级 [Source: allin-packages/disability-module/src/entities/disabled-person.entity.ts:157]
• 银行卡实体字段:
  • bankNameId: number - 银行名称ID [Source: allin-packages/disability-module/src/entities/disabled-bank-card.entity.ts:38]
  • cardType: string - 银行卡类型 [Source: allin-packages/disability-module/src/entities/disabled-bank-card.entity.ts:65]
• 银行名称实体字段:
  • id: number - 银行ID [Source: packages/bank-names-module/src/entities/bank-name.entity.ts:6]
  • name: string - 银行名称 [Source: packages/bank-names-module/src/entities/bank-name.entity.ts:14]
  • code: string - 银行代码 [Source: packages/bank-names-module/src/entities/bank-name.entity.ts:23]

枚举信息

• 残疾类型枚举: DisabilityType [Source: allin-packages/enums/src/enums/disability-type.enum.ts:8]
  • VISION: 'vision' - 视力残疾
  • HEARING: 'hearing' - 听力残疾
  • SPEECH: 'speech' - 言语残疾
  • PHYSICAL: 'physical' - 肢体残疾
  • INTELLECTUAL: 'intellectual' - 智力残疾
  • MENTAL: 'mental' - 精神残疾
  • MULTIPLE: 'multiple' - 多重残疾
• 残疾等级枚举: DisabilityLevel [Source: allin-packages/enums/src/enums/disability-level.enum.ts:8]
  • ONE: 1 - 一级
  • TWO: 2 - 二级
  • THREE: 3 - 三级
  • FOUR: 4 - 四级

API端点信息

• 获取残疾人列表端点: GET /getAllDisabledPersons [Source: allin-packages/disability-module/src/routes/disabled-person-crud.routes.ts:需要确认]
• 现有查询参数: skip, take [Source: allin-packages/disability-module/src/schemas/disabled-person.schema.ts:251]
• 现有搜索参数: keyword (姓名或身份证号) [Source: allin-packages/disability-module/src/schemas/disabled-person.schema.ts:263]
• 需要扩展的查询参数:
  • bankNameId: 银行名称ID筛选
  • cardType: 银行卡类型筛选
  • disabilityType: 残疾类型筛选
  • disabilityLevel: 残疾等级筛选
  • province: 省份筛选

前端组件信息

• 页面路径: 搜索菜单 > 残疾人管理 [Source: docs/prd/epic-010-system-bug-fixes.md:61]
• 主组件文件: allin-packages/disability-person-management-ui/src/components/DisabilityPersonManagement.tsx
• 现有搜索功能: 关键词搜索（姓名或身份证号）
• 需要添加的筛选组件:
  • 银行卡类别筛选：需要从银行名称模块获取银行列表
  • 残疾类型筛选：使用DISABILITY_TYPES枚举
  • 残疾级别筛选：使用DISABILITY_LEVELS枚举
  • 居住省份筛选：需要从地区模块获取省份列表

关联数据获取

• 银行名称列表: 需要调用银行名称模块的API获取启用的银行列表
• 省份列表: 需要调用地区模块的API获取省份数据
• 枚举数据: 直接从枚举包导入DISABILITY_TYPES和DISABILITY_LEVELS

筛选逻辑实现要点

1. 后端筛选逻辑:

   • 需要扩展disabled-person.service.ts中的查询方法
   • 支持多条件组合查询
   • 需要处理关联表查询（银行卡表）
   • 需要处理枚举值匹配

2. 前端筛选逻辑:

   • 使用React Query管理筛选状态
   • 筛选条件变化时重新查询数据
   • 支持筛选条件重置
   • 显示当前应用的筛选条件

UI包开发规范要求

• 必须遵循UI包开发规范: [Source: architecture/coding-standards.md#UI包开发提示]
• API路径映射验证: 开发前必须验证故事中的API路径映射与实际后端路由定义的一致性
• 类型推断最佳实践: 必须使用RPC推断类型，而不是直接导入schema类型
• 测试选择器优化: 必须为关键交互元素添加data-testid属性
• 表单组件模式: 必须使用条件渲染两个独立的Form组件

Testing

• 测试框架: Vitest 3.2.4 [Source: architecture/testing-strategy.md#工具版本]
• 测试位置: allin-packages/disability-person-management-ui/tests/integration/ [Source: architecture/testing-strategy.md#集成测试]
• 测试标准: 集成测试覆盖率目标 ≥ 60% [Source: architecture/testing-strategy.md#集成测试]
• 测试要求:
  • 筛选功能集成测试
  • 各筛选条件单独使用测试
  • 筛选条件组合使用测试
  • 筛选结果准确性验证
• 测试选择器: 必须为筛选组件添加data-testid属性 [Source: architecture/coding-standards.md#关键检查点]

项目结构注意事项

1. 残疾人管理模块位于allin-packages目录下
2. 银行名称模块位于packages目录下，需要正确配置依赖
3. 地区模块位于packages目录下，需要正确配置依赖
4. 枚举包位于allin-packages目录下，已配置依赖
5. 需要确保模块间的依赖关系正确

性能考虑

1. 筛选条件较多时需要考虑查询性能
2. 关联表查询需要优化索引
3. 前端筛选组件需要支持防抖处理
4. 大数据量时需要考虑分页加载

Change Log

Date	Version	Description	Author
2025-12-12	1.0	故事创建	Bob (Scrum Master)

Dev Agent Record

Agent Model Used

Debug Log References

Completion Notes List

File List

QA Results