上传源代码版本
This commit is contained in:
Im-Jenisson
181
.trae/documents/batch_webhook_plan.md
Normal file
181
.trae/documents/batch_webhook_plan.md
Normal file
@@ -0,0 +1,181 @@
|
||||
# 批量推送扫描记录接口开发计划
|
||||
|
||||
## 需求分析
|
||||
|
||||
用户需要开发一个接口，支持：
|
||||
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
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user