182 lines
5.9 KiB
Markdown
182 lines
5.9 KiB
Markdown
# 批量推送扫描记录接口开发计划
|
||
|
||
## 需求分析
|
||
|
||
用户需要开发一个接口，支持：
|
||
1. 按批量订单号查询扫描记录
|
||
2. 按时间范围查询扫描记录
|
||
3. 对每个客户推送其订单最新的扫描记录
|
||
4. 有最新记录则推送，没有则不推送
|
||
|
||
## 现有代码结构
|
||
|
||
### 核心组件
|
||
- **LabelController** (`src/CONTROLLER/Controllers/LabelController.cs`): 控制器，包含webhook推送方法
|
||
- **ILabelScanService** (`src/BLL/Interfaces/ILabelScanService.cs`): 扫描服务接口
|
||
- **LabelScanService** (`src/BLL/Services/LabelScanService.cs`): 扫描服务实现
|
||
- **LabelScanEntity** (`src/MDL/Models/LabelScanEntity.cs`): 扫描记录实体
|
||
- **CustomerEntity** (`src/MDL/Models/CustomerEntity.cs`): 客户实体
|
||
|
||
### 现有Webhook方法
|
||
| 客户代码 | 推送方法 | 参数 |
|
||
|---------|---------|------|
|
||
| PT_GZ | `SendWebhookToPatuen` | waybillNumber, scanTime, printTime |
|
||
| XT_JX | `SendWebhookToXunTong` | waybillNumber, scanTime, printTime, scanResult, scanDescription |
|
||
| ZY_SH | `SendWebhookToZunYou` | waybillNumber, scanTime, printTime, scanResult, finalMileTrackingNumber |
|
||
| IDI_ZJ | `SendWebhookToIDI` | waybillNumber, scanTime, printTime, scanResult, scanDescription |
|
||
| WEM_ZJ | `SendWebhookToWEM` | waybillNumber, scanTime, printTime, scanResult, scanDescription |
|
||
|
||
## 实现方案
|
||
|
||
### 1. 新增DTO定义
|
||
|
||
创建批量推送请求和响应DTO：
|
||
|
||
```csharp
|
||
// 请求DTO
|
||
public class BatchPushRequestDto
|
||
{
|
||
public List<string> WaybillNumbers { get; set; } // 批量订单号（可选）
|
||
public string StartTime { get; set; } // 开始时间（可选，格式：yyyy-MM-dd HH:mm:ss）
|
||
public string EndTime { get; set; } // 结束时间（可选，格式：yyyy-MM-dd HH:mm:ss）
|
||
public string CustomerCode { get; set; } // 客户代码（可选，指定推送特定客户）
|
||
}
|
||
|
||
// 响应DTO
|
||
public class BatchPushResponseDto
|
||
{
|
||
public string Status { get; set; }
|
||
public string Message { get; set; }
|
||
public int TotalOrders { get; set; }
|
||
public int PushedCount { get; set; }
|
||
public int SkippedCount { get; set; }
|
||
public List<PushResultDetail> Details { get; set; }
|
||
}
|
||
|
||
public class PushResultDetail
|
||
{
|
||
public string WaybillNumber { get; set; }
|
||
public string CustomerCode { get; set; }
|
||
public bool Success { get; set; }
|
||
public string Message { get; set; }
|
||
public DateTime? ScanTime { get; set; }
|
||
}
|
||
```
|
||
|
||
### 2. 新增服务方法
|
||
|
||
在 `ILabelScanService` 接口中添加：
|
||
|
||
```csharp
|
||
/// <summary>
|
||
/// 获取指定条件的最新扫描记录（按订单号分组，取最新的一条）
|
||
/// </summary>
|
||
Task<List<LabelScanEntity>> GetLatestScanRecordsAsync(
|
||
List<string> waybillNumbers = null,
|
||
DateTime? startTime = null,
|
||
DateTime? endTime = null,
|
||
int? customerId = null);
|
||
```
|
||
|
||
### 3. 新增Controller接口
|
||
|
||
在 `LabelController` 中添加：
|
||
|
||
```csharp
|
||
/// <summary>
|
||
/// 批量推送扫描记录到客户系统
|
||
/// </summary>
|
||
[HttpPost("webhook/batch-push")]
|
||
public async Task<IActionResult> BatchPushWebhook([FromBody] BatchPushRequestDto request)
|
||
```
|
||
|
||
### 4. 核心业务逻辑
|
||
|
||
1. **参数校验**：验证请求参数，至少提供订单号列表或时间范围
|
||
2. **数据查询**：根据条件查询扫描记录，按订单号分组取最新记录
|
||
3. **客户匹配**：根据订单关联的客户ID获取客户信息
|
||
4. **条件过滤**：如果指定了客户代码，只处理该客户的订单
|
||
5. **推送执行**：根据客户代码调用对应的webhook方法
|
||
6. **结果汇总**：返回推送结果统计
|
||
|
||
## 文件修改清单
|
||
|
||
| 文件 | 修改类型 | 说明 |
|
||
|-----|---------|------|
|
||
| `src/MDL/DTOs/BatchPushDto.cs` | 新建 | 批量推送请求/响应DTO |
|
||
| `src/BLL/Interfaces/ILabelScanService.cs` | 修改 | 添加获取最新扫描记录方法 |
|
||
| `src/BLL/Services/LabelScanService.cs` | 修改 | 实现获取最新扫描记录方法 |
|
||
| `src/DAL/Interfaces/ILabelScanRepository.cs` | 修改 | 添加仓储方法 |
|
||
| `src/DAL/Repositories/LabelScanRepository.cs` | 修改 | 实现仓储方法 |
|
||
| `src/CONTROLLER/Controllers/LabelController.cs` | 修改 | 添加批量推送接口 |
|
||
|
||
## 数据库查询逻辑
|
||
|
||
获取每个订单的最新扫描记录：
|
||
|
||
```sql
|
||
SELECT * FROM label_scan_history
|
||
WHERE (NeutralWaybillNumber IN (@waybillNumbers) OR @waybillNumbers IS NULL)
|
||
AND (CreatedAt >= @startTime OR @startTime IS NULL)
|
||
AND (CreatedAt <= @endTime OR @endTime IS NULL)
|
||
AND (CustomerId = @customerId OR @customerId IS NULL)
|
||
ORDER BY NeutralWaybillNumber, CreatedAt DESC
|
||
```
|
||
|
||
然后按订单号分组，取每组第一条（最新的）记录。
|
||
|
||
## 注意事项
|
||
|
||
1. **性能考虑**：批量查询时限制单次最大订单数量（建议2000条以内）
|
||
2. **异步处理**：推送操作应异步执行，不阻塞接口响应
|
||
3. **日志记录**：记录每条推送的详细结果，便于问题排查
|
||
4. **异常处理**：单个订单推送失败不应影响其他订单
|
||
5. **幂等性**：相同订单重复推送时应考虑是否需要重复发送
|
||
|
||
## 接口调用示例
|
||
|
||
### 请求
|
||
|
||
```json
|
||
POST /api/label/webhook/batch-push
|
||
{
|
||
"waybillNumbers": ["WB001", "WB002", "WB003"],
|
||
"customerCode": "XT_JX"
|
||
}
|
||
```
|
||
|
||
### 响应
|
||
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"message": "批量推送完成",
|
||
"totalOrders": 3,
|
||
"pushedCount": 2,
|
||
"skippedCount": 1,
|
||
"details": [
|
||
{
|
||
"waybillNumber": "WB001",
|
||
"customerCode": "XT_JX",
|
||
"success": true,
|
||
"message": "推送成功",
|
||
"scanTime": "2024-01-15 10:30:00"
|
||
},
|
||
{
|
||
"waybillNumber": "WB002",
|
||
"customerCode": "XT_JX",
|
||
"success": true,
|
||
"message": "推送成功",
|
||
"scanTime": "2024-01-15 10:35:00"
|
||
},
|
||
{
|
||
"waybillNumber": "WB003",
|
||
"customerCode": "XT_JX",
|
||
"success": false,
|
||
"message": "无扫描记录",
|
||
"scanTime": null
|
||
}
|
||
]
|
||
}
|
||
```
|