# USPS 自动集包开发任务分解

## 任务概览

| 阶段     | 任务数    | 预计工时    |
| ------ | ------ | ------- |
| 模型定义   | 2      | 2h      |
| 数据访问层  | 2      | 3h      |
| 业务逻辑层  | 3      | 5h      |
| 接口层    | 2      | 3h      |
| 测试与优化  | 2      | 3h      |
| **总计** | **11** | **16h** |

***

## 阶段一：模型定义

### 任务 1.1：创建任务状态模型

**文件**：`src/MDL/Models/AutoPackTaskStatus.cs`

**内容**：

```csharp
namespace MDL.Models
{
    /// <summary>
    /// 自动集包任务状态
    /// </summary>
    public class AutoPackTaskStatus
    {
        public string TaskId { get; set; }
        public string TagNumber { get; set; }
        public string Status { get; set; } // pending/processing/completed/failed/cancelled
        public int TotalCount { get; set; }
        public int ProcessedCount { get; set; }
        public int SuccessCount { get; set; }
        public int FailedCount { get; set; }
        public string CurrentWaybill { get; set; }
        public DateTime StartTime { get; set; }
        public DateTime? EndTime { get; set; }
        public List<AutoPackFailedItem> FailedItems { get; set; } = new();
        public CancellationTokenSource CancellationTokenSource { get; set; }
    }

    public class AutoPackFailedItem
    {
        public string WaybillNumber { get; set; }
        public int ErrorCode { get; set; }
        public string ErrorMessage { get; set; }
    }
}
```

**验收标准**：

- [ ] 模型包含所有必要字段
- [ ] 字段命名符合项目规范
- [ ] 支持 JSON 序列化

***

### 任务 1.2：创建请求/响应 DTO

**文件**：`src/MDL/Models/AutoPackRequest.cs`

**内容**：

```csharp
namespace MDL.Models
{
    /// <summary>
    /// 启动自动集包请求
    /// </summary>
    public class StartAutoPackRequest
    {
        public string TagNumber { get; set; }
        public string Creator { get; set; } = "system";
    }

    /// <summary>
    /// 启动自动集包响应
    /// </summary>
    public class StartAutoPackResponse
    {
        public string TaskId { get; set; }
        public string TagNumber { get; set; }
        public string Status { get; set; }
        public int TotalCount { get; set; }
        public string Message { get; set; }
    }

    /// <summary>
    /// 自动集包进度响应
    /// </summary>
    public class AutoPackProgressResponse
    {
        public string TaskId { get; set; }
        public string TagNumber { get; set; }
        public string Status { get; set; }
        public int TotalCount { get; set; }
        public int ProcessedCount { get; set; }
        public int SuccessCount { get; set; }
        public int FailedCount { get; set; }
        public string CurrentWaybill { get; set; }
        public int Progress { get; set; }
        public string Message { get; set; }
        public DateTime StartTime { get; set; }
        public DateTime? EstimatedEndTime { get; set; }
        public List<AutoPackFailedItem> FailedItems { get; set; }
    }

    /// <summary>
    /// 自动集包结果响应
    /// </summary>
    public class AutoPackResultResponse
    {
        public string TaskId { get; set; }
        public string TagNumber { get; set; }
        public string Status { get; set; }
        public int TotalCount { get; set; }
        public int SuccessCount { get; set; }
        public int FailedCount { get; set; }
        public DateTime StartTime { get; set; }
        public DateTime? EndTime { get; set; }
        public int Duration { get; set; }
        public List<AutoPackFailedItem> FailedItems { get; set; }
    }
}
```

**验收标准**：

- [ ] 包含 Start、Progress、Result 三种响应 DTO
- [ ] 字段与 spec.md 定义一致
- [ ] 支持前端 WinForm 调用

***

## 阶段二：数据访问层

### 任务 2.1：扩展 Repository 接口

**文件**：`src/DAL/Interfaces/IBagTagRepository.cs`

**新增方法**：

```csharp
/// <summary>
/// 查询符合条件的 USPS 包裹
/// </summary>
Task<List<string>> GetEligibleUspsWaybillsAsync(DateTime cutoffTime);

/// <summary>
/// 获取符合条件的包裹数量
/// </summary>
Task<int> GetEligibleUspsWaybillCountAsync(DateTime cutoffTime);
```

**验收标准**：

- [ ] 接口定义符合项目规范
- [ ] 参数设计合理（cutoffTime = 当前时间 - 84小时）

***

### 任务 2.2：实现 Repository 方法

