上传源代码版本

.trae/specs/add-zunyou-webhook/checklist.md

@@ -0,0 +1,41 @@
+# 尊祐客户分拣信息回传 - 验证检查清单
+
+## 功能验证
+- [ ] 检查 SendWebhookToZunYou 方法是否正确实现
+- [ ] 检查方法参数是否正确，包括 waybillNumber, scanTime, printTime, scanResult, finalMileTrackingNumber
+- [ ] 检查回传数据格式是否符合尊祐系统要求
+- [ ] 检查请求头是否包含正确的 token
+- [ ] 检查是否在 DownloadLabelByWaybillNumber 方法的 finally 块中添加了尊祐客户的判断
+- [ ] 检查尊祐客户(ZY_SH)的回传是否能够正确触发
+- [ ] 检查回传是否采用异步方式，不阻塞主流程
+
+## 数据验证
+- [ ] 检查回传数据中的 WaybillNumber 是否正确
+- [ ] 检查回传数据中的 TrackingNumber 是否正确获取自 finalMileTrackingNumber
+- [ ] 检查回传数据中的 Replaced 字段是否根据 scanResult 正确判断
+- [ ] 检查回传数据中的 ReplacedAt 是否使用正确的 UTC 时间格式
+
+## 错误处理
+- [ ] 检查网络错误处理是否正确
+- [ ] 检查尊祐系统返回错误时的处理是否正确
+- [ ] 检查错误日志是否完整记录
+- [ ] 检查回传失败是否不影响主流程
+
+## 日志记录
+- [ ] 检查回传请求的详细信息是否记录
+- [ ] 检查回传成功时的响应信息是否记录
+- [ ] 检查回传失败时的错误信息是否记录
+- [ ] 检查日志格式是否与现有回传方法一致
+
+## 代码质量
+- [ ] 检查代码风格是否与现有代码一致
+- [ ] 检查方法命名是否规范
+- [ ] 检查注释是否完整
+- [ ] 检查是否存在代码重复
+
+## 测试验证
+- [ ] 测试尊祐客户的标签下载请求是否能够触发回传
+- [ ] 测试回传数据格式是否正确
+- [ ] 测试请求头的 token 是否正确设置
+- [ ] 测试错误处理机制是否正常工作
+- [ ] 测试日志记录是否完整

.trae/specs/add-zunyou-webhook/spec.md

@@ -0,0 +1,87 @@
+# 尊祐客户分拣信息回传 - 产品需求文档
+
+## Overview
+- **Summary**: 为尊祐客户添加分拣信息回传功能，当系统处理标签替换请求时，向尊祐系统发送回传通知，包含面单号、跟踪号、替换状态和替换时间等信息。
+- **Purpose**: 实现与尊祐系统的对接，确保尊祐能够及时获取标签替换的状态信息，便于其内部物流管理和跟踪。
+- **Target Users**: 尊祐客户及其系统集成人员。
+
+## Goals
+- 实现向尊祐系统的分拣信息回传功能
+- 确保回传数据的准确性和及时性
+- 与现有回传机制保持一致的代码风格和错误处理方式
+- 提供必要的日志记录以便于问题排查
+
+## Non-Goals (Out of Scope)
+- 不修改现有的其他客户回传逻辑
+- 不改变系统的核心业务流程
+- 不涉及尊祐系统内部的业务逻辑修改
+
+## Background & Context
+- 系统已经实现了向派通国际(PT_GZ)和讯通系统(XT_JX)的回传功能
+- 回传逻辑位于LabelController.cs的DownloadLabelByWaybillNumber方法中
+- 回传采用异步方式，不阻塞主流程
+- 尊祐系统提供了RESTful API接口用于接收回传数据
+
+## Functional Requirements
+- **FR-1**: 当客户代码为ZY_SH时，向尊祐系统发送回传通知
+- **FR-2**: 回传数据应包含面单号、跟踪号、替换状态和替换时间
+- **FR-3**: 回传请求应包含指定的token认证信息
+- **FR-4**: 回传应采用异步方式，不阻塞主流程
+- **FR-5**: 回传失败时应记录错误日志，但不影响主流程
+
+## Non-Functional Requirements
+- **NFR-1**: 回传请求应设置合理的超时时间，避免长时间阻塞
+- **NFR-2**: 应提供详细的日志记录，便于问题排查
+- **NFR-3**: 代码应遵循现有代码风格和架构模式
+
+## Constraints
+- **Technical**: 使用现有的HttpClientFactory创建HttpClient实例
+- **Business**: 必须使用尊祐提供的API地址和token
+- **Dependencies**: 依赖现有的LabelReplaceEntity数据模型，需要从中获取跟踪号信息
+
+## Assumptions
+- 尊祐系统的API接口能够正常接收和处理回传数据
+- LabelReplaceEntity中包含了所需的跟踪号信息
+- 系统能够正确获取客户代码ZY_SH的客户信息
+
+## Acceptance Criteria
+
+### AC-1: 尊祐客户回传触发
+- **Given**: 系统处理尊祐客户(ZY_SH)的标签替换请求
+- **When**: 标签下载完成后
+- **Then**: 系统应向尊祐系统发送回传通知
+- **Verification**: `programmatic`
+- **Notes**: 回传应在finally块中异步执行
+
+### AC-2: 回传数据格式正确
+- **Given**: 系统向尊祐系统发送回传通知
+- **When**: 构造回传数据
+- **Then**: 回传数据应符合尊祐系统要求的格式，包含WaybillNumber、TrackingNumber、Replaced和ReplacedAt字段
+- **Verification**: `programmatic`
+- **Notes**: Replaced字段应根据扫描结果判断，ReplacedAt应使用UTC时间
+
+### AC-3: 回传请求头正确
+- **Given**: 系统向尊祐系统发送回传通知
+- **When**: 构造HTTP请求
+- **Then**: 请求头应包含指定的token认证信息
+- **Verification**: `programmatic`
+- **Notes**: token值为1c96499e-3c58-4e20-bc5d-b52ce9f9e36d
+
+### AC-4: 回传失败处理
+- **Given**: 向尊祐系统发送回传通知失败
+- **When**: 网络错误或尊祐系统返回错误
+- **Then**: 系统应记录错误日志，但不影响主流程
+- **Verification**: `human-judgment`
+- **Notes**: 应使用与现有回传逻辑相同的错误处理方式
+
+### AC-5: 回传成功记录
+- **Given**: 向尊祐系统发送回传通知成功
+- **When**: 尊祐系统返回成功状态
+- **Then**: 系统应记录成功日志
+- **Verification**: `human-judgment`
+- **Notes**: 应记录响应状态码和响应内容
+
+## Open Questions
+- [ ] 尊祐系统对回传数据的具体验证规则是什么？
+- [ ] 尊祐系统的API接口是否需要额外的认证或参数？
+- [ ] 当TrackingNumber为空时，回传应如何处理？

