上传源代码版本

2026-06-01 16:30:29 +08:00
commit b2a9b7d3c2
462 changed files with 104365 additions and 0 deletions
--- a/.trae/specs/batch_query_apis/checklist.md
+++ b/.trae/specs/batch_query_apis/checklist.md
@@ -0,0 +1,24 @@
+# 批量查询接口 - 验证清单
+
+- [ ] 批量查询label_replace_requests接口
+  - [ ] 接口返回正确的记录列表，包含所有字段
+  - [ ] 分页参数正常工作
+  - [ ] 排序参数正常工作
+  - [ ] 筛选参数正常工作
+  - [ ] 接口响应时间不超过5秒
+  - [ ] 支持至少1000条记录的批量查询
+
+- [ ] 批量查询label_scan_history接口
+  - [ ] 接口返回正确的记录列表，包含所有字段
+  - [ ] 分页参数正常工作
+  - [ ] 排序参数正常工作
+  - [ ] 筛选参数正常工作
+  - [ ] 接口响应时间不超过5秒
+  - [ ] 支持至少1000条记录的批量查询
+
+- [ ] HTML页面
+  - [ ] 页面布局清晰，交互流畅
+  - [ ] 页面能正确调用批量查询接口
+  - [ ] 页面能正确展示查询结果
+  - [ ] 页面支持分页、排序和筛选操作
+  - [ ] 页面响应迅速，交互流畅
--- a/.trae/specs/batch_query_apis/spec.md
+++ b/.trae/specs/batch_query_apis/spec.md
@@ -0,0 +1,140 @@
+# 批量查询换单状态接口规格说明
+
+## 1. 需求概述
+
+新增一个可以查询有没有换单成功以及换单成功时间的接口。支持输入多个中性面单或者是尾程单号。头部中要加入customerCode和apiKey的校验。然后要通过customerCode在labelreplacerequests中找到对应的订单并且换单是否成功要通过有没有成功返回标签的扫描记录来判断，这里做连表查询。
+
+## 2. 接口设计
+
+### 2.1 接口路径
+
+`GET /api/Label/label-replace/status`
+
+### 2.2 请求参数
+
+#### 2.2.1 头部参数
+
+| 参数名 | 类型 | 必选 | 描述 |
+|-------|------|------|------|
+| customerCode | string | 是 | 客户代码 |
+| apiKey | string | 是 | API密钥 |
+
+#### 2.2.2 查询参数
+
+| 参数名 | 类型 | 必选 | 描述 |
+|-------|------|------|------|
+| waybills | string | 否 | 中性面单单号，多个单号用逗号分隔 |
+| trackings | string | 否 | 尾程跟踪单号，多个单号用逗号分隔 |
+
+### 2.3 响应结构
+
+```json
+{
+  "status": "ok",
+  "timestamp": "2026-03-10T10:00:00Z",
+  "count": 2,
+  "data": [
+    {
+      "waybillNumber": "WB1234567890",
+      "trackingNumber": "TN9876543210",
+      "replaced": true,
+      "replacedAt": "2026-03-10T09:30:00Z"
+    },
+    {
+      "waybillNumber": "WB0987654321",
+      "trackingNumber": "TN1234567890",
+      "replaced": false,
+      "replacedAt": null
+    }
+  ]
+}
+```
+
+### 2.4 错误响应
+
+```json
+{
+  "status": "error",
+  "message": "错误信息",
+  "errorDetails": "详细错误信息"
+}
+```
+
+## 3. 业务逻辑
+
+1. **头部校验**：验证customerCode和apiKey是否有效
+2. **参数验证**：确保至少提供了waybills或trackings参数
+3. **数据查询**：
+   - 根据customerCode找到对应的客户ID
+   - 根据提供的单号查询label_replace_requests表
+   - 联合查询label_scan_history表，判断是否有成功的扫描记录（Result=0）
+4. **结果处理**：
+   - 对于每个单号，判断是否换单成功
+   - 记录换单成功的时间（最新的成功扫描记录时间）
+   - 构建响应数据
+
+## 4. 技术实现
+
+### 4.1 控制器实现
+
+在`LabelController`中添加新的方法，处理批量查询请求。
+
+### 4.2 服务层实现
+
+在`ILabelReplaceService`接口中添加新的方法，实现批量查询逻辑。
+
+### 4.3 数据访问层实现
+
+在`ILabelReplaceRepository`接口中添加新的方法，实现连表查询逻辑。
+
+## 5. 验证规则
+
+1. **头部校验**：
+   - customerCode和apiKey不能为空
+   - 验证apiKey是否与customerCode匹配且有效
+
+2. **参数验证**：
+   - 至少提供waybills或trackings参数
+   - 单号格式验证
+
+3. **数据验证**：
+   - 确保查询的订单属于指定的客户
+   - 确保扫描记录与订单关联
+
+## 6. 性能考虑
+
+- 支持批量查询，减少API调用次数
+- 使用索引优化查询性能
+- 合理处理大数据量的情况
+
+## 7. 安全考虑
+
+- 严格的API密钥验证
+- 防止SQL注入攻击
+- 限制查询结果数量
+
+## 8. 测试用例
+
+### 8.1 成功场景
+
+- 批量查询多个中性面单号
+- 批量查询多个尾程跟踪单号
+- 混合查询中性面单和尾程跟踪单号
+
+### 8.2 失败场景
+
+- 缺少头部参数
+- API密钥无效
+- 提供的单号不存在
+- 提供的单号不属于指定客户
+
+## 9. 实现步骤
+
+1. 在`ILabelReplaceService`中添加新方法
+2. 在`LabelReplaceService`中实现该方法
+3. 在`ILabelReplaceRepository`中添加新方法
+4. 在`LabelReplaceRepository`中实现该方法
+5. 在`LabelController`中添加新的API端点
+6. 实现头部校验逻辑
+7. 编写测试用例
+8. 部署和验证
--- a/.trae/specs/batch_query_apis/tasks.md
+++ b/.trae/specs/batch_query_apis/tasks.md
@@ -0,0 +1,60 @@
+# 批量查询接口 - 实现计划
+
+## [x] 任务 1: 添加批量查询label_replace_requests的接口
+- **Priority**: P0
+- **Depends On**: None
+- **Description**:
+  - 在LabelController中添加批量查询接口
+  - 支持分页、排序和筛选参数
+  - 返回所有字段的记录列表
+- **Acceptance Criteria Addressed**: AC-1
+- **Test Requirements**:
+  - `programmatic` TR-1.1: 接口返回正确的记录列表，包含所有字段
+  - `programmatic` TR-1.2: 分页参数正常工作
+  - `programmatic` TR-1.3: 排序参数正常工作
+  - `programmatic` TR-1.4: 筛选参数正常工作
+- **Notes**: 使用现有的ILabelReplaceService和ILabelReplaceRepository服务
+
+## [x] 任务 2: 添加批量查询label_scan_history的接口
+- **Priority**: P0
+- **Depends On**: None
+- **Description**:
+  - 在LabelController中添加批量查询接口
+  - 支持分页、排序和筛选参数
+  - 返回所有字段的记录列表
+- **Acceptance Criteria Addressed**: AC-2
+- **Test Requirements**:
+  - `programmatic` TR-2.1: 接口返回正确的记录列表，包含所有字段
+  - `programmatic` TR-2.2: 分页参数正常工作
+  - `programmatic` TR-2.3: 排序参数正常工作
+  - `programmatic` TR-2.4: 筛选参数正常工作
+- **Notes**: 使用现有的ILabelScanService和ILabelScanRepository服务
+
+## [x] 任务 3: 生成HTML页面
+- **Priority**: P1
+- **Depends On**: 任务 1, 任务 2
+- **Description**:
+  - 创建HTML页面，包含查询表单和结果展示
+  - 添加JavaScript代码调用批量查询接口
+  - 支持分页、排序和筛选操作
+- **Acceptance Criteria Addressed**: AC-3
+- **Test Requirements**:
+  - `human-judgment` TR-3.1: 页面布局清晰，交互流畅
+  - `programmatic` TR-3.2: 页面能正确调用批量查询接口
+  - `programmatic` TR-3.3: 页面能正确展示查询结果
+  - `human-judgment` TR-3.4: 页面支持分页、排序和筛选操作
+- **Notes**: 使用Bootstrap和jQuery简化开发
+
+## [x] 任务 4: 测试和验证
+- **Priority**: P1
+- **Depends On**: 任务 1, 任务 2, 任务 3
+- **Description**:
+  - 测试批量查询接口的功能
+  - 测试HTML页面的功能
+  - 验证接口响应时间
+- **Acceptance Criteria Addressed**: AC-1, AC-2, AC-3
+- **Test Requirements**:
+  - `programmatic` TR-4.1: 接口响应时间不超过5秒
+  - `programmatic` TR-4.2: 支持至少1000条记录的批量查询
+  - `human-judgment` TR-4.3: HTML页面响应迅速，交互流畅
+- **Notes**: 使用Postman测试API接口