**文件**：`src/DAL/Repositories/BagTagRepository.cs`

**实现要点**：

1. 使用 SqlSugar 执行 SQL 查询
2. 查询条件：
   - ReplaceStatus = 'Y'
   - CreatedAt >= cutoffTime
   - FinalMileTrackingNumber 不为空
   - 未关联到 bag\_tag\_waybills
   - USPS 运单号格式（92/93/94/95 或 420+邮编+92/93/94/95）
   - 有一条换单成功的扫描记录

**SQL 参考**：

```sql
SELECT DISTINCT 
    l.FinalMileTrackingNumber
FROM label_replace_requests l
LEFT JOIN bag_tag_waybills b ON l.FinalMileTrackingNumber = b.FinalMileTrackingNumber
WHERE 
    l.ReplaceStatus = 'Y'
    AND l.CreatedAt >= @CutoffTime
    AND l.FinalMileTrackingNumber IS NOT NULL
    AND l.FinalMileTrackingNumber != ''
    AND b.Id IS NULL
    AND (
        l.FinalMileTrackingNumber REGEXP '^(92|93|94|95)'
        OR l.FinalMileTrackingNumber REGEXP '^420[0-9]{5}(92|93|94|95)'
        OR l.FinalMileTrackingNumber REGEXP '^420[0-9]{9}(92|93|94|95)'
    )
ORDER BY l.CreatedAt ASC
```

**验收标准**：

- [ ] SQL 查询性能优化（使用索引）
- [ ] 正确处理 USPS 运单号格式
- [ ] 返回结果按 CreatedAt 升序排列

***

## 阶段三：业务逻辑层

### 任务 3.1：扩展 Service 接口

**文件**：`src/BLL/Interfaces/IBagTagService.cs`

**新增方法**：

```csharp
/// <summary>
/// 启动自动集包任务
/// </summary>
Task<StartAutoPackResponse> StartAutoPackAsync(string tagNumber, string creator);

/// <summary>
/// 查询自动集包进度
/// </summary>
Task<AutoPackProgressResponse> GetAutoPackProgressAsync(string taskId);

/// <summary>
/// 取消自动集包任务
/// </summary>
Task<bool> CancelAutoPackAsync(string taskId);

/// <summary>
/// 获取自动集包结果
/// </summary>
Task<AutoPackResultResponse> GetAutoPackResultAsync(string taskId);
```

**验收标准**：

- [ ] 接口定义完整
- [ ] 返回类型与 DTO 对应

***

### 任务 3.2：实现任务启动逻辑

**文件**：`src/BLL/Services/BagTagService.cs`

**实现步骤**：

1. 验证袋牌存在且状态为 Opened
2. 生成唯一任务ID（格式：`task_{timestamp}_{guid}`）
3. 查询符合条件的包裹列表
4. 如果无符合条件的包裹，返回错误
5. 创建任务状态对象，存入缓存
6. 启动后台任务执行自动集包
7. 返回任务信息给前端

**关键代码**：

```csharp
public async Task<StartAutoPackResponse> StartAutoPackAsync(string tagNumber, string creator)
{
    // 1. 验证袋牌
    var tag = await _bagTagRepository.GetByTagNumberAsync(tagNumber);
    if (tag == null || tag.Status != "Opened")
    {
        throw new Exception("Bag tag not found or not in opened status");
    }

    // 2. 查询符合条件的包裹
    var cutoffTime = DateTime.UtcNow.AddHours(-84);
    var waybills = await _bagTagRepository.GetEligibleUspsWaybillsAsync(cutoffTime);
    
    if (waybills.Count == 0)
    {
        throw new Exception("No eligible waybills found");
    }

    // 3. 创建任务
    var taskId = $"task_{DateTime.UtcNow:yyyyMMddHHmmss}_{Guid.NewGuid().ToString("N").Substring(0, 8)}";
    var taskStatus = new AutoPackTaskStatus
    {
        TaskId = taskId,
        TagNumber = tagNumber,
        Status = "processing",
        TotalCount = waybills.Count,
        ProcessedCount = 0,
        SuccessCount = 0,
        FailedCount = 0,
        StartTime = DateTime.UtcNow,
        FailedItems = new List<AutoPackFailedItem>(),
        CancellationTokenSource = new CancellationTokenSource()
    };

    // 4. 保存任务状态到缓存
    await _cacheService.SetAsync($"autopack:{taskId}", taskStatus, 60); // 缓存60分钟

    // 5. 启动后台任务
    _ = Task.Run(async () => await ExecuteAutoPackAsync(taskId, tagNumber, waybills, creator));

    // 6. 返回响应
    return new StartAutoPackResponse
    {
        TaskId = taskId,
        TagNumber = tagNumber,
        Status = "processing",
        TotalCount = waybills.Count,
        Message = "自动集包任务已启动"
    };
}
```