.trae/specs/add-zunyou-webhook/tasks.md

@@ -0,0 +1,49 @@
+# 尊祐客户分拣信息回传 - 实现计划
+
+## [ ] 任务 1: 实现 SendWebhookToZunYou 方法
+- **Priority**: P0
+- **Depends On**: None
+- **Description**:
+  - 在 LabelController.cs 中添加新的私有方法 SendWebhookToZunYou
+  - 方法参数包括 waybillNumber, scanTime, printTime, scanResult, finalMileTrackingNumber
+  - 实现向尊祐系统发送回传通知的逻辑
+  - 构造符合尊祐系统要求的 JSON 数据
+  - 设置请求头包含指定的 token
+  - 处理响应和错误情况
+- **Acceptance Criteria Addressed**: AC-2, AC-3, AC-4, AC-5
+- **Test Requirements**:
+  - `programmatic` TR-1.1: 方法能够正确构造回传数据格式
+  - `programmatic` TR-1.2: 方法能够正确设置请求头的 token
+  - `programmatic` TR-1.3: 方法能够正确处理网络错误和响应错误
+  - `human-judgment` TR-1.4: 方法的代码风格与现有回传方法一致
+- **Notes**: 参考现有的 SendWebhookToPatuen 和 SendWebhookToXunTong 方法的实现方式
+
+## [ ] 任务 2: 在回传逻辑中添加尊祐客户判断
+- **Priority**: P0
+- **Depends On**: 任务 1
+- **Description**:
+  - 在 DownloadLabelByWaybillNumber 方法的 finally 块中，添加对尊祐客户(ZY_SH)的判断
+  - 当客户代码为 ZY_SH 时，调用 SendWebhookToZunYou 方法
+  - 确保使用异步方式调用，不阻塞主流程
+- **Acceptance Criteria Addressed**: AC-1
+- **Test Requirements**:
+  - `programmatic` TR-2.1: 当客户代码为 ZY_SH 时，能够触发回传
+  - `programmatic` TR-2.2: 回传调用不阻塞主流程
+  - `human-judgment` TR-2.3: 代码逻辑与现有回传判断逻辑一致
+- **Notes**: 参考现有的 PT_GZ 和 XT_JX 客户的回传判断逻辑
+
+## [ ] 任务 3: 测试回传功能
+- **Priority**: P1
+- **Depends On**: 任务 1, 任务 2
+- **Description**:
+  - 模拟尊祐客户的标签下载请求
+  - 验证回传请求是否正确发送
+  - 检查日志记录是否完整
+  - 验证错误处理是否正常
+- **Acceptance Criteria Addressed**: AC-1, AC-2, AC-3, AC-4, AC-5
+- **Test Requirements**:
+  - `programmatic` TR-3.1: 系统能够正确触发尊祐客户的回传
+  - `programmatic` TR-3.2: 回传数据格式符合要求
+  - `human-judgment` TR-3.3: 日志记录完整且清晰
+  - `human-judgment` TR-3.4: 错误处理机制正常工作
+- **Notes**: 可以使用现有的测试方法 TestXunTongWebhook 作为参考，创建类似的测试方法