# Story 010.003: 优化订单管理搜索功能

## Status
Implemented

## Story
**As a** 订单管理员
**I want** 能够使用更多搜索条件查询订单
**so that** 更高效地管理和跟踪订单

## Acceptance Criteria
1. 新增平台搜索条件
2. 新增公司搜索条件
3. 新增开始日期搜索条件
4. 新增结束日期搜索条件
5. 日期范围搜索功能正常工作
6. 搜索条件能够组合使用

## Tasks / Subtasks
- [x] 分析当前订单管理UI组件的搜索功能实现 (AC: 1-6)
  - [x] 检查 `allin-packages/order-management-ui/src/components/OrderManagement.tsx` 中的搜索逻辑
  - [x] 分析 `searchParams` 状态和 `handleSearch` 函数
  - [x] 检查API调用参数传递
- [x] 修改订单管理UI组件，添加新的搜索条件 (AC: 1-4)
  - [x] 在 `searchParams` 状态中添加平台搜索字段
  - [x] 在 `searchParams` 状态中添加公司搜索字段
  - [x] 在 `searchParams` 状态中添加开始日期和结束日期字段
  - [x] 更新搜索表单UI，添加新的输入控件
- [x] 更新API调用逻辑，支持新的搜索参数 (AC: 1-6)
  - [x] 修改 `handleSearch` 函数，将新参数传递给API
  - [x] 检查订单模块路由的搜索字段配置
  - [x] 确保日期范围搜索逻辑正确
- [x] 添加平台和公司选择器组件依赖 (AC: 1-2)
  - [x] 在 `package.json` 中添加对平台管理UI包的依赖
  - [x] 在 `package.json` 中添加对公司管理UI包的依赖
  - [x] 导入并使用现有的 `PlatformSelector` 组件
  - [x] 导入并使用现有的 `CompanySelector` 组件
- [x] 实现日期范围选择组件 (AC: 3-5)
  - [x] 使用共享UI组件库的日期选择器
  - [x] 实现开始日期和结束日期联动逻辑
  - [x] 添加日期格式化和验证
- [x] 更新测试用例，验证新的搜索功能 (AC: 1-6)
  - [x] 更新现有集成测试，包含新的搜索条件
  - [x] 添加日期范围搜索的测试用例
  - [x] 验证组合搜索功能
- [x] 进行功能测试和验证 (AC: 1-6)
  - [x] 手动测试所有新的搜索条件
  - [x] 验证搜索结果的准确性
  - [x] 检查UI响应性和用户体验

## Dev Notes

### 技术栈信息 [Source: architecture/tech-stack.md]
- **前端框架**: React 19.1.0 + TypeScript
- **路由**: React Router v7
- **状态管理**: @tanstack/react-query (服务端状态) + Context (本地状态)
- **UI组件库**: shadcn/ui (基于Radix UI)
- **构建工具**: Vite 7.0.0
- **样式**: Tailwind CSS 4.1.11
- **HTTP客户端**: 基于Hono Client的封装 + axios适配器

### 项目结构信息 [Source: architecture/source-tree.md]
- **订单管理UI包路径**: `packages/order-management-ui/`
- **订单模块路径**: `packages/orders-module/`
- **Web应用路径**: `web/src/client/admin/`
- **组件位置**: `packages/order-management-ui/src/components/OrderManagement.tsx`
- **API客户端位置**: `packages/order-management-ui/src/api/orderClient.ts`

### 当前搜索功能分析
根据代码分析，当前订单管理组件有以下搜索功能：
1. **关键字搜索**: 通过 `searchParams.search` 字段
2. **状态筛选**: 通过 `searchParams.status` 字段
3. **支付状态筛选**: 通过 `searchParams.payStatus` 字段
4. **分页参数**: `searchParams.page` 和 `searchParams.limit`

### 订单模块API信息 [Source: 代码分析]
- **管理员订单路由**: `packages/orders-module/src/routes/admin/orders.ts`
- **搜索字段配置**: `searchFields: ['orderNo', 'userPhone', 'recevierName']`
- **关系加载**: `relations: ['user', 'merchant', 'supplier', 'deliveryAddress']`
- **通用CRUD路由**: 使用 `@d8d/shared-crud` 的 `createCrudRoutes`

### UI包开发规范要求 [Source: architecture/ui-package-standards.md]
1. **必须遵循UI包开发规范**，基于史诗008经验总结
2. **API路径映射验证**: 开发前必须验证故事中的API路径映射与实际后端路由定义的一致性
3. **类型推断最佳实践**: 必须使用RPC推断类型，而不是直接导入schema类型
4. **测试选择器优化**: 必须为关键交互元素添加 `data-testid` 属性
5. **表单组件模式**: 必须使用条件渲染两个独立的Form组件
6. **API调用一致性**: 必须根据实际路由名称修正API调用

### 编码标准要求 [Source: architecture/coding-standards.md]
1. **测试框架**: 使用Vitest + Testing Library + hono/testing + Playwright
2. **测试位置**: `tests/` 文件夹与源码并列
3. **覆盖率目标**: 核心业务逻辑 > 80%
4. **测试类型**: 单元测试、集成测试、E2E测试

### 现有选择器组件信息
1. **平台选择器组件**: `allin-packages/platform-management-ui/src/components/PlatformSelector.tsx`
   - **功能**: 提供平台下拉选择功能，自动加载平台数据
   - **Props**: `value` (选中的平台ID), `onChange` (选择回调), `placeholder`, `disabled`, `className`, `testId`
   - **数据获取**: 使用React Query自动获取平台列表，支持分页（默认取前100条）
   - **依赖**: 需要 `@d8d/shared-ui-components` 和平台管理API客户端