**验收标准**：

- [ ] 袋牌验证逻辑正确
- [ ] 任务ID生成唯一
- [ ] 任务状态正确存入缓存
- [ ] 后台任务正确启动

***

### 任务 3.3：实现自动集包执行逻辑

**文件**：`src/BLL/Services/BagTagService.cs`

**实现步骤**：

1. 从缓存获取任务状态
2. 遍历包裹列表逐个处理
3. 每次处理前检查取消令牌
4. 调用 AssociateWaybillAsync 进行关联
5. 更新任务状态（成功/失败计数、当前单号）
6. 记录订单日志
7. 生成 2-4 秒随机延迟
8. 处理完成后更新任务状态为 completed 或 failed

**关键代码**：

```csharp
private async Task ExecuteAutoPackAsync(string taskId, string tagNumber, List<string> waybills, string creator)
{
    var random = new Random();
    var cacheKey = $"autopack:{taskId}";
    
    foreach (var waybill in waybills)
    {
        // 1. 获取任务状态
        var taskStatus = await _cacheService.GetAsync<AutoPackTaskStatus>(cacheKey);
        if (taskStatus == null || taskStatus.CancellationTokenSource?.IsCancellationRequested == true)
        {
            break;
        }

        // 2. 更新当前处理单号
        taskStatus.CurrentWaybill = waybill;
        await _cacheService.SetAsync(cacheKey, taskStatus, 60);

        try
        {
            // 3. 执行关联
            var (success, errorCode, errorMessage) = await AssociateWaybillAsync(tagNumber, waybill, "system_auto");
            
            if (success)
            {
                taskStatus.SuccessCount++;
            }
            else
            {
                taskStatus.FailedCount++;
                taskStatus.FailedItems.Add(new AutoPackFailedItem
                {
                    WaybillNumber = waybill,
                    ErrorCode = errorCode,
                    ErrorMessage = errorMessage
                });
            }
        }
        catch (Exception ex)
        {
            taskStatus.FailedCount++;
            taskStatus.FailedItems.Add(new AutoPackFailedItem
            {
                WaybillNumber = waybill,
                ErrorCode = 9999,
                ErrorMessage = ex.Message
            });
        }

        // 4. 更新进度
        taskStatus.ProcessedCount++;
        await _cacheService.SetAsync(cacheKey, taskStatus, 60);

        // 5. 随机延迟 2-4 秒
        if (taskStatus.ProcessedCount < waybills.Count)
        {
            var delay = random.Next(2000, 4001);
            await Task.Delay(delay);
        }
    }

    // 6. 任务完成
    var finalStatus = await _cacheService.GetAsync<AutoPackTaskStatus>(cacheKey);
    if (finalStatus != null)
    {
        finalStatus.Status = finalStatus.CancellationTokenSource?.IsCancellationRequested == true ? "cancelled" : "completed";
        finalStatus.EndTime = DateTime.UtcNow;
        finalStatus.CurrentWaybill = null;
        await _cacheService.SetAsync(cacheKey, finalStatus, 60);
    }
}
```

**验收标准**：

- [ ] 支持取消操作
- [ ] 2-4 秒随机延迟正确实现
- [ ] 进度实时更新到缓存
- [ ] 失败记录完整保存
- [ ] 订单日志正确记录

***

## 阶段四：接口层

### 任务 4.1：实现控制器方法

**文件**：`src/CONTROLLER/Controllers/BagTagController.cs`

**新增接口**：

1. **启动自动集包**

```csharp
[HttpPost("auto-pack/start")]
public async Task<IActionResult> StartAutoPack([FromBody] StartAutoPackRequest request)
{
    try
    {
        var result = await _bagTagService.StartAutoPackAsync(request.TagNumber, request.Creator);
        return Ok(new { code = 0, message = "success", data = result });
    }
    catch (Exception ex)
    {
        return Ok(new { code = 1001, message = ex.Message });
    }
}
```

1. **查询进度**

