# 集包数据查询界面规格文档

## 1. 需求概述

在现有的 `batch_query.html` 查询界面中新增一个集包数据查询界面，UI 界面参考现有的查询界面，后台新增查询接口。

## 2. 功能需求

### 2.1 前端功能

1. **标签页导航**：在现有导航栏中添加"集包数据查询"标签页
2. **筛选表单**：
   - 袋牌号码输入框
   - 渠道下拉选择框（UPS、USPS、GOFO、UNIUNI、SPEEDX）
   - 状态下拉选择框（已生成、已打开、已关闭）
   - 创建人输入框
   - 排序字段选择框（创建时间、ID、袋牌号码）
   - 排序顺序选择框（降序、升序）
   - 每页记录数选择框（500、1000、2000、自定义）
   - 查询和重置按钮
3. **结果展示**：
   - 数据表格，包含以下列：ID、袋牌号码、渠道、状态、创建人、创建时间、打开时间、关闭时间、关联运单数量、操作
   - 分页控件
   - 记录总数显示
   - 导出 Excel 功能
4. **交互功能**：
   - 表单提交和数据加载
   - 分页导航
   - 查看运单详情
   - 气泡通知提示

### 2.2 后台接口

1. **集包数据批量查询接口**：
   - 路径：`/bagtag/batch`
   - 方法：GET
   - 参数：
     - page：页码，默认 1
     - pageSize：每页记录数，默认 500
     - sortBy：排序字段，默认 CreatedAt
     - sortOrder：排序顺序，默认 desc
     - tagNumber：袋牌号码
     - channel：渠道
     - status：状态
     - creator：创建人
   - 返回格式：JSONP
   - 响应数据：
     ```json
     {
       "status": "ok",
       "data": [
         {
           "Id": 1,
           "TagNumber": "BT202310010001",
           "ChannelName": "UPS",
           "Status": "Closed",
           "Creator": "admin",
           "CreatedAt": "2023-10-01T10:00:00",
           "OpenedAt": "2023-10-01T11:00:00",
           "ClosedAt": "2023-10-01T12:00:00",
           "WaybillCount": 10
         }
       ],
       "page": 1,
       "pageSize": 500,
       "totalPages": 1,
       "totalCount": 1
     }
     ```

## 3. 技术实现

### 3.1 前端实现

1. **HTML 结构**：
   - 在现有标签页导航中添加"集包数据查询"标签页
   - 复制现有查询界面的结构，修改为集包数据查询的表单和表格

2. **CSS 样式**：
   - 沿用现有 Bootstrap 样式
   - 添加必要的自定义样式

3. **JavaScript 功能**：
   - 表单提交和 AJAX 请求
   - 数据渲染和表格生成
   - 分页控件生成和导航
   - 气泡通知提示

### 3.2 后台实现

1. **服务层**：
   - 在 `IBagTagService` 接口中添加 `GetBagTagsBatchAsync` 方法
   - 在 `BagTagService` 类中实现该方法

2. **数据访问层**：
   - 在 `IBagTagRepository` 接口中添加 `GetBagTagsBatchAsync` 方法
   - 在 `BagTagRepository` 类中实现该方法，支持过滤、排序和分页

3. **控制器**：
   - 在 `BagTagController` 中添加 `GetBagTagsBatch` 方法，处理 HTTP 请求

## 4. 界面设计

### 4.1 布局

- 采用与现有查询界面相同的布局
- 顶部为环境选择下拉框
- 中间为标签页导航
- 每个标签页包含筛选表单和结果展示区域

### 4.2 响应式设计

- 适配不同屏幕尺寸
- 在小屏幕上自动调整表单布局

## 5. 测试要求

1. **功能测试**：
   - 验证筛选条件是否正确应用
   - 验证排序功能是否正常
   - 验证分页功能是否正常
   - 验证导出 Excel 功能是否正常

2. **性能测试**：
   - 测试大量数据下的加载速度
   - 测试分页查询的响应时间

3. **兼容性测试**：
   - 测试在不同浏览器中的显示效果

## 6. 实现计划

1. **前端实现**：
   - 添加集包数据查询标签页
   - 实现筛选表单
   - 实现结果展示表格
   - 实现 JavaScript 交互功能

2. **后台实现**：
   - 添加服务层方法
   - 添加数据访问层方法
   - 添加控制器接口

3. **测试**：
   - 功能测试
   - 性能测试
   - 兼容性测试

## 7. 验收标准

1. 集包数据查询界面与现有查询界面风格一致
2. 筛选条件能够正确过滤数据
3. 排序功能能够正确排序数据
4. 分页功能能够正确分页数据
5. 导出 Excel 功能能够正确导出数据
6. 后台接口能够正确处理请求并返回数据
7. 界面在不同浏览器中显示正常
8. 界面在不同屏幕尺寸下显示正常

## 8. 风险评估

1. **数据量风险**：如果集包数据量较大，可能会影响查询性能
   - 缓解措施：实现分页查询，限制每页记录数

2. **兼容性风险**：不同浏览器可能对某些 JavaScript 特性支持不同
   - 缓解措施：使用兼容的 JavaScript 代码，测试在主流浏览器中的显示效果

3. **接口风险**：后台接口可能无法处理大量并发请求
   - 缓解措施：优化数据库查询，添加缓存机制

## 9. 依赖项

1. **前端依赖**：
   - Bootstrap 5.3.0
   - jQuery 3.6.4

2. **后台依赖**：
   - ASP.NET Core
   - SQL Server
   - Dapper (数据访问)

## 10. 交付物

1. **前端文件**：
   - 修改后的 `batch_query.html` 文件

2. **后台文件**：
   - 修改后的 `IBagTagService.cs` 文件
   - 修改后的 `BagTagService.cs` 文件
   - 修改后的 `IBagTagRepository.cs` 文件
   - 修改后的 `BagTagRepository.cs` 文件
   - 修改后的 `BagTagController.cs` 文件

3. **测试报告**：
   - 功能测试报告
   - 性能测试报告
   - 兼容性测试报告