上传源代码版本

.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为空时，回传应如何处理？