```csharp
[HttpGet("auto-pack/progress/{taskId}")]
public async Task<IActionResult> GetAutoPackProgress(string taskId)
{
    try
    {
        var result = await _bagTagService.GetAutoPackProgressAsync(taskId);
        if (result == null)
        {
            return Ok(new { code = 1002, message = "Task not found" });
        }
        return Ok(new { code = 0, message = "success", data = result });
    }
    catch (Exception ex)
    {
        return Ok(new { code = 9999, message = ex.Message });
    }
}
```

1. **取消任务**

```csharp
[HttpPost("auto-pack/cancel/{taskId}")]
public async Task<IActionResult> CancelAutoPack(string taskId)
{
    try
    {
        var success = await _bagTagService.CancelAutoPackAsync(taskId);
        if (!success)
        {
            return Ok(new { code = 1002, message = "Task not found or already completed" });
        }
        return Ok(new { code = 0, message = "Task cancelled successfully" });
    }
    catch (Exception ex)
    {
        return Ok(new { code = 9999, message = ex.Message });
    }
}
```

1. **获取结果**

```csharp
[HttpGet("auto-pack/result/{taskId}")]
public async Task<IActionResult> GetAutoPackResult(string taskId)
{
    try
    {
        var result = await _bagTagService.GetAutoPackResultAsync(taskId);
        if (result == null)
        {
            return Ok(new { code = 1002, message = "Task not found" });
        }
        return Ok(new { code = 0, message = "success", data = result });
    }
    catch (Exception ex)
    {
        return Ok(new { code = 9999, message = ex.Message });
    }
}
```

**验收标准**：

- [ ] 所有接口响应格式统一
- [ ] 错误码与 spec.md 一致
- [ ] 支持 JSONP（参考现有代码）

***

### 任务 4.2：注册依赖注入

**文件**：`src/CONTROLLER/Program.cs`（如有需要）

检查是否需要额外注册服务，通常现有 DI 配置已足够。

**验收标准**：

- [ ] 服务能正常解析
- [ ] 无循环依赖

***

## 阶段五：测试与优化

### 任务 5.1：编写单元测试

**文件**：`test/...`（根据项目测试规范）

**测试用例**：

1. 启动任务 - 袋牌不存在
2. 启动任务 - 袋牌未打开
3. 启动任务 - 无符合条件的包裹
4. 启动任务 - 成功启动
5. 查询进度 - 任务不存在
6. 查询进度 - 正常查询
7. 取消任务 - 任务不存在
8. 取消任务 - 任务已完成
9. 取消任务 - 正常取消
10. 自动集包执行 - 全部成功
11. 自动集包执行 - 部分失败
12. 自动集包执行 - 取消操作

**验收标准**：

- [ ] 核心逻辑覆盖率达到 80%+
- [ ] 所有测试用例通过

***

### 任务 5.2：性能优化与联调

**优化项**：

1. SQL 查询性能优化（添加索引）
2. 缓存过期时间调整
3. 并发任务数限制
4. 异常处理完善

**联调检查**：

1. WinForm 前端能正常调用接口
2. 进度实时更新
3. 取消功能正常
4. 大数据量（1000+ 包裹）测试

**验收标准**：

- [ ] 100 个包裹处理时间 < 10 分钟
- [ ] 内存占用稳定
- [ ] 前端无卡顿

***

## 依赖关系图

```
任务 1.1 (模型) ──┐
                  ├──→ 任务 2.1 (Repository接口) ──→ 任务 2.2 (Repository实现)
任务 1.2 (DTO) ───┘                                          │
                                                             │
任务 3.1 (Service接口) ──────────────────────────────────────┤
                          │                                  │
                          ↓                                  ↓
                    任务 3.2 (启动逻辑) ─────────────→ 任务 3.3 (执行逻辑)
                          │                                  │
                          └────────────────┬─────────────────┘
                                           ↓
                                    任务 4.1 (控制器)
                                           │
                                           ↓
                                    任务 4.2 (DI注册)
                                           │
                                           ↓
                              ┌───────────┴───────────┐
                              ↓                       ↓
                         任务 5.1 (单元测试)      任务 5.2 (优化联调)
```

***

## 风险与应对

| 风险           | 影响 | 应对措施                       |
| ------------ | -- | -------------------------- |
| 包裹数量过大导致任务超时 | 高  | 添加任务超时机制，支持断点续传            |
| 缓存失效导致进度丢失   | 中  | 使用持久化存储（如数据库）保存任务状态        |
| 并发任务过多       | 中  | 限制同时运行的自动集包任务数量            |
| 前端轮询频率过高     | 低  | 建议轮询间隔 1-2 秒，或改用 WebSocket |