2. **公司选择器组件**: `allin-packages/company-management-ui/src/components/CompanySelector.tsx`
   - **功能**: 提供公司下拉选择功能，支持按平台过滤
   - **Props**: `value` (选中的公司ID), `onChange` (选择回调), `placeholder`, `disabled`, `className`, `testId`, `platformId` (可选平台过滤)
   - **数据获取**: 使用React Query获取公司列表，支持按平台ID过滤
   - **依赖**: 需要 `@d8d/shared-ui-components` 和公司管理API客户端

### 依赖包信息
1. **平台管理UI包**: `@d8d/allin-platform-management-ui` (workspace:*)
   - **导出组件**: `PlatformSelector`
   - **包路径**: `allin-packages/platform-management-ui/`

2. **公司管理UI包**: `@d8d/allin-company-management-ui` (workspace:*)
   - **导出组件**: `CompanySelector`
   - **包路径**: `allin-packages/company-management-ui/`

3. **当前订单管理UI包**: `@d8d/order-management-ui`
   - **需要添加的依赖**:
     - `"@d8d/allin-platform-management-ui": "workspace:*"`
     - `"@d8d/allin-company-management-ui": "workspace:*"`

### 需要添加的搜索字段
根据故事需求，需要添加以下搜索字段：
1. **平台搜索**: 使用现有的 `PlatformSelector` 组件
2. **公司搜索**: 使用现有的 `CompanySelector` 组件
3. **开始日期**: 订单创建时间范围查询
4. **结束日期**: 订单创建时间范围查询

### 技术考虑
1. **日期范围搜索**: 需要处理日期格式化和数据库查询优化
2. **平台/公司选择器**: 可以直接使用现有组件，无需重新实现
3. **依赖管理**: 需要在订单管理UI包的 `package.json` 中添加对平台管理UI包和公司管理UI包的依赖
4. **组合搜索**: 确保所有搜索条件可以同时使用
5. **性能优化**: 考虑大数据量下的搜索性能

### 文件位置
- **主要修改文件**: `packages/order-management-ui/src/components/OrderManagement.tsx`
- **依赖配置文件**: `packages/order-management-ui/package.json` (需要添加新依赖)
- **现有组件文件**:
  - `allin-packages/platform-management-ui/src/components/PlatformSelector.tsx`
  - `allin-packages/company-management-ui/src/components/CompanySelector.tsx`
- **测试文件**: `packages/order-management-ui/tests/integration/order-management.integration.test.tsx`
- **类型定义**: `packages/order-management-ui/src/types/order.ts`

### 测试
#### 测试标准 [Source: architecture/coding-standards.md]
- **测试框架**: Vitest + Testing Library
- **测试位置**: `tests/integration/` 文件夹
- **测试类型**: 集成测试验证组件与API交互
- **覆盖率要求**: 核心搜索功能 > 80%

#### 具体测试要求
1. **单元测试**: 测试新的搜索参数处理逻辑
2. **集成测试**: 测试组件与API的完整交互
3. **日期范围测试**: 验证开始日期和结束日期的各种边界情况
4. **组合搜索测试**: 验证多个搜索条件同时使用的场景
5. **UI测试**: 验证新的搜索表单控件交互

#### 测试选择器要求
必须为新的搜索控件添加 `data-testid` 属性：
- `data-testid="platform-search-select"`
- `data-testid="company-search-select"`
- `data-testid="start-date-input"`
- `data-testid="end-date-input"`

## Change Log
| Date | Version | Description | Author |
|------|---------|-------------|--------|
| 2025-12-12 | 1.0 | 故事创建，基于史诗010-03需求 | Scrum Master Bob |

## Dev Agent Record
*此部分由开发代理在实施过程中填写*

### Agent Model Used
Claude Code (d8d-model)

### Debug Log References
1. 修复了包路径错误：最初修改了错误的包路径（packages/order-management-ui），后修正为allin-packages/order-management-ui
2. 修复了测试网络错误：通过mock共享工具包中的rpcClient函数而不是axios
3. 修复了实体关系错误：添加了OrderPerson#person关联实体到集成测试配置
4. 修复了外键约束错误：在创建OrderPerson之前先创建DisabledPerson记录
5. 修复了字段长度错误：修复测试数据工厂，确保字段值不超过长度限制

### Completion Notes List
1. 更新了OrderSearchParams类型，添加startDate和endDate字段
2. 修改了OrderManagement组件，添加了平台、公司、开始日期、结束日期搜索条件
3. 实现了两行搜索布局（第一行4列，第二行5列）
4. 添加了重置筛选功能
5. 更新了后端QueryOrderSchema，添加startDate和endDate参数
6. 更新了OrderService.findAll方法，支持日期范围查询
7. 修复了所有集成测试，31个测试全部通过

### File List
1. `allin-packages/order-management-ui/src/api/types.ts` - 更新OrderSearchParams接口
2. `allin-packages/order-management-ui/src/components/OrderManagement.tsx` - 添加新的搜索条件
3. `allin-packages/order-management-ui/tests/integration/order.integration.test.tsx` - 更新测试用例
4. `allin-packages/order-module/src/schemas/order.schema.ts` - 更新QueryOrderSchema
5. `allin-packages/order-module/src/services/order.service.ts` - 更新findAll方法
6. `allin-packages/order-module/tests/integration/order.integration.test.ts` - 修复集成测试
7. `allin-packages/order-module/tests/utils/test-data-factory.ts` - 修复测试数据工厂
8. `allin-packages/order-module/package.json` - 添加@d8d/bank-names-module依赖

## QA Results
*此部分由QA代理在审查完成后